AGENTS.md — AdsCalculator.xyz

Context Loading Protocol (MANDATORY)

When working on a task, load context in this order:

1. Read wiki/INDEX.md — find the relevant section (Calculators, Blog, Infrastructure, CSS)
2. Read wiki/graph.json — find the feature node, follow edges to files
3. Read ONLY targeted files identified by graph edges — never read full wiki monolith
4. Read wiki/adscalculator-xyz.md only for strategy/roadmap questions

Example: "fix the ROAS calculator"

INDEX.md → Simple Calculators → ROAS row → JS, HTML, schema
graph.json → node "roas" → edges:
  - simple-main-js (implements — shared with CPC, CPM, CTR, Revenue!)
  - roas-html (renders)
  - roas-schema (has_schema)
  - cpc, cpm, ctr, roi-ltv (related_to)
  - campaign-funnel, email-marketing, mmo (related_to from other side)
→ read_file(js/simple-main.js)  # targeted, not monolith
⚠️ BUG WARNING: simple-main.js is shared by 5 calculators — a bug here breaks all 5

Example: "write a blog post about CPA vs ROAS"

INDEX.md → Blog table → "CPA vs ROAS" → related calcs: [[roas]], [[cpc]]
INDEX.md → Calculators → ROAS + CPC rows → schemas, JS
graph.json → node "roas" → has_schema → roas-schema
              node "cpc" → has_schema → cpc-schema
wiki/content-strategy.md → editorial guidelines

What NOT to do

• ❌ Do NOT read wiki/adscalculator-xyz.md for file/code questions (it's strategy only)
• ❌ Do NOT grep the entire project when graph.json has the answer
• ❌ Do NOT read the full wiki monolith to find one thing
• ❌ Do NOT use patch tool on HTML with complex quotes (Escape-drift bug) — use write_file

Updating the Graph

When you add, remove, or rename a file:

1. Update wiki/graph.json — add/remove node + edges
2. Update wiki/INDEX.md — add/remove row in the relevant table
3. Commit both together with the code change

Project Conventions

• Eleventy 3.x — flat structure (no src/ subfolder)
• One feature = one commit — never batch unrelated changes
• Build verification: npx @11ty/eleventy after every change (must be 0 errors)
• QA server: node serve.js on port 8080
• CSS: 26 modular files in style/ → concatenated to style/style.css (NEVER @import)
• Tests: Jest in tests/ (currently only calculations.test.js)
• Blog: blog/<slug>/index.md + PNG images, shared blog/blog.json frontmatter
• Schemas: Every calculator has its own _includes/schemas/<name>.njk
• Cross-project: footer links to oddscalculator.xyz
• Revenue goal: $100+/month

Known Quirks

File Patterns