{"description":"Formal machine-readable contract registry for agent-facing JSON endpoints.","objective":"Give a future agent enough structure to start from the main URL and understand how to inspect, plan, build, validate, and improve a serious website without needing prior chat context.","contracts":[{"id":"agent-manifest-contract","endpoint":"/agent-manifest.json","schema":"/schemas/agent-manifest.schema.json","source":"src/pages/agent-manifest.json.ts","owner":"Reference Layer","purpose":"Top-level machine-readable index that lets an agent discover the system from the main URL.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Schema endpoint returns valid JSON","Manifest lists all machine endpoints and repo files"],"failureMode":"A future agent cannot reliably discover the site operating system without prior chat context."},{"id":"file-map-contract","endpoint":"/file-map.json","schema":"/schemas/file-map.schema.json","source":"src/pages/file-map.json.ts","owner":"Reference Layer","purpose":"Maps important source files, generated endpoints, docs, schemas, and source-retention locations.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Every listed repo path exists","Schema endpoint returns valid JSON"],"failureMode":"Agents waste time searching or act on stale file assumptions."},{"id":"qa-contract","endpoint":"/qa-contract.json","schema":"/schemas/qa-contract.schema.json","source":"src/pages/qa-contract.json.ts","owner":"Evaluation Layer","purpose":"Defines executable readiness checks, required command gates, and future testing backlog.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","required_before_ready remains npm run qa:all","Schema endpoint returns valid JSON"],"failureMode":"Agents can claim readiness without running the expected proof commands."},{"id":"examples-contract","endpoint":"/examples.json","schema":"/schemas/examples.schema.json","source":"src/pages/examples.json.ts","owner":"Reference Layer","purpose":"Exposes reusable page, schema, SEO, AEO, and QA examples as structured patterns.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Examples include source assumptions and QA requirements","Schema endpoint returns valid JSON"],"failureMode":"Agents copy visual patterns without understanding the technical obligations underneath them."},{"id":"agent-tasks-contract","endpoint":"/agent-tasks.json","schema":"/schemas/agent-tasks.schema.json","source":"src/pages/agent-tasks.json.ts","owner":"Execution Layer","purpose":"Publishes the prioritized backlog agents should use to continue improving the product.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","At least one next task remains until the roadmap is complete","Schema endpoint returns valid JSON"],"failureMode":"Future agents cannot tell what to build next or how backlog work maps to the roadmap."},{"id":"product-roadmap-contract","endpoint":"/product-roadmap.json","schema":"/schemas/product-roadmap.schema.json","source":"src/pages/product-roadmap.json.ts","owner":"Execution Layer","purpose":"Turns value multipliers into prioritized execution items, stress tests, and acceptance criteria.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Roadmap priorities are contiguous","Schema endpoint returns valid JSON"],"failureMode":"The product direction becomes a loose idea list instead of an executable plan."},{"id":"walkthroughs-contract","endpoint":"/walkthroughs.json","schema":"/schemas/walkthroughs.schema.json","source":"src/pages/walkthroughs.json.ts","owner":"Execution Layer","purpose":"Gives each roadmap area step-by-step actions, rationale, evidence, and pass/warn/fail criteria.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Every roadmap item has exactly one walkthrough","Schema endpoint returns valid JSON"],"failureMode":"Agents see the objective but skip hidden steps and verification details."},{"id":"contract-registry-contract","endpoint":"/contract-registry.json","schema":"/schemas/contract-registry.schema.json","source":"src/pages/contract-registry.json.ts","owner":"Reference Layer","purpose":"Lists every formal JSON contract, its schema, owning source file, validation command, evidence, and failure mode.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Every registry source path exists","Every registry endpoint and schema is reachable"],"failureMode":"Agents cannot distinguish formal machine contracts from incidental generated files."},{"id":"site-studies-contract","endpoint":"/site-studies.json","schema":"/schemas/site-studies.schema.json","source":"src/pages/site-studies.json.ts","owner":"Reference Layer","purpose":"Turns real-site SEO/AEO audits into reusable good and bad examples with evidence paths and checks to add.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Every study has reusable patterns and avoid patterns","Evidence paths exist"],"failureMode":"Agents lose the lessons from real audits or copy inspiration without its technical caveats."},{"id":"seo-aeo-evaluation-contract","endpoint":"/seo-aeo-evaluation.json","schema":"/schemas/seo-aeo-evaluation.schema.json","source":"src/pages/seo-aeo-evaluation.json.ts","owner":"Evaluation Layer","purpose":"Defines repeatable SEO/AEO checks, why each exists, validation commands, evidence, and current automation status.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Implemented checks name an executable validation command","Planned checks state the missing evidence path"],"failureMode":"Agents treat SEO/AEO as vague advice instead of an inspectable evaluation system."},{"id":"source-traceability-contract","endpoint":"/source-traceability.json","schema":"/schemas/source-traceability.schema.json","source":"src/pages/source-traceability.json.ts","owner":"Reference Layer","purpose":"Maps raw sources, cleaned facts, derived briefs, public-safe claims, blocked claims, page usage, and proof requirements.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Referenced source/working/derived paths exist","Claim ledger separates allowed and blocked claims"],"failureMode":"Agents publish unsupported claims or lose the source chain behind page, schema, SEO, and AEO decisions."},{"id":"site-type-playbooks-contract","endpoint":"/site-type-playbooks.json","schema":"/schemas/site-type-playbooks.schema.json","source":"src/pages/site-type-playbooks.json.ts","owner":"Execution Layer","purpose":"Converts reusable site examples into full build playbooks with inputs, page models, build sequence, QA gates, stress tests, and done criteria.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Every playbook maps to an example type","Every playbook includes stress tests and completion criteria"],"failureMode":"Agents know what a site type is but still have to guess the build order, proof gates, and readiness standard."},{"id":"page-patterns-contract","endpoint":"/page-patterns.json","schema":"/schemas/page-patterns.schema.json","source":"src/pages/page-patterns.json.ts","owner":"Execution Layer","purpose":"Defines reusable page-level contracts for page intent, required sections, schema, SEO/AEO, traceability, QA, anti-patterns, and stress tests.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Every pattern has required sections and QA gates","Patterns map to existing route examples where available"],"failureMode":"Agents build pages from visual intuition instead of page-specific contracts and verification rules."},{"id":"page-pattern-fixtures-contract","endpoint":"/page-pattern-fixtures.json","schema":"/schemas/page-pattern-fixtures.schema.json","source":"src/pages/page-pattern-fixtures.json.ts","owner":"Execution Layer","purpose":"Maps every reusable page-pattern contract to an actual fixture route with visible sections, metadata, schema, traceability, good/bad examples, agent instructions, QA gates, and completion criteria.","required":true,"validationCommand":"npm run qa:fixtures","evidence":["Endpoint returns valid JSON","Every pattern has a fixture route","Fixture routes render with one H1, required sections, source notes, and QA gates"],"failureMode":"Agents can read abstract page contracts but cannot see how those contracts become concrete routes."},{"id":"browser-visual-qa-contract","endpoint":"/browser-visual-qa.json","schema":"/schemas/browser-visual-qa.schema.json","source":"src/pages/browser-visual-qa.json.ts","owner":"Evaluation Layer","purpose":"Defines browser screenshot, viewport, layout-overflow, clipping, visible-heading, and report evidence expectations.","required":true,"validationCommand":"npm run qa:browser","evidence":["Endpoint returns valid JSON","qa:browser writes reports/browser/browser-visual-report.json","Screenshots are captured for each core route at desktop and mobile widths"],"failureMode":"Agents declare pages visually ready without viewport evidence, screenshot artifacts, or reproducible layout checks."},{"id":"crawl-evidence-contract","endpoint":"/crawl-evidence.json","schema":"/schemas/crawl-evidence.schema.json","source":"src/pages/crawl-evidence.json.ts","owner":"Evaluation Layer","purpose":"Defines Screaming Frog/local crawl evidence requirements, export inputs, summary reports, severity rules, and launch-readiness criteria.","required":true,"validationCommand":"npm run qa:crawl -- --export-dir <crawl-export-dir>","evidence":["Endpoint returns valid JSON","qa:crawl summarizes Screaming Frog CSV exports","Crawl report records critical findings and missing exports"],"failureMode":"Agents claim crawl readiness without saved exports, machine-readable findings, or reproducible crawl evidence."},{"id":"design-system-contract","endpoint":"/design-system-contracts.json","schema":"/schemas/design-system-contracts.schema.json","source":"src/pages/design-system-contracts.json.ts","owner":"Reference Layer","purpose":"Defines design principles, tokens, component rules, responsive constraints, accessibility rules, anti-patterns, QA gates, and stress tests before visual redesign work.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Design rules include tokens, components, accessibility, anti-patterns, stress tests, and QA gates","Design changes remain tied to browser visual QA"],"failureMode":"Agents change visuals from taste or trend instead of an explicit, testable design system contract."},{"id":"aeo-geo-model-context-contract","endpoint":"/aeo-geo-context.json","schema":"/schemas/aeo-geo-context.schema.json","source":"src/pages/aeo-geo-context.json.ts","owner":"Evaluation Layer","purpose":"Defines answer-engine and generative-engine context surfaces, prompt fixtures, citation expectations, blocked-claim checks, model review records, and stress tests.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Prompt and answer-evidence fixtures exist","AEO/GEO context maps prompts to source, schema, LLM, and page evidence"],"failureMode":"Agents optimize for search pages while leaving answer engines without explicit context, citation paths, or claim boundaries."},{"id":"why-explanations-contract","endpoint":"/why-explanations.json","schema":"/schemas/why-explanations.schema.json","source":"src/pages/why-explanations.json.ts","owner":"Reference Layer","purpose":"Defines where rationale is required, what a useful why must contain, anti-patterns to avoid, QA gates, and stress tests for explainable agent work.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Required rationale surfaces are listed","QA checks representative contracts for why/rationale/objectiveAlignment fields"],"failureMode":"Agents follow broad objectives without understanding the reason, tradeoff, evidence, or failure mode behind each step."},{"id":"real-site-comparisons-contract","endpoint":"/real-site-comparisons.json","schema":"/schemas/real-site-comparisons.schema.json","source":"src/pages/real-site-comparisons.json.ts","owner":"Evaluation Layer","purpose":"Defines how agents compare target sites against real reference sites, score reusable patterns and gaps, cite evidence, and convert findings into tasks.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Comparison dimensions map to site studies and QA gates","At least one comparison profile references an existing site study"],"failureMode":"Agents learn from real sites informally without repeatable dimensions, evidence, scoring, or follow-up tasks."},{"id":"handoff-reports-contract","endpoint":"/handoff-reports.json","schema":"/schemas/handoff-reports.schema.json","source":"src/pages/handoff-reports.json.ts","owner":"Execution Layer","purpose":"Defines final handoff report structure for outcome, changes, verification, evidence, residual risks, next actions, and required closeout fields.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Example handoff report fixture exists","Required sections cover QA, source, crawl, browser, contracts, risks, and next tasks"],"failureMode":"Agents finish work without a durable record of what changed, what passed, what evidence exists, and what remains risky."},{"id":"conversion-copy-contract","endpoint":"/conversion-copy.json","schema":"/schemas/conversion-copy.schema.json","source":"src/pages/conversion-copy.json.ts","owner":"Content Strategy Layer","purpose":"Defines conversion copy principles, public source boundaries, copy types, weak/strong examples, agent workflow, anti-patterns, QA gates, and pass criteria.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Source-study manifest exists","Principles include why, checks, examples, and guardrails"],"failureMode":"Agents write generic or unsupported website copy because conversion principles, proof expectations, and ethical boundaries are implied instead of explicit."},{"id":"offer-ecosystem-contract","endpoint":"/offer-ecosystem.json","schema":"/schemas/offer-ecosystem.schema.json","source":"src/pages/offer-ecosystem.json.ts","owner":"Content Strategy Layer","purpose":"Defines how agents map AI tools, communities, workshops, playbooks, pricing tiers, qualification gates, referral engines, and disclaimers into one coherent website funnel.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Funnel layers include why, page role, proof needs, and guardrails","QA validates layer and path coverage"],"failureMode":"Agents build disconnected offer sections instead of a coherent acquisition path with qualification, value delivery, pricing, referrals, and outcome boundaries."},{"id":"infrastructure-decisions-contract","endpoint":"/infrastructure-decisions.json","schema":"/schemas/infrastructure-decisions.schema.json","source":"src/pages/infrastructure-decisions.json.ts","owner":"Infrastructure Strategy Layer","purpose":"Defines tiered infrastructure decisions for hosting, rendering, CMS, data, auth, media, search, analytics, forms, payments, DNS/CDN, observability, and deployment workflow.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON","Decision areas include tiers, triggers, tradeoffs, agent questions, and guardrails","QA validates required infrastructure coverage"],"failureMode":"Agents choose infrastructure by habit or platform preference instead of matching site requirements, risk, budget, maintainability, and launch constraints."},{"id":"agent-index-contract","endpoint":"/agent-index.json","schema":"/schemas/agent-index.schema.json","source":"src/pages/agent-index.json.ts","owner":"Reference Layer","purpose":"Token-cheap orientation index with reading order and the complete endpoint list, so agents are not forced through the 400KB aggregate manifest to orient.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Endpoint returns valid JSON under 25KB","Reading order routes all return 200","Endpoint list matches the manifest"],"failureMode":"Token-constrained agents burn context on the aggregate manifest or orient from partial guesses."},{"id":"evidence-index-contract","endpoint":"/evidence/index.json","schema":"/schemas/evidence-index.schema.json","source":"scripts/publish-evidence.mjs","owner":"Quality Layer","purpose":"Published QA evidence from the latest accepted run, so the live site proves its quality claims instead of asserting them. One accepted run behind by design.","required":true,"validationCommand":"npm run qa:aeo","evidence":["Index returns valid JSON with dated entries","Every listed report URL returns 200","Workstation paths are redacted"],"failureMode":"External agents must take the entire QA story on faith, which contradicts the system's evidence-over-assertion promise."},{"id":"accessibility-contract","endpoint":"/accessibility-contract.json","schema":"/schemas/accessibility-contract.schema.json","source":"src/pages/accessibility-contract.json.ts","owner":"Quality Layer","purpose":"WCAG 2.2 AA target with value-level rules, axe/keyboard enforcement method, manual review checklist, and honest automated-coverage limits.","required":true,"validationCommand":"npm run qa:browser","evidence":["Endpoint returns valid JSON","Zero critical/serious axe violations under the 2.2 tag set","Keyboard pass per desktop route","Manual checklist documented"],"failureMode":"Accessibility stays a scattered heuristic; regressions exclude users and accumulate legal risk invisibly."},{"id":"performance-budgets-contract","endpoint":"/performance-budgets.json","schema":"/schemas/performance-budgets.schema.json","source":"src/pages/performance-budgets.json.ts","owner":"Quality Layer","purpose":"Core Web Vitals targets, asset-weight budgets, page rules, and the measurement method enforced by qa:perf.","required":true,"validationCommand":"npm run qa:perf","evidence":["Endpoint returns valid JSON","Every core route meets local LCP/CLS budgets","Asset budgets and page rules pass on the built output","Negative controls fail as expected"],"failureMode":"Performance stays an accident of being static; an agent could ship a slow site while passing every other gate."},{"id":"demo-build-contract","endpoint":"/demo-build.json","schema":"/schemas/demo-build.schema.json","source":"src/pages/demo-build.json.ts","owner":"Execution Layer","purpose":"Machine-readable record of the canonical demo build: fictional source chain, playbook execution, pages, claims, blocked phrases, QA gates, and residual risks.","required":true,"validationCommand":"npm run qa:demo","evidence":["Endpoint returns valid JSON","Source chain files exist on disk","Demo pages render with required schema and claim IDs","Blocked phrases stay out of demo surfaces"],"failureMode":"The operating system stays described-but-undemonstrated, and future agents have no complete worked implementation to diff real adaptations against."}]}