{"name":"Agent Website Reference","purpose":"An agent-facing website operating system for learning, executing, and validating high-quality website builds.","system_purpose":{"mission":"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.","identity":"Agent-facing website operating system","not":["Human marketing destination","Cosmetic template","Generic Astro starter","Design-system showcase"],"layers":[{"name":"Reference Layer","purpose":"Explain the standard, repo map, examples, source-retention model, and machine-readable contract."},{"name":"Execution Layer","purpose":"Tell agents which workflows to run and what outputs each workflow must produce."},{"name":"Evaluation Layer","purpose":"Prove quality through build checks, route checks, SEO/AEO checks, contract checks, and future browser/crawl stress tests."}],"primaryJourney":["Open the main URL.","Read /agent-manifest.json.","Read /file-map.json.","Read /qa-contract.json.","Read /examples.json.","Read /agent-tasks.json.","Inspect referenced repo files.","Run npm run qa:all.","Choose the next improvement from evidence."],"successCriteria":["An agent can explain the system purpose without prior conversation.","An agent can identify canonical data, docs, source folders, endpoints, and QA scripts.","An agent can build or adapt a site from source evidence without inventing unsupported claims.","HTML, metadata, schema, LLM endpoints, sitemap, and QA stay aligned.","Readiness is proven with repeatable checks and remaining risk is stated clearly."]},"agent_build_principles":[{"objective":"Do not stop at the objective statement.","why":"Agents often satisfy the headline instruction and skip the implied work underneath it. This system must spell out each inspection angle, each check, and the reason the check exists.","requiredDetails":["State the major objective.","Break the objective into specific steps.","Explain why each step matters.","List the files, routes, data, or tests involved.","Define what counts as pass, warning, and fail.","Capture evidence so future agents do not need to rediscover the same facts."]},{"objective":"Evaluate the whole website system, not just the visual UI.","why":"A good website is the visible interface plus routing, metadata, schema, crawlability, source truth, internal links, evidence, QA, and agent-readable context.","requiredDetails":["Inspect visual hierarchy and mobile fit.","Inspect HTML semantics, H1/H2 structure, and content order.","Inspect metadata, canonicals, Open Graph, sitemap, and robots.","Inspect schema and entity consistency.","Inspect source-retention and claim/proof traceability.","Inspect LLM/AEO endpoints and agent-readable files.","Inspect crawl evidence and browser evidence before calling work ready."]},{"objective":"Use good and bad examples as training data.","why":"Agents learn faster when a pattern includes both what to copy and what to avoid. A strong reference system should turn external examples into reusable rules, not vague inspiration.","requiredDetails":["Record the example URL and crawl date.","List the strong patterns worth reusing.","List the weak patterns or technical gaps to avoid.","Convert each observation into a check or backlog item.","Preserve the evidence path for the crawl or manual inspection.","Avoid copying brand, copy, or proprietary assets."]},{"objective":"Force SEO and AEO work through step-by-step verification.","why":"SEO/AEO failures hide in small mismatches: an indexable page without an H1, a missing LLM endpoint, a sitemap gap, a certificate issue, or schema that does not match visible content.","requiredDetails":["Check apex, www, HTTP, HTTPS, redirects, and TLS.","Compare sitemap URLs against crawled indexable URLs.","Check titles, descriptions, H1s, canonicals, and indexability.","Check schema by page type.","Check llms.txt, llms-full.txt, and agent-facing endpoints.","Separate crawler-visible 403s from true broken links with direct/browser validation.","Turn repeated findings into automated QA where possible."]}],"agent_walkthroughs":[{"id":"step-by-step-agent-walkthroughs-walkthrough","roadmapId":"step-by-step-agent-walkthroughs","priority":1,"title":"Step-by-step agent walkthroughs","objective":"Every major website-building task decomposes into objective, why, detailed steps, required evidence, pass/warn/fail criteria, and good/bad examples.","why":"Agents often complete the headline request and miss hidden work. The system must force the reasoning path so quality does not depend on agent intuition.","steps":[{"order":1,"action":"Create a reusable walkthrough data model.","why":"This step moves \"Step-by-step agent walkthroughs\" from a concept into verified operating behavior. It matters because Agents often complete the headline request and miss hidden work. The system must force the reasoning path so quality does not depend on agent intuition.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Convert current workflows into detailed walkthroughs.","why":"This step moves \"Step-by-step agent walkthroughs\" from a concept into verified operating behavior. It matters because Agents often complete the headline request and miss hidden work. The system must force the reasoning path so quality does not depend on agent intuition.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Add pass, warning, and fail criteria for each walkthrough.","why":"This step moves \"Step-by-step agent walkthroughs\" from a concept into verified operating behavior. It matters because Agents often complete the headline request and miss hidden work. The system must force the reasoning path so quality does not depend on agent intuition.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Attach example evidence paths and relevant QA commands.","why":"This step moves \"Step-by-step agent walkthroughs\" from a concept into verified operating behavior. It matters because Agents often complete the headline request and miss hidden work. The system must force the reasoning path so quality does not depend on agent intuition.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Expose walkthroughs through the manifest and a dedicated endpoint.","why":"This step moves \"Step-by-step agent walkthroughs\" from a concept into verified operating behavior. It matters because Agents often complete the headline request and miss hidden work. The system must force the reasoning path so quality does not depend on agent intuition.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["Every roadmap area has objective, why, steps, evidence, and pass/fail criteria.","The manifest exposes the walkthrough model.","QA validates that no major area is only a vague objective statement."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Give an agent only the main URL and confirm it can enumerate the required steps for SEO, AEO, buildout, and handoff.","Remove one required detail from a walkthrough and confirm QA fails.","Ask an agent to adapt a site type and confirm it cites the walkthrough before editing."],"objectiveAlignment":"Directly supports the system mission by making the agent inspect, plan, build, validate, and improve without prior context."},{"id":"machine-readable-contracts-walkthrough","roadmapId":"machine-readable-contracts","priority":2,"title":"Machine-readable contracts","objective":"Expose every critical concept as structured JSON with matching schemas and validation.","why":"Agents need stable contracts for routes, files, examples, QA, tasks, roadmap, and future evaluation rubrics.","steps":[{"order":1,"action":"Maintain /agent-manifest.json as the top-level index.","why":"This step moves \"Machine-readable contracts\" from a concept into verified operating behavior. It matters because Agents need stable contracts for routes, files, examples, QA, tasks, roadmap, and future evaluation rubrics.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Keep /file-map.json, /qa-contract.json, /examples.json, /agent-tasks.json, and /product-roadmap.json aligned.","why":"This step moves \"Machine-readable contracts\" from a concept into verified operating behavior. It matters because Agents need stable contracts for routes, files, examples, QA, tasks, roadmap, and future evaluation rubrics.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Add JSON Schema for each endpoint.","why":"This step moves \"Machine-readable contracts\" from a concept into verified operating behavior. It matters because Agents need stable contracts for routes, files, examples, QA, tasks, roadmap, and future evaluation rubrics.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Validate endpoint shapes in qa:aeo.","why":"This step moves \"Machine-readable contracts\" from a concept into verified operating behavior. It matters because Agents need stable contracts for routes, files, examples, QA, tasks, roadmap, and future evaluation rubrics.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Document contract-change rules in AGENTS and playbook.","why":"This step moves \"Machine-readable contracts\" from a concept into verified operating behavior. It matters because Agents need stable contracts for routes, files, examples, QA, tasks, roadmap, and future evaluation rubrics.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["Every machine endpoint has a schema.","qa:aeo validates all required contract fields.","Future agents can identify all machine endpoints from /agent-manifest.json."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Fetch every machine endpoint and validate JSON shape.","Break one endpoint schema intentionally in a fixture and confirm validation catches it.","Confirm all file-map paths resolve on disk."],"objectiveAlignment":"Supports context discovery from the main URL and prevents drift between human docs and agent-readable data."},{"id":"good-bad-example-library-walkthrough","roadmapId":"good-bad-example-library","priority":3,"title":"Good and bad example library","objective":"Create a structured library of site studies with patterns to reuse, failures to avoid, evidence paths, and checks to add.","why":"Agents learn faster from concrete examples. A good example without its failure modes is incomplete training data.","steps":[{"order":1,"action":"Define a site-study schema.","why":"This step moves \"Good and bad example library\" from a concept into verified operating behavior. It matters because Agents learn faster from concrete examples. A good example without its failure modes is incomplete training data.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Add Nectiv as the first site study.","why":"This step moves \"Good and bad example library\" from a concept into verified operating behavior. It matters because Agents learn faster from concrete examples. A good example without its failure modes is incomplete training data.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Capture good patterns, bad patterns, why each matters, and how to detect each one.","why":"This step moves \"Good and bad example library\" from a concept into verified operating behavior. It matters because Agents learn faster from concrete examples. A good example without its failure modes is incomplete training data.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Link each pattern to roadmap tasks or QA checks.","why":"This step moves \"Good and bad example library\" from a concept into verified operating behavior. It matters because Agents learn faster from concrete examples. A good example without its failure modes is incomplete training data.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Add future examples across local service, SaaS, agency, content hub, and poor AI-generated sites.","why":"This step moves \"Good and bad example library\" from a concept into verified operating behavior. It matters because Agents learn faster from concrete examples. A good example without its failure modes is incomplete training data.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["Site studies are structured and machine-readable.","At least one good and one bad pattern exists for each study.","The system can generate QA improvements from site-study findings."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Ask an agent what to copy from Nectiv and what to avoid.","Confirm each site-study issue maps to a check, task, or explicit non-action.","Confirm evidence paths exist for each saved site study."],"objectiveAlignment":"Improves the reference layer by grounding standards in real-world evidence."},{"id":"seo-aeo-evaluation-layer-walkthrough","roadmapId":"seo-aeo-evaluation-layer","priority":4,"title":"SEO/AEO evaluation layer","objective":"Build a repeatable SEO/AEO evaluation suite covering crawlability, indexability, metadata, schema, LLM endpoints, and domain behavior.","why":"Small technical gaps can break search and model consumption even when a site looks polished.","steps":[{"order":1,"action":"Add apex/www/http/https/TLS checks.","why":"This step moves \"SEO/AEO evaluation layer\" from a concept into verified operating behavior. It matters because Small technical gaps can break search and model consumption even when a site looks polished.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Compare sitemap URLs against crawled indexable URLs.","why":"This step moves \"SEO/AEO evaluation layer\" from a concept into verified operating behavior. It matters because Small technical gaps can break search and model consumption even when a site looks polished.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Check robots, canonicals, titles, descriptions, H1s, and indexability.","why":"This step moves \"SEO/AEO evaluation layer\" from a concept into verified operating behavior. It matters because Small technical gaps can break search and model consumption even when a site looks polished.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Validate schema by page type.","why":"This step moves \"SEO/AEO evaluation layer\" from a concept into verified operating behavior. It matters because Small technical gaps can break search and model consumption even when a site looks polished.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Require llms.txt and llms-full.txt where AEO/AI-search claims exist.","why":"This step moves \"SEO/AEO evaluation layer\" from a concept into verified operating behavior. It matters because Small technical gaps can break search and model consumption even when a site looks polished.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":6,"action":"Classify crawler-visible 403s separately from confirmed broken links.","why":"This step moves \"SEO/AEO evaluation layer\" from a concept into verified operating behavior. It matters because Small technical gaps can break search and model consumption even when a site looks polished.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["SEO/AEO checks produce machine-readable findings.","Findings include severity, why, evidence, and remediation.","The suite distinguishes fail, warning, and manual-verification states."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Run against Nectiv and confirm the known issues are detected.","Run against the local starter build and confirm expected pass state.","Create fixture pages with missing H1/meta/schema and confirm failures are specific."],"objectiveAlignment":"Strengthens the evaluation layer and directly supports launch readiness."},{"id":"source-to-site-traceability-walkthrough","roadmapId":"source-to-site-traceability","priority":5,"title":"Source-to-site traceability","objective":"Track every public claim from raw source to cleaned fact, derived brief, page copy, schema, and QA evidence.","why":"Agents can invent proof, credentials, metrics, pricing, or service scope unless source truth is enforced.","steps":[{"order":1,"action":"Expand source-retention fixtures.","why":"This step moves \"Source-to-site traceability\" from a concept into verified operating behavior. It matters because Agents can invent proof, credentials, metrics, pricing, or service scope unless source truth is enforced.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Create claim objects with source, allowed-use status, public copy, and schema mapping.","why":"This step moves \"Source-to-site traceability\" from a concept into verified operating behavior. It matters because Agents can invent proof, credentials, metrics, pricing, or service scope unless source truth is enforced.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Add page briefs that cite cleaned facts.","why":"This step moves \"Source-to-site traceability\" from a concept into verified operating behavior. It matters because Agents can invent proof, credentials, metrics, pricing, or service scope unless source truth is enforced.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Add QA checks for claim/proof traceability on proof-heavy pages.","why":"This step moves \"Source-to-site traceability\" from a concept into verified operating behavior. It matters because Agents can invent proof, credentials, metrics, pricing, or service scope unless source truth is enforced.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Document privacy and permission boundaries.","why":"This step moves \"Source-to-site traceability\" from a concept into verified operating behavior. It matters because Agents can invent proof, credentials, metrics, pricing, or service scope unless source truth is enforced.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["Every example claim has a source or an explicit placeholder status.","Proof/case-study patterns require source evidence.","Handoff reports include unresolved claim risks."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Insert an unsupported metric into a fixture brief and confirm review catches it.","Ask an agent to build a proof page and confirm it references source facts.","Confirm private/raw data is not surfaced in public outputs."],"objectiveAlignment":"Supports trustworthy buildout and avoids hallucinated website claims."},{"id":"site-type-build-playbooks-walkthrough","roadmapId":"site-type-build-playbooks","priority":6,"title":"Site-type build playbooks","objective":"Create detailed playbooks for local service, B2B SaaS, professional services, ecommerce/product, content hub, proof hub, AI/AEO authority, and agent-facing documentation sites.","why":"A good website pattern changes by business model. A local service site, SaaS site, and proof hub should not share the same page map or schema defaults.","steps":[{"order":1,"action":"Define required pages for each site type.","why":"This step moves \"Site-type build playbooks\" from a concept into verified operating behavior. It matters because A good website pattern changes by business model. A local service site, SaaS site, and proof hub should not share the same page map or schema defaults.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Define schema, metadata, internal-link, proof, and conversion requirements.","why":"This step moves \"Site-type build playbooks\" from a concept into verified operating behavior. It matters because A good website pattern changes by business model. A local service site, SaaS site, and proof hub should not share the same page map or schema defaults.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Map each playbook to examples and QA commands.","why":"This step moves \"Site-type build playbooks\" from a concept into verified operating behavior. It matters because A good website pattern changes by business model. A local service site, SaaS site, and proof hub should not share the same page map or schema defaults.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Add source-input requirements for each site type.","why":"This step moves \"Site-type build playbooks\" from a concept into verified operating behavior. It matters because A good website pattern changes by business model. A local service site, SaaS site, and proof hub should not share the same page map or schema defaults.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Expose playbooks as structured JSON.","why":"This step moves \"Site-type build playbooks\" from a concept into verified operating behavior. It matters because A good website pattern changes by business model. A local service site, SaaS site, and proof hub should not share the same page map or schema defaults.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["Each site type has detailed requirements and rationale.","Each playbook maps to page patterns and QA checks.","Agents can select and justify a playbook."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Ask an agent to choose a playbook from a short business brief.","Confirm the chosen playbook lists pages, schema, source needs, and QA.","Compare two site types and confirm their requirements differ."],"objectiveAlignment":"Moves the execution layer from generic site advice to business-specific build systems."},{"id":"page-pattern-library-walkthrough","roadmapId":"page-pattern-library","priority":7,"title":"Reusable page pattern library","objective":"Define patterns for homepage, service, product/technology, comparison, case study, proof, FAQ, glossary/entity, article, contact, AI instructions, privacy, and security pages.","why":"Most website quality failures happen at page level: wrong heading, wrong schema, missing proof, weak internal links, or unsupported claims.","steps":[{"order":1,"action":"Create a page-pattern data model.","why":"This step moves \"Reusable page pattern library\" from a concept into verified operating behavior. It matters because Most website quality failures happen at page level: wrong heading, wrong schema, missing proof, weak internal links, or unsupported claims.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Define required sections and schema for each page type.","why":"This step moves \"Reusable page pattern library\" from a concept into verified operating behavior. It matters because Most website quality failures happen at page level: wrong heading, wrong schema, missing proof, weak internal links, or unsupported claims.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Add SEO/AEO requirements per page type.","why":"This step moves \"Reusable page pattern library\" from a concept into verified operating behavior. It matters because Most website quality failures happen at page level: wrong heading, wrong schema, missing proof, weak internal links, or unsupported claims.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Add good/bad examples for each pattern.","why":"This step moves \"Reusable page pattern library\" from a concept into verified operating behavior. It matters because Most website quality failures happen at page level: wrong heading, wrong schema, missing proof, weak internal links, or unsupported claims.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Add page-pattern validation hooks where possible.","why":"This step moves \"Reusable page pattern library\" from a concept into verified operating behavior. It matters because Most website quality failures happen at page level: wrong heading, wrong schema, missing proof, weak internal links, or unsupported claims.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["Every core page type has a pattern contract.","Pattern contracts include why, evidence, pass/fail, and examples.","Page patterns are linked from relevant playbooks."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Ask an agent to create a page from a pattern and inspect whether all required sections appear.","Remove a required section from a fixture and confirm QA or review flags it.","Compare visible content against schema facts."],"objectiveAlignment":"Improves build quality by making page creation systematic."},{"id":"browser-visual-qa-walkthrough","roadmapId":"browser-visual-qa","priority":8,"title":"Automated browser and visual QA","objective":"Add browser checks for desktop/mobile rendering, clipping, overlap, navigation, visible headings, and screenshot evidence.","why":"A technically valid site can still fail for users or agents if text clips, controls overlap, or navigation breaks.","steps":[{"order":1,"action":"Create browser test runner scripts.","why":"This step moves \"Automated browser and visual QA\" from a concept into verified operating behavior. It matters because A technically valid site can still fail for users or agents if text clips, controls overlap, or navigation breaks.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Capture desktop and mobile screenshots for core routes.","why":"This step moves \"Automated browser and visual QA\" from a concept into verified operating behavior. It matters because A technically valid site can still fail for users or agents if text clips, controls overlap, or navigation breaks.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Check for visible H1, nav, footer, and primary content.","why":"This step moves \"Automated browser and visual QA\" from a concept into verified operating behavior. It matters because A technically valid site can still fail for users or agents if text clips, controls overlap, or navigation breaks.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Add heuristics for clipped or overlapping text.","why":"This step moves \"Automated browser and visual QA\" from a concept into verified operating behavior. It matters because A technically valid site can still fail for users or agents if text clips, controls overlap, or navigation breaks.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Store screenshots and findings under reports/browser/.","why":"This step moves \"Automated browser and visual QA\" from a concept into verified operating behavior. It matters because A technically valid site can still fail for users or agents if text clips, controls overlap, or navigation breaks.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["Browser QA is repeatable locally.","Screenshots are saved for core routes.","Visual failures produce actionable findings."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Run browser QA at mobile and desktop widths.","Introduce a fixture with clipped text and confirm failure.","Confirm screenshot paths are recorded in handoff evidence."],"objectiveAlignment":"Completes the evaluation layer beyond static crawl and build checks."},{"id":"crawl-evidence-artifacts-walkthrough","roadmapId":"crawl-evidence-artifacts","priority":9,"title":"Crawl evidence as a first-class artifact","objective":"Standardize crawl execution, exports, summaries, and before/after evidence.","why":"Without saved crawl evidence, agents repeatedly rediscover the same issues and cannot prove readiness.","steps":[{"order":1,"action":"Create a crawl report format.","why":"This step moves \"Crawl evidence as a first-class artifact\" from a concept into verified operating behavior. It matters because Without saved crawl evidence, agents repeatedly rediscover the same issues and cannot prove readiness.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Record target, date, settings, exports, findings, and residual risk.","why":"This step moves \"Crawl evidence as a first-class artifact\" from a concept into verified operating behavior. It matters because Without saved crawl evidence, agents repeatedly rediscover the same issues and cannot prove readiness.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Add summary parsers for Screaming Frog exports.","why":"This step moves \"Crawl evidence as a first-class artifact\" from a concept into verified operating behavior. It matters because Without saved crawl evidence, agents repeatedly rediscover the same issues and cannot prove readiness.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Add before/after comparison guidance.","why":"This step moves \"Crawl evidence as a first-class artifact\" from a concept into verified operating behavior. It matters because Without saved crawl evidence, agents repeatedly rediscover the same issues and cannot prove readiness.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Link crawl artifacts from handoff reports.","why":"This step moves \"Crawl evidence as a first-class artifact\" from a concept into verified operating behavior. It matters because Without saved crawl evidence, agents repeatedly rediscover the same issues and cannot prove readiness.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["Crawl evidence has a standard path and summary shape.","Critical crawl findings are machine-readable.","Handoff reports cite crawl evidence."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Run a crawl and verify required exports exist.","Parse crawl overview into structured findings.","Confirm a missing export fails the report completeness check."],"objectiveAlignment":"Improves evaluation and source-of-truth continuity."},{"id":"agent-backlog-intelligence-walkthrough","roadmapId":"agent-backlog-intelligence","priority":10,"title":"Agent backlog intelligence","objective":"Turn /agent-tasks.json into a serious execution queue with priority, rationale, dependencies, acceptance criteria, risks, and evidence links.","why":"The system should always explain what remains incomplete and how to improve it safely.","steps":[{"order":1,"action":"Expand task fields beyond title/status.","why":"This step moves \"Agent backlog intelligence\" from a concept into verified operating behavior. It matters because The system should always explain what remains incomplete and how to improve it safely.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Add dependencies, risk, evidence, and expected output.","why":"This step moves \"Agent backlog intelligence\" from a concept into verified operating behavior. It matters because The system should always explain what remains incomplete and how to improve it safely.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Map tasks to roadmap items.","why":"This step moves \"Agent backlog intelligence\" from a concept into verified operating behavior. It matters because The system should always explain what remains incomplete and how to improve it safely.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Add task validation to QA.","why":"This step moves \"Agent backlog intelligence\" from a concept into verified operating behavior. It matters because The system should always explain what remains incomplete and how to improve it safely.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Add completed-task evidence links.","why":"This step moves \"Agent backlog intelligence\" from a concept into verified operating behavior. It matters because The system should always explain what remains incomplete and how to improve it safely.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["Every task has enough detail to execute.","Backlog ordering reflects product priorities.","Completed tasks include evidence."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Ask an agent to choose the next task and justify the choice.","Confirm every task maps to a roadmap item.","Confirm no high-priority task lacks acceptance criteria."],"objectiveAlignment":"Supports continuous improvement without hidden open loops."},{"id":"design-system-contracts-walkthrough","roadmapId":"design-system-contracts","priority":11,"title":"Design system contracts","objective":"Define design tokens, component rules, layout standards, accessibility constraints, and screenshot pass/fail criteria.","why":"Design work should improve clarity and usability without breaking the agent-readable technical surface.","steps":[{"order":1,"action":"Create design principles tied to site purpose.","why":"This step moves \"Design system contracts\" from a concept into verified operating behavior. It matters because Design work should improve clarity and usability without breaking the agent-readable technical surface.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Define tokens for typography, spacing, color, and layout.","why":"This step moves \"Design system contracts\" from a concept into verified operating behavior. It matters because Design work should improve clarity and usability without breaking the agent-readable technical surface.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Define component usage rules.","why":"This step moves \"Design system contracts\" from a concept into verified operating behavior. It matters because Design work should improve clarity and usability without breaking the agent-readable technical surface.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Add responsive behavior requirements.","why":"This step moves \"Design system contracts\" from a concept into verified operating behavior. It matters because Design work should improve clarity and usability without breaking the agent-readable technical surface.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Validate screenshots after visual changes.","why":"This step moves \"Design system contracts\" from a concept into verified operating behavior. It matters because Design work should improve clarity and usability without breaking the agent-readable technical surface.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["Design rules are documented and structured.","Components have usage guidance.","Visual QA passes after design changes."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Apply design changes and confirm agent pages remain readable.","Check mobile and desktop screenshots.","Confirm UI changes do not hide machine endpoint discovery."],"objectiveAlignment":"Adds polish only after the technical operating system remains intact."},{"id":"aeo-geo-model-context-walkthrough","roadmapId":"aeo-geo-model-context","priority":12,"title":"AEO/GEO model context","objective":"Standardize model-readable context: AI instructions, LLM files, entity summaries, answer-ready sections, tables, FAQs, schema maps, and source-backed facts.","why":"AEO/GEO work requires explicit context surfaces, not only traditional HTML pages.","steps":[{"order":1,"action":"Define AI instructions page pattern.","why":"This step moves \"AEO/GEO model context\" from a concept into verified operating behavior. It matters because AEO/GEO work requires explicit context surfaces, not only traditional HTML pages.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Enhance llms.txt and llms-full.txt requirements.","why":"This step moves \"AEO/GEO model context\" from a concept into verified operating behavior. It matters because AEO/GEO work requires explicit context surfaces, not only traditional HTML pages.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Add entity-summary and answer-ready content rules.","why":"This step moves \"AEO/GEO model context\" from a concept into verified operating behavior. It matters because AEO/GEO work requires explicit context surfaces, not only traditional HTML pages.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Add table/FAQ/schema guidance for citation-worthy facts.","why":"This step moves \"AEO/GEO model context\" from a concept into verified operating behavior. It matters because AEO/GEO work requires explicit context surfaces, not only traditional HTML pages.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Compare model-readable context against visible content.","why":"This step moves \"AEO/GEO model context\" from a concept into verified operating behavior. It matters because AEO/GEO work requires explicit context surfaces, not only traditional HTML pages.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["AEO pages expose direct answers and source-backed facts.","LLM endpoints are complete and current.","Agent-facing pages are treated as first-class SEO assets."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Ask an agent to summarize the site from LLM endpoints only.","Confirm model-readable facts match visible source-backed facts.","Run a missing-LLM-endpoint fixture and confirm failure."],"objectiveAlignment":"Strengthens the agent-readiness and answer-engine layer."},{"id":"why-explanations-everywhere-walkthrough","roadmapId":"why-explanations-everywhere","priority":13,"title":"Why explanations everywhere","objective":"Attach rationale to every checklist item, QA finding, roadmap task, and page pattern requirement.","why":"Agents are more reliable when they understand why a step exists and what breaks if it is skipped.","steps":[{"order":1,"action":"Audit existing checks for missing rationale.","why":"This step moves \"Why explanations everywhere\" from a concept into verified operating behavior. It matters because Agents are more reliable when they understand why a step exists and what breaks if it is skipped.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Add why fields to tasks, playbooks, page patterns, and QA findings.","why":"This step moves \"Why explanations everywhere\" from a concept into verified operating behavior. It matters because Agents are more reliable when they understand why a step exists and what breaks if it is skipped.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Document failure modes beside each check.","why":"This step moves \"Why explanations everywhere\" from a concept into verified operating behavior. It matters because Agents are more reliable when they understand why a step exists and what breaks if it is skipped.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Add schema validation for required rationale fields.","why":"This step moves \"Why explanations everywhere\" from a concept into verified operating behavior. It matters because Agents are more reliable when they understand why a step exists and what breaks if it is skipped.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Use Nectiv examples to show why small technical gaps matter.","why":"This step moves \"Why explanations everywhere\" from a concept into verified operating behavior. It matters because Agents are more reliable when they understand why a step exists and what breaks if it is skipped.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["No major requirement is rationale-free.","Machine endpoints expose why fields.","Reports explain impact, not just status."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Remove a rationale field and confirm schema/QA catches it.","Ask an agent why a check exists and confirm it can answer from the manifest.","Confirm final reports include why for major findings."],"objectiveAlignment":"Supports the detailed walkthrough rule and makes the system teach, not merely assert."},{"id":"real-site-comparisons-walkthrough","roadmapId":"real-site-comparisons","priority":14,"title":"Comparison against real sites","objective":"Create repeatable site-study workflows for excellent, average, and poor websites across categories.","why":"The operating system should learn from real-world SEO/AEO patterns rather than staying theoretical.","steps":[{"order":1,"action":"Define site-study intake process.","why":"This step moves \"Comparison against real sites\" from a concept into verified operating behavior. It matters because The operating system should learn from real-world SEO/AEO patterns rather than staying theoretical.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Crawl and inspect each target.","why":"This step moves \"Comparison against real sites\" from a concept into verified operating behavior. It matters because The operating system should learn from real-world SEO/AEO patterns rather than staying theoretical.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Classify good patterns and failure modes.","why":"This step moves \"Comparison against real sites\" from a concept into verified operating behavior. It matters because The operating system should learn from real-world SEO/AEO patterns rather than staying theoretical.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Convert findings into roadmap tasks or QA checks.","why":"This step moves \"Comparison against real sites\" from a concept into verified operating behavior. It matters because The operating system should learn from real-world SEO/AEO patterns rather than staying theoretical.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Maintain a site-study index.","why":"This step moves \"Comparison against real sites\" from a concept into verified operating behavior. It matters because The operating system should learn from real-world SEO/AEO patterns rather than staying theoretical.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["Every site study has evidence, analysis, and extracted lessons.","Studies feed the roadmap or examples library.","Agents can compare patterns across studies."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Run the workflow on Nectiv and at least one contrasting weak site.","Confirm each study produces reusable checks.","Confirm study evidence is saved and discoverable."],"objectiveAlignment":"Keeps the reference layer grounded in live market examples."},{"id":"handoff-reports-walkthrough","roadmapId":"handoff-reports","priority":15,"title":"Handoff reports","objective":"Create a standard final report format for builds, audits, fixes, verification, residual risks, and next steps.","why":"Without a handoff artifact, future agents lose context and users cannot judge readiness.","steps":[{"order":1,"action":"Define handoff report schema.","why":"This step moves \"Handoff reports\" from a concept into verified operating behavior. It matters because Without a handoff artifact, future agents lose context and users cannot judge readiness.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":2,"action":"Include changed files, verification, crawl/browser evidence, unresolved risks, and next tasks.","why":"This step moves \"Handoff reports\" from a concept into verified operating behavior. It matters because Without a handoff artifact, future agents lose context and users cannot judge readiness.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":3,"action":"Add templates for audit-only, buildout, launch, and fix reports.","why":"This step moves \"Handoff reports\" from a concept into verified operating behavior. It matters because Without a handoff artifact, future agents lose context and users cannot judge readiness.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":4,"action":"Link handoff reports from agent tasks.","why":"This step moves \"Handoff reports\" from a concept into verified operating behavior. It matters because Without a handoff artifact, future agents lose context and users cannot judge readiness.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]},{"order":5,"action":"Validate report completeness before ready state.","why":"This step moves \"Handoff reports\" from a concept into verified operating behavior. It matters because Without a handoff artifact, future agents lose context and users cannot judge readiness.","filesOrRoutes":["src/data/agent-reference.ts","/agent-manifest.json","/product-roadmap.json","/agent-tasks.json","docs/product-roadmap.md","docs/system-purpose.md"],"evidence":["Updated structured data or implementation files.","QA output proving the contract still passes.","Saved report, fixture, screenshot, crawl export, or handoff artifact when the step creates operational evidence."]}],"evidenceToCollect":["Changed files or generated endpoint output.","Relevant QA command output.","Stress-test notes or report artifacts.","Comparison back to docs/system-purpose.md."],"passCriteria":["Every substantial task can produce a standard handoff.","Reports include evidence and residual risk.","Future agents can resume from the report."],"warningCriteria":["The concept exists only in prose and is not exposed through a machine-readable endpoint.","The implementation has no saved evidence path.","The work passes narrow checks but has not been compared back to the system purpose."],"failCriteria":["The roadmap item has no objective, why, steps, evidence, or acceptance criteria.","A future agent cannot discover the work from the main URL, manifest, or file map.","The implementation cannot be verified by QA, crawl evidence, browser evidence, fixture evidence, or a handoff report."],"stressTests":["Generate a handoff after a crawl audit.","Generate a handoff after a site build fixture.","Confirm missing evidence or unresolved risk is visible."],"objectiveAlignment":"Completes the operating loop: inspect, build, validate, and hand off."}],"start_url":"https://agents.valyou.solutions","intended_audience":"agents","human_marketing_site":false,"core_pages":[{"title":"Agent Start","path":"/agent-start/","description":"Entry route for agents: what this repo is, how to inspect it, and the fastest path to competence."},{"title":"Repo Map","path":"/repo-map/","description":"Human-readable and machine-oriented map of source files, generated endpoints, docs, data, and QA evidence."},{"title":"Standards","path":"/standards/","description":"Website Specification category map translated into implementation responsibilities for this starter."},{"title":"Workflows","path":"/workflows/","description":"Step-by-step workflows for adapting, validating, crawling, and handing off a serious website."},{"title":"Examples","path":"/examples/","description":"Pattern examples agents can reuse for local service, B2B SaaS, professional services, proof, and FAQ pages."},{"title":"Copy Lab","path":"/copy-lab/","description":"Conversion copy principles, good/bad examples, source boundaries, and agent workflow based on public offer/copy pattern study."},{"title":"Page Pattern Fixtures","path":"/fixtures/page-patterns/","description":"Concrete route fixtures that turn page-pattern contracts into inspectable Astro pages with metadata, schema, traceability, and QA expectations."},{"title":"Design System Fixtures","path":"/fixtures/design-system/","description":"Concrete design-system fixtures for endpoint rows, QA command blocks, evidence cards, pattern tables, and status badges."},{"title":"QA Contract","path":"/qa-contract/","description":"Executable quality contract behind qa:routes, qa:seo, qa:aeo, and qa:all."}],"machine_endpoints":[{"path":"/agent-manifest.json","purpose":"Top-level machine-readable index of pages, files, standards, workflows, examples, and QA commands."},{"path":"/file-map.json","purpose":"Structured map of important source files and generated endpoints."},{"path":"/qa-contract.json","purpose":"Machine-readable definition of route, SEO, AEO, build, and crawl expectations."},{"path":"/examples.json","purpose":"Structured example pattern catalog."},{"path":"/agent-tasks.json","purpose":"Structured future-agent backlog for improving this reference before real implementation work."},{"path":"/product-roadmap.json","purpose":"Structured product roadmap for executing every value multiplier to completion."},{"path":"/walkthroughs.json","purpose":"Step-by-step execution walkthroughs for every roadmap value multiplier."},{"path":"/contract-registry.json","purpose":"Formal registry of JSON contracts, schemas, source owners, validation evidence, and failure modes."},{"path":"/site-studies.json","purpose":"Structured good/bad real-site studies with audit evidence and agent checks."},{"path":"/seo-aeo-evaluation.json","purpose":"Structured SEO/AEO evaluation checks, proof commands, evidence expectations, and automation status."},{"path":"/source-traceability.json","purpose":"Structured source-to-site claim ledger, artifact chain, and proof policy."},{"path":"/site-type-playbooks.json","purpose":"Structured build playbooks for local service, SaaS, professional services, proof, and answer-ready resource sites."},{"path":"/page-patterns.json","purpose":"Structured reusable page-pattern contracts for service, proof, resource, contact, home, and schema-backed pages."},{"path":"/page-pattern-fixtures.json","purpose":"Structured route fixture inventory proving each page-pattern contract can drive an actual Astro route."},{"path":"/conversion-copy.json","purpose":"Structured conversion copy system with principles, copy types, good/bad examples, source boundaries, workflow, and QA gates."},{"path":"/offer-ecosystem.json","purpose":"Structured offer-ecosystem funnel contract for AI tools, communities, workshops, playbooks, pricing tiers, qualification gates, referrals, and disclaimers."},{"path":"/infrastructure-decisions.json","purpose":"Structured infrastructure decision system for hosting, rendering, CMS, data, auth, media, search, analytics, forms, payments, DNS/CDN, observability, and deployment tiers."},{"path":"/browser-visual-qa.json","purpose":"Structured browser visual QA contract for screenshots, viewports, layout checks, and report evidence."},{"path":"/crawl-evidence.json","purpose":"Structured crawl evidence contract for Screaming Frog exports, summary reports, and readiness criteria."},{"path":"/design-system-contracts.json","purpose":"Structured design-system contract for tokens, components, accessibility, anti-patterns, QA gates, and stress tests."},{"path":"/aeo-geo-context.json","purpose":"Structured AEO/GEO model context contract for answer-engine prompts, citations, source boundaries, and stress tests."},{"path":"/why-explanations.json","purpose":"Structured rationale contract for where explanations, tradeoffs, evidence, and failure modes are required."},{"path":"/real-site-comparisons.json","purpose":"Structured real-site comparison contract for reference studies, scoring dimensions, evidence, and follow-up tasks."},{"path":"/handoff-reports.json","purpose":"Structured handoff report contract for final evidence, risks, next actions, and closeout records."},{"path":"/agent-index.json","purpose":"Lightweight orientation index (reading order plus endpoint list) for token-constrained agents; the cheapest complete index."},{"path":"/evidence/index.json","purpose":"Published QA evidence index from the latest accepted run; every entry links a live report artifact."},{"path":"/accessibility-contract.json","purpose":"WCAG 2.2 AA accessibility contract: value rules, enforcement method, manual checklist, anti-patterns."},{"path":"/performance-budgets.json","purpose":"Core Web Vitals targets, asset budgets, page rules, and measurement method enforced by qa:perf."},{"path":"/demo-build.json","purpose":"Canonical demo build record: fictional source chain, playbook execution, pages, claims, and QA gates."},{"path":"/demo/brightline/schema.json","purpose":"Machine-readable schema facts for the fictional local-service demo with claim IDs."},{"path":"/demo/logpilot/schema.json","purpose":"Machine-readable schema facts for the fictional B2B SaaS demo with claim IDs."},{"path":"/llms.txt","purpose":"Concise LLM entry point."},{"path":"/llms-full.txt","purpose":"Longer LLM-readable repo and site summary."},{"path":"/schemamap.xml","purpose":"Schema endpoint discovery map."},{"path":"/sitemap.xml","purpose":"Indexable route discovery."},{"path":"/robots.txt","purpose":"Crawler and AI-use policy hints."},{"path":"/schemas/agent-manifest.schema.json","purpose":"JSON Schema for /agent-manifest.json."},{"path":"/schemas/file-map.schema.json","purpose":"JSON Schema for /file-map.json."},{"path":"/schemas/qa-contract.schema.json","purpose":"JSON Schema for /qa-contract.json."},{"path":"/schemas/examples.schema.json","purpose":"JSON Schema for /examples.json."},{"path":"/schemas/agent-tasks.schema.json","purpose":"JSON Schema for /agent-tasks.json."},{"path":"/schemas/product-roadmap.schema.json","purpose":"JSON Schema for /product-roadmap.json."},{"path":"/schemas/walkthroughs.schema.json","purpose":"JSON Schema for /walkthroughs.json."},{"path":"/schemas/contract-registry.schema.json","purpose":"JSON Schema for /contract-registry.json."},{"path":"/schemas/site-studies.schema.json","purpose":"JSON Schema for /site-studies.json."},{"path":"/schemas/seo-aeo-evaluation.schema.json","purpose":"JSON Schema for /seo-aeo-evaluation.json."},{"path":"/schemas/source-traceability.schema.json","purpose":"JSON Schema for /source-traceability.json."},{"path":"/schemas/site-type-playbooks.schema.json","purpose":"JSON Schema for /site-type-playbooks.json."},{"path":"/schemas/page-patterns.schema.json","purpose":"JSON Schema for /page-patterns.json."},{"path":"/schemas/page-pattern-fixtures.schema.json","purpose":"JSON Schema for /page-pattern-fixtures.json."},{"path":"/schemas/conversion-copy.schema.json","purpose":"JSON Schema for /conversion-copy.json."},{"path":"/schemas/offer-ecosystem.schema.json","purpose":"JSON Schema for /offer-ecosystem.json."},{"path":"/schemas/infrastructure-decisions.schema.json","purpose":"JSON Schema for /infrastructure-decisions.json."},{"path":"/schemas/browser-visual-qa.schema.json","purpose":"JSON Schema for /browser-visual-qa.json."},{"path":"/schemas/crawl-evidence.schema.json","purpose":"JSON Schema for /crawl-evidence.json."},{"path":"/schemas/design-system-contracts.schema.json","purpose":"JSON Schema for /design-system-contracts.json."},{"path":"/schemas/aeo-geo-context.schema.json","purpose":"JSON Schema for /aeo-geo-context.json."},{"path":"/schemas/why-explanations.schema.json","purpose":"JSON Schema for /why-explanations.json."},{"path":"/schemas/real-site-comparisons.schema.json","purpose":"JSON Schema for /real-site-comparisons.json."},{"path":"/schemas/handoff-reports.schema.json","purpose":"JSON Schema for /handoff-reports.json."},{"path":"/schemas/demo-build.schema.json","purpose":"JSON Schema for /demo-build.json."},{"path":"/schemas/performance-budgets.schema.json","purpose":"JSON Schema for /performance-budgets.json."},{"path":"/schemas/accessibility-contract.schema.json","purpose":"JSON Schema for /accessibility-contract.json."},{"path":"/schemas/evidence-index.schema.json","purpose":"JSON Schema for /evidence/index.json."},{"path":"/schemas/agent-index.schema.json","purpose":"JSON Schema for /agent-index.json."}],"repo_files":[{"group":"Agent orientation","files":[{"path":"AGENTS.md","purpose":"Non-negotiable repo rules for future agents."},{"path":"docs/system-purpose.md","purpose":"North-star definition of what this system is, is not, and must prove."},{"path":"docs/product-roadmap.md","purpose":"Priority-ordered product roadmap for executing every value multiplier."},{"path":"docs/site-expansion-execution-track.md","purpose":"Durable execution track for filling out the site with studies, fixtures, infrastructure, design, copy, simulations, stress tests, docs, and demo builds."},{"path":"docs/agent-playbook.md","purpose":"Full adaptation workflow and definition of done."},{"path":"docs/deployment-runbook.md","purpose":"Gated Cloudflare Pages deployment path: required decisions, deploy sequence, and post-deploy production evidence."},{"path":"deploy.sh","purpose":"Guarded deploy script; refuses to run without explicit confirmation, account ID, Pages project, and canonical URL."},{"path":"README.md","purpose":"Human-readable starter overview and command list."}]},{"group":"Site identity and routing","files":[{"path":"src/site.config.ts","purpose":"Site name, URL, contact data, address, social profiles, and AI policy."},{"path":"src/data/navigation.ts","purpose":"Primary navigation."},{"path":"src/data/agent-reference.ts","purpose":"Agent-facing pages, machine endpoints, examples, QA contract, workflows, and file map."},{"path":"astro.config.mjs","purpose":"Astro config, site URL, and trailing slash behavior."}]},{"group":"Machine-readable endpoints","files":[{"path":"src/pages/agent-manifest.json.ts","purpose":"Structured agent entry manifest."},{"path":"src/pages/file-map.json.ts","purpose":"Structured repo file map."},{"path":"src/pages/qa-contract.json.ts","purpose":"Structured quality contract."},{"path":"src/pages/examples.json.ts","purpose":"Structured examples catalog."},{"path":"src/pages/agent-tasks.json.ts","purpose":"Structured future-agent backlog."},{"path":"src/pages/product-roadmap.json.ts","purpose":"Structured product roadmap endpoint."},{"path":"src/pages/walkthroughs.json.ts","purpose":"Structured step-by-step walkthrough endpoint."},{"path":"src/pages/contract-registry.json.ts","purpose":"Formal JSON contract registry endpoint."},{"path":"src/pages/site-studies.json.ts","purpose":"Structured real-site study endpoint."},{"path":"src/pages/seo-aeo-evaluation.json.ts","purpose":"Structured SEO/AEO evaluation endpoint."},{"path":"src/pages/source-traceability.json.ts","purpose":"Structured source-to-site traceability endpoint."},{"path":"src/pages/site-type-playbooks.json.ts","purpose":"Structured site-type build playbook endpoint."},{"path":"src/pages/page-patterns.json.ts","purpose":"Structured reusable page-pattern endpoint."},{"path":"src/pages/page-pattern-fixtures.json.ts","purpose":"Structured inventory of concrete page-pattern fixture routes."},{"path":"src/pages/fixtures/design-system/","purpose":"Concrete design-system fixture routes for agent-operable UI patterns."},{"path":"src/pages/conversion-copy.json.ts","purpose":"Structured conversion copy system endpoint."},{"path":"src/pages/offer-ecosystem.json.ts","purpose":"Structured offer-ecosystem funnel endpoint."},{"path":"src/pages/infrastructure-decisions.json.ts","purpose":"Structured infrastructure decision system endpoint."},{"path":"src/pages/browser-visual-qa.json.ts","purpose":"Structured browser visual QA contract endpoint."},{"path":"src/pages/crawl-evidence.json.ts","purpose":"Structured crawl evidence contract endpoint."},{"path":"src/pages/design-system-contracts.json.ts","purpose":"Structured design-system contract endpoint."},{"path":"src/pages/aeo-geo-context.json.ts","purpose":"Structured AEO/GEO model context contract endpoint."},{"path":"src/pages/why-explanations.json.ts","purpose":"Structured why-explanations contract endpoint."},{"path":"src/pages/real-site-comparisons.json.ts","purpose":"Structured real-site comparison contract endpoint."},{"path":"src/pages/handoff-reports.json.ts","purpose":"Structured handoff report contract endpoint."},{"path":"src/pages/llms.txt.ts","purpose":"Concise LLM index."},{"path":"src/pages/llms-full.txt.ts","purpose":"Expanded LLM summary."},{"path":"src/pages/sitemap.xml.ts","purpose":"Sitemap generation."},{"path":"src/pages/schemamap.xml.ts","purpose":"Schema discovery map."},{"path":"src/pages/robots.txt.ts","purpose":"Crawler policy."}]},{"group":"Quality automation","files":[{"path":"scripts/spec-audit.mjs","purpose":"Static required-file audit."},{"path":"scripts/qa-routes.mjs","purpose":"Route, link, and sitemap checks."},{"path":"scripts/qa-seo.mjs","purpose":"Metadata, canonical, H1, OG, and JSON-LD checks."},{"path":"scripts/qa-aeo.mjs","purpose":"LLM endpoint, schema endpoint, and AEO contract checks."},{"path":"scripts/qa-browser.mjs","purpose":"Browser screenshot, viewport overflow, visible H1, accessibility heuristic, and visual report checks."},{"path":"scripts/qa-crawl.mjs","purpose":"Screaming Frog CSV export summarizer and crawl evidence report checks."},{"path":"scripts/qa-copy-stress.mjs","purpose":"Stress tests weak-to-stronger conversion copy transformations against the copy contract."},{"path":"scripts/qa-page-pattern-fixtures.mjs","purpose":"Stress tests concrete page-pattern fixture routes, section coverage, pattern mapping, and report evidence."},{"path":"scripts/qa-playbook-simulation.mjs","purpose":"Stress tests every site-type playbook with simulated builds and negative controls for inputs, patterns, schema, claims, QA gates, and risk honesty."},{"path":"scripts/qa-crawl-stress.mjs","purpose":"License-free static-export crawler enforcing link health, redirect budgets, sitemap reachability, and response budgets with synthetic negative controls."},{"path":"scripts/publish-evidence.mjs","purpose":"Publishes the latest accepted QA reports to public/evidence/ with workstation paths redacted."},{"path":"scripts/qa-performance.mjs","purpose":"Measures local LCP/CLS per route via Playwright and enforces asset budgets and page rules with negative controls."},{"path":"scripts/qa-demo-build.mjs","purpose":"Validates the canonical demo build against its playbook, simulation record, claim ledger, schema requirements, and blocked phrases with negative controls."},{"path":"scripts/qa-agent-simulation.mjs","purpose":"Simulates future-agent use from the main URL and saves scenario evidence."},{"path":"scripts/qa-contract-drift.mjs","purpose":"Runs live contract checks plus negative drift fixtures for endpoints, schemas, sources, and evidence."},{"path":"scripts/qa-domain.mjs","purpose":"Checks local static route readiness and optional production domain variants via QA_PRODUCTION_URL."},{"path":"scripts/qa-handoff.mjs","purpose":"Generates a current handoff report from QA, contract, crawl, browser, domain, and agent-simulation evidence."},{"path":"scripts/qa-nectiv-lessons.mjs","purpose":"Turns Nectiv-derived SEO/AEO lessons into dedicated local guardrail checks and production-evidence warnings."},{"path":"scripts/qa-common.mjs","purpose":"Shared static server and parsing helpers for QA scripts."}]},{"group":"Source retention","files":[{"path":"data/sources/raw/","purpose":"Immutable raw source archive."},{"path":"data/sources/manifests/","purpose":"Source manifests and provenance notes."},{"path":"data/working/","purpose":"Cleaned or transformed source material."},{"path":"data/derived/","purpose":"Generated briefs, summaries, copy, and QA outputs."},{"path":"data/sources/manifests/example-client-discovery.md","purpose":"Example source manifest for a fictional site build."},{"path":"data/working/example-client-facts.json","purpose":"Example cleaned public-safe fact set derived from raw inputs."},{"path":"data/derived/example-page-brief.json","purpose":"Example page brief connecting source facts to page, schema, SEO, and AEO requirements."},{"path":"data/derived/example-crawl-export/","purpose":"Example Screaming Frog-style crawl exports used by qa:crawl."},{"path":"data/derived/aeo-geo-context/","purpose":"Example prompt and answer-evidence fixtures for AEO/GEO model context checks."},{"path":"data/derived/copy-stress/copy-stress-fixtures.json","purpose":"Weak-to-stronger copy stress fixtures used by qa:copy."},{"path":"data/derived/playbook-simulations/playbook-simulation-fixtures.json","purpose":"Fictional simulated build fixtures for every site-type playbook used by qa:playbooks."},{"path":"data/sources/manifests/demo-brightline-gutter-discovery.md","purpose":"Fictional source manifest for the canonical demo build."},{"path":"data/working/demo-brightline-facts.json","purpose":"Cleaned fictional facts and blocked claims for the canonical demo build."},{"path":"data/derived/demo-brightline-page-brief.json","purpose":"Page brief connecting demo facts to routes, patterns, schema, claims, and QA gates."},{"path":"src/pages/demo/brightline/","purpose":"Canonical demo routes: a fictional local-service site executing the local service playbook end to end."},{"path":"src/pages/demo/logpilot/","purpose":"Second canonical demo: a fictional B2B SaaS site executing the B2B SaaS playbook with its own brand tokens."},{"path":"data/sources/manifests/demo-logpilot-discovery.md","purpose":"Fictional source manifest for the SaaS demo build."},{"path":"data/working/demo-logpilot-facts.json","purpose":"Cleaned fictional facts and blocked claims for the SaaS demo build."},{"path":"data/derived/demo-logpilot-page-brief.json","purpose":"Page brief for the SaaS demo build."},{"path":"reports/demo/","purpose":"Generated canonical demo build QA evidence."},{"path":"reports/performance/","purpose":"Generated performance budget and Core Web Vitals measurement evidence."},{"path":"data/sources/manifests/hormozi-conversion-copy-study-2026-06-06.md","purpose":"Public source-study manifest for conversion copy patterns inspired by Alex Hormozi and Acquisition.com."},{"path":"reports/browser/","purpose":"Generated browser QA screenshots, visual diff images, and layout/keyboard/accessibility report."},{"path":"tests/browser/baselines/","purpose":"Committed screenshot baselines for visual diff; update intentionally with QA_UPDATE_BASELINES=1 npm run qa:browser."},{"path":"reports/crawl/","purpose":"Generated crawl evidence reports and saved crawl summaries."},{"path":"reports/seo-aeo/","purpose":"Generated SEO/AEO guardrail reports, including Nectiv-derived lesson checks."},{"path":"reports/agent-simulation/","purpose":"Generated future-agent simulation evidence from main URL scenarios."},{"path":"reports/contracts/","purpose":"Generated contract drift and negative-fixture evidence."},{"path":"reports/copy-stress/","purpose":"Generated copy stress-test evidence."},{"path":"reports/page-pattern-fixtures/","purpose":"Generated page-pattern fixture route stress-test evidence."},{"path":"reports/playbooks/","purpose":"Generated site-type playbook simulated-build stress-test evidence."},{"path":"reports/domain/","purpose":"Generated static route and optional production domain evidence."},{"path":"reports/handoff/example-handoff-report.json","purpose":"Example handoff report fixture for final closeout evidence."},{"path":"reports/handoff/generated-handoff-report.json","purpose":"Generated current handoff report from the latest QA evidence."}]},{"group":"Contract schemas","files":[{"path":"public/schemas/agent-manifest.schema.json","purpose":"Validates the top-level agent manifest shape."},{"path":"public/schemas/file-map.schema.json","purpose":"Validates file-map groups and paths."},{"path":"public/schemas/qa-contract.schema.json","purpose":"Validates QA command contract."},{"path":"public/schemas/examples.schema.json","purpose":"Validates reusable example blueprints."},{"path":"public/schemas/agent-tasks.schema.json","purpose":"Validates future-agent backlog items."},{"path":"public/schemas/product-roadmap.schema.json","purpose":"Validates product roadmap items."},{"path":"public/schemas/walkthroughs.schema.json","purpose":"Validates roadmap walkthrough items."},{"path":"public/schemas/contract-registry.schema.json","purpose":"Validates the formal contract registry."},{"path":"public/schemas/site-studies.schema.json","purpose":"Validates real-site study items."},{"path":"public/schemas/seo-aeo-evaluation.schema.json","purpose":"Validates SEO/AEO evaluation checks."},{"path":"public/schemas/source-traceability.schema.json","purpose":"Validates source-to-site traceability records."},{"path":"public/schemas/site-type-playbooks.schema.json","purpose":"Validates site-type build playbooks."},{"path":"public/schemas/page-patterns.schema.json","purpose":"Validates reusable page patterns."},{"path":"public/schemas/page-pattern-fixtures.schema.json","purpose":"Validates concrete page-pattern route fixtures."},{"path":"public/schemas/conversion-copy.schema.json","purpose":"Validates conversion copy system."},{"path":"public/schemas/offer-ecosystem.schema.json","purpose":"Validates offer-ecosystem funnel system."},{"path":"public/schemas/infrastructure-decisions.schema.json","purpose":"Validates infrastructure decision system."},{"path":"public/schemas/browser-visual-qa.schema.json","purpose":"Validates browser visual QA contract."},{"path":"public/schemas/crawl-evidence.schema.json","purpose":"Validates crawl evidence contract."},{"path":"public/schemas/design-system-contracts.schema.json","purpose":"Validates design-system contract."},{"path":"public/schemas/aeo-geo-context.schema.json","purpose":"Validates AEO/GEO model context contract."},{"path":"public/schemas/why-explanations.schema.json","purpose":"Validates why-explanations contract."},{"path":"public/schemas/real-site-comparisons.schema.json","purpose":"Validates real-site comparison contract."},{"path":"public/schemas/handoff-reports.schema.json","purpose":"Validates handoff report contract."}]}],"standards":[{"category":"Foundations","implementation":"Stable pages, titles, descriptions, canonicals, favicon, social image, and clear route ownership."},{"category":"SEO","implementation":"Sitemap, robots, canonical URLs, unique metadata, one H1, internal links, schema, and crawl evidence."},{"category":"Accessibility","implementation":"Semantic landmarks, skip link, focus styles, contrast, keyboard-safe controls, and no clipped mobile text."},{"category":"Security","implementation":"Static host headers, security.txt, no secrets, no unsafe external scripts by default."},{"category":"Well-Known URIs","implementation":"security.txt plus only relevant well-known endpoints."},{"category":"Agent Readiness","implementation":"llms.txt, llms-full.txt, schemamap.xml, schema JSON endpoints, file-map.json, qa-contract.json, examples.json, contract-registry.json, site-studies.json, seo-aeo-evaluation.json, source-traceability.json, site-type-playbooks.json, page-patterns.json, page-pattern-fixtures.json, conversion-copy.json, offer-ecosystem.json, infrastructure-decisions.json, browser-visual-qa.json, crawl-evidence.json, design-system-contracts.json, aeo-geo-context.json, why-explanations.json, real-site-comparisons.json, handoff-reports.json."},{"category":"Performance","implementation":"Static output, minimal JavaScript, stable dimensions, local assets, and crawlable HTML-first pages."},{"category":"Privacy","implementation":"Privacy page placeholder, no analytics by default, source separation, no private data in public outputs."},{"category":"Resilience","implementation":"404 page, direct internal links, no internal redirects, route tests, and crawl evidence."},{"category":"Internationalisation","implementation":"html lang, locale config, and documented future hreflang expansion point."}],"workflows":[{"id":"agent-orientation","name":"Agent orientation","trigger":"A future agent receives only the main URL and needs to understand the website and repo.","inputs":["Main URL","/agent-manifest.json","/file-map.json","AGENTS.md","docs/agent-playbook.md"],"outputs":["Context summary","Relevant source-file list","QA command plan"],"steps":["Open the main URL.","Read /agent-manifest.json.","Read AGENTS.md and docs/agent-playbook.md.","Read /file-map.json to identify source files and generated outputs.","Run npm run qa:all before changing behavior."],"completionCriteria":["Agent can describe repo purpose without chat context","Agent can identify canonical data and QA files","Agent knows which command proves baseline health"]},{"id":"new-local-service-site","name":"Adapt this starter to a real site","trigger":"A business site needs to be created from source evidence.","inputs":["Public-safe business facts","Raw source archive","Brand assets","Target PUBLIC_SITE_URL"],"outputs":["Configured site","Updated machine endpoints","Source manifest","QA evidence"],"steps":["Preserve raw inputs in data/sources/raw/ and write a manifest.","Update src/site.config.ts and PUBLIC_SITE_URL.","Replace placeholder pages with public-safe content.","Update page schema endpoints and schemamap.xml entries together.","Update llms.txt, llms-full.txt, sitemap.xml, and navigation.","Run npm run qa:all, then browser and crawl QA."],"completionCriteria":["No placeholder identity remains","Every public claim traces to source or approved brief","qa:all passes","Crawl/browser evidence is recorded"]},{"id":"new-page-pattern","name":"Create a new page pattern","trigger":"A site needs a new reusable page or endpoint pattern.","inputs":["Page objective","Source facts","Target URL","Schema type","Internal-link targets"],"outputs":["Astro route","Metadata","Schema endpoint when needed","Updated indexes"],"steps":["Add the Astro route under src/pages/.","Add metadata, canonical path, one H1, semantic sections, and proof/source notes.","Add a matching schema endpoint when the page introduces reusable facts.","Add navigation or hub links if the page is intended to be discovered.","Update sitemap, llms endpoints, examples or file map if relevant.","Run focused QA and fix failures."],"completionCriteria":["Route is linked or intentionally discoverable","Metadata and schema match visible content","Relevant generated indexes are updated","Focused QA passes"]},{"id":"seo-aeo-readiness-pass","name":"SEO and AEO readiness pass","trigger":"A site has content but needs technical discovery and answer-engine readiness hardened.","inputs":["Built site","PUBLIC_SITE_URL","Page inventory","Entity facts","QA output"],"outputs":["Metadata fixes","Schema fixes","llms endpoint updates","Internal-link fixes"],"steps":["Run npm run qa:seo and npm run qa:aeo.","Check that page titles, descriptions, H1s, canonicals, and OG tags are unique and accurate.","Check that schema endpoints expose only visible or source-backed facts.","Check llms.txt and llms-full.txt for complete agent-readable coverage.","Fix route, metadata, schema, or endpoint gaps at the source.","Rerun npm run qa:all."],"completionCriteria":["SEO QA passes","AEO QA passes","Structured facts match public page content","Agent endpoints explain the current site"]},{"id":"launch-readiness-pass","name":"Launch QA","trigger":"A site is close to release or handoff.","inputs":["Production build","Real PUBLIC_SITE_URL","Browser screenshots","Crawl evidence"],"outputs":["Launch QA report","Known-risk list","Ready/not-ready decision"],"steps":["Run npm run qa:all.","Build with the production PUBLIC_SITE_URL.","Serve the static output and crawl it with Screaming Frog.","Capture desktop and mobile screenshots.","Record evidence and remaining risk in reports/.","Do not call the site ready while placeholders, missing proof, or unresolved crawl issues remain."],"completionCriteria":["qa:all passes","Crawl evidence has no unresolved critical issues","Desktop and mobile screenshots show no clipping or overlap","Remaining risks are documented"]},{"id":"design-system-integration-later","name":"Design system integration later","trigger":"The technical/reference contract is stable and visual system work begins.","inputs":["Approved design direction","Component inventory","Current content model","Accessibility constraints"],"outputs":["Component tokens","Reusable layout primitives","Visual QA evidence"],"steps":["Keep the current agent endpoints stable while changing presentation.","Convert repeated patterns into components only where reuse is real.","Add design tokens and component documentation without hiding technical content.","Check desktop and mobile screenshots for text fit, hierarchy, and navigation clarity.","Rerun npm run qa:all and browser QA."],"completionCriteria":["Main URL remains useful to agents","Design tokens do not break readability","Visual QA confirms no overlap or clipped text","Machine endpoints remain unchanged or intentionally versioned"]}],"why_explanations":{"objective":"Require useful rationale wherever an agent could otherwise follow a broad objective without understanding the reason, evidence, tradeoff, or failure mode.","why":"This system is designed for agents that build websites. Agents need explicit reasoning scaffolds so they can continue work, stress test decisions, avoid bad examples, and adapt patterns without guessing.","requiredSurfaces":[{"id":"roadmap-items","surface":"/product-roadmap.json","requiredFields":["objective","why","valueMultiplier","objectiveAlignment"],"why":"Roadmap work should explain why each value multiplier matters and how it supports the system purpose."},{"id":"walkthrough-steps","surface":"/walkthroughs.json","requiredFields":["objective","why","steps.why","objectiveAlignment"],"why":"Step-by-step work needs rationale at the step level, not only at the heading level."},{"id":"contract-registry","surface":"/contract-registry.json","requiredFields":["purpose","evidence","failureMode"],"why":"A contract is only useful when agents know why it exists, how it is proven, and what breaks when it drifts."},{"id":"site-studies","surface":"/site-studies.json","requiredFields":["strongPatterns.why","avoidPatterns.why","agentTakeaways"],"why":"Good and bad examples should become reusable reasoning, not screenshots or impressions."},{"id":"qa-and-evaluation","surface":"/seo-aeo-evaluation.json and /qa-contract.json","requiredFields":["why","evidenceRequired","passCriteria","warningCriteria","failCriteria"],"why":"QA gates need to explain what they prove and what they do not prove."},{"id":"source-and-claims","surface":"/source-traceability.json","requiredFields":["policy.why","publicUse","requiredQualifier"],"why":"Claim safety depends on explicit source support, blocked use, and qualifier rationale."},{"id":"design-and-aeo-context","surface":"/design-system-contracts.json and /aeo-geo-context.json","requiredFields":["why","objectiveAlignment","rules with why fields"],"why":"Design and model-context work are easy to overgeneralize unless the contract explains tradeoffs and risks."}],"qualityRules":["A useful why explains the consequence of doing or skipping the work.","A useful why names the specific agent failure it prevents.","A useful why connects to evidence, QA, source truth, or the system objective.","A useful why is specific enough to guide a future implementation decision.","A useful why distinguishes pass, warning, and fail states when the work is evaluative."],"antiPatterns":["Because it is best practice.","Because SEO needs it.","Because users like it.","Because the design looks better.","Because agents need context, with no detail about what context or failure mode.","A broad objective with no step-level rationale."],"qaCoverage":[{"check":"Roadmap items","command":"npm run qa:aeo","coverage":"Requires objective, why, valueMultiplier, and objectiveAlignment on each item."},{"check":"Walkthrough steps","command":"npm run qa:aeo","coverage":"Requires why on every execution step."},{"check":"Contracts","command":"npm run qa:aeo","coverage":"Requires purpose, evidence, and failureMode."},{"check":"Site studies","command":"npm run qa:aeo","coverage":"Requires why on strong and avoid patterns."},{"check":"Context contracts","command":"npm run qa:aeo","coverage":"Requires why-bearing objects in design and AEO/GEO context."}],"stressTests":["Remove a walkthrough step why and confirm QA fails.","Replace a site-study why with vague best-practice language and flag it during review.","Ask a future agent to choose between two tasks using only rationale fields.","Remove a contract failureMode and confirm QA fails.","Check that every done task has evidence links that explain why it is complete."],"passCriteria":["Required rationale surfaces are listed.","Each required surface names fields that carry rationale.","Anti-patterns describe vague explanations to avoid.","QA coverage maps rationale checks to commands.","Stress tests explain how to prove rationale is useful."],"warningCriteria":["A rationale exists but is too generic to guide implementation.","A rationale explains value but not failure mode.","A rationale cites evidence but not objective alignment.","A completed task has evidence links but no clear why."],"failCriteria":["A major objective lacks a why.","A walkthrough step lacks a why.","A contract lacks failureMode or evidence.","A good/bad example lacks why.","A QA check lacks pass/warn/fail reasoning."],"objectiveAlignment":"Makes the operating system explainable enough for future agents to execute, audit, stress test, and adapt without relying on hidden assumptions."},"examples":[{"id":"local-service","type":"Local service website","routePattern":"/examples/#local-service","requiredPages":["Home","Services","Service detail","Service area","Proof","FAQ","Contact"],"requiredSchema":["LocalBusiness","Service","FAQPage","BreadcrumbList"],"sourceAssumptions":["Verified service list","Service-area list","Contact details","Licensing or qualification facts","Customer proof"],"pagePatterns":["Homepage entity summary","Service detail page per primary offer","Location or service-area proof section","FAQ backed by actual buyer questions"],"seoRequirements":["Local title modifiers where true","Canonical service URLs","Internal links between service and proof pages"],"aeoRequirements":["Direct service answers","Plain-language eligibility/scope details","FAQPage schema for visible FAQs"],"qaRequirements":["qa:all","Screaming Frog crawl before launch","Mobile contact path check"],"notes":"Use when a company serves a geography and needs clear local relevance, proof, service detail, and contact conversion."},{"id":"b2b-saas","type":"B2B SaaS website","routePattern":"/examples/#b2b-saas","requiredPages":["Home","Product","Use cases","Integrations","Comparison","Proof","Resources","Contact"],"requiredSchema":["Organization","SoftwareApplication","Product","FAQPage","Article"],"sourceAssumptions":["Product positioning","Feature facts","Integration list","Security/compliance notes","Customer proof"],"pagePatterns":["Product overview","Use-case detail","Integration/entity page","Comparison page with sourced claims","Resource hub"],"seoRequirements":["Category and use-case page metadata","Comparison pages avoid unsupported claims","Resource pages use Article schema"],"aeoRequirements":["Definition-ready product description","Feature and integration facts in visible copy","Comparison FAQs with caveats"],"qaRequirements":["qa:all","Structured data review","Claim/proof traceability review"],"notes":"Use when buyers need category clarity, use-case mapping, objections, proof, and integration/entity pages."},{"id":"professional-services","type":"Professional services website","routePattern":"/examples/#professional-services","requiredPages":["Home","Services","Industries","About","Proof","Insights","Contact"],"requiredSchema":["ProfessionalService","Person","Organization","FAQPage","Article"],"sourceAssumptions":["Service scope","Practitioner or team credentials","Industry experience","Client proof","Engagement process"],"pagePatterns":["Service overview","Industry-specific fit page","About/trust page","Insights article","Proof page"],"seoRequirements":["Service and industry URLs are distinct","Author or organization attribution is explicit","Proof pages support trust claims"],"aeoRequirements":["Clear who/what/where fit answers","Visible process and qualification details","FAQ schema for service objections"],"qaRequirements":["qa:all","Accessibility review for dense content","Proof claim review"],"notes":"Use when trust, qualifications, service scope, and proof matter more than product-style feature grids."},{"id":"proof-page","type":"Proof page","routePattern":"/examples/#proof-page","requiredPages":["Proof index","Case study","Testimonials","Before-after evidence"],"requiredSchema":["Review","CreativeWork","Article"],"sourceAssumptions":["Approved testimonials","Case-study facts","Before/after artifacts","Metrics with dates","Permission notes"],"pagePatterns":["Proof index","Case-study template","Metric callout with source note","Testimonial block with attribution rules"],"seoRequirements":["Case-study titles include specific outcome when approved","No invented metrics","Canonical proof URLs"],"aeoRequirements":["Claims are answerable with context","Dates and conditions are visible when metrics are used","Review schema only for eligible visible reviews"],"qaRequirements":["qa:all","Claim/source audit","Permission/privacy review"],"notes":"Use to make claims inspectable. Every claim should point to an example, artifact, metric, review, screenshot, or source note."},{"id":"answer-ready-resource","type":"Answer-ready resource page","routePattern":"/examples/#answer-ready-resource","requiredPages":["Guide","Comparison","Glossary/entity page","FAQ"],"requiredSchema":["Article","FAQPage","DefinedTerm","BreadcrumbList"],"sourceAssumptions":["Topic definitions","Approved recommendations","Comparison criteria","Public source references","Entity glossary"],"pagePatterns":["Concise answer block","Expanded guide","Comparison table","Glossary entry","FAQ cluster"],"seoRequirements":["Search-intent-aligned titles","Stable URLs for glossary/entity pages","Internal links from guide to definitions"],"aeoRequirements":["Direct answers before nuance","Caveats visible near recommendations","Machine-readable schema for FAQs/articles/terms"],"qaRequirements":["qa:all","Internal-link crawl","Schema review"],"notes":"Use for AEO/GEO pages that answer concrete questions and expose stable facts agents can quote or reason over."}],"conversion_copy":{"objective":"Teach future agents how to write clear, proof-aware, conversion-focused website copy without copying another creator's proprietary language.","why":"Strong site copy is not just tone. It clarifies the market, names the painful problem, makes the outcome concrete, explains the mechanism, reduces perceived risk, proves claims, and gives the next step. Agents need that sequence spelled out so they do not ship vague, clever, unsupported, or visually attractive copy that fails to convert.","studyDate":"2026-06-07","sourceStudy":{"name":"Alex Hormozi / Acquisition.com public conversion-copy pattern study","sourceBoundary":"Use these sources to learn principles and page patterns. Do not copy proprietary copy, income claims, testimonials, guarantees, course structures, or brand language into client work.","sources":[{"title":"Acquisition.com homepage","url":"https://www.acquisition.com/","usefulFor":"Offer-first page framing, founder proof, free training positioning, and direct CTA structure."},{"title":"Acquisition.com training library","url":"https://www.acquisition.com/training","usefulFor":"Lead magnet hierarchy, course naming, free-value positioning, and workshop escalation."},{"title":"Acquisition.com Alex Hormozi bio","url":"https://www.acquisition.com/bio-alex","usefulFor":"Credibility sequencing, business history, and expertise claims tied to specific accomplishments."},{"title":"Acquisition.com books page","url":"https://www.acquisition.com/books","usefulFor":"Authority positioning, book ecosystem, practical education promise, and proof stacking."},{"title":"Acquisition.com lead generation course","url":"https://www.acquisition.com/training/leads","usefulFor":"Ethical disclaimer language, outcome boundaries, education versus guarantee separation, and stepwise training structure."},{"title":"ACQ AI","url":"https://ai.acquisition.com/","usefulFor":"AI-assistant positioning, model/tool trust cues, grounded-answer claims, and advisor-in-your-pocket framing."},{"title":"ACQ Vantage","url":"https://vantage.acquisition.com/","usefulFor":"Ecosystem offer architecture across AI tools, founder network, workshops, playbooks, pricing tiers, referral economics, qualification, and disclaimers."},{"title":"Acquisition.com store and $100M book ecosystem","url":"https://shop.acquisition.com/","usefulFor":"Book-to-training-to-workshop ladder, proof stacking, implementation-plan framing, and productized education copy."},{"title":"The Lost Chapter: Your First Avatar","url":"https://acquisition.com/hubfs/The_Lost_Chapter-Your_First_Avatar.pdf","usefulFor":"Avatar selection, best-customer research, qualification, buyer-journey reverse engineering, and quality-over-volume messaging."}]},"supplementaryFrameworks":{"why":"A single source study breeds house-style monoculture. These public-domain copy frameworks give agents independent lenses to cross-check any draft against, so guidance never reduces to one creator's voice.","frameworks":[{"id":"aida","name":"AIDA (Attention, Interest, Desire, Action)","origin":"Classic advertising canon, public domain (attributed to E. St. Elmo Lewis, 1898).","agentUse":"Sequence check: does the page earn attention with relevance (not tricks), build interest with specifics, create desire with proof, and end with one unambiguous action?","failureSignal":"Pages that jump from attention to action with no proof in between."},{"id":"pas","name":"PAS (Problem, Agitate, Solve)","origin":"Direct-response canon, public domain.","agentUse":"Lead check: state the buyer's problem in their words, make its cost concrete without manufacturing fear, then present the mechanism that resolves it.","failureSignal":"Agitation that exaggerates beyond the source evidence, or solutions presented before the problem is established."},{"id":"four-u","name":"4U headlines (Useful, Urgent, Unique, Ultra-specific)","origin":"Direct-response canon (popularized by Michael Masterson), used here as a public scoring rubric.","agentUse":"Score every headline 1-4 on each U; rewrite anything that scores under 3 on Useful or Ultra-specific. Urgency only counts when real.","failureSignal":"Headlines that are clever before clear, or urgent without an operational reason."},{"id":"jtbd","name":"Jobs to Be Done framing","origin":"Public product-strategy literature (Christensen et al.).","agentUse":"Voice check: copy describes the job the buyer is hiring for and the progress they seek, not the vendor's feature taxonomy.","failureSignal":"Feature names doing the work that buyer outcomes should do."}]},"conversionPrinciples":[{"id":"specific-dream-outcome","name":"Make the desired outcome concrete","why":"People evaluate offers by the clarity and value of the future state. Vague outcomes force the reader to imagine the value themselves.","agentCheck":"Can a reader repeat the promised outcome in one sentence without guessing the audience, timeframe, or result type?","weakExample":"We help businesses grow with modern digital solutions.","strongerExample":"Turn your current website into a source-backed sales asset that explains your offer, answers buyer objections, and gives agents clean data to cite.","guardrail":"Do not promise specific revenue, rankings, traffic, or timelines unless source evidence and legal approval support the claim."},{"id":"pain-before-platform","name":"Name the painful problem before explaining the system","why":"Buyers care about the job they need solved before they care about tools, frameworks, or implementation details.","agentCheck":"Does the copy state the buyer's actual constraint before listing features?","weakExample":"Our platform includes dashboards, automation, AI, and analytics.","strongerExample":"When prospects cannot understand what you do, your team keeps re-explaining the same basics and your best proof stays buried.","guardrail":"Avoid fear-based exaggeration. The problem must match actual audience research or source material."},{"id":"value-equation","name":"Increase perceived value and reduce perceived cost","why":"Conversion copy should improve the ratio between desired outcome and likelihood of success while reducing time, effort, delay, and risk.","agentCheck":"Does each section either increase outcome clarity, increase confidence, reduce effort, reduce delay, or reduce risk?","weakExample":"We provide a comprehensive solution for your online presence.","strongerExample":"The starter gives agents a route map, machine endpoints, schemas, examples, and QA commands so they can understand the site before touching implementation.","guardrail":"Do not hide effort. If the offer requires client work, name it clearly and make the sequence manageable."},{"id":"offer-stack","name":"Show the offer as a bundle of outcomes, not a pile of features","why":"A strong offer makes the components feel inevitable because each one removes a buyer obstacle.","agentCheck":"Can every feature be translated into the obstacle it removes or the decision it helps the buyer make?","weakExample":"Includes strategy, design, development, SEO, AEO, and testing.","strongerExample":"You get a source ledger for claims, page patterns for build speed, SEO/AEO contracts for discovery, and QA evidence for handoff confidence.","guardrail":"Do not inflate the stack with filler bonuses. Every component must have a reason to exist."},{"id":"mechanism-clarity","name":"Explain why this approach works","why":"A specific mechanism makes the claim more believable than a broad promise because it gives the reader a causal path.","agentCheck":"Does the copy explain the method behind the outcome in plain language?","weakExample":"Our proven process gets results.","strongerExample":"The system starts by preserving source evidence, then turns approved facts into visible copy, schema, LLM summaries, and tests that catch unsupported claims.","guardrail":"Do not claim a proprietary mechanism unless the business actually owns one."},{"id":"proof-before-claim","name":"Attach proof to claims before asking for belief","why":"Strong conversion copy earns trust by pairing claims with evidence, examples, screenshots, crawl results, testimonials, or source-backed facts.","agentCheck":"Does every meaningful claim have a visible proof element or claim ID?","weakExample":"We are the best choice for serious businesses.","strongerExample":"The current build exposes QA reports, crawl evidence, browser screenshots, schema maps, and contract drift checks so readiness is inspectable.","guardrail":"Never fabricate testimonials, logos, statistics, or case studies."},{"id":"risk-reversal","name":"Reduce buyer risk honestly","why":"A reader who wants the outcome may still hesitate because of uncertainty, effort, budget, switching cost, or fear of a bad decision.","agentCheck":"Does the page answer what happens if this does not work, is not a fit, or requires more effort than expected?","weakExample":"Contact us today to get started.","strongerExample":"Start with a source and QA audit before implementation, so gaps are found while the cost of correction is low.","guardrail":"Do not add guarantees the business cannot operationally and legally honor."},{"id":"ethical-urgency","name":"Use urgency only when it is real","why":"Urgency can improve action, but fake scarcity damages trust and teaches agents the wrong habit.","agentCheck":"Is the urgency tied to a real capacity, date, price change, event, or operational constraint?","weakExample":"Spots are limited, act now.","strongerExample":"The next audit batch closes Friday because each review includes manual crawl and source-traceability checks.","guardrail":"If there is no real constraint, use clarity of next step instead of urgency."},{"id":"cta-specificity","name":"Make the next step specific and low-confusion","why":"A conversion path fails when the reader likes the idea but cannot tell what action starts the process.","agentCheck":"Does the CTA say exactly what happens next, who it is for, and what the reader should expect?","weakExample":"Learn more.","strongerExample":"Run the agent readiness audit.","guardrail":"The CTA must match the destination. Do not use high-commitment language for a low-commitment page or vice versa."},{"id":"qualified-who-before-what","name":"Define who this is for before explaining everything they get","why":"The newer Acquisition.com surfaces use fit boundaries, revenue thresholds, and operator language to make the offer feel more valuable to the right buyer while filtering poor-fit demand.","agentCheck":"Does the page state who qualifies, who does not, and why that boundary improves the outcome?","weakExample":"This is for any business that wants to grow.","strongerExample":"This is for teams that already have source material, proof, and a real offer, but need an agent-readable site system that keeps claims, schema, and QA evidence aligned.","guardrail":"Do not invent exclusivity. Qualification must reflect a real operational, pricing, legal, capacity, or value-delivery reason."},{"id":"ecosystem-offer-architecture","name":"Show the offer ecosystem, not just one asset","why":"Modern conversion pages often sell an integrated system: tool, training, community, live guidance, playbooks, and escalation paths. The bundle works when each layer has a distinct job.","agentCheck":"Can the reader tell what each layer does, what order to use it in, and why the layers are stronger together?","weakExample":"Members get AI, workshops, templates, calls, and a community.","strongerExample":"Agents start with the manifest, use copy and page contracts to draft, use traceability to prove claims, then run QA and handoff reports before implementation is called ready.","guardrail":"Do not stack unrelated bonuses. Ecosystem layers must connect to one customer journey."},{"id":"ai-tool-trust","name":"Position AI tools with boundaries and implementation use cases","why":"AI-tool copy converts better when it explains what the tool is trained to help with, how the user should apply outputs, and where human judgment or source evidence still controls the result.","agentCheck":"Does AI copy name the jobs the AI helps with, the evidence it should use, and the decisions humans must still verify?","weakExample":"Our AI writes everything for your business instantly.","strongerExample":"Use the copy endpoint to draft options, then validate each claim against source traceability, page context, and QA before it reaches a live site.","guardrail":"Do not imply AI outputs are inherently true, current, legal, or ready to publish without review."},{"id":"value-in-advance-journey","name":"Use value-in-advance content to shape the buyer journey","why":"The avatar material emphasizes studying how best customers bought and then recreating that journey with genuinely useful long-form content before a sales conversation.","agentCheck":"Does the site give a qualified buyer useful context before asking for a high-commitment action?","weakExample":"Book a call to find out how it works.","strongerExample":"Read the copy lab, inspect the endpoint, and run the stress report before deciding whether the starter is ready for implementation work.","guardrail":"Value-in-advance content must be genuinely useful, not a disguised pitch."},{"id":"pricing-and-path-choice","name":"Make tiers and paths easy to compare","why":"Tiered offers convert when each path explains who it is for, what changes, what stays the same, and why the higher commitment exists.","agentCheck":"Can a buyer compare options without reading every line twice?","weakExample":"Basic, Pro, and Elite plans are available.","strongerExample":"Use Standard for core access, Premium when implementation speed matters, and VIP when direct advisory support is the constraint.","guardrail":"Do not bury material constraints, cancellation rules, trial terms, or eligibility requirements."},{"id":"disclaimer-near-outcome","name":"Place outcome boundaries near ambitious claims","why":"Strong direct-response pages can use bold proof and ambitious outcomes, but trust improves when disclaimers and result boundaries live near the relevant promise.","agentCheck":"Are atypical results, earnings claims, investment-like claims, AI claims, and referral incentives paired with plain disclaimers?","weakExample":"Use our system and get the same results.","strongerExample":"The system can improve copy and QA discipline, but results depend on the offer, source quality, market, execution, traffic, and review process.","guardrail":"Never use disclaimers as permission to make reckless claims."}],"copyTypes":[{"id":"homepage-hero","name":"Homepage hero","purpose":"Clarify who the site is for, what outcome it creates, why it is credible, and what to do next.","structure":["Audience or category","Specific outcome","Mechanism","Proof cue","Primary CTA"],"agentPrompt":"Write a hero that a qualified buyer understands in five seconds without needing buzzwords."},{"id":"offer-section","name":"Offer section","purpose":"Turn the service or product into an obstacle-removal stack.","structure":["Problem","Offer component","Obstacle removed","Proof or example","Fit boundary"],"agentPrompt":"List each component only if it improves outcome, certainty, speed, effort, or risk."},{"id":"proof-section","name":"Proof section","purpose":"Let evidence carry belief instead of relying on adjectives.","structure":["Claim","Evidence type","Source","What it proves","Limitation"],"agentPrompt":"Pair every impressive statement with the proof source and state what it does not prove."},{"id":"objection-faq","name":"Objection FAQ","purpose":"Answer real buyer hesitation with direct, non-defensive copy.","structure":["Objection","Plain answer","Evidence or boundary","Next step"],"agentPrompt":"Write answers that reduce uncertainty without overpromising."},{"id":"lead-magnet","name":"Lead magnet page","purpose":"Make free value feel specific enough to justify attention and contact exchange.","structure":["Who it helps","Problem it solves","Asset delivered","Use case","CTA","Consent/disclaimer"],"agentPrompt":"Make the free asset concrete. Avoid vague newsletter language."},{"id":"service-page","name":"Service page","purpose":"Explain fit, scope, sequence, proof, and buying path for a concrete service.","structure":["Use case","Problem","Process","Deliverables","Proof","Boundaries","CTA"],"agentPrompt":"Make scope and decision criteria clear enough that the wrong buyer can opt out."},{"id":"ai-tool-page","name":"AI tool page","purpose":"Explain what the AI helps produce, what it is grounded in, how the user should apply it, and what must be verified before use.","structure":["User job","AI capability","Grounding source","Implementation use cases","Human review boundary","CTA"],"agentPrompt":"Write AI copy that is useful, specific, and bounded by source evidence."},{"id":"community-membership-page","name":"Community or membership page","purpose":"Show why the network, live guidance, tools, and playbooks are more valuable together than separately.","structure":["Qualified member","Core promise","Member layers","How it works","Pricing/path choice","Disclaimers","CTA"],"agentPrompt":"Make the membership feel filtered, operational, and outcome-oriented without fake exclusivity."},{"id":"qualification-gate","name":"Qualification gate","purpose":"Filter fit before high-commitment sales, workshops, or advisory paths.","structure":["Who qualifies","Why the gate exists","What is reviewed","What happens next","Alternative path"],"agentPrompt":"Explain qualification as value protection for both sides, not as status theater."},{"id":"pricing-tier-section","name":"Pricing tier section","purpose":"Help a buyer choose between access levels with minimal confusion.","structure":["Shared value","Tier-specific difference","Best-fit cue","Risk/cancellation boundary","CTA per tier"],"agentPrompt":"Make each tier's reason to exist obvious without pushing everyone to the highest price."}],"exampleTransformations":[{"id":"generic-agency-to-agent-operating-system","weakCopy":"We build beautiful, high-performing websites that help your business grow.","strongerCopy":"We build source-backed websites that agents, search engines, and buyers can understand: every core claim maps to evidence, every key page has schema, and every handoff includes QA proof.","whyStronger":"It names the mechanism, audience, proof model, and operational output instead of leaning on broad adjectives.","requiredChecks":["Source-backed claim","Specific audience","Mechanism stated","QA or proof cue present"]},{"id":"feature-list-to-offer-stack","weakCopy":"Includes design, SEO, content, schema, analytics, and testing.","strongerCopy":"Design gives buyers a clear path, SEO and schema make the offer discoverable, source traceability keeps claims defensible, and testing proves the site works before handoff.","whyStronger":"It translates each feature into the buyer or agent obstacle it removes.","requiredChecks":["Every feature has a job","No filler component","Benefit tied to system objective"]},{"id":"unsupported-proof-to-evidence-led","weakCopy":"Trusted by businesses that want the best results.","strongerCopy":"Use crawl reports, browser screenshots, schema maps, and source manifests as visible proof before calling a page launch-ready.","whyStronger":"It replaces a vague trust claim with inspectable evidence types.","requiredChecks":["No unverifiable superlative","Evidence type named","Launch criteria stated"]},{"id":"generic-ai-to-bounded-ai-tool","weakCopy":"Our AI will write all your website copy instantly.","strongerCopy":"Use the copy endpoint to draft conversion options, then check every claim against source traceability, page context, and QA before publishing.","whyStronger":"It names the AI job, the implementation path, and the human/source verification boundary.","requiredChecks":["AI use case named","Source boundary stated","No publish-ready claim","QA gate present"]},{"id":"open-to-everyone-to-qualified-fit","weakCopy":"Anyone who wants a better website should book a call.","strongerCopy":"Book implementation only after the source package, proof inventory, required pages, and launch constraints are clear enough for an agent to validate.","whyStronger":"It turns a broad CTA into a qualification gate that protects execution quality.","requiredChecks":["Fit criteria named","Next step is specific","Operational reason for gate is clear"]},{"id":"local-service-vague-trust-to-bounded-promise","vertical":"local service (see /demo/brightline/)","weakCopy":"Your trusted local gutter experts — satisfaction guaranteed!","strongerCopy":"Two crews, three named counties, photo documentation of every finished run, and a walk-through before any quote. Requests outside the service area are declined, not waitlisted.","whyStronger":"It replaces unverifiable trust language with operational facts a buyer can check, and the explicit boundary makes the in-area promise credible.","requiredChecks":["Every fact maps to a source claim","Service boundary stated","No guarantee the business cannot operationally honor"]},{"id":"saas-feature-dump-to-job-outcome","vertical":"B2B SaaS (see /demo/logpilot/)","weakCopy":"Powerful, flexible log management with enterprise-grade security and seamless integrations.","strongerCopy":"When a client's auditor asks for nine months of access logs, export them in one operation — retention is set per client at 30, 90, or 365 days with immutable locks, across six verified integrations.","whyStronger":"It anchors on the buyer's job (the audit request), states exact capability boundaries, and counts integrations instead of calling them seamless.","requiredChecks":["Job-to-be-done leads","Numbers replace adjectives","Integration claims match the verified list","No superiority language"]},{"id":"professional-services-credential-fog-to-sourced-scope","vertical":"professional services","weakCopy":"Our award-winning team of experts delivers world-class advisory services.","strongerCopy":"Two licensed practitioners (license numbers on the about page), three defined engagements with explicit exclusions, and anonymized case summaries published with written approval.","whyStronger":"Credential-heavy buyers verify; copy that points at checkable credentials and bounded scope converts the skeptics that adjectives repel.","requiredChecks":["Credentials visible and sourced","Scope exclusions stated","Proof carries permission status"]}],"agentWorkflow":["Identify the business model, audience, buying stage, and site type before writing.","Identify the best-fit buyer and the poor-fit buyer before writing the offer.","Map the buyer journey: value-in-advance content, low-commitment action, qualification gate, paid path, and implementation/handoff.","Extract source-backed facts, proof, constraints, and disallowed claims from the source ledger.","Write the plain-language problem in the buyer's words before naming the solution.","Define the dream outcome, likelihood proof, time-to-value, effort reduction, and risk reduction.","Build the offer stack by mapping each feature to the obstacle it removes.","If the offer includes AI, community, workshops, playbooks, referrals, or pricing tiers, write the role and boundary of each layer separately.","Draft hero, offer, proof, objection, and CTA copy separately before polishing tone.","Attach claim IDs, source notes, proof blocks, or disclaimers to meaningful claims.","Stress test for vague adjectives, fake urgency, unsupported outcomes, unclear audience, and missing next step.","Run SEO/AEO QA and verify LLM summaries do not overstate the visible page."],"antiPatterns":[{"id":"clever-before-clear","issue":"The headline is memorable but does not tell the reader what the offer does.","fix":"Lead with the concrete outcome, then add personality."},{"id":"feature-dump","issue":"The page lists capabilities without explaining the buyer obstacle each one removes.","fix":"Rewrite each feature as an outcome, confidence, speed, effort, or risk improvement."},{"id":"fake-scarcity","issue":"Urgency is invented because the page lacks a strong reason to act.","fix":"Use real capacity/date constraints or remove urgency entirely."},{"id":"proofless-superlatives","issue":"The copy says best, fastest, leading, trusted, or proven without evidence.","fix":"Replace with specific proof or remove the claim."},{"id":"ai-slop-generalities","issue":"The copy could apply to any business in any market.","fix":"Add audience, pain, mechanism, proof, and fit boundaries from source data."},{"id":"unbounded-ai-claims","issue":"The page implies AI can replace source evidence, expert review, legal review, or implementation judgment.","fix":"Name the AI job, the source material it should use, the review boundary, and the QA gate."},{"id":"ecosystem-confusion","issue":"The offer stacks tools, community, live help, playbooks, pricing, and referrals without a clear buyer journey.","fix":"Put each layer in order and state the job it performs."},{"id":"qualification-theater","issue":"The page uses exclusivity language without a real operational reason.","fix":"Tie qualification to fit, capacity, source readiness, value delivery, or risk reduction."},{"id":"buried-disclaimer","issue":"Ambitious results, referral incentives, or AI claims appear far away from the relevant boundary language.","fix":"Move plain disclaimers beside the claim or offer component they qualify."}],"qaGates":["npm run qa:aeo","npm run qa:seo","npm run qa:browser","npm run qa:all"],"stressTestSuite":{"command":"npm run qa:copy","fixturePath":"data/derived/copy-stress/copy-stress-fixtures.json","reportPath":"reports/copy-stress/copy-stress-report.json","why":"Copy guidance should be proven against weak prompts and bad examples, not only documented as principles."},"passCriteria":["Copy states a specific audience, problem, outcome, mechanism, proof model, and next step.","Every meaningful claim is source-backed, visible, or clearly framed as a process principle.","Offer sections explain why each component exists.","Bad examples and better examples are both available for agent training.","LLM summaries can describe the copy strategy without inventing unsupported claims."],"objectiveAlignment":"Adds conversion copy as a reusable operating layer so future agents can build sites that are not merely technically valid, but clear, believable, and action-oriented."},"offer_ecosystem":{"objective":"Teach agents how to turn multiple offer assets into one coherent website funnel instead of disconnected sections.","measurementLayer":{"why":"A funnel that is not instrumented cannot be honest about working. Each layer needs the event that proves usage and the threshold that says it is failing, or the ecosystem becomes decoration.","perLayerInstrumentation":[{"layerId":"value-in-advance","instrument":"Views and completion depth of the free asset, plus the rate of progression to the next step.","failingWhen":"Progression to any next step stays under ~2% after meaningful traffic, or completion depth shows readers bounce before the value lands."},{"layerId":"ai-tools","instrument":"Tool sessions, output-saved events, and review-boundary acknowledgements.","failingWhen":"Outputs are generated but never saved or reused; that means novelty, not utility."},{"layerId":"community","instrument":"Active-member ratio and first-contribution time.","failingWhen":"Under ~10% of members act monthly, or first contributions take longer than the onboarding promise."},{"layerId":"pricing-tiers","instrument":"Tier-selection distribution and downgrade/refund reasons.","failingWhen":"One tier takes ~90%+ of volume (the others are noise) or refund reasons repeat one missing expectation."},{"layerId":"qualification-gates","instrument":"Gate pass rate and the post-gate close rate against the pre-gate baseline.","failingWhen":"The gate filters volume without improving close rate; it is theater, remove or retune it."},{"layerId":"referral-engine","instrument":"Referred-visitor conversion against organic baseline and payout integrity.","failingWhen":"Referred traffic converts below organic, meaning incentives attract the wrong audience."}],"experimentRule":"Change one layer at a time with a dated note of expected effect; an ecosystem change without a falsifiable expectation is redecorating, not optimizing.","instrumentationGuardrail":"All measurement obeys the privacy contract: consent-gated analytics, no individual tracking beyond what the privacy page discloses."},"why":"Current high-converting business education offers are rarely a single page promise. They combine value-in-advance content, AI tools, community, workshops, playbooks, pricing paths, qualification gates, referral incentives, proof, and disclaimers. Agents need a step-by-step map so every layer has a job, every claim has a boundary, and every CTA moves the buyer to the right next decision.","sourceStudy":{"name":"Acquisition.com / Hormozi offer ecosystem pattern study","sourceBoundary":"Use this as a structural study only. Do not copy Acquisition.com product names, private playbooks, testimonials, revenue claims, pricing, or proprietary positioning into client work.","sourceManifest":"data/sources/manifests/hormozi-conversion-copy-study-2026-06-06.md","studiedPatterns":["AI assistant or tool as immediate utility","Verified community as peer proof and retention layer","Live workshops or advisory as decision support","Playbooks and SOPs as implementation leverage","Pricing tiers as path selection","Qualification gates as value-protection filters","Referral engines as network growth loops","Disclaimers as trust-preserving claim boundaries"]},"funnelLayers":[{"id":"value-in-advance","layer":"Free or low-friction value","websiteRole":"Educate the qualified buyer before a high-commitment action.","why":"Useful public value builds trust, lets the buyer self-diagnose, and makes later qualification more productive.","pageElements":["Specific free asset","Who it helps","Problem it solves","How to use it","Next step"],"proofNeeds":["Source of methodology","Example output or preview","Clear limitation"],"guardrails":["Do not disguise a sales pitch as education","Do not require high-friction contact before showing value"]},{"id":"ai-tools","layer":"AI tool or assistant","websiteRole":"Give the buyer an immediate way to create, diagnose, draft, or decide.","why":"AI tools can make a complex framework usable, but the page must explain grounding, use cases, and human review boundaries.","pageElements":["Jobs the AI helps with","Grounding source","Example use cases","Review boundary","CTA"],"proofNeeds":["Training/source boundary","Example prompts or outputs","AI terms or disclaimer"],"guardrails":["No claim that AI output is automatically true","No publish-ready implication without review","No hidden replacement of source evidence"]},{"id":"community","layer":"Community or founder network","websiteRole":"Convert isolated learning into peer feedback, social proof, and retention.","why":"A community layer is valuable when members are filtered enough to make the network useful and when the page explains the interaction model.","pageElements":["Who qualifies","Member profile","What members exchange","Geographic or market relevance","Conduct/value expectations"],"proofNeeds":["Qualification criteria","Review count or member evidence if allowed","Community rules or expectations"],"guardrails":["Do not imply universal access if there are fit criteria","Do not fabricate activity, reviews, or member outcomes"]},{"id":"workshops","layer":"Live workshops or advisory","websiteRole":"Provide decision support when static materials are not enough.","why":"Live guidance increases perceived certainty when the buyer has context-specific decisions to make.","pageElements":["Session topic","Who leads it","Frequency","Decision it helps make","What happens after"],"proofNeeds":["Instructor/advisor credential","Topic list","Eligibility and availability boundary"],"guardrails":["Do not promise personal access unless it is operationally true","Do not overstate guaranteed outcomes from advice"]},{"id":"playbooks","layer":"Playbooks and SOPs","websiteRole":"Turn strategy into repeatable implementation.","why":"Playbooks reduce effort and time-to-value when the page names which jobs they help the buyer perform.","pageElements":["Playbook category","Use case","Inputs needed","Expected output","Where it fits in the sequence"],"proofNeeds":["Example table of contents or sample","Update policy if relevant","Implementation caveats"],"guardrails":["Do not list proprietary playbooks without permission","Do not treat SOPs as a substitute for execution quality"]},{"id":"pricing-tiers","layer":"Pricing tiers or access paths","websiteRole":"Help the buyer choose the right commitment level.","why":"Tiers reduce decision friction when each path has a clear constraint: access, speed, advisory intensity, or implementation support.","pageElements":["Shared value","Difference by tier","Best-fit cue","Cancellation or term boundary","CTA per tier"],"proofNeeds":["Price and billing clarity","Eligibility rules","Refund/cancel terms if offered"],"guardrails":["Do not bury constraints","Do not push a tier without explaining the tradeoff"]},{"id":"qualification-gates","layer":"Qualification gate","websiteRole":"Protect the buyer and provider from bad-fit sales conversations.","why":"Fit filters increase quality when they are based on value delivery, readiness, capacity, or compliance rather than status language.","pageElements":["Minimum requirements","Why the gate exists","What is reviewed","Alternate path for not-yet-fit buyers"],"proofNeeds":["Operational reason for the gate","Plain next-step explanation","Privacy note if collecting sensitive data"],"guardrails":["No fake exclusivity","No unnecessary sensitive data collection","No unclear rejection path"]},{"id":"referral-engine","layer":"Referral or affiliate growth loop","websiteRole":"Let members or customers strengthen the network while understanding incentives and limits.","why":"Referral economics can increase perceived value, but only if terms, eligibility, payout logic, and non-guarantee language are clear.","pageElements":["Who can refer","Who qualifies","Incentive","Conditions","Non-guarantee language"],"proofNeeds":["Terms","Eligibility rules","Payout or credit boundaries"],"guardrails":["No guaranteed-income implication","No unclear commission math","No referral promise without terms"]},{"id":"disclaimers","layer":"Disclaimers and result boundaries","websiteRole":"Keep ambitious claims credible and legally safer.","why":"The stronger the proof or outcome language, the closer the page needs plain limits that explain what varies by user, market, effort, and execution.","pageElements":["Nearby result boundary","Atypical-results note","AI/tool limitation","Investment/legal/professional advice boundary if relevant"],"proofNeeds":["Legal-approved disclaimer where needed","Claim-to-disclaimer proximity","Terms links"],"guardrails":["No buried fine-print for central claims","No disclaimer used to excuse reckless copy"]}],"funnelPaths":[{"id":"education-to-tool-to-qualified-call","useWhen":"The buyer needs to understand the method before deciding whether implementation or advisory help fits.","sequence":["value-in-advance","ai-tools","qualification-gates","workshops","disclaimers"],"why":"Education creates context, the tool creates immediate utility, qualification filters fit, and advisory handles complex decisions.","agentCheck":"Can the agent explain why the CTA changes from learn to try to qualify to buy?"},{"id":"community-membership-with-tiers","useWhen":"The offer includes peer network value plus different levels of access or support.","sequence":["community","ai-tools","workshops","playbooks","pricing-tiers","referral-engine","disclaimers"],"why":"A membership needs both ongoing value and path clarity; the buyer must understand what each tier changes.","agentCheck":"Can the buyer tell who belongs, what they get, how they use it, which tier fits, and what results are not guaranteed?"},{"id":"implementation-ready-site-build","useWhen":"An agent is adapting this starter into a real client or product website.","sequence":["qualification-gates","value-in-advance","playbooks","ai-tools","pricing-tiers","disclaimers"],"why":"Readiness depends on source quality, proof inventory, page requirements, AI drafting boundaries, and clear implementation scope.","agentCheck":"Can the agent identify source inputs, proof needs, build path, review boundaries, and scope before writing sales copy?"}],"agentWorkflow":["List every offer asset: free content, tool, community, workshop, playbook, pricing path, referral, guarantee, and disclaimer.","Remove any asset that does not perform a distinct job in the buyer journey.","Define the qualified buyer and not-yet-fit buyer before writing page copy.","Map the funnel path from lowest-friction value to highest-commitment action.","For each layer, write the role, why, proof needed, guardrail, and CTA.","Place claim boundaries next to the claims they qualify, especially AI, earnings, investment-like, referral, or atypical-result claims.","Check that pricing tiers differ by a real constraint such as speed, access, support, or scope.","Run conversion copy and AEO QA so LLM surfaces describe the offer without inventing unsupported outcomes."],"antiPatterns":[{"id":"asset-pile","issue":"The page lists AI, community, workshops, templates, calls, bonuses, and discounts without explaining the path.","fix":"Assign each asset one job in the buyer journey or remove it."},{"id":"qualification-without-reason","issue":"The offer claims exclusivity but does not explain the operational reason for qualification.","fix":"Tie the gate to readiness, fit, capacity, compliance, or value delivery."},{"id":"tier-confusion","issue":"Pricing tiers differ by quantity but not by buyer constraint.","fix":"Define which buyer, speed, access, support level, or scope each tier serves."},{"id":"referral-without-terms","issue":"Referral incentives appear before eligibility, conditions, and non-guarantee language.","fix":"Put terms and outcome boundaries beside the incentive."},{"id":"ai-without-review-boundary","issue":"AI is presented as an answer source instead of a drafting or decision-support layer.","fix":"Name the evidence, review, and QA gates before publishing AI-assisted output."}],"qaGates":["npm run qa:aeo","npm run qa:copy","npm run qa:all"],"passCriteria":["Every funnel layer has a distinct role, why, page elements, proof needs, and guardrails.","Every funnel path has an ordered sequence and explains why the order matters.","Qualification, referral, AI, pricing, and outcome claims include explicit boundaries.","Agents can map offer assets into a coherent path without copying Acquisition.com language.","The manifest, LLM summary, endpoint, schema, and QA checks expose the same offer ecosystem."],"objectiveAlignment":"Adds a deeper funnel architecture layer so future agents can build complete conversion systems, not just individual pages or copy blocks."},"infrastructure_decisions":{"objective":"Teach agents how to choose website infrastructure by decision tier instead of defaulting to a preferred platform.","why":"A good website is partly content and UX, but infrastructure determines what can be built, how safely it can launch, how much it costs to maintain, how quickly it loads, who can edit it, how data is protected, and how future agents can continue the work. Agents need explicit decision tiers so a brochure site does not inherit SaaS complexity and a transactional product does not ship on infrastructure that cannot support it.","decisionPrinciples":["Start with the simplest infrastructure that satisfies the verified requirements.","After requirements are clear, apply the owner-stack preference when it fits because familiar infrastructure reduces delivery risk and future-agent confusion.","Do not add runtime, database, auth, or CMS complexity until a real workflow requires it.","Separate launch requirements from future wishes; document future upgrade paths without building them prematurely.","Choose infrastructure that future agents can inspect, test, and hand off with evidence.","Treat privacy, security, compliance, ownership, backups, and rollback as first-order decisions, not cleanup tasks."],"ownerStackPreference":{"objective":"Bias infrastructure decisions toward Aaron's proven operating stack when it satisfies requirements, while preserving explicit override logic.","why":"A theoretically neutral stack can be worse in practice if it increases maintenance load, deployment friction, account confusion, or future-agent uncertainty. The correct decision should account for the infrastructure Aaron already knows, trusts, pays for, documents, and can hand off.","defaultStack":[{"layer":"source-control-and-collaboration","preferred":"GitHub","defaultUse":"Use as source of truth for code, issues/PRs when relevant, CI triggers, review history, and durable agent handoff.","why":"GitHub is the familiar shared workspace and keeps future-agent continuation anchored in repo state.","overrideOnlyIf":["Client requires another source host","Existing production repo already lives elsewhere","Compliance or enterprise policy requires another system"]},{"layer":"edge-hosting-and-dns","preferred":"Cloudflare","defaultUse":"Prefer for static or edge-friendly marketing sites, DNS/CDN, redirects, security headers, Pages/Workers where appropriate, and public performance/security surfaces.","why":"Cloudflare matches the existing infrastructure pattern for public sites and gives strong DNS/CDN/deploy primitives.","overrideOnlyIf":["Cloudflare account ownership is unclear","Client requires another host","Framework/runtime needs are better supported elsewhere","Existing domain/DNS governance makes another provider safer"]},{"layer":"content-and-marketing-framework","preferred":"Astro","defaultUse":"Prefer for marketing, SEO/AEO, documentation, local service, professional services, content-heavy, and agent-reference sites.","why":"Astro keeps static-first sites fast, inspectable, simpler to crawl, and easier to reason about for agents.","overrideOnlyIf":["The site is truly app-like","The team needs deep React app patterns","Request-time personalization is central","Shared component/runtime requirements point to another framework"]},{"layer":"app-framework","preferred":"Next.js","defaultUse":"Use when the build is a real app or app-adjacent system with auth, dashboards, dynamic user state, richer React UI, Stripe account flows, admin tools, SSR, or team familiarity reducing risk.","why":"Next.js is familiar and still a safe mainstream choice for serious React app work, but should not be the automatic choice for ordinary websites.","overrideOnlyIf":["Astro is enough because the site is mostly public/static","A lighter Vite/React app has no SEO/SSR need","A future app discussion chooses a different framework based on concrete requirements","The client/team has a stronger existing framework standard"]},{"layer":"payments","preferred":"Stripe","defaultUse":"Prefer for payment links, checkout, subscriptions, deposits, portals, invoices, and payment-webhook workflows unless commerce needs clearly point elsewhere.","why":"Stripe is the clearest known payment portal and supports both simple payment links and deeper app workflows.","overrideOnlyIf":["Shopify or commerce platform owns catalog/checkout","Client already has a required processor","Marketplace/tax/fulfillment needs exceed the planned Stripe setup","Compliance or geography requires another provider"]}],"frameworkDecisionRules":[{"id":"astro-first-for-websites","rule":"If the project is a website before it is an app, start with Astro.","chooseAstroWhen":["Mostly public pages","SEO/AEO matters","Content/reference/docs/local-service/professional-services site","Static-first delivery is enough","Cloudflare Pages deployment is a natural fit"],"chooseNextWhen":["Auth or dashboards are central","Per-user state drives the experience","SSR/server actions/API routes are central","React app familiarity materially reduces risk","Stripe portal/account flows require app-like behavior"],"agentCheck":"Can every requested dynamic feature be handled with static pages, forms, external tools, or small serverless functions? If yes, do not default to Next.js."},{"id":"next-js-not-by-habit","rule":"Do not pick Next.js only because it is familiar.","acceptableReasons":["The project is app-like","The user explicitly wants Next.js","Existing codebase is Next.js","Team maintenance favors Next.js","Required integrations are already built around Next.js"],"unacceptableReasons":["Default comfort alone","Marketing site with no runtime needs","A small content site where Astro is simpler","A desire to future-proof without concrete app requirements"],"agentCheck":"Write the exact app requirement that Astro cannot satisfy before choosing Next.js."}],"overrideEvidenceRequired":["State the default owner-stack choice that would normally apply.","State the requirement or constraint that makes the default weaker.","Name the alternative and its operational tradeoffs.","Identify migration, rollback, account ownership, and future-agent handoff impacts.","Record the decision in handoff evidence before implementation."],"antiBiasRules":["Owner-stack preference is a bias to reduce practical risk, not a rule to ignore requirements.","Do not recommend a different stack for novelty or model preference.","Do not recommend the owner stack if the project requirements clearly exceed it.","If Cloudflare account state matters, follow Cloudflare/Wrangler safety rules before any mutation.","If payment processing changes from Stripe, document why Stripe is not sufficient."]},"decisionAreas":[{"id":"rendering-and-hosting","name":"Rendering and hosting","objective":"Choose static, SSR, serverless, or application hosting based on update frequency, personalization, data needs, and operational complexity.","tiers":[{"tier":"static-cdn","chooseWhen":"The site is mostly public content, has no per-user state, and can rebuild when content changes.","examples":["marketing site","local service site","documentation hub","agent reference site"],"tradeoffs":["Fast and cheap","Simple rollback","Limited runtime personalization"]},{"tier":"ssr-or-edge","chooseWhen":"Pages need request-time data, personalization, localization, experiments, or frequent content changes without full rebuilds.","examples":["pricing by region","logged-out app marketing with dynamic content","large content library"],"tradeoffs":["More flexible","More moving parts","Requires runtime observability"]},{"tier":"application-platform","chooseWhen":"The website is also a product with accounts, dashboards, payments, workflows, or heavy integrations.","examples":["SaaS app","client portal","marketplace","member platform"],"tradeoffs":["Supports real app behavior","Higher maintenance","Security and data ownership matter more"]}],"agentQuestions":["Does any page require request-time data?","Can content updates wait for a rebuild?","What must happen if the host is down?","Who owns rollback?"],"guardrails":["Do not add SSR only for marketing copy","Do not host authenticated workflows as a static-only site","Document the deployment and rollback path before launch"]},{"id":"content-management","name":"Content management","objective":"Decide whether content belongs in code, files, a headless CMS, a visual CMS, or an app database.","tiers":[{"tier":"code-and-files","chooseWhen":"Developers or agents own updates and content changes are infrequent or review-heavy.","examples":["source-backed starter","technical docs","small service site"],"tradeoffs":["Version controlled","Strong review path","Less friendly for nontechnical editors"]},{"tier":"headless-cms","chooseWhen":"Nontechnical editors need structured content workflows, drafts, roles, scheduled publishing, or large content inventories.","examples":["resource library","multi-author blog","multi-location pages"],"tradeoffs":["Editor-friendly","Adds integration and schema drift risk","Needs backup/export plan"]},{"tier":"visual-builder","chooseWhen":"Marketing teams need fast visual iteration and accept platform constraints.","examples":["campaign landing pages","brand-managed microsites"],"tradeoffs":["Fast editing","Can hurt source traceability","Harder to enforce code-level QA"]}],"agentQuestions":["Who edits content after launch?","Does content require approval workflow?","Can source traceability survive the CMS?","How is content exported or backed up?"],"guardrails":["Do not choose a CMS without an ownership and backup plan","Do not let visual editing bypass claim/source rules","Keep schema and page content aligned"]},{"id":"data-and-state","name":"Data and state","objective":"Decide whether the site needs no database, lightweight storage, managed relational data, search index, or event stream.","tiers":[{"tier":"no-database","chooseWhen":"The site only serves public content and sends users to external contact or booking flows.","examples":["brochure site","proof site","agent reference"],"tradeoffs":["Lowest operational risk","No in-site records","External systems own state"]},{"tier":"managed-database","chooseWhen":"The site stores accounts, leads, orders, preferences, submissions, or workflow state.","examples":["portal","member site","lead database","commerce workflow"],"tradeoffs":["Persistent state","Needs backups and access control","Data model becomes a contract"]},{"tier":"specialized-indexes","chooseWhen":"The site needs full-text search, vector search, analytics events, queues, or high-volume logs.","examples":["large knowledge base","AI search","event-heavy product"],"tradeoffs":["Better retrieval/performance","More sync paths","More drift to monitor"]}],"agentQuestions":["What data is created by users?","What must be retained or deleted?","What is the backup and restore plan?","What data is private?"],"guardrails":["Do not store form data without retention and access rules","Do not introduce a database for content that can live in versioned files","Document migrations and restore tests"]},{"id":"identity-and-access","name":"Identity and access","objective":"Choose no auth, gated content, member auth, admin auth, or enterprise SSO based on real access needs.","tiers":[{"tier":"public-only","chooseWhen":"Every page can be public and no private data is collected.","examples":["marketing site","public docs","SEO resource hub"],"tradeoffs":["Simple","Crawlable","No personalization"]},{"tier":"simple-gates","chooseWhen":"Downloads, webinars, or resources need light qualification or email capture.","examples":["lead magnet","workshop registration","private PDF"],"tradeoffs":["Supports lead flow","Needs consent/privacy handling","Not true account security"]},{"tier":"full-auth","chooseWhen":"Users need accounts, private dashboards, roles, billing, or protected records.","examples":["member area","client portal","SaaS dashboard"],"tradeoffs":["Real access control","Security burden","Session and permission testing required"]}],"agentQuestions":["What content or data must be private?","Who can access admin tools?","Does the site need roles?","What happens when access is revoked?"],"guardrails":["Do not use client-side hiding for private data","Do not collect gated data without consent copy","Test role boundaries before launch"]},{"id":"forms-and-lead-routing","name":"Forms and lead routing","objective":"Choose contact links, embedded forms, managed form backends, CRM routing, or custom workflows based on lead value and operational needs.","tiers":[{"tier":"direct-contact","chooseWhen":"A phone, email, calendar, or external form is enough.","examples":["small service site","initial MVP"],"tradeoffs":["Simple","Less tracking","External system owns reliability"]},{"tier":"managed-forms","chooseWhen":"The site needs spam controls, notification routing, field validation, and saved submissions.","examples":["contact forms","quote requests","event registrations"],"tradeoffs":["Faster to ship","Vendor dependence","Privacy and retention rules needed"]},{"tier":"crm-workflow","chooseWhen":"Submissions need assignment, scoring, enrichment, automations, or sales handoff.","examples":["high-value B2B leads","multi-location intake","partner/referral intake"],"tradeoffs":["Better operations","More integration failure points","Requires tracking and consent alignment"]}],"agentQuestions":["Who receives submissions?","What fields are necessary?","What consent is needed?","How is spam handled?","What is the SLA?"],"guardrails":["Do not collect unnecessary sensitive fields","Do not route leads without testing notifications","Document where submissions are stored"]},{"id":"media-and-assets","name":"Media and assets","objective":"Choose local assets, optimized image pipeline, DAM, video host, or streaming platform based on volume, performance, and ownership.","tiers":[{"tier":"local-optimized-assets","chooseWhen":"The site has a small, stable asset set.","examples":["logo","social image","small proof screenshots"],"tradeoffs":["Versioned","Fast","Requires build optimization"]},{"tier":"managed-media","chooseWhen":"Editors upload assets frequently or there are many transformations/sizes.","examples":["blog images","case study galleries","team photos"],"tradeoffs":["Editor-friendly","Costs and vendor lock-in","Needs alt/metadata rules"]},{"tier":"video-platform","chooseWhen":"Video quality, privacy, captions, analytics, or streaming reliability matter.","examples":["course library","webinar archive","sales videos"],"tradeoffs":["Reliable playback","External dependency","Accessibility/caption QA required"]}],"agentQuestions":["Who uploads assets?","What formats and sizes are needed?","Do videos need captions or privacy?","What alt text is required?"],"guardrails":["Do not ship unoptimized hero media","Do not use stock-like assets when product/place proof matters","Do not publish video without captions when accessibility matters"]},{"id":"search-and-discovery","name":"Search and discovery","objective":"Choose no internal search, static search, hosted search, or AI/vector retrieval based on content depth and answer needs.","tiers":[{"tier":"navigation-only","chooseWhen":"The site has few pages and clear IA.","examples":["small service site","single offer site"],"tradeoffs":["Simple","No search maintenance","Navigation must be excellent"]},{"tier":"indexed-site-search","chooseWhen":"Users need keyword discovery across many pages or resources.","examples":["knowledge base","resource library","docs"],"tradeoffs":["Better discovery","Index freshness concerns","Needs noindex/private filtering"]},{"tier":"ai-retrieval","chooseWhen":"Users or agents need answer synthesis over source-backed content.","examples":["agent reference","technical docs","support knowledge base"],"tradeoffs":["Powerful answers","Citation and hallucination risk","Requires source boundaries"]}],"agentQuestions":["Can users find content through navigation?","What content must never be indexed?","Do answers need citations?","How is index freshness checked?"],"guardrails":["Do not expose private content to search indexes","Do not use AI retrieval without citations","Keep robots, llms, sitemap, and source boundaries aligned"]},{"id":"analytics-and-observability","name":"Analytics and observability","objective":"Choose privacy-light analytics, product analytics, server logs, uptime monitoring, and error tracking based on risk and decision needs.","tiers":[{"tier":"privacy-light-analytics","chooseWhen":"The site needs basic traffic and conversion visibility without heavy tracking.","examples":["marketing site","content site"],"tradeoffs":["Low privacy burden","Less granular","Good for launch basics"]},{"tier":"product-analytics","chooseWhen":"User behavior, funnels, cohorts, or feature usage drive decisions.","examples":["SaaS app","member area","conversion experiments"],"tradeoffs":["Better insight","Consent and privacy complexity","Event taxonomy required"]},{"tier":"operational-observability","chooseWhen":"Runtime errors, uptime, latency, queues, or integrations affect business outcomes.","examples":["SSR app","checkout flow","lead routing system"],"tradeoffs":["Faster incident response","More setup","Alert ownership required"]}],"agentQuestions":["What decisions will analytics support?","What events are necessary?","What consent is required?","Who receives alerts?"],"guardrails":["Do not install analytics without privacy review","Do not track sensitive fields","Do not launch runtime systems without error and uptime evidence"]},{"id":"payments-and-commerce","name":"Payments and commerce","objective":"Choose external checkout, embedded checkout, subscription billing, marketplace payments, or no payments based on transaction risk.","tiers":[{"tier":"no-payments-or-external","chooseWhen":"Sales happen by invoice, proposal, or external checkout link.","examples":["agency service","consulting","manual proposal"],"tradeoffs":["Simple site","Less integrated UX","External system owns payment risk"]},{"tier":"embedded-checkout","chooseWhen":"The site sells simple products, deposits, workshops, or subscriptions.","examples":["course sale","event ticket","membership"],"tradeoffs":["Better conversion","Needs tax/refund/terms clarity","Webhook reliability matters"]},{"tier":"custom-commerce","chooseWhen":"Orders, fulfillment, discounts, tax, inventory, entitlements, or marketplaces require custom logic.","examples":["commerce platform","multi-vendor marketplace","complex subscriptions"],"tradeoffs":["Flexible","High compliance and testing load","Requires operational ownership"]}],"agentQuestions":["What is being sold?","Are refunds, taxes, subscriptions, or entitlements involved?","What terms must appear before payment?","How are payment failures handled?"],"guardrails":["Do not build custom checkout unless needed","Do not hide refund/cancellation terms","Do not ignore webhook and receipt testing"]},{"id":"dns-cdn-security","name":"DNS, CDN, and security headers","objective":"Choose DNS/CDN/security posture based on host, risk, domain ownership, cache needs, and public exposure.","tiers":[{"tier":"basic-managed-dns","chooseWhen":"A low-risk static site only needs stable records and HTTPS.","examples":["starter site","small brochure site"],"tradeoffs":["Simple","Low overhead","Limited advanced protection"]},{"tier":"cdn-and-cache-control","chooseWhen":"Performance, global delivery, cache rules, redirects, or asset control matter.","examples":["content-heavy site","multi-region audience","large media"],"tradeoffs":["Better performance","Cache invalidation risk","Needs header testing"]},{"tier":"advanced-security-edge","chooseWhen":"The site has auth, payments, private data, public APIs, or attack exposure.","examples":["app with accounts","checkout","admin portal"],"tradeoffs":["Stronger controls","More configuration","Requires monitoring and incident plan"]}],"agentQuestions":["Who controls DNS?","Are redirects and canonical hosts defined?","What headers are required?","What is cached and for how long?"],"guardrails":["Do not mutate Cloudflare/Wrangler accounts without explicit account confirmation","Do not launch with unknown canonical host behavior","Do not cache private responses publicly"]},{"id":"deployment-and-handoff","name":"Deployment and handoff","objective":"Choose deployment workflow, preview environments, rollback, secrets handling, and evidence handoff based on team maturity and risk.","tiers":[{"tier":"manual-static-deploy","chooseWhen":"A small low-risk site can be deployed by a responsible operator with documented commands.","examples":["temporary microsite","internal reference"],"tradeoffs":["Simple","Human-dependent","Can drift without notes"]},{"tier":"ci-preview-deploys","chooseWhen":"Changes need review, preview URLs, automated tests, and safe rollback.","examples":["client site","production marketing site","multi-agent work"],"tradeoffs":["Better quality","More setup","Requires CI ownership"]},{"tier":"multi-environment-release","chooseWhen":"The product has staging, production data, migrations, integrations, or compliance review.","examples":["SaaS","portal","commerce"],"tradeoffs":["Controlled releases","Higher process cost","Requires release discipline"]}],"agentQuestions":["Where are secrets stored?","How are previews created?","How is rollback done?","What evidence must be generated before deploy?"],"guardrails":["Never commit secrets","Do not deploy without QA evidence","Do not leave handoff without commands, risks, and rollback notes"]}],"internationalisation":{"id":"internationalisation","objective":"Decide whether and how to localize before content scales, because retrofitting i18n onto a grown site is the most expensive version of the work.","decisionRule":"Localize when a measurable audience segment cannot buy or comply in the site language, not because a market might exist someday.","tiers":[{"tier":"deliberately-monolingual","chooseWhen":"The audience operates in one language and no regulatory or market evidence demands more.","examples":["this reference (en, documented as deliberate)","local service sites","single-market SaaS"],"tradeoffs":["Zero i18n complexity","Document the decision so it reads as chosen, not forgotten"]},{"tier":"localized-subpaths","chooseWhen":"Two to five locales with shared branding and a translation workflow that can keep parity.","examples":["/es/ subpath localization","docs in two languages"],"tradeoffs":["One domain and zone","hreflang pairs required on every localized page","Stale-translation risk needs a parity check"]},{"tier":"localized-domains-or-subdomains","chooseWhen":"Locales have separate legal entities, pricing, or search markets that justify independent properties.","examples":["country ccTLDs","regional subdomains"],"tradeoffs":["Strongest geo-targeting","Multiplies every QA, crawl, and evidence surface per locale"]}],"technicalRules":["html lang is always set (enforced by qa:seo even on monolingual sites).","hreflang must be reciprocal and include x-default when any second locale ships.","Canonical URLs and hreflang must agree; a localized page canonicalizing to another locale destroys the cluster.","Translate metadata, schema text fields, llms surfaces, and alt text with the copy, or the localized page fails the same QA gates as the original."],"agentQuestions":["Which locale demand is evidence and which is hope?","Who owns translation parity after launch?","Do prices, claims, and legal pages differ by locale?"],"guardrails":["No machine-translated pages without review on claim-bearing copy","No locale launch without its own QA evidence run"]},"siteTypeRecommendations":[{"siteType":"local-service","defaultTiers":["static-cdn","code-and-files","no-database","public-only","direct-contact","privacy-light-analytics"],"upgradeTriggers":["Multiple editors","CRM lead routing","location inventory","booking/payment workflow","large resource library"]},{"siteType":"b2b-saas","defaultTiers":["static-cdn or ssr-or-edge for marketing","headless-cms when marketing owns content","full-auth for app","product-analytics","operational-observability"],"upgradeTriggers":["Logged-in marketing personalization","trial signup","pricing experiments","docs search","security/compliance needs"]},{"siteType":"professional-services","defaultTiers":["static-cdn","code-and-files or headless-cms","managed-forms","indexed-site-search for insights library","privacy-light-analytics"],"upgradeTriggers":["Multi-author publishing","private client resources","webinar workflows","CRM scoring","credential/proof library scale"]},{"siteType":"agent-reference-or-docs","defaultTiers":["static-cdn","code-and-files","ai-retrieval when source citations exist","ci-preview-deploys","crawl/browser/contract QA"],"upgradeTriggers":["Large source corpus","authenticated internal docs","live tool execution","multi-repo documentation","model-evaluation harnesses"]}],"scenarioExamples":[{"id":"owner-stack-marketing-site","scenario":"Public marketing, local service, or professional-services website where SEO/AEO, fast load, source-backed copy, and simple handoff matter more than runtime app behavior.","recommendedStack":[{"layer":"source","choice":"GitHub","why":"Keeps source truth, review history, issues, CI, and future-agent continuation in one inspectable place."},{"layer":"framework","choice":"Astro","why":"Static-first pages are simpler to crawl, faster to ship, easier to audit, and enough when there is no account state."},{"layer":"hosting-dns-cdn","choice":"Cloudflare Pages plus Cloudflare DNS","why":"Matches owner infrastructure, supports fast static hosting, redirects, security headers, previews, and domain control."},{"layer":"forms","choice":"Managed form or direct contact path","why":"Avoids custom backend state until lead routing, CRM sync, or saved submissions are proven requirements."},{"layer":"analytics","choice":"Privacy-light analytics","why":"Gives launch visibility without heavy consent or event-taxonomy complexity."}],"decisionPath":["Confirm the site is public-first and does not require user accounts.","Confirm content can be generated from source files and rebuilt on changes.","Use Astro unless a concrete app requirement cannot be satisfied by static pages, forms, or small serverless functions.","Use Cloudflare only after account ownership and deployment target are clear.","Document upgrade triggers for CMS, CRM, auth, payments, or app behavior without building them early."],"explicitTradeoffs":["Nontechnical editing is weaker unless a CMS is later added.","Runtime personalization should be deferred or handled by small edge/serverless functions.","Lead data lives in the selected form/CRM system, not in the static site repo."],"qaEvidence":["npm run qa:all","npm run qa:domain","npm run qa:crawl-runner","reports/handoff/generated-handoff-report.json"],"overrideTriggers":["Client requires Webflow or a visual CMS","Multiple editors need drafts and approvals","Content inventory is large enough to require CMS governance","Personalized app-like flows become launch requirements"],"blockedChoices":["Next.js chosen only because it is familiar","Custom database for ordinary contact forms","Cloudflare mutation without account confirmation"]},{"id":"technical-docs-agent-reference","scenario":"Documentation, specification, or agent-reference website where agents need to traverse files, endpoints, LLM summaries, route fixtures, schemas, and QA evidence.","recommendedStack":[{"layer":"source","choice":"GitHub","why":"Versioned docs, schemas, generated endpoints, and QA evidence need durable source control."},{"layer":"framework","choice":"Astro","why":"Static docs and machine-readable endpoints stay crawlable, inspectable, and easy for agents to reason about."},{"layer":"hosting-dns-cdn","choice":"Cloudflare Pages plus explicit well-known routes","why":"Static distribution, security headers, and discovery surfaces align with agent-readiness goals."},{"layer":"search","choice":"Static search or source-backed AI retrieval only when citations exist","why":"Agent answers must cite visible/source-backed content instead of synthesizing from private or stale data."},{"layer":"observability","choice":"Domain checks, crawl evidence, browser QA, and contract drift QA","why":"The product is only useful if discovery surfaces and machine contracts stay synchronized."}],"decisionPath":["Start from the main URL and confirm agents can discover manifest, file map, QA contract, LLM files, schemas, and fixture routes.","Keep docs and contracts in versioned source files before adding a CMS.","Expose structured JSON and schemas for every critical concept.","Add AI retrieval only after source boundaries, citation rules, and answer-evidence fixtures exist.","Treat every new endpoint as a contract with schema, registry entry, QA, and handoff evidence."],"explicitTradeoffs":["Static source files require repo access for edits, but preserve traceability.","Adding a CMS can improve editing but risks drift between prose, schemas, and QA contracts.","AI retrieval raises citation, privacy, and stale-source risks unless evidence is enforced."],"qaEvidence":["npm run qa:aeo","npm run qa:contracts","npm run qa:fixtures","npm run qa:all"],"overrideTriggers":["Large documentation team needs editorial roles","Private internal docs require auth","Live tool execution requires server runtime","Search volume requires a dedicated index"],"blockedChoices":["CMS added without export and source-traceability plan","AI retrieval without citations","Agent/API endpoint without method-aware QA"]},{"id":"next-app-with-stripe-portal","scenario":"App-like system with user accounts, dashboards, billing portal, checkout, account state, admin flows, or dynamic React UI where Next.js is justified by real runtime requirements.","recommendedStack":[{"layer":"source","choice":"GitHub","why":"Application changes need review, CI, deployment history, and rollback visibility."},{"layer":"framework","choice":"Next.js","why":"Auth, dashboards, API routes/server actions, dynamic user state, and richer React app patterns make Next.js a practical owner-stack choice."},{"layer":"payments","choice":"Stripe Checkout, Billing Portal, and webhooks","why":"Stripe handles payment collection, subscriptions, invoices, customer portal, and event-driven account updates."},{"layer":"data","choice":"Managed database with migrations and backups","why":"Accounts, entitlements, billing status, and admin workflows require durable state."},{"layer":"observability","choice":"Error tracking, uptime checks, logs, and webhook replay plan","why":"Runtime app behavior and payment flows need operational evidence beyond static crawl checks."}],"decisionPath":["Write the app requirement Astro cannot satisfy before selecting Next.js.","Identify the private data model, roles, auth provider, and account lifecycle.","Map every Stripe event that changes access, subscription, entitlement, or receipt state.","Define database backup, migration, rollback, and secret-management rules.","Add runtime, payment, auth, and webhook QA to the handoff report before launch."],"explicitTradeoffs":["Next.js adds runtime, dependency, deployment, and monitoring complexity compared with Astro.","Stripe simplifies payment collection but shifts correctness to webhook handling and entitlement logic.","Database-backed apps require backup, migration, access-control, and privacy policies."],"qaEvidence":["npm run qa:all","Payment webhook test report","Auth/role boundary test report","Database backup and rollback notes","reports/handoff/generated-handoff-report.json"],"overrideTriggers":["The app is mostly public content and does not need accounts","Shopify owns commerce catalog and checkout","Existing production app uses a different framework","Compliance requires another payment or auth provider"],"blockedChoices":["Next.js for a simple content site","Stripe webhook launch without replay/test evidence","Private data stored without retention and access policy"]},{"id":"content-team-cms-site","scenario":"Marketing or resource website where nontechnical editors need drafts, approvals, scheduled publishing, structured content, or large content inventory management.","recommendedStack":[{"layer":"source","choice":"GitHub for code plus CMS export/backup","why":"Code and infrastructure stay versioned while content governance is handled by the CMS."},{"layer":"framework","choice":"Astro unless runtime personalization is required","why":"Static-first rendering keeps public content crawlable while consuming structured CMS content."},{"layer":"cms","choice":"Headless CMS with roles, schema, drafts, and export path","why":"Editors need workflow support, but future agents need content structure and backup evidence."},{"layer":"hosting","choice":"Cloudflare Pages with rebuild hooks or equivalent preview deploys","why":"Public content can remain static while editorial changes trigger rebuilds."},{"layer":"search","choice":"Indexed site search when the content library is large","why":"Navigation alone becomes insufficient once resources, articles, glossary, and comparison pages scale."}],"decisionPath":["Confirm who edits content and whether they can work through GitHub.","Define CMS content types, required source fields, approval workflow, and export/backup process.","Prove CMS content can still map to page patterns, schema, claim IDs, and LLM summaries.","Set preview and rebuild behavior before editors publish.","Document what content lives in code versus CMS."],"explicitTradeoffs":["CMS improves editing but introduces content/schema drift risk.","Preview and rebuild automation become part of launch readiness.","Source-traceability fields must exist in the CMS, not only in repo docs."],"qaEvidence":["CMS schema/export notes","Preview deploy evidence","npm run qa:aeo","npm run qa:crawl-runner","reports/handoff/generated-handoff-report.json"],"overrideTriggers":["Only agents/developers edit content","Client requires a visual builder","Content changes are rare and review-heavy","Private editorial workflow requires an authenticated app"],"blockedChoices":["CMS with no export path","CMS fields that bypass claim/source rules","Visual builder that prevents route/schema/LLM QA"]},{"id":"commerce-or-workshop-checkout","scenario":"Site selling a workshop, deposit, subscription, productized service, or paid resource where payment is part of the public conversion path.","recommendedStack":[{"layer":"source","choice":"GitHub","why":"Offer copy, terms, checkout links, and handoff evidence need review history."},{"layer":"framework","choice":"Astro for simple public checkout paths; Next.js only for account/stateful purchase flows","why":"Most simple offers can link to Stripe without adding app runtime."},{"layer":"payments","choice":"Stripe Payment Links or Checkout first","why":"Stripe covers simple payment collection without custom checkout complexity."},{"layer":"forms-crm","choice":"Managed form or CRM routing for qualification","why":"High-touch offers often need qualification before or after payment."},{"layer":"legal-ops","choice":"Visible terms, refund/cancellation policy, receipts, and support path","why":"Payment conversion is not ready without buyer expectations and operational follow-through."}],"decisionPath":["Classify whether the site sells directly, collects deposits, or routes to invoice/proposal.","Use Stripe Payment Links or Checkout before custom payment UI.","State refund, cancellation, delivery, tax, and support expectations near the payment path.","Add webhooks only if access, fulfillment, receipts, or entitlement state must update automatically.","Test the full payment path before launch and save evidence."],"explicitTradeoffs":["Simple Stripe-hosted checkout is less customizable but safer and faster.","Custom checkout can improve UX but increases testing, compliance, and webhook burden.","Subscriptions require cancellation, portal, entitlement, and dunning decisions."],"qaEvidence":["Stripe test-mode checkout evidence","Terms/refund page evidence","npm run qa:seo","npm run qa:aeo","reports/handoff/generated-handoff-report.json"],"overrideTriggers":["Shopify owns catalog, inventory, tax, or fulfillment","Marketplace payments are required","Client already has a required processor","Entitlements require app accounts"],"blockedChoices":["Custom checkout without need","Payment path without refund/cancellation terms","Subscription without billing portal or support path"]}],"agentWorkflow":["Classify the site type and business model before choosing tools.","List the required workflows: edit content, collect leads, authenticate users, store data, take payment, search content, publish media, monitor runtime, and deploy safely.","For each workflow, choose the lowest tier that satisfies current requirements.","Document upgrade triggers separately from launch requirements.","Add guardrails for secrets, privacy, backups, rollback, canonical host, and data retention.","Map infrastructure choices back to QA evidence: route, SEO, AEO, browser, crawl, domain, copy, contract, and handoff checks.","Record remaining infrastructure risks in the handoff report."],"antiPatterns":[{"id":"platform-first-thinking","issue":"The agent starts with a favorite platform instead of requirements.","fix":"Classify workflows and choose tiers from explicit needs."},{"id":"premature-app-complexity","issue":"A public marketing site inherits auth, databases, and runtime hosting without a real workflow.","fix":"Default to static/CDN until dynamic behavior is required."},{"id":"cms-without-governance","issue":"A CMS is added without source traceability, permissions, backup/export, or approval workflow.","fix":"Define editor roles, content schema, export path, and claim rules before adoption."},{"id":"runtime-without-observability","issue":"SSR, serverless, integrations, or checkout launch without logs, alerts, and error evidence.","fix":"Add monitoring and incident ownership before launch."},{"id":"hidden-ops-ownership","issue":"The repo does not say who owns DNS, deploys, secrets, backups, analytics, or rollback.","fix":"Record ownership and commands in docs and handoff reports."}],"qaGates":["npm run qa:aeo","npm run qa:domain","npm run qa:crawl-runner","npm run qa:handoff","npm run qa:all"],"passCriteria":["Every major infrastructure area has tiered options, choose-when guidance, tradeoffs, agent questions, and guardrails.","Site-type recommendations give default tiers and upgrade triggers.","Agents can explain why the chosen infrastructure is enough for launch and what would trigger an upgrade.","Infrastructure choices map to QA and handoff evidence.","No infrastructure recommendation requires guessing a vendor account, secret, or deployment target."],"objectiveAlignment":"Adds the missing infrastructure decision layer so future agents can choose the right technical foundation for each website rather than treating all builds as the same template."},"handoff_reports":{"objective":"Make final handoff durable, evidence-backed, and useful to the next agent or maintainer.","why":"A website operating system is incomplete if work ends with passing tests but no record of scope, evidence, residual risks, and next actions. Handoff reports preserve continuity after the chat context disappears.","defaultReportPath":"reports/handoff/","exampleReportPath":"reports/handoff/example-handoff-report.json","requiredSections":[{"id":"outcome","title":"Outcome","requiredFields":["title","status","scope","objective_alignment"],"why":"The next agent needs to know what was actually accomplished and how it maps to the system objective."},{"id":"changes-made","title":"Changes made","requiredFields":["completed_work.item","completed_work.evidence"],"why":"A handoff should name the durable files, endpoints, reports, and contracts changed."},{"id":"verification","title":"Verification","requiredFields":["verification.command","verification.status","verification.evidence"],"why":"Passing claims must cite command output, generated reports, or other inspectable evidence."},{"id":"evidence","title":"Evidence","requiredFields":["contract endpoints","schemas","QA reports","source/crawl/browser/model evidence where relevant"],"why":"Evidence lets future agents trust, reproduce, or challenge the handoff."},{"id":"risks","title":"Remaining risks","requiredFields":["remaining_risks.risk","remaining_risks.severity","remaining_risks.next_action"],"why":"A clean handoff distinguishes complete work from unresolved risk."},{"id":"next-actions","title":"Next actions","requiredFields":["next_actions.task_id","next_actions.why"],"why":"Next work should connect back to the structured backlog and rationale."}],"evidenceSources":["/agent-manifest.json","/contract-registry.json","/agent-tasks.json","/qa-contract.json","/browser-visual-qa.json","/crawl-evidence.json","/aeo-geo-context.json","/why-explanations.json","/real-site-comparisons.json","reports/browser/browser-visual-report.json","reports/crawl/crawl-evidence-report.json"],"closeoutChecklist":["State the outcome and objective alignment.","List files/endpoints/contracts changed.","List verification commands and status.","Link generated reports and evidence paths.","Name unresolved risks with severity and next action.","Point to next tasks from /agent-tasks.json.","State whether a dev server, background process, or open command remains active."],"qaGates":["npm run qa:all","npm audit --omit=dev"],"stressTests":["Remove verification evidence from a handoff fixture and confirm QA fails.","Reference a missing task ID in next actions and confirm review catches it.","Try to mark a handoff complete while residual risks are empty for a fixture site and require explicit none.","Ask a future agent to continue work using only the handoff report and /agent-tasks.json.","Compare handoff evidence against the contract registry and confirm endpoints still exist."],"passCriteria":["Handoff contract endpoint exists.","Example handoff report fixture exists.","Required sections include outcome, changes, verification, evidence, risks, and next actions.","Evidence sources cite current agent contracts and generated reports.","QA validates the fixture path and required handoff fields."],"warningCriteria":["A handoff has passing commands but no generated report paths.","A handoff has next actions but no task IDs.","A handoff has risks but no severity.","A handoff cites stale evidence from a previous build."],"failCriteria":["No handoff report is generated for substantial work.","Verification status is claimed without evidence.","Risks are omitted rather than explicitly marked none.","Next actions do not map to the structured backlog.","Open background work is not disclosed."],"objectiveAlignment":"Preserves the operating system's state so future agents can continue from evidence instead of reconstructing context from memory."},"aeo_geo_context":{"objective":"Make answer-engine and generative-engine context explicit, testable, source-bound, and reusable by future agents.","why":"AEO/GEO work cannot rely on normal pages alone. Agents need prompt fixtures, expected answer context, citation paths, source boundaries, blocked-claim checks, and model-review records before claiming answer readiness.","contextSurfaces":[{"id":"llm-entry-surfaces","surface":"llms.txt and llms-full.txt","purpose":"Give models a concise and expanded route into the site's purpose, endpoints, schema, QA, and examples.","evidenceRoutes":["/llms.txt","/llms-full.txt"],"requiredChecks":["Both routes return 200","llms-full.txt includes QA, source traceability, crawl evidence, and contract registry"]},{"id":"schema-entity-surfaces","surface":"JSON-LD and schema endpoint map","purpose":"Expose stable entity facts that match visible page content.","evidenceRoutes":["/schemamap.xml","/schema.json","/services/schema.json","/contact/schema.json"],"requiredChecks":["Schema routes return JSON","Organization and WebSite facts are stable","Service and LocalBusiness facts remain source-backed"]},{"id":"source-boundary-surfaces","surface":"Source traceability and claim ledger","purpose":"Prevent answer engines from receiving unsupported claims as approved facts.","evidenceRoutes":["/source-traceability.json","data/working/example-client-facts.json","data/derived/example-page-brief.json"],"requiredChecks":["Allowed claims name source paths","Blocked claims have no public locations","Answer evidence checks blocked claim IDs"]},{"id":"evaluation-surfaces","surface":"SEO/AEO evaluation, site studies, crawl evidence, and prompt fixtures","purpose":"Turn answer-engine readiness into evidence rather than narrative.","evidenceRoutes":["/seo-aeo-evaluation.json","/site-studies.json","/crawl-evidence.json","data/derived/aeo-geo-context/example-prompt-set.json"],"requiredChecks":["Prompt fixtures exist","Answer evidence fixture exists","Findings map to roadmap and QA gates"]}],"promptFixtures":[{"id":"service-scope-answer","fixturePath":"data/derived/aeo-geo-context/example-prompt-set.json","promptType":"service understanding","expectedEvidence":["/services/","/services/schema.json","/llms-full.txt","/source-traceability.json"],"blockedBehavior":"Do not add service categories beyond approved source facts.","passCriteria":"Answer names only source-backed services and cites visible/schema/LLM context."},{"id":"brightline-service-area-answer","fixturePath":"data/derived/aeo-geo-context/demo-prompt-set.json","promptType":"local entity understanding with fictional boundary","expectedEvidence":["/demo/brightline/","/demo/brightline/service-areas/","/demo/brightline/schema.json","/llms.txt"],"blockedBehavior":"Do not surface the counties without the fictional disclosure, and never present demo facts as real.","passCriteria":"Answer names the three counties and the fictional boundary together, citing visible copy and labeled schema."},{"id":"logpilot-capability-answer","fixturePath":"data/derived/aeo-geo-context/demo-prompt-set.json","promptType":"product capability understanding","expectedEvidence":["/demo/logpilot/product/","/demo/logpilot/schema.json","/source-traceability.json"],"blockedBehavior":"Do not extend the 30/90/365 retention set or imply correlation/alerting capability the pages disclaim.","passCriteria":"Answer states exact capability boundaries including what the product does not do."},{"id":"logpilot-comparison-caveat-answer","fixturePath":"data/derived/aeo-geo-context/demo-prompt-set.json","promptType":"comparison with preserved caveats","expectedEvidence":["/demo/logpilot/comparison/","FAQPage comparison schema"],"blockedBehavior":"Do not strip the where-the-alternative-wins caveat or the as-of dates.","passCriteria":"Answer reproduces the dated factual difference and the case where the alternative is the right choice."},{"id":"reference-system-orientation-answer","fixturePath":"data/derived/aeo-geo-context/demo-prompt-set.json","promptType":"system orientation","expectedEvidence":["/","/llms.txt","/agent-manifest.json"],"blockedBehavior":"Do not frame the reference as a human marketing template.","passCriteria":"Answer states the agent-first purpose and the manifest-first reading order."},{"id":"local-entity-answer","fixturePath":"data/derived/aeo-geo-context/example-prompt-set.json","promptType":"local entity understanding","expectedEvidence":["/contact/","/contact/schema.json","/schema.json","/source-traceability.json"],"blockedBehavior":"Do not claim real production geography until fixture facts are replaced.","passCriteria":"Answer preserves fixture qualifier and cites source-backed service-area context."}],"answerEvidenceRecords":[{"id":"example-supported-answer-record","fixturePath":"data/derived/aeo-geo-context/example-answer-evidence.json","requiredFields":["prompt_id","answer_status","supporting_routes","required_citations","blocked_claim_checks","residual_risk"],"why":"Answer reviews need consistent evidence fields so agents can compare runs across models and dates."},{"id":"baseline-site-grounded-run-2026-06-10","fixturePath":"data/derived/aeo-geo-context/baseline-answer-evidence-2026-06-10.json","requiredFields":["prompt_id","answer_status","supporting_routes","required_citations","blocked_claim_checks","residual_risk"],"why":"The first real dated record: site-grounded runs against the live deployment proving each prompt is answerable from published surfaces, with the honest limit that public answer-engine citations cannot exist before indexing."}],"citationRules":["Every answer-ready claim should be traceable to a visible route, schema endpoint, LLM surface, or source artifact.","Answers must cite source-traceability records for claims that could otherwise drift.","Blocked claim IDs must be checked before marking an answer supported.","Model outputs should preserve qualifiers for fixture, example, stale, or partial data.","Prompt records should include model family, date, prompt, answer status, support routes, citations, and residual risk."],"qaGates":["npm run qa:seo","npm run qa:aeo","npm run qa:crawl","npm run qa:all"],"stressTests":["Ask the service-scope prompt and verify the answer cites only approved services.","Ask the local-entity prompt and verify fixture qualifiers are preserved.","Remove a source-traceability claim and confirm AEO/GEO context review cannot mark the answer supported.","Remove llms-full.txt from the context surface list and confirm QA fails.","Compare model answers before and after a schema/content change and record residual risk."],"passCriteria":["Context surfaces include LLM, schema, source, and evaluation surfaces.","Prompt fixtures exist on disk.","Answer evidence fixture exists on disk.","Citation rules include blocked-claim and residual-risk handling.","QA validates endpoint shape, fixture paths, and required context sections."],"warningCriteria":["A model answer is directionally correct but lacks citations.","A prompt fixture exists but has not been run against current production context.","A model answer uses stale crawl or schema evidence.","An answer requires a qualifier that is not visible near the cited source."],"failCriteria":["Prompt or answer evidence fixtures are missing.","Context surfaces omit LLM, schema, source traceability, or evaluation evidence.","A model answer includes blocked claims.","AEO/GEO readiness is claimed without prompt, citation, and residual-risk evidence."],"objectiveAlignment":"Extends the operating system from crawlable pages into answer-ready context that agents can inspect, test, and cite."},"page_patterns":[{"id":"homepage-entity-summary","title":"Homepage entity summary","routeExamples":["/"],"purpose":"Orient agents, crawlers, and users to the entity, offer, audience, proof, and next routes.","requiredSections":["Entity and positioning H1","Primary offer or purpose","Who/where fit","Proof summary","Internal links to core routes","Machine-readable discovery links when agent-facing"],"requiredSchema":["Organization","WebSite","LocalBusiness or domain-specific entity","FAQPage when visible FAQs exist"],"seoRequirements":["Canonical root URL","Unique title and description","One H1","Open Graph parity","Index,follow robots"],"aeoRequirements":["Direct answer to what this site/entity is","Stable entity names","Links to manifest/LLM endpoints when agent-facing","Concise facts before deeper detail"],"traceabilityRequirements":["Identity, offer, service area, proof, and claims must map to allowed source facts"],"qaGates":["npm run qa:all","Schema endpoint review","Source traceability review"],"antiPatterns":["Hero copy with no concrete entity or offer","Unsupported superiority claims","Homepage-only facts missing from manifest or LLM summary"],"stressTests":["Ask an agent to explain the site purpose from the homepage only","Remove the manifest link and confirm agent-readiness QA catches the gap","Try adding an unproved claim and confirm traceability blocks it"],"completionCriteria":["Entity and purpose are clear","Core routes are linked","Schema matches visible facts","Agent endpoints reflect homepage claims","qa:all passes"]},{"id":"service-offer-page","title":"Service or offer page","routeExamples":["/services/"],"purpose":"Explain a service, package, productized offer, or implementation path with scope, process, proof, and next step.","requiredSections":["Problem","Offer scope","Inputs required","Process","Deliverables","Proof","FAQ or objections","Next step"],"requiredSchema":["Service","BreadcrumbList","FAQPage when visible FAQs exist"],"seoRequirements":["Service-specific title and description","Canonical service URL","Internal links to proof, contact, and related resources","No duplicate H1 intent across services"],"aeoRequirements":["Direct answers for what is included, who it is for, where/when it applies, and how to start","Caveats near scope limitations"],"traceabilityRequirements":["Service scope, deliverables, proof, and pricing/guarantee claims require source evidence"],"qaGates":["npm run qa:all","Claim/source audit","Internal-link review"],"antiPatterns":["Vague capability list","Process without deliverables","Proof claims without evidence","Schema facts not visible on page"],"stressTests":["Ask an agent to list the service inputs and outputs","Try to add an unsupported guarantee and confirm it is blocked","Remove proof links and confirm completion criteria fails"],"completionCriteria":["Scope and deliverables are explicit","Proof and next step are linked","Schema is visible-fact-only","qa:all passes"]},{"id":"proof-evidence-page","title":"Proof evidence page","routeExamples":["/proof/"],"purpose":"Make claims inspectable through case studies, testimonials, metrics, screenshots, crawl reports, reviews, or other permissioned artifacts.","requiredSections":["Claim being supported","Evidence artifact","Source/permission note","Before or baseline","Work/change","Result","Limitations or caveats"],"requiredSchema":["Review when eligible","CreativeWork","Article or BreadcrumbList when appropriate"],"seoRequirements":["Outcome language only when approved","Canonical proof URL","Links back to related service/product pages"],"aeoRequirements":["Keep caveats near metrics","Explain context and date ranges","Do not summarize private proof into public LLM endpoints"],"traceabilityRequirements":["Every testimonial, metric, logo, screenshot, and result requires permission and source evidence"],"qaGates":["npm run qa:all","Permission/privacy review","Claim/source audit"],"antiPatterns":["Anonymous proof without permission context","Metrics without date range","Review schema on non-eligible testimonials","Private proof leaking into LLM summaries"],"stressTests":["Ask an agent to find evidence for a claim","Remove permission notes and confirm readiness fails","Attempt to publish private proof in llms-full.txt and confirm it is blocked"],"completionCriteria":["Every proof item has source and permission status","Claims stay caveated","Schema eligibility is clear","qa:all passes"]},{"id":"answer-ready-resource-page","title":"Answer-ready resource page","routeExamples":["/resources/"],"purpose":"Answer a concrete question or explain an entity/topic in a way search engines and answer systems can reuse safely.","requiredSections":["Direct answer","Definition or context","Detailed explanation","Comparison or decision criteria when relevant","Caveats","Related entity links","FAQ"],"requiredSchema":["Article","FAQPage","DefinedTerm when defining an entity","BreadcrumbList"],"seoRequirements":["Search-intent-aligned title","Stable URL","Internal links to definitions/proof/services","Description summarizes the answer without overclaiming"],"aeoRequirements":["Direct answer before nuance","Caveats near recommendations","Entity links and definitions are stable","LLM summary uses canonical answer"],"traceabilityRequirements":["Definitions, recommendations, and comparisons must cite approved sources or internal proof"],"qaGates":["npm run qa:all","Internal-link review","Schema review","Source/reference review"],"antiPatterns":["Long intro before answer","Uncaveated recommendations","Glossary terms without stable URLs","FAQ schema for questions not visible on page"],"stressTests":["Ask an agent to answer the target question from the page","Remove a definition link and confirm review catches it","Try to publish uncaveated advice and confirm traceability flags it"],"completionCriteria":["Question is answered directly","Entities are linked","Caveats are visible","Schema matches content","qa:all passes"]},{"id":"contact-conversion-page","title":"Contact conversion page","routeExamples":["/contact/"],"purpose":"Give users, crawlers, and agents a clear next step with contact facts, qualification notes, service fit, and accessible interaction paths.","requiredSections":["Contact options","Expected next step","Service/fit qualifier","Location or service area when relevant","Privacy or form expectation","Fallback path"],"requiredSchema":["ContactPage","Organization or LocalBusiness"],"seoRequirements":["Contact-specific title and description","Canonical contact URL","Indexable when it contains useful business facts","No missing H1"],"aeoRequirements":["Directly state how to contact, what information to provide, and who the contact path is for"],"traceabilityRequirements":["Email, phone, address, service area, response-time, and availability claims require source-backed configuration"],"qaGates":["npm run qa:all","Keyboard/contact path check","Mobile contact check"],"antiPatterns":["Form-only contact with no fallback","Unverified response-time promises","Contact route missing H1","Phone/email hidden from crawlers"],"stressTests":["Ask an agent to find the fastest contact path","Remove fallback contact info and confirm completion criteria fails","Try adding unverified response-time claim and confirm it is blocked"],"completionCriteria":["Contact options are visible and accessible","Fit/qualification is clear","Contact facts come from source config","qa:all passes"]},{"id":"schema-backed-detail-page","title":"Schema-backed detail page","routeExamples":["/services/schema.json","/proof/schema.json","/resources/schema.json","/contact/schema.json"],"purpose":"Expose page facts through structured data that matches visible content and source-backed claims.","requiredSections":["Visible fact inventory","Schema type selection","Stable entity IDs where needed","Breadcrumb or relationship context","Source-backed claim references"],"requiredSchema":["Organization","WebSite","Service","Article","FAQPage","BreadcrumbList","LocalBusiness as appropriate"],"seoRequirements":["Schema endpoint appears in schemamap when reusable","Schema does not contradict canonical page metadata","Schema route returns valid JSON"],"aeoRequirements":["Machine facts match visible page facts","No private or blocked claims appear in schema","Entity IDs stay stable across pages"],"traceabilityRequirements":["Every schema fact must be visible on page, in site config, or allowed by source traceability"],"qaGates":["npm run qa:all","Schema endpoint review","Source traceability review"],"antiPatterns":["Schema-only claims","Private facts in JSON-LD","Changing entity IDs without migration reason","FAQ schema for hidden questions"],"stressTests":["Ask an agent to compare schema facts to visible page facts","Try adding a blocked claim to schema and confirm it is rejected","Remove schema endpoint from schemamap and confirm QA catches it"],"completionCriteria":["Schema endpoint returns valid JSON","Schema matches visible/source-backed facts","Entity IDs are stable","qa:all passes"]}],"page_pattern_fixtures":[{"id":"homepage-agent-entity-fixture","patternId":"homepage-entity-summary","route":"/fixtures/page-patterns/homepage-agent-entity/","title":"Homepage Agent Entity Fixture","scenario":"A public website homepage that must let an agent identify the entity, offer, audience, proof, next routes, and machine-readable discovery surfaces without prior chat context.","canonicalQuestion":"What is this site, who is it for, what proof exists, and where should the agent inspect next?","requiredVisibleSections":["Entity summary","Primary offer","Audience fit","Proof summary","Core route links","Machine discovery links","Source and claim notes"],"metadataChecks":["One H1 states the entity and purpose","Title and description identify the agent-facing reference","Canonical route matches fixture route","Open Graph metadata mirrors the page purpose"],"schemaChecks":["Organization and WebSite schema come from BaseLayout","WebPage schema names the fixture and pattern ID","Schema does not introduce claims missing from visible sections"],"traceabilityChecks":["Identity, proof, and next-step claims cite approved fixture evidence","Unsupported superiority language is listed as a blocked example"],"sourceEvidence":["src/data/agent-reference.ts: pagePatterns.homepage-entity-summary","src/data/agent-reference.ts: systemPurpose","/agent-manifest.json","/llms-full.txt"],"goodExample":"A homepage starts with an entity summary, links to agent-manifest, file-map, examples, QA contract, and states what claims are source-backed.","badExample":"A homepage uses a clever hero line, vague transformation promise, and no manifest or source route links.","agentInstructions":["Read the H1 and first section before judging visual design","Verify the linked machine endpoints exist","Compare homepage claims to manifest and LLM summaries","Run qa:fixtures after changing this pattern"],"qaGates":["npm run qa:fixtures","npm run qa:seo","npm run qa:aeo"],"completionCriteria":["Agent can explain entity and purpose from the fixture","Fixture links to machine discovery surfaces","Visible claims match schema and source notes"]},{"id":"service-offer-scope-fixture","patternId":"service-offer-page","route":"/fixtures/page-patterns/service-offer-scope/","title":"Service Offer Scope Fixture","scenario":"A service page where an agent must separate buyer pain, scope, inputs, deliverables, proof, objections, and next step before writing copy or schema.","canonicalQuestion":"What is included in the offer, what inputs are required, what proof supports it, and what is the next step?","requiredVisibleSections":["Problem","Offer scope","Inputs required","Process","Deliverables","Proof","Objections","Next step","Source and claim notes"],"metadataChecks":["One H1 identifies the specific service fixture","Title and description are service-specific","Canonical route is the fixture route"],"schemaChecks":["WebPage schema names service-offer-page as the pattern","Service schema requirements are visible as obligations","No pricing, guarantee, or credential claims appear without source notes"],"traceabilityChecks":["Scope, deliverables, proof, and next-step claims cite fixture evidence","Unsupported guarantees are called out as blocked"],"sourceEvidence":["src/data/agent-reference.ts: pagePatterns.service-offer-page","/source-traceability.json","/services/schema.json"],"goodExample":"The offer states the inputs required, the work sequence, deliverables, proof link, scope caveats, and a low-friction next step.","badExample":"The service page promises growth, lists capabilities, and asks for a call without defining outputs or evidence.","agentInstructions":["Map every offer claim to source evidence before polishing copy","Keep scope caveats near benefits","Link proof and contact routes","Run qa:fixtures after changing route structure"],"qaGates":["npm run qa:fixtures","npm run qa:seo","npm run qa:aeo"],"completionCriteria":["Inputs and deliverables are explicit","Proof and next step are visible","Schema obligations match visible facts"]},{"id":"proof-evidence-artifact-fixture","patternId":"proof-evidence-page","route":"/fixtures/page-patterns/proof-evidence-artifact/","title":"Proof Evidence Artifact Fixture","scenario":"A proof page where an agent must preserve permission, baseline, action, result, metric context, and caveats before using evidence in copy or schema.","canonicalQuestion":"What claim is being supported, what evidence proves it, and what limitations must stay attached?","requiredVisibleSections":["Supported claim","Evidence artifact","Permission note","Baseline","Work performed","Result","Limitations","Related offer link","Source and claim notes"],"metadataChecks":["One H1 identifies the proof fixture","Title avoids unsupported outcome hype","Description includes evidence context"],"schemaChecks":["WebPage schema names proof-evidence-page as the pattern","Review schema is treated as conditional, not automatic","Metrics require dates and context"],"traceabilityChecks":["Every result, testimonial, screenshot, logo, or metric has source and permission status","Private evidence cannot leak to LLM summaries"],"sourceEvidence":["src/data/agent-reference.ts: pagePatterns.proof-evidence-page","/source-traceability.json","/crawl-evidence.json"],"goodExample":"A proof item states the claim, evidence type, permission status, baseline, action, result, date range, caveat, and related service.","badExample":"A proof page shows anonymous wins, percentages without dates, and review schema for a quote that is not eligible.","agentInstructions":["Classify public, private, or sanitized proof before publishing","Keep metric caveats next to metrics","Do not place private proof in LLM endpoints","Run qa:fixtures after proof pattern changes"],"qaGates":["npm run qa:fixtures","npm run qa:crawl","npm run qa:aeo"],"completionCriteria":["Claim, evidence, permission, and caveat are visible","Schema eligibility is explicit","Private-proof boundaries are documented"]},{"id":"answer-ready-resource-fixture","patternId":"answer-ready-resource-page","route":"/fixtures/page-patterns/answer-ready-resource/","title":"Answer Ready Resource Fixture","scenario":"A resource page where an agent must answer the target question directly, then add definitions, nuance, decision criteria, caveats, and related entity links.","canonicalQuestion":"What is the direct answer, what entities matter, what caveats apply, and what should the reader inspect next?","requiredVisibleSections":["Direct answer","Definition","Detailed explanation","Decision criteria","Caveats","Related entity links","FAQ","Source and claim notes"],"metadataChecks":["One H1 matches the target question intent","Title and description answer without overclaiming","Canonical route is stable"],"schemaChecks":["WebPage schema names answer-ready-resource-page as the pattern","Article, FAQPage, DefinedTerm, and BreadcrumbList obligations map to visible sections","FAQ questions must be visible"],"traceabilityChecks":["Definitions and recommendations cite source or internal proof","Caveats remain attached to recommendations"],"sourceEvidence":["src/data/agent-reference.ts: pagePatterns.answer-ready-resource-page","/aeo-geo-context.json","/llms-full.txt"],"goodExample":"The page begins with the answer, defines terms, gives criteria, keeps caveats near recommendations, and links to related proof or services.","badExample":"The page opens with a long intro, hides the answer, recommends a tool without criteria, and marks invisible questions as FAQ schema.","agentInstructions":["Write the direct answer before expanding context","Link stable entity definitions","Keep caveats near recommendations","Run qa:fixtures after changing resource structure"],"qaGates":["npm run qa:fixtures","npm run qa:aeo"],"completionCriteria":["Question is answered directly","Entities and caveats are visible","Schema requirements match the visible FAQ and article sections"]},{"id":"contact-conversion-fixture","patternId":"contact-conversion-page","route":"/fixtures/page-patterns/contact-conversion/","title":"Contact Conversion Fixture","scenario":"A contact page where an agent must expose the next step, contact options, fit qualifier, expectations, service area, fallback path, and privacy note.","canonicalQuestion":"How should a qualified person contact the business, what should they provide, and what fallback exists?","requiredVisibleSections":["Contact options","Expected next step","Fit qualifier","Service area","Privacy expectation","Fallback path","Source and claim notes"],"metadataChecks":["One H1 identifies the contact fixture","Title and description describe the contact path","Contact facts are visible to crawlers"],"schemaChecks":["WebPage schema names contact-conversion-page as the pattern","ContactPage and Organization obligations are visible","Response-time claims require source-backed configuration"],"traceabilityChecks":["Email, phone, address, service area, response time, and availability claims require configured source facts","Form-only contact is blocked unless fallback is documented"],"sourceEvidence":["src/data/agent-reference.ts: pagePatterns.contact-conversion-page","/contact/schema.json","src/site.config.ts"],"goodExample":"The contact page states who should reach out, what to include, what happens next, the privacy expectation, and a fallback path.","badExample":"The contact page has only an embedded form, no fallback, no service-fit qualifier, and an unverified response-time promise.","agentInstructions":["Confirm contact facts come from config before publishing","Provide a crawler-visible fallback path","Keep privacy expectations close to the form path","Run qa:fixtures after changing contact pattern"],"qaGates":["npm run qa:fixtures","npm run qa:seo","npm run qa:aeo"],"completionCriteria":["Contact options and fallback are visible","Fit and expectations are clear","Contact claims trace to source configuration"]},{"id":"schema-backed-detail-fixture","patternId":"schema-backed-detail-page","route":"/fixtures/page-patterns/schema-backed-detail/","title":"Schema Backed Detail Fixture","scenario":"A schema-backed detail page where an agent must compare visible facts, schema type, entity IDs, breadcrumbs, source claims, and blocked private facts.","canonicalQuestion":"Which visible facts are safe to expose through schema, and which facts must be blocked or sourced first?","requiredVisibleSections":["Visible fact inventory","Schema type selection","Stable entity IDs","Relationship context","Source-backed claim references","Blocked schema examples","Source and claim notes"],"metadataChecks":["One H1 identifies the schema fixture","Title and description describe schema validation","Canonical route is stable"],"schemaChecks":["WebPage schema names schema-backed-detail-page as the pattern","Schema facts are visible or source-backed","Entity IDs stay stable across related endpoints"],"traceabilityChecks":["Every schema fact maps to visible content, site config, or source traceability","Private or blocked facts are excluded"],"sourceEvidence":["src/data/agent-reference.ts: pagePatterns.schema-backed-detail-page","/schemamap.xml","/schema.json","/source-traceability.json"],"goodExample":"The route lists visible facts, source IDs, schema type, entity ID, related schema endpoints, and blocked facts that must not appear in JSON-LD.","badExample":"The schema endpoint adds credentials, hidden FAQ answers, private service areas, or unstable entity IDs not visible on the page.","agentInstructions":["Inventory visible facts before editing JSON-LD","Check source traceability for every schema claim","Keep entity IDs stable","Run qa:fixtures after changing schema-backed patterns"],"qaGates":["npm run qa:fixtures","npm run qa:aeo"],"completionCriteria":["Visible fact inventory exists","Blocked schema facts are named","Schema and source-traceability surfaces align"]}],"browser_visual_qa":{"objective":"Prove desktop and mobile rendering quality with reproducible browser checks and screenshot evidence.","why":"Static route, SEO, and schema checks do not prove that text fits, headings are visible, layouts avoid horizontal overflow, or pages are usable at mobile and desktop widths.","command":"npm run qa:browser","reportPath":"reports/browser/browser-visual-report.json","screenshotDirectory":"reports/browser/screenshots/","baselineDirectory":"tests/browser/baselines/","diffDirectory":"reports/browser/diffs/","baselineUpdateCommand":"QA_UPDATE_BASELINES=1 npm run qa:browser","viewports":[{"id":"desktop","width":1440,"height":1000,"why":"Catches wide-layout hierarchy, card/grid, and navigation issues."},{"id":"mobile","width":390,"height":844,"why":"Catches common phone-width wrapping, clipping, overflow, and navigation issues."}],"routes":[{"path":"/","why":"Main agent entry and first-viewport orientation."},{"path":"/agent-start/","why":"Agent onboarding path."},{"path":"/repo-map/","why":"File-system discovery path."},{"path":"/standards/","why":"Specification mapping path."},{"path":"/workflows/","why":"Execution workflow path."},{"path":"/examples/","why":"Pattern/example discovery path."},{"path":"/copy-lab/","why":"Conversion copy training and weak/strong example path."},{"path":"/fixtures/page-patterns/","why":"Concrete page-pattern route fixture discovery path."},{"path":"/fixtures/design-system/","why":"Concrete design-system fixture discovery path."},{"path":"/qa-contract/","why":"Quality contract explanation path."},{"path":"/demo/brightline/","why":"Canonical demo homepage proving the playbook-built entity summary renders correctly."},{"path":"/demo/brightline/services/","why":"Demo service-offer page rendering check."},{"path":"/demo/brightline/service-areas/","why":"Demo service-area detail page rendering check."},{"path":"/demo/brightline/proof/","why":"Demo proof page rendering check."},{"path":"/demo/brightline/contact/","why":"Demo contact/conversion page rendering check."},{"path":"/demo/logpilot/","why":"SaaS demo homepage with the dark LogPilot brand tokens."},{"path":"/demo/logpilot/product/","why":"SaaS demo product page rendering check."},{"path":"/demo/logpilot/use-cases/","why":"SaaS demo use-case page rendering check."},{"path":"/demo/logpilot/integrations/","why":"SaaS demo integrations page rendering check."},{"path":"/demo/logpilot/comparison/","why":"SaaS demo comparison page rendering check."}],"checks":[{"id":"screenshot-capture","severity":"critical","method":"Capture full-page PNG screenshots for every configured route and viewport.","passCriteria":"Every route/viewport pair has a screenshot path in the report.","failCriteria":"Any screenshot is missing or the browser cannot render a route."},{"id":"visible-heading","severity":"critical","method":"Evaluate the DOM for exactly one visible H1 per route.","passCriteria":"Every checked page has exactly one visible H1.","failCriteria":"A checked page has no H1, multiple H1s, or a hidden H1."},{"id":"horizontal-overflow","severity":"critical","method":"Compare document scroll width and element bounding boxes against viewport width.","passCriteria":"No document or visible element extends beyond the viewport.","failCriteria":"Document or visible elements create horizontal overflow."},{"id":"text-clipping","severity":"warning","method":"Compare text-bearing element scroll width against client width.","passCriteria":"No likely clipped text is detected.","failCriteria":"Potential clipping is recorded as a warning for review."},{"id":"visual-diff-baseline","severity":"critical","method":"Compare every route/viewport screenshot against its committed baseline under tests/browser/baselines/ with pixelmatch; intentional changes are accepted via QA_UPDATE_BASELINES=1. A synthetic mutated-screenshot control must always register as different.","passCriteria":"Every screenshot matches its baseline within the documented diff ratio, and the mutation control detects changed pixels.","failCriteria":"A screenshot differs beyond the diff ratio or changes dimensions without a baseline update, or the diff engine fails its negative control. Failures cite route, viewport, baseline path, and a saved diff image."},{"id":"keyboard-focus-navigation","severity":"critical","method":"Tab through each desktop route, recording distinct focus stops and whether each focused element shows a visible outline or box-shadow indicator.","passCriteria":"Every route exposes at least two distinct keyboard focus stops and focused elements have visible indicators.","failCriteria":"A route is not keyboard-operable (fewer than two focus stops). Stops without visible indicators are warnings."},{"id":"axe-accessibility","severity":"critical","method":"Run axe-core with the WCAG 2.0/2.1/2.2 A+AA and best-practice tag sets on every route and viewport.","passCriteria":"No critical or serious axe violations on any route/viewport.","failCriteria":"Critical or serious violations fail with rule IDs and sample node targets; moderate/minor violations are warnings."}],"passCriteria":["Browser launches successfully.","Every configured route renders at every configured viewport.","Screenshots are saved under reports/browser/screenshots/.","The JSON report is saved at reports/browser/browser-visual-report.json.","No critical visual findings are present."],"warningCriteria":["Potential text clipping is present but does not create document overflow.","A screenshot exists but needs human visual review before launch.","The route passes local browser checks but has not been checked against production assets."],"failCriteria":["Browser cannot launch.","A route fails to render.","A configured screenshot is missing.","A page has missing/hidden/multiple H1s.","A page or visible element overflows horizontally.","A screenshot drifts from its committed baseline without QA_UPDATE_BASELINES=1.","A route is not keyboard-operable.","axe-core reports critical or serious accessibility violations.","The visual-diff mutation control fails to detect changed pixels."],"objectiveAlignment":"Adds the visual evidence layer needed before this agent-facing system can support design-system work or launch handoffs."},"crawl_evidence":{"objective":"Make crawl evidence reproducible, machine-readable, and usable by future agents before launch or handoff.","why":"A site can pass local route and browser checks while still having crawl-specific issues in exported indexability, metadata, H1, canonical, response-code, or structured-data data.","crawlTool":"Screaming Frog SEO Spider","approvedWrapper":"workspace-local licensed Screaming Frog wrapper (private; invoked by scripts/run-crawl-evidence.mjs, never published)","command":"npm run qa:crawl -- --export-dir <crawl-export-dir>","runnerCommands":[{"id":"plan-local-crawl","command":"npm run crawl:plan","why":"Writes the local static crawl plan without consuming the Screaming Frog license."},{"id":"execute-local-crawl","command":"npm run crawl:local","why":"Serves the static build locally, runs Screaming Frog through the approved wrapper, and summarizes exports."},{"id":"execute-production-crawl","command":"QA_PRODUCTION_URL=<canonical-url> npm run crawl:production","why":"Runs the same crawl evidence path against the deployed canonical URL when launch evidence is required."},{"id":"verify-runner-shape","command":"npm run qa:crawl-runner","why":"Validates wrapper availability and writes a plan during normal QA without launching a long crawl."}],"defaultReportPath":"reports/crawl/crawl-evidence-report.json","repoReportDirectory":"reports/crawl/","requiredExports":[{"id":"crawl-overview","fileName":"crawl_overview.csv","severity":"critical","why":"Provides crawl totals and high-level issue counts."},{"id":"internal-all","fileName":"internal_all.csv","severity":"critical","why":"Provides complete crawled internal URL inventory."}],"issueExports":[{"id":"client-error-4xx","fileName":"response_codes_client_error_(4xx).csv","severity":"critical","why":"Identifies broken internal links and crawler-visible client errors."},{"id":"server-error-5xx","fileName":"response_codes_server_error_(5xx).csv","severity":"critical","why":"Identifies server-side failures."},{"id":"no-response","fileName":"response_codes_no_response.csv","severity":"critical","why":"Identifies URLs that failed to respond."},{"id":"h1-missing","fileName":"h1_missing.csv","severity":"high","why":"Identifies indexable pages with missing primary headings."},{"id":"meta-description-missing","fileName":"meta_description_missing.csv","severity":"high","why":"Identifies indexable pages with missing search snippets."}],"optionalExports":[{"id":"page-title-missing","fileName":"page_titles_missing.csv","why":"Useful for deeper metadata audits."},{"id":"canonical-missing","fileName":"canonicals_missing.csv","why":"Useful for launch SEO audits."},{"id":"structured-data-validation-errors","fileName":"structured_data_validation_errors.csv","why":"Useful when schema is part of the work."}],"severityRules":[{"id":"missing-required-export","severity":"critical","condition":"A required inventory export file is absent from the crawl export directory."},{"id":"missing-issue-export","severity":"info","condition":"An issue export is absent because Screaming Frog --skip-empty omitted an empty export."},{"id":"internal-4xx","severity":"critical","condition":"Client error export contains one or more rows after headers."},{"id":"internal-5xx","severity":"critical","condition":"Server error export contains one or more rows after headers."},{"id":"no-response","severity":"critical","condition":"No-response export contains one or more rows after headers."},{"id":"missing-h1","severity":"high","condition":"H1 missing export contains one or more rows after headers."},{"id":"missing-meta-description","severity":"high","condition":"Meta description missing export contains one or more rows after headers."}],"passCriteria":["Required inventory crawl exports exist.","Crawl evidence report is written to reports/crawl/.","Critical response-code exports contain no rows after headers.","High-severity metadata/heading findings are either zero or explicitly documented for follow-up.","The crawl target, export directory, generated date, and finding counts are recorded."],"warningCriteria":["High-severity findings exist but are documented for review.","Issue exports are missing only when Screaming Frog --skip-empty omitted empty exports.","Optional exports are missing because the crawl scope did not include them.","Crawler-visible 403s require direct/browser validation before being treated as broken."],"failCriteria":["Required inventory exports are missing.","Critical internal 4xx, 5xx, or no-response findings exist.","The report cannot be generated from the crawl export directory.","The approved Screaming Frog wrapper is missing when a crawl runner plan is requested."],"stressSuite":{"command":"npm run qa:crawl-stress","why":"Screaming Frog evidence depends on a licensed external tool and a manual export step. The stress suite re-crawls the static export with a built-in crawler on every QA run, so broken internal links, redirect chains, orphaned sitemap URLs, and slow or oversized responses fail QA without waiting for licensed crawl evidence.","reportPath":"reports/crawl/crawl-stress-report.json","responseBudgets":[{"id":"max-response-ms","limit":2000,"severity":"high","why":"A local static response beyond two seconds signals a pathological document or server problem that will only be worse behind a real network."},{"id":"max-response-bytes","limit":1500000,"severity":"high","why":"Oversized documents waste crawl budget and slow answer-engine retrieval; anything beyond roughly 1.5MB needs explicit justification."},{"id":"max-redirect-hops","limit":1,"severity":"critical","why":"Redirect chains waste crawl budget and dilute link signals; one hop is tolerated for canonical normalization, longer chains fail."}],"failureRules":[{"id":"broken-internal-link","severity":"critical","condition":"Any crawled internal URL returns 4xx, 5xx, or no response, with the referring page recorded."},{"id":"redirect-chain","severity":"critical","condition":"Any crawled URL needs more than the budgeted redirect hops to resolve."},{"id":"budget-exceeded","severity":"high","condition":"Any crawled URL exceeds a documented response-time or response-size budget."},{"id":"orphan-sitemap-url","severity":"high","condition":"A sitemap URL cannot be reached by following internal links from the homepage."}],"negativeControls":"Synthetic broken-link, redirect-chain, slow-response, and oversized-response records must produce their expected failure kinds through the same evaluation rules applied to the live crawl, proving the rules fail when reality drifts."},"objectiveAlignment":"Turns crawl outputs into durable evidence an agent can inspect, compare, and cite in launch or handoff decisions."},"design_system_contracts":{"objective":"Make future visual design work agent-operable, testable, and aligned with the site purpose before changing the interface.","why":"This reference is not a human marketing template. Design changes must improve agent comprehension, evidence discovery, responsive readability, and QA confidence without hiding machine-readable structure.","principles":[{"id":"agent-comprehension-first","rule":"Prioritize dense, scannable structure over promotional composition.","why":"Agents need fast orientation, file/path discovery, and operational context more than brand persuasion."},{"id":"contracts-stay-visible","rule":"Do not hide key endpoints, commands, file paths, or QA evidence behind decorative interactions.","why":"The visual layer must reinforce the machine-readable operating system."},{"id":"boring-before-branded","rule":"Use restrained visuals until tokens, accessibility, and browser QA are stable.","why":"Premature styling can create layout debt before the system is proven."}],"tokens":[{"id":"color-ink","category":"color","cssVariable":"--ink","value":"#171717","darkValue":"#f8fafc","why":"Primary text color; pairs with paper/surface at better than 12:1 contrast in both schemes."},{"id":"color-muted","category":"color","cssVariable":"--muted","value":"#5b6470","darkValue":"#aab3c2","why":"Secondary text; stays above the 4.5:1 body-text contrast floor on both surfaces."},{"id":"color-paper","category":"color","cssVariable":"--paper","value":"#f7f3eb","darkValue":"#15171a","why":"Page background; warm neutral instead of pure white/black to reduce glare in long technical reading."},{"id":"color-surface","category":"color","cssVariable":"--surface","value":"#fffdf8","darkValue":"#20242b","why":"Card and table surfaces; one step off paper so structure reads without borders doing all the work."},{"id":"color-line","category":"color","cssVariable":"--line","value":"#d8d1c4","darkValue":"#343a45","why":"Hairlines and table rules; visible at 1px on both schemes without competing with text."},{"id":"color-accent","category":"color","cssVariable":"--accent","value":"#0f766e","darkValue":"#5eead4","why":"The single accent, reserved for links, active states, and evidence cues; one accent keeps actions scannable."},{"id":"color-accent-ink","category":"color","cssVariable":"--accent-ink","value":"#ecfdf5","darkValue":"#042f2e","why":"Text on accent fills; maintains AA contrast against the accent in both schemes."},{"id":"color-deep","category":"color","cssVariable":"--deep","value":"#172033","darkValue":"#0f172a","why":"High-contrast band background for code-dense or inverted sections."},{"id":"color-warm","category":"color","cssVariable":"--warm","value":"#b45309","darkValue":"#fbbf24","why":"Warning/attention hue for status badges; distinct from the accent so state never depends on one hue."},{"id":"shape-radius","category":"shape","cssVariable":"--radius","value":"8px","why":"Single small radius for cards and controls; utilitarian, not marketing-card rounding."},{"id":"elevation-shadow","category":"elevation","cssVariable":"--shadow","value":"0 20px 60px rgb(23 23 23 / 12%)","darkValue":"0 20px 60px rgb(0 0 0 / 28%)","why":"One soft elevation level; depth is hierarchy, not decoration."},{"id":"type-family","category":"typography","cssVariable":"--font-sans","value":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif","why":"System-first stack: zero webfont bytes by default, per the performance font budget."},{"id":"type-display","category":"typography","cssVariable":"--text-display","value":"clamp(3rem, 8vw, 6.8rem)","why":"Homepage display heading; clamps keep it fluid without viewport overflow at 320px."},{"id":"type-title","category":"typography","cssVariable":"--text-title","value":"clamp(2rem, 5vw, 4rem)","why":"Page H1 scale."},{"id":"type-title-compact","category":"typography","cssVariable":"--text-title-compact","value":"clamp(2rem, 4vw, 3.5rem)","why":"Dense-page H1 scale for contract-heavy routes."},{"id":"type-heading","category":"typography","cssVariable":"--text-heading","value":"1.6rem","why":"Section H2 scale."},{"id":"type-lead","category":"typography","cssVariable":"--text-lead","value":"1.16rem","why":"Lead paragraph scale."},{"id":"type-body","category":"typography","cssVariable":"--text-body","value":"1rem","why":"Body baseline; 1.5 line-height set globally."},{"id":"type-small","category":"typography","cssVariable":"--text-small","value":"0.92rem","why":"Table and dense-row text; smallest size used for running copy."},{"id":"type-micro","category":"typography","cssVariable":"--text-micro","value":"0.78rem","why":"Eyebrows and badges only; never body copy."},{"id":"space-xs","category":"spacing","cssVariable":"--space-xs","value":"0.5rem","why":"Inline gaps and badge padding."},{"id":"space-sm","category":"spacing","cssVariable":"--space-sm","value":"0.75rem","why":"Tight stacks inside cards and table cells."},{"id":"space-md","category":"spacing","cssVariable":"--space-md","value":"1.25rem","why":"Default block gap."},{"id":"space-lg","category":"spacing","cssVariable":"--space-lg","value":"2rem","why":"Card padding and grid gaps."},{"id":"space-xl","category":"spacing","cssVariable":"--space-xl","value":"3.5rem","why":"Section band separation."}],"tokenSource":{"file":"src/styles/global.css","rule":"Every token above must exactly match the CSS custom property in :root (and the dark-scheme :root override where darkValue exists). qa:aeo parses the stylesheet and fails on any drift, so the published tokens can never be aspirational.","adoptionRule":"New CSS must consume tokens via var(); literal colors, font sizes, or radii in new rules are a review failure."},"mediaRules":[{"id":"image-purpose","rule":"Images only when they show the real product, place, people, work, or proof; no decorative stock.","why":"Decorative imagery costs LCP and trust without adding evidence."},{"id":"image-format","rule":"AVIF or WebP with width/height attributes, loading=\"lazy\" below the fold, and a 250KB per-file ceiling from the performance budget.","why":"Dimensioned, compressed, lazy media is the difference between fast and slow pages with identical design."},{"id":"image-alt","rule":"Alt text states function or content; decorative images get empty alt.","why":"Accessibility contract requirement; alt noise is as bad as alt absence."}],"motionRules":[{"id":"motion-budget","rule":"No animation is load-bearing; the baseline ships zero animation.","why":"Motion must never carry meaning that disappears for reduced-motion users."},{"id":"motion-preference","rule":"Any future transition or animation must be wrapped in a prefers-reduced-motion media query with a no-motion fallback.","why":"WCAG 2.3.3 and basic respect for vestibular disorders."},{"id":"motion-scope","rule":"Permissible motion is micro-feedback (focus, hover, state change) under 200ms; no scroll-driven or looping ambient animation.","why":"The reference is an inspection surface; ambient motion competes with reading."}],"componentRules":[{"component":"Endpoint list","rule":"Show route, purpose, schema if relevant, and owning source path.","why":"Agents should not need to search manually for endpoint ownership."},{"component":"QA command block","rule":"Show exact command, what it checks, and generated report path.","why":"Commands need operational meaning, not just names."},{"component":"Evidence card","rule":"Show source path, generated output, date when known, and residual risk.","why":"Evidence should be traceable and reusable in handoff work."},{"component":"Pattern table","rule":"Allow horizontal scrolling inside an explicit wrapper on small screens.","why":"Dense technical tables should remain usable without document overflow."},{"component":"Status badge","rule":"Use compact labels for done, next, later, planned, implemented, pass, warning, and fail.","why":"Agents need status scanning across backlog, QA, and roadmap surfaces."}],"designExamples":[{"id":"endpoint-discovery-row","title":"Endpoint discovery row","fixtureRoute":"/fixtures/design-system/endpoint-discovery-row/","component":"Endpoint list","objective":"Show agents route, purpose, schema, source file, and validation command in one scannable row.","goodExample":"A row lists /agent-manifest.json, purpose, /schemas/agent-manifest.schema.json, src/pages/agent-manifest.json.ts, and npm run qa:aeo.","badExample":"A decorative link labeled Manifest with no schema, source owner, validation command, or failure mode.","requiredStates":["default","focus","long-path-wrapping","schema-linked","missing-evidence-warning"],"responsiveRequirement":"Long routes and source paths wrap inside the row without document-level horizontal overflow.","accessibilityRequirement":"Every route, schema, and source file link has visible text and a focus style.","agentCheck":"Can an agent identify the endpoint owner and validation command without searching the repo?","qaGates":["npm run qa:browser","npm run qa:aeo"]},{"id":"qa-command-block","title":"QA command block","fixtureRoute":"/fixtures/design-system/qa-command-block/","component":"QA command block","objective":"Show exact command, checks performed, generated report, and pass/fail meaning.","goodExample":"A command block displays npm run qa:browser, screenshots/report paths, checked viewports, and what fails the run.","badExample":"A button labeled Run QA without command text, report path, or explanation of what the result proves.","requiredStates":["ready","running","pass","warning","fail"],"responsiveRequirement":"Command text wraps or scrolls in a bounded code surface on mobile.","accessibilityRequirement":"Status is conveyed by text, not color alone, and the command is selectable.","agentCheck":"Can an agent copy the command and know what evidence file should exist after it runs?","qaGates":["npm run qa:browser","npm run qa:handoff"]},{"id":"evidence-card","title":"Evidence card","fixtureRoute":"/fixtures/design-system/evidence-card/","component":"Evidence card","objective":"Show source path, generated output, date, residual risk, and next action without nesting cards.","goodExample":"A card lists the crawl export path, generated report, date, status, residual risk, and the next verification command.","badExample":"A proof card claims Passed with no report path, date, or remaining risk.","requiredStates":["pass","needs-review","blocked","stale","missing-file"],"responsiveRequirement":"Dense evidence metadata stays readable in a single card and never nests another card inside it.","accessibilityRequirement":"Status labels include text and remain readable in light and dark color schemes.","agentCheck":"Can an agent cite this evidence in a handoff report without inventing missing context?","qaGates":["npm run qa:browser","npm run qa:handoff"]},{"id":"pattern-table","title":"Pattern table","fixtureRoute":"/fixtures/design-system/pattern-table/","component":"Pattern table","objective":"Show dense page-pattern or infrastructure rows while keeping mobile overflow intentional and bounded.","goodExample":"A table sits inside .table-wrap, uses clear column labels, preserves row meaning, and allows horizontal scroll only inside the wrapper.","badExample":"A wide table forces the entire document to scroll horizontally and clips long paths.","requiredStates":["desktop-fit","mobile-scroll-wrapper","long-command","many-columns","empty-state"],"responsiveRequirement":"Horizontal overflow is allowed only inside the table wrapper, not at the document level.","accessibilityRequirement":"Table headers identify columns, and long cells remain readable with wrapping or bounded scroll.","agentCheck":"Can an agent inspect every column on mobile without losing page navigation or H1 visibility?","qaGates":["npm run qa:browser"]},{"id":"status-badge-set","title":"Status badge set","fixtureRoute":"/fixtures/design-system/status-badge-set/","component":"Status badge","objective":"Provide compact status labels for done, next, later, planned, implemented, pass, warning, and fail.","goodExample":"Badges use short text labels, sufficient contrast, consistent dimensions, and no color-only meaning.","badExample":"Small colored dots require a legend, clip text on mobile, or use red/green alone.","requiredStates":["done","next","later","planned","implemented","pass","warning","fail"],"responsiveRequirement":"Badges wrap as a group without changing their internal dimensions or clipping labels.","accessibilityRequirement":"Each badge contains readable text and enough contrast in light and dark modes.","agentCheck":"Can an agent scan task state without reading surrounding paragraphs?","qaGates":["npm run qa:browser","npm run qa:aeo"]}],"layoutRules":["Keep the main URL as an agent orientation surface, not a landing-page hero.","Keep file paths, endpoints, commands, and evidence visible in the first agent path.","Use full-width page bands and constrained content; do not nest cards inside cards.","Reserve large display type for true page headings, not compact data panels.","Use stable dimensions for repeated controls, badges, and data rows."],"responsiveRules":["Mobile layouts must not create document-level horizontal overflow.","Long paths and commands must wrap or sit inside intentional scroll containers.","Tables may scroll horizontally only inside a visible table wrapper.","Buttons and badges must preserve readable text without clipping.","Primary navigation must remain discoverable without covering content."],"accessibilityRules":["Every page keeps exactly one visible H1.","Focus states remain visible on links, buttons, and controls.","Text contrast is sufficient on surface, accent, warning, and error states.","Icons need accessible names when they convey an action.","Semantic landmarks must stay intact after visual changes."],"antiPatterns":["Marketing hero that hides the operating contract.","Decorative gradient/orb background that reduces readability.","One-note palette that makes status and evidence hard to distinguish.","Cards inside cards for page sections.","Viewport-scaled text that clips on mobile.","Visual redesign without updating browser QA screenshots."],"qaGates":["npm run qa:browser","npm run qa:seo","npm run qa:aeo","npm run qa:all"],"stressTests":["Add a long file path and confirm it wraps or scrolls inside a bounded container.","Add a large endpoint table and confirm mobile has no document overflow.","Apply a visual token change and confirm screenshots still pass.","Remove visible focus styling and confirm review catches the accessibility regression.","Try to replace the agent start page with a marketing hero and confirm the design contract blocks it."],"objectiveAlignment":"Lets future design work improve clarity and trust without compromising the agent-first website operating system."},"site_type_playbooks":[{"id":"local-service-build-playbook","exampleId":"local-service","title":"Local service website build playbook","objective":"Build a local service site that proves service scope, geography, trust, contact paths, and crawlable local relevance without unsupported claims.","bestFor":["Home services","Field services","Local professional operators","Service-area businesses"],"requiredInputs":["Verified business identity","Service list","Service area","Contact details","Licensing or qualification facts","Approved proof","Source manifest"],"pageModel":[{"routePattern":"/","purpose":"Entity summary, service-area fit, proof, and primary contact path.","requiredSchema":["LocalBusiness","WebSite","FAQPage"]},{"routePattern":"/services/","purpose":"Service category hub with links to detail pages.","requiredSchema":["Service","BreadcrumbList"]},{"routePattern":"/service-areas/","purpose":"Service-area proof and local relevance.","requiredSchema":["LocalBusiness","BreadcrumbList"]},{"routePattern":"/proof/","purpose":"Approved reviews, case studies, credentials, and source-backed trust.","requiredSchema":["Review","CreativeWork"]},{"routePattern":"/contact/","purpose":"Fast, crawlable contact route with location and service-fit context.","requiredSchema":["ContactPage","LocalBusiness"]}],"buildSequence":["Create or update source manifest and cleaned public-safe facts.","Configure identity, service area, contact data, and canonical site URL.","Build homepage, services, proof, resources/FAQ, and contact routes from allowed claims.","Add schema only for visible and source-backed facts.","Update sitemap, llms endpoints, manifest, examples, traceability, and QA contracts.","Run qa:all, then browser and crawl checks before launch."],"seoAeoRequirements":["Unique local-service metadata","One H1 per indexable page","Service-area facts visible in copy and schema","Direct answers for services offered, where served, and how to contact","llms-full.txt includes service scope and canonical routes"],"traceabilityRequirements":["Every service, area, credential, review, and comparative claim maps to source_traceability","Blocked claims cannot appear in metadata, schema, page copy, or LLM summaries"],"qaGates":["npm run qa:all","Source traceability audit","Mobile contact path check","Screaming Frog crawl before launch"],"stressTests":["Ask an agent to identify service area and services from only the main URL","Attempt to add an unproved fastest/best claim and confirm traceability blocks it","Remove a service page from sitemap and confirm route/sitemap QA catches it"],"completionCriteria":["All required pages exist or are explicitly waived","Service and local claims trace to allowed sources","Schema matches visible content","qa:all passes","Crawl/browser evidence is saved for launch work"],"objectiveAlignment":"Turns a common business-site type into a source-backed, crawlable, answer-ready build path."},{"id":"b2b-saas-build-playbook","exampleId":"b2b-saas","title":"B2B SaaS website build playbook","objective":"Build a SaaS site that makes category, product, use cases, integrations, comparisons, proof, and security facts inspectable.","bestFor":["B2B SaaS","AI products","Developer tools","Security/compliance platforms"],"requiredInputs":["Product positioning","Feature facts","Use cases","Integration list","Security/compliance notes","Customer proof","Comparison claim policy"],"pageModel":[{"routePattern":"/","purpose":"Category and product positioning with proof and primary conversion path.","requiredSchema":["Organization","SoftwareApplication","WebSite"]},{"routePattern":"/product/","purpose":"Product capabilities, use boundaries, and feature proof.","requiredSchema":["SoftwareApplication","Product"]},{"routePattern":"/use-cases/","purpose":"Buyer/problem mapping by role, industry, or workflow.","requiredSchema":["CollectionPage","BreadcrumbList"]},{"routePattern":"/integrations/","purpose":"Entity pages for integrations and ecosystem relevance.","requiredSchema":["SoftwareApplication","BreadcrumbList"]},{"routePattern":"/comparison/","purpose":"Sourced comparison pages with caveats and no unsupported competitor claims.","requiredSchema":["FAQPage","Article"]}],"buildSequence":["Validate product claims and feature boundaries before page copy.","Build product and use-case pages before comparison pages.","Create integration/entity pages only for verified integrations.","Add proof and security/compliance facts with source references.","Update schemas, llms endpoints, sitemap, traceability, and evaluation checks together.","Run qa:all plus claim/proof review."],"seoAeoRequirements":["Product/category title clarity","Use-case pages answer who it is for and when to use it","Comparison FAQs include caveats","Integration pages use stable entity names","AEO summaries avoid unsupported superiority claims"],"traceabilityRequirements":["Feature, integration, compliance, security, customer, and comparison claims require source IDs","Competitor claims require explicit approval and evidence"],"qaGates":["npm run qa:all","Claim/proof traceability review","Structured data review","Comparison claim review"],"stressTests":["Ask an agent to explain product fit without prior chat","Try to add an unverified integration and confirm source traceability blocks it","Remove a caveat from a comparison claim and confirm review criteria catches it"],"completionCriteria":["Product, use-case, integration, proof, and comparison paths are defined","Claims are source-backed","Schema matches visible product facts","qa:all passes","Remaining unsupported claims are documented as blocked"],"objectiveAlignment":"Gives agents a rigorous path for complex product sites where unsupported claims are high risk."},{"id":"professional-services-build-playbook","exampleId":"professional-services","title":"Professional services website build playbook","objective":"Build a trust-heavy services site with clear scope, qualification, process, industry fit, proof, and expert content.","bestFor":["Consultancies","Agencies","Law/accounting/advisory firms","Specialized practices"],"requiredInputs":["Service scope","Practitioner/team credentials","Engagement process","Industry experience","Approved proof","Author attribution policy"],"pageModel":[{"routePattern":"/","purpose":"Positioning, service fit, qualifications, proof, and contact path.","requiredSchema":["ProfessionalService","Organization","Person"]},{"routePattern":"/services/","purpose":"Service scope and engagement model.","requiredSchema":["Service","BreadcrumbList"]},{"routePattern":"/industries/","purpose":"Industry-specific fit and caveats.","requiredSchema":["CollectionPage","BreadcrumbList"]},{"routePattern":"/about/","purpose":"Practitioner/entity trust, credentials, and source-backed background.","requiredSchema":["Person","Organization"]},{"routePattern":"/insights/","purpose":"Expert content with attribution and source-safe recommendations.","requiredSchema":["Article","BreadcrumbList"]}],"buildSequence":["Separate service scope from credentials and proof.","Build service and industry pages with non-overlapping intent.","Add practitioner/team facts only when approved for public use.","Create proof and insight pages with attribution and source checks.","Update schema IDs, author facts, llms endpoints, and source traceability.","Run qa:all and proof/credential review."],"seoAeoRequirements":["Service and industry pages have distinct titles and H1s","Author/entity attribution is visible","FAQs answer scope, process, fit, and qualification questions","Schema does not imply credentials not visible on page"],"traceabilityRequirements":["Credentials, results, client names, testimonials, and industry experience require approved sources","Regulated claims require extra review before publication"],"qaGates":["npm run qa:all","Credential/source review","Accessibility review for dense content","Author/entity schema review"],"stressTests":["Ask an agent to distinguish service scope from industry fit","Try to add a credential without source proof and confirm it is blocked","Check that insight pages have visible attribution"],"completionCriteria":["Services, industries, about/trust, insights, proof, and contact paths are clear","Credentials and proof are source-backed","Schema mirrors visible facts","qa:all passes"],"objectiveAlignment":"Helps agents build trust-heavy sites without inventing credentials, proof, or regulated claims."},{"id":"proof-library-build-playbook","exampleId":"proof-page","title":"Proof library build playbook","objective":"Build a proof system where testimonials, case studies, metrics, screenshots, and before/after claims are permissioned and inspectable.","bestFor":["Case-study sections","Proof hubs","Portfolio pages","Results libraries"],"requiredInputs":["Approved testimonials","Case-study facts","Metrics with date ranges","Before/after artifacts","Permission notes","Privacy constraints"],"pageModel":[{"routePattern":"/proof/","purpose":"Proof index with filters and source-safe summaries.","requiredSchema":["CollectionPage","Review"]},{"routePattern":"/proof/[case-study]/","purpose":"Case detail with source-backed problem, action, result, and constraints.","requiredSchema":["Article","CreativeWork"]},{"routePattern":"/testimonials/","purpose":"Approved review/testimonial inventory.","requiredSchema":["Review"]}],"buildSequence":["Collect proof artifacts and permission notes before writing copy.","Classify each proof item by public/private/sanitized status.","Build proof index and detail pages from approved facts only.","Add metrics with dates, scope, and caveats near the claim.","Use Review schema only for eligible visible reviews.","Run qa:all plus privacy/permission review."],"seoAeoRequirements":["Case-study titles use approved outcome language","Metrics include conditions and dates","Proof pages link back to relevant service/product pages","AEO answers do not strip away caveats"],"traceabilityRequirements":["Every testimonial, metric, logo, client name, screenshot, and outcome claim must map to permissioned source evidence","Private proof can be summarized only when approved"],"qaGates":["npm run qa:all","Permission/privacy review","Claim/source audit","Schema eligibility review"],"stressTests":["Attempt to publish a metric without date/context and confirm it is blocked","Ask an agent to find proof for a service claim","Confirm private proof cannot leak into LLM summaries"],"completionCriteria":["Every proof item has permission status","Every public claim has source evidence","Review schema is eligible and visible","qa:all passes","Remaining proof risks are listed"],"objectiveAlignment":"Makes proof reusable without turning it into unsupported or privacy-risky marketing claims."},{"id":"answer-ready-resource-build-playbook","exampleId":"answer-ready-resource","title":"Answer-ready resource build playbook","objective":"Build resource pages that answer concrete questions, expose stable entities, preserve caveats, and support search plus answer-engine retrieval.","bestFor":["Guides","Glossaries","Comparison hubs","FAQ clusters","AEO/GEO resources"],"requiredInputs":["Topic definitions","Question set","Approved recommendations","Comparison criteria","Public source references","Entity glossary"],"pageModel":[{"routePattern":"/resources/","purpose":"Resource hub by topic, entity, and buyer question.","requiredSchema":["CollectionPage","BreadcrumbList"]},{"routePattern":"/resources/[guide]/","purpose":"Direct answer plus deeper explanation and source links.","requiredSchema":["Article","FAQPage"]},{"routePattern":"/glossary/[term]/","purpose":"Stable entity/definition page.","requiredSchema":["DefinedTerm","BreadcrumbList"]},{"routePattern":"/compare/[topic]/","purpose":"Comparison criteria, caveats, and decision guidance.","requiredSchema":["Article","FAQPage"]}],"buildSequence":["Define the question set and entity glossary first.","Build concise answer blocks before long-form explanation.","Add caveats near recommendations and comparisons.","Link guides to glossary/entity pages and related proof.","Add Article, FAQPage, DefinedTerm, and BreadcrumbList schema where visible.","Run qa:all and internal-link/schema review."],"seoAeoRequirements":["Direct answer appears before nuance","Definitions are stable and internally linked","Comparison criteria are explicit","Caveats stay near recommendations","llms endpoints summarize canonical answers"],"traceabilityRequirements":["Definitions, recommendations, comparisons, and source references require approved source links or internal proof","Speculative answers must be marked as caveated or excluded"],"qaGates":["npm run qa:all","Internal-link crawl","Schema review","Source/reference review"],"stressTests":["Ask an agent to answer a target question from the page","Remove a glossary link and confirm internal-link review catches the gap","Try to make an uncaveated recommendation and confirm traceability flags it"],"completionCriteria":["Question set, guide pages, glossary/entity pages, and comparison pages are mapped","Direct answers and caveats are visible","Schema matches content","qa:all passes"],"objectiveAlignment":"Turns content into a model-readable answer system instead of a generic blog."}],"site_studies":[{"id":"nectiv-digital-seo-aeo-2026-06-04","siteName":"Nectiv Digital","url":"https://nectivdigital.com/","auditDate":"2026-06-04","evidenceRoot":"data/derived/site-studies/nectiv-digital-2026-06-04/","evidenceFiles":["data/derived/site-studies/nectiv-digital-2026-06-04/analysis-notes.md","data/derived/site-studies/nectiv-digital-2026-06-04/crawl_overview.csv"],"context":"Public agency site used as an SEO/AEO reference study for entity architecture, AI-search positioning, crawl discipline, and model-readable gaps.","strongPatterns":[{"pattern":"Narrow topical/entity focus","why":"The site consistently reinforces SEO, AEO/GEO, AI Search, ChatGPT, Perplexity, Google AI Mode, AI citations, and B2B brands instead of drifting into generic agency positioning.","reuseAs":"Build a small set of commercial entity pages, then support them with methods, proof, technology pages, and question-driven articles.","checkToAdd":"Confirm service, technology, proof, and article pages repeat a coherent entity set without unsupported keyword sprawl."},{"pattern":"Commercial pages map to distinct buying jobs","why":"Specific service pages make it easier for search engines, answer engines, and buyers to understand what the agency does.","reuseAs":"Create service pages around real buying intent rather than vague capability labels.","checkToAdd":"Confirm each primary service page has a unique purpose, title, H1, schema type, and internal-link role."},{"pattern":"Technology pages support differentiation","why":"Technology pages make the agency's approach inspectable instead of leaving differentiation as a broad claim.","reuseAs":"Add method, system, or technology pages when a site sells expertise that needs explanation.","checkToAdd":"Require differentiation pages to connect visible claims to proof, process, schema, and internal links."},{"pattern":"Entity schema is stable across page types","why":"Organization, WebSite, founder, Service, BlogPosting, and BreadcrumbList schema help connect visible content to machine-readable entity facts.","reuseAs":"Keep entity IDs and schema roles consistent across home, service, and article pages.","checkToAdd":"Validate that schema entities match visible page content and reuse stable IDs."}],"avoidPatterns":[{"issue":"www hostname TLS failure","why":"A certificate mismatch on https://www.nectivdigital.com/ weakens trust and can break a common direct-entry hostname before redirect logic is reached.","detectedBy":"Direct TLS/hostname check plus Screaming Frog domain verification.","checkToAdd":"Check apex, www, HTTP, HTTPS, redirect target, and certificate coverage before launch."},{"issue":"Missing llms.txt and llms-full.txt","why":"For a site selling AI-search/AEO services, missing model-readable entry points are a visible mismatch between positioning and technical surface.","detectedBy":"Direct requests to /llms.txt and /llms-full.txt returned 404.","checkToAdd":"Require llms.txt and llms-full.txt when a site claims AI-search, AEO, GEO, or agent-readiness expertise."},{"issue":"Indexable pages missing H1","why":"Indexable pages without an H1 reduce page clarity for users, crawlers, and answer systems.","detectedBy":"Screaming Frog h1_missing.csv flagged /ai-instructions and /contact.","checkToAdd":"Fail or warn on every indexable HTML page with no H1."},{"issue":"Indexable article missing meta description","why":"A missing description leaves search snippets and model summaries less controlled for a page designed to demonstrate AEO performance.","detectedBy":"Screaming Frog meta_description_missing.csv flagged the AEO experiment article.","checkToAdd":"Warn on indexable pages without descriptions, with an explicit exception path only for intentional no-description pages."},{"issue":"Crawler-visible internal media 403s","why":"Blocked embedded assets can degrade real page experience even when core HTML is indexable.","detectedBy":"Screaming Frog response_codes_client_error_(4xx).csv flagged internal media URLs.","checkToAdd":"Verify crawler-visible 403s directly before classifying them as broken or intentionally restricted."}],"agentTakeaways":["Good examples should be copied as principles, not as brand, copy, or proprietary assets.","Bad examples should become checks, backlog items, or explicit non-actions.","AEO claims should be backed by model-readable endpoints, schema, entity clarity, and crawl evidence.","Crawler findings need direct validation when a response code may reflect crawler blocking instead of real user failure."],"linkedRoadmapItems":["good-bad-example-library","seo-aeo-evaluation-layer","crawl-evidence-artifacts","real-site-comparisons","aeo-geo-model-context"]},{"id":"specification-website-agent-reference-2026-06-09","siteName":"Specification Website","url":"https://specification.website/","auditDate":"2026-06-09","evidenceRoot":"data/derived/site-studies/specification-website-2026-06-09/","evidenceFiles":["data/derived/site-studies/specification-website-2026-06-09/analysis-notes.md","data/derived/site-studies/specification-website-2026-06-09/crawl_overview.csv"],"context":"Agent-facing specification/documentation site used to teach machine-readable discovery surfaces, well-known/API links, reference-site information architecture, security headers, sitemap migration, external-reference maintenance, and method-aware endpoint classification.","strongPatterns":[{"pattern":"Agent and API discovery surfaces are first-class","why":"The site exposes llms.txt, llms-full.txt, .well-known discovery, API catalog links, MCP/A2A hints, agent skills discovery, sitemap index, RSS, and security policy through headers and routes.","reuseAs":"Model agent-facing websites with visible and protocol-level discovery surfaces so agents can recover purpose, files, APIs, and operating context from the main URL.","checkToAdd":"Require agent-facing sites to expose LLM files, manifest-style discovery, sitemap, security policy, and any API/agent cards through stable routes or response links."},{"pattern":"Specification IA uses stable category and detail routes","why":"The crawl found a broad set of indexable HTML routes organized around specification categories and detail pages, making traversal predictable for agents and crawlers.","reuseAs":"Use stable category/detail URL conventions for documentation-heavy reference sites.","checkToAdd":"Validate that documentation category pages, detail pages, checklists, and examples have explicit route purpose, title/H1 intent, and internal-link roles."},{"pattern":"Security and policy headers are part of the reference surface","why":"Direct response checks showed HSTS, CSP, frame denial, COOP/CORP, no-vary-search, permissions policy, referrer policy, and x-content-type-options.","reuseAs":"Treat production web hygiene as part of the website operating contract, not a post-launch infrastructure add-on.","checkToAdd":"Add production launch checks for security headers and document which headers are required, optional, or context-dependent."},{"pattern":"Sitemap index migration keeps legacy discovery working","why":"/sitemap.xml redirects to /sitemap-index.xml while headers advertise the sitemap index, preserving crawler discovery through a common legacy path.","reuseAs":"Use clean redirects for discovery-surface migrations when the canonical replacement is explicit and consistently advertised.","checkToAdd":"Allow sitemap redirects only when the final target returns XML, is advertised, and all sitemap URLs resolve."}],"avoidPatterns":[{"issue":"External standards/reference links can rot or block crawlers","why":"The 4xx export included stale or crawler-blocked external references across standards and documentation sites, which weakens reference trust if left unclassified.","detectedBy":"Screaming Frog response_codes_client_error_(4xx).csv plus direct classification notes in analysis-notes.md.","checkToAdd":"Run recurring external-link classification for reference-heavy sites and separate true 404s from crawler-blocked 403s or method-specific API responses."},{"issue":"Overview/detail page pairs can duplicate titles and H1s","why":"Duplicate title/H1 exports flagged category/detail pairs for well-known URIs, privacy policy, and agent readiness. These may be intentional, but agents need canonical rationale or differentiated titles.","detectedBy":"Screaming Frog page_titles_duplicate.csv and h1_duplicate.csv.","checkToAdd":"Require documentation category and detail pages to either differentiate title/H1 intent or document canonical/internal-link rationale."},{"issue":"Agent/API endpoints need method-aware classification","why":"An A2A endpoint returned 405 to a crawler GET request, which may be correct API behavior but should not be treated as an ordinary broken HTML page.","detectedBy":"Screaming Frog client-error export and analysis notes.","checkToAdd":"Classify API, MCP, A2A, and agent-card endpoints separately from HTML route crawl health."}],"agentTakeaways":["Agent-facing sites should expose discovery through HTML, headers, LLM files, well-known files, API catalogs, and agent cards.","Reference sites need external-link maintenance because authoritative standards links move or block crawlers over time.","Duplicate title/H1 pairs may be acceptable for overview/detail pairs only when page intent and canonical rationale are explicit.","Crawler-visible API errors need method-aware checks before they become broken-link tasks."],"linkedRoadmapItems":["good-bad-example-library","seo-aeo-evaluation-layer","real-site-comparisons","aeo-geo-model-context","crawl-evidence-artifacts"]},{"id":"ryan-pierce-personal-consultant-2026-05-21","siteName":"RyanPierce.ai","url":"https://www.ryanpierce.ai/","auditDate":"2026-05-21","evidenceRoot":"data/derived/site-studies/ryanpierce-ai-2026-05-21/","evidenceFiles":["data/derived/site-studies/ryanpierce-ai-2026-05-21/ryanpierce-ai-analysis.md","data/derived/site-studies/ryanpierce-ai-2026-05-21/crawl_overview.csv"],"context":"Small personal/consulting portfolio site used to teach canonical-host consistency, clean small-site metadata, external-link verification, and security-header hardening.","strongPatterns":[{"pattern":"Small site with clean on-page metadata","why":"The crawl showed no missing titles, descriptions, H1s, H2s, or image alt text on the crawled 200 HTML pages, proving a small expert site can keep basic SEO hygiene simple and complete.","reuseAs":"Use small personal sites as a controlled baseline for metadata, H1, canonical, and image-alt expectations before adding complex content systems.","checkToAdd":"Confirm every public HTML page has a title, meta description, H1, H2 where useful, canonical tag, and image alt policy."},{"pattern":"All important pages are shallow from the homepage","why":"A compact crawl depth helps agents, users, and crawlers recover the site structure quickly.","reuseAs":"Keep personal consultant portfolios shallow, with work examples and conversion paths reachable directly from the homepage.","checkToAdd":"Warn when core proof/work pages require more than two clicks from the homepage."}],"avoidPatterns":[{"issue":"Canonical host mismatch","why":"The live final host used www while canonical tags pointed to bare-domain URLs that redirected back to www, causing pages to be treated as canonicalized/non-indexable by the crawl.","detectedBy":"Screaming Frog canonical/indexability data plus direct bare-domain redirect verification.","checkToAdd":"Require canonicals, Open Graph URLs, sitemap URLs, redirects, and final host to agree before launch."},{"issue":"External profile links require browser validation","why":"Medium and LinkedIn returned crawler-block or bot-block style responses, so agents need to separate real broken links from crawler-visible blocks before changing public profile links.","detectedBy":"Screaming Frog external response codes plus direct HTTP checks.","checkToAdd":"Classify external 403/999/social responses as manual-verification warnings, not automatic broken-link failures."},{"issue":"Baseline security headers are incomplete","why":"A site can be SEO-clean but still lack CSP, X-Content-Type-Options, X-Frame-Options, and Referrer-Policy hardening.","detectedBy":"Direct response/header checks captured in the analysis notes.","checkToAdd":"Add launch QA for baseline security headers on production responses."}],"agentTakeaways":["Small sites are useful QA baselines because every page can be inspected deeply.","Canonical host mismatch can invalidate otherwise clean metadata.","External social/profile links need manual browser validation when crawler responses are ambiguous.","Security headers belong in launch QA even when they are not the primary SEO issue."],"linkedRoadmapItems":["good-bad-example-library","seo-aeo-evaluation-layer","crawl-evidence-artifacts","real-site-comparisons"]},{"id":"the-prep-casa-saas-2026-05-21","siteName":"The Prep Casa","url":"https://www.the-prep.casa/","auditDate":"2026-05-21","evidenceRoot":"data/derived/site-studies/the-prep-casa-2026-05-21/","evidenceFiles":["data/derived/site-studies/the-prep-casa-2026-05-21/the-prep-casa-analysis.md","data/derived/site-studies/the-prep-casa-2026-05-21/crawl_overview.csv"],"context":"SaaS/product site study used to teach head metadata rendering, canonical discipline, signup-page indexability decisions, image-alt policy, and direct-link hygiene.","strongPatterns":[{"pattern":"Healthy crawl response baseline","why":"The crawl found no internal 4xx, 5xx, no-response URLs, mixed content, or redirect chains, which makes deeper metadata and rendering issues easier to isolate.","reuseAs":"Use clean response-code health as the starting line for SaaS launch QA, not the finish line.","checkToAdd":"Separate response-code pass state from metadata, schema, accessibility, and rendered-head validation."},{"pattern":"Product information architecture has feature and resource routes","why":"Feature pages, resources, blog posts, and changelog-style content give agents a clear product-site pattern for mapping use cases to page types.","reuseAs":"Create SaaS playbooks that pair homepage, feature, resource, signup, and contact-sales routes with distinct SEO/AEO duties.","checkToAdd":"Require every SaaS feature route to have a unique title, description, H1, canonical, schema role, and internal-link purpose."}],"avoidPatterns":[{"issue":"Metadata and canonical tags appear outside the expected head surface","why":"Non-JS crawlers, social crawlers, and SEO tools may miss metadata if title, description, canonical, and robots signals are not present in the server-rendered head.","detectedBy":"Screaming Frog outside-head warnings plus browser-rendered spot checks.","checkToAdd":"Verify rendered and raw head metadata for title, description, canonical, robots, Open Graph, and schema on representative routes."},{"issue":"Indexable signup page lacks heading structure","why":"A signup route that remains indexable needs clear H1/H2 structure; otherwise it should have an explicit noindex decision.","detectedBy":"Screaming Frog h1_missing/h2_missing exports and browser-rendered spot checks.","checkToAdd":"Require every indexable conversion route to either expose a meaningful H1 or document a noindex policy."},{"issue":"Meaningful logo images lack alt policy","why":"Technology/trust logos can be decorative or meaningful, but agents must make that choice explicitly instead of leaving assistive technology behavior accidental.","detectedBy":"Screaming Frog images_missing_alt_text.csv.","checkToAdd":"Require image-alt decisions to classify logos as decorative alt-empty or meaningful with concise alt text."}],"agentTakeaways":["Clean crawl response codes do not prove SEO readiness.","SaaS sites need raw/rendered head validation because framework metadata behavior can drift.","Signup and conversion routes need explicit indexability decisions.","Feature-route IA should become a site-type playbook, not just a visual sitemap."],"linkedRoadmapItems":["good-bad-example-library","seo-aeo-evaluation-layer","site-type-build-playbooks","page-pattern-library","real-site-comparisons"]},{"id":"jordan-browne-moore-content-consultant-2026-06-04","siteName":"Jordan Browne-Moore","url":"https://www.jordanbrowne-moore.com/","auditDate":"2026-06-04","evidenceRoot":"data/derived/site-studies/jordan-browne-moore-2026-06-03/","evidenceFiles":["data/derived/site-studies/jordan-browne-moore-2026-06-03/jordan-browne-moore-website-audit.md","data/derived/site-studies/jordan-browne-moore-2026-06-03/crawl_overview.csv"],"context":"Content-led expert consultant site study used to teach the difference between rendered quality and crawler-visible raw HTML, plus domain health, sitemap/robots validity, soft 404s, and article-route SEO.","strongPatterns":[{"pattern":"Specific expert positioning and article depth","why":"The rendered site has clear fintech ML, LLM, credit-risk, fraud, and KYC positioning with article content that demonstrates real expertise rather than generic thought leadership.","reuseAs":"Use content-led consultant sites to show how proof, technical depth, and topic specificity can create authority signals.","checkToAdd":"Require expert/article sites to map articles to a coherent entity/topic set with proof and conversion paths."},{"pattern":"Rendered desktop and mobile layouts are coherent","why":"The browser evidence showed no horizontal overflow across tested routes and credible visual continuity across long article pages.","reuseAs":"Use rendered screenshots and Lighthouse/browser evidence to evaluate design operability after technical crawl checks.","checkToAdd":"Pair crawler raw-HTML checks with browser-rendered layout and accessibility checks for JavaScript-heavy sites."}],"avoidPatterns":[{"issue":"Apex domain fails while www works","why":"A strong site can lose direct users and natural backlinks when the bare domain returns an infrastructure error.","detectedBy":"Direct HTTP/domain checks recorded in the audit.","checkToAdd":"Require apex, www, HTTP, HTTPS, TLS, and canonical redirect checks before launch."},{"issue":"robots.txt and sitemap.xml return app HTML instead of valid files","why":"Crawler discovery surfaces must be real protocol files, not client-app fallback shells.","detectedBy":"Direct requests and Lighthouse/Screaming Frog findings.","checkToAdd":"Fail QA when robots.txt is not robots syntax or sitemap.xml is not XML."},{"issue":"Client-rendered SPA hides article content from raw HTML","why":"A content-led expert site depends on crawlable article text, headings, and internal links; browser-rendered quality is not enough if raw HTML is nearly empty.","detectedBy":"Screaming Frog raw crawl plus rendered Playwright evidence comparison.","checkToAdd":"Compare raw HTML and rendered DOM for core article routes and flag missing raw H1/content/internal links."},{"issue":"Unknown routes return 200 soft 404s","why":"Soft 404s waste crawl budget and can create low-value indexable URLs.","detectedBy":"Direct invalid-route status check in the audit.","checkToAdd":"Require unknown routes to return a real 404 status and useful 404 page."}],"agentTakeaways":["Rendered UX quality and crawler-visible SEO quality must be tested separately.","Content-led expert sites need SSR/SSG/prerendered article content or equivalent crawlable HTML.","Robots and sitemap files are protocol surfaces, not decorative endpoints.","Soft 404 behavior should be part of launch QA for every framework app."],"linkedRoadmapItems":["good-bad-example-library","seo-aeo-evaluation-layer","browser-visual-qa","crawl-evidence-artifacts","site-type-build-playbooks","real-site-comparisons"]},{"id":"poor-ai-generated-service-site-fixture-2026-06-04","siteName":"Poor AI-Generated Service Site Fixture","url":"fixture://poor-ai-generated-service-site","auditDate":"2026-06-04","evidenceRoot":"data/derived/site-studies/poor-ai-generated-service-site/","evidenceFiles":["data/derived/site-studies/poor-ai-generated-service-site/analysis-notes.md"],"context":"Intentionally weak local-service fixture used to teach agents what to reject: generic AI copy, unsupported claims, thin entity context, mismatched schema/content, and missing machine-readable surfaces.","strongPatterns":[{"pattern":"Visible offer and contact path exist","why":"Even weak AI-generated sites often include the basic commercial shape: a service offer, some FAQs, and a contact path. Agents should preserve useful intent while rebuilding the evidence layer.","reuseAs":"Treat visible offer/contact intent as a starting point, then require source-backed facts, specific service details, and validated metadata/schema.","checkToAdd":"Confirm every conversion path is tied to a real service, service area, source fact, and contact route."}],"avoidPatterns":[{"issue":"Generic copy with no source-backed entity model","why":"A page can sound plausible while failing to identify who the business is, what proof exists, where it operates, and which claims are approved.","detectedBy":"Fixture analysis notes and absence of source ledger/crawl/LLM evidence.","checkToAdd":"Require source-traceability claims before public copy, schema, FAQ answers, or LLM summaries can be marked ready."},{"issue":"FAQ, schema, and visible copy drift","why":"AI-generated FAQ answers often introduce service promises or proof claims that are not visible elsewhere or supported by sources.","detectedBy":"Fixture analysis notes.","checkToAdd":"Compare FAQ/schema facts against visible page sections and source-traceability records."},{"issue":"No agent-readable or crawl evidence surfaces","why":"Without llms files, sitemap, robots, crawl reports, and handoff evidence, future agents must infer readiness from appearance.","detectedBy":"Fixture analysis notes.","checkToAdd":"Block readiness claims until llms.txt, llms-full.txt, sitemap, robots, crawl report, and handoff report exist."}],"agentTakeaways":["Bad examples should be safe fixtures when copying a real weak site would be noisy or unfair.","Generic AI copy is not a content system; it needs source, claim, schema, and QA contracts.","Agents should salvage useful intent while rejecting unsupported claims and vague positioning.","A site can only be called ready when evidence surfaces exist, not when it looks complete."],"linkedRoadmapItems":["good-bad-example-library","source-to-site-traceability","seo-aeo-evaluation-layer","aeo-geo-model-context","handoff-reports"]}],"seo_aeo_evaluation":[{"id":"route-response-and-sitemap-coverage","category":"Crawlability","status":"implemented","severity":"critical","objective":"Confirm every required HTML route, machine route, internal link, and sitemap URL returns 200 in the static build.","why":"Search engines and answer systems cannot trust a site whose core routes, internal links, or sitemap entries do not resolve cleanly.","checkMethod":"Serve dist/ locally, request required routes, crawl internal links from core pages, parse sitemap.xml, and verify each sitemap URL resolves locally.","validationCommand":"npm run qa:routes","evidenceRequired":["PASS route QA","Sitemap URLs use PUBLIC_SITE_URL","No internal links return non-200"],"passCriteria":["All required routes return 200","All discovered internal links return 200","All sitemap URLs resolve"],"warningCriteria":["A route is reachable but missing from a discovery surface","A route is intentionally excluded but not documented"],"failCriteria":["Any required route, internal link, or sitemap URL returns non-200"],"sourceLessons":["Nectiv sitemap coverage was strong and should be preserved as a model."]},{"id":"metadata-canonical-h1-parity","category":"SEO","status":"implemented","severity":"critical","objective":"Confirm indexable pages have unique titles, useful descriptions, correct canonicals, explicit robots policy, and exactly one H1.","why":"Nectiv showed that a site can be strong overall while still shipping indexable pages with missing H1 or description details.","checkMethod":"Parse each core HTML page and validate title, description, canonical, robots, Open Graph, favicon, and H1 count.","validationCommand":"npm run qa:seo","evidenceRequired":["PASS SEO QA","One H1 per core HTML page","Descriptions stay inside snippet guidance"],"passCriteria":["Each core page has a unique title","Each core page has a 50-160 character description","Each core page has exactly one H1","Canonical and Open Graph URL match"],"warningCriteria":["A deliberately long title or description lacks an explicit AEO rationale"],"failCriteria":["Missing title, description, canonical, robots policy, Open Graph parity, favicon, schema, or H1"],"sourceLessons":["Nectiv /ai-instructions and /contact H1 gaps","Nectiv AEO experiment article missing meta description"]},{"id":"llm-and-agent-endpoint-presence","category":"AEO","status":"implemented","severity":"critical","objective":"Confirm LLM and agent-readable endpoints exist, are linked from the manifest, and expose the sections agents need.","why":"For AI-search and agent-facing work, model-readable surfaces are part of the product, not optional documentation.","checkMethod":"Request llms.txt, llms-full.txt, manifest JSON, formal contracts, schemas, roadmap, walkthroughs, site studies, and related endpoints.","validationCommand":"npm run qa:aeo","evidenceRequired":["PASS AEO QA","llms.txt includes key pages and machine endpoints","llms-full.txt includes Contract Registry and Site Studies"],"passCriteria":["llms.txt and llms-full.txt return 200","Manifest exposes all required agent sections","Every machine endpoint returns 200"],"warningCriteria":["A human doc contains guidance not reflected in machine-readable endpoints"],"failCriteria":["Missing LLM endpoint, missing manifest section, invalid JSON endpoint, or unregistered formal contract"],"sourceLessons":["Nectiv /llms.txt and /llms-full.txt 404 gap"]},{"id":"structured-data-entity-coverage","category":"Schema","status":"implemented","severity":"high","objective":"Confirm visible page content is supported by JSON-LD and schema discovery endpoints.","why":"AEO depends on stable entity clarity: Organization, WebSite, LocalBusiness, FAQPage, Service, Article, and breadcrumbs where relevant.","checkMethod":"Parse JSON-LD blocks on HTML pages and schema endpoints from schemamap.xml.","validationCommand":"npm run qa:seo && npm run qa:aeo","evidenceRequired":["PASS SEO QA","PASS AEO QA","schemamap.xml schema URLs return JSON"],"passCriteria":["Every core HTML page includes valid JSON-LD","Schema endpoints include Organization and WebSite","Home schema includes FAQPage and LocalBusiness"],"warningCriteria":["Schema exists but is thinner than visible page content"],"failCriteria":["Invalid JSON-LD, missing schema endpoint, or schema facts that do not match visible content"],"sourceLessons":["Nectiv stable Organization, WebSite, founder, Service, BlogPosting, and BreadcrumbList schema pattern"]},{"id":"real-site-findings-to-qa-loop","category":"Evaluation Feedback","status":"implemented","severity":"high","objective":"Turn every real-site study into reusable checks, roadmap links, and evidence paths.","why":"Good examples and bad examples are only useful if they become operational rules future agents can inspect and reuse.","checkMethod":"Validate site studies for strong patterns, avoid patterns, evidence files, and valid roadmap links.","validationCommand":"npm run qa:aeo","evidenceRequired":["PASS AEO QA","site-studies.json includes strongPatterns and avoidPatterns","Evidence files resolve on disk"],"passCriteria":["Each study has good and bad patterns","Each pattern explains why it matters","Each study links to roadmap items","Evidence files exist"],"warningCriteria":["A study has observations that do not map to a check, task, or explicit non-action"],"failCriteria":["A study lacks evidence, lacks good/bad distinction, or references an unknown roadmap item"],"sourceLessons":["Nectiv audit converted into reusable positive and negative patterns"]},{"id":"domain-variant-tls-and-redirects","category":"Prelaunch Domain QA","status":"planned","severity":"critical","objective":"Check apex, www, HTTP, HTTPS, redirect behavior, and certificate coverage for production domains.","why":"A static local build can pass while the production domain still has a broken www hostname, redirect chain, or certificate mismatch.","checkMethod":"Run production-domain checks after deployment using curl/OpenSSL or crawl tooling, then save evidence under reports/domain/.","validationCommand":"planned: reports/domain/domain-variant-check.md","evidenceRequired":["Apex HTTPS works","www HTTPS has valid certificate coverage","HTTP redirects cleanly to HTTPS canonical","No internal redirect chains"],"passCriteria":["Apex and www hostnames are covered by valid TLS","Canonical host is explicit","All non-canonical variants redirect cleanly"],"warningCriteria":["A non-canonical hostname works but redirects through more than one hop"],"failCriteria":["TLS mismatch, no-response hostname, redirect loop, or canonical conflict"],"sourceLessons":["Nectiv www TLS certificate mismatch"]},{"id":"crawl-export-indexability-comparison","category":"Crawl Evidence","status":"planned","severity":"high","objective":"Compare Screaming Frog crawl exports against sitemap, indexability, metadata, H1, response codes, and schema expectations.","why":"Local unit checks prove intent; crawl exports prove what a crawler actually sees across the rendered/static surface.","checkMethod":"Run Screaming Frog against the deployed or static-export URL and save exports under reports/crawl/.","validationCommand":"planned: reports/crawl/latest/analysis-notes.md","evidenceRequired":["Crawl overview","Internal all export","H1 missing export","Meta description missing export","4xx/no-response export","Sitemap coverage comparison"],"passCriteria":["No unresolved internal 4xx/5xx/no-response URLs","No indexable pages missing H1 or descriptions","Sitemap and indexable HTML inventory are reconciled"],"warningCriteria":["Crawler-visible external 403s need direct validation","Long snippets need explicit AEO rationale"],"failCriteria":["Unresolved internal broken URLs","Indexable page inventory mismatch","Missing crawl evidence before launch"],"sourceLessons":["Nectiv crawl exported sitemap/indexability, H1, description, and 4xx findings"]},{"id":"nectiv-derived-guardrail-suite","category":"SEO/AEO Source Lessons","status":"implemented","severity":"high","objective":"Convert the Nectiv audit gaps into a dedicated guardrail suite for LLM surfaces, indexable metadata, sitemap parity, crawler-visible errors, and production-domain evidence.","why":"The most useful real-site lessons should become executable checks. Otherwise future agents may praise the example without preventing the specific failure modes it revealed.","checkMethod":"Run a local static server, inspect llms endpoints, page metadata/H1/canonicals, sitemap coverage, crawl evidence, and domain evidence state.","validationCommand":"npm run qa:nectiv","evidenceRequired":["reports/seo-aeo/nectiv-derived-checks-report.json","PASS Nectiv-derived SEO/AEO QA"],"passCriteria":["LLM surfaces exist when AI/AEO claims exist","Indexable pages have H1, description, and canonical","Configured core pages are present in sitemap","Crawl evidence has no critical URL findings"],"warningCriteria":["Production-domain evidence has not been run because no canonical deployed URL is configured"],"failCriteria":["Missing LLM endpoints","Indexable page missing H1/description/canonical","Core page missing from sitemap","Critical crawl URL finding exists"],"sourceLessons":["Nectiv missing llms.txt/llms-full.txt","Nectiv indexable H1/meta gaps","Nectiv crawler-visible 4xx/media findings","Nectiv www TLS issue"]}],"source_traceability":{"policy":{"objective":"Prevent unsupported public claims by connecting page, SEO, schema, and AEO decisions to source artifacts.","why":"Agents can generate polished copy faster than they can verify it. The system must make source support explicit before content is treated as publishable.","rule":"A claim may appear on a public page only when it is present in a raw source, cleaned working fact, approved derived brief, or explicitly marked as fictional/example content.","blockedRule":"Comparative, numeric, testimonial, credential, price, guarantee, legal, medical, financial, and performance claims stay blocked until a source explicitly approves them."},"artifactChain":[{"stage":"raw","path":"data/sources/manifests/example-client-discovery.md","purpose":"Human-readable provenance and permission record for the fictional discovery source.","required":true},{"stage":"working","path":"data/working/example-client-facts.json","purpose":"Cleaned public-safe facts and blocked claims derived from the discovery source.","required":true},{"stage":"derived","path":"data/derived/example-page-brief.json","purpose":"Implementation-ready page brief connecting facts to page purpose, SEO, AEO, schema, and QA.","required":true}],"claimLedger":[{"id":"example-service-area-claim","claim":"Serves Phoenix-area residential and commercial customers.","status":"allowed","sourcePath":"data/working/example-client-facts.json","publicUse":"Allowed because this is a fictional fixture fact marked public-safe.","allowedLocations":["/","/services/","/contact/","LocalBusiness schema","llms-full.txt"],"requiredQualifier":"Keep the claim framed as fixture/example content until adapting to a real site."},{"id":"example-service-list-claim","claim":"Offers preventive maintenance, emergency repair, and system inspection.","status":"allowed","sourcePath":"data/working/example-client-facts.json","publicUse":"Allowed because service categories are listed in the cleaned public-safe fact set.","allowedLocations":["/services/","Service schema","FAQPage schema","llms-full.txt"],"requiredQualifier":"Do not add service details beyond the approved categories without new source evidence."},{"id":"fastest-response-claim","claim":"Fastest response time in the market.","status":"blocked","sourcePath":"data/working/example-client-facts.json","publicUse":"Blocked because comparative performance requires documented proof.","allowedLocations":[],"requiredQualifier":"Requires approved benchmark, methodology, market definition, and date range."},{"id":"hundreds-five-star-reviews-claim","claim":"Hundreds of five-star reviews.","status":"blocked","sourcePath":"data/working/example-client-facts.json","publicUse":"Blocked because review count and rating require an approved live source.","allowedLocations":[],"requiredQualifier":"Requires approved review source, count, rating, capture date, and permission to publish."},{"id":"demo-brightline-service-area-claim","claim":"Serves Alder, Birchfield, and Carver counties with two full-time crews (fictional demo fact).","status":"allowed","sourcePath":"data/working/demo-brightline-facts.json","publicUse":"Allowed inside the canonical demo because the fictional fact set marks it public-safe with the fictional framing preserved.","allowedLocations":["/demo/brightline/","/demo/brightline/service-areas/","/demo/brightline/contact/","LocalBusiness schema","llms-full.txt"],"requiredQualifier":"Must stay framed as fictional demo content."},{"id":"demo-brightline-service-list-claim","claim":"Provides gutter cleaning, gutter repair, gutter guard installation, and downspout maintenance (fictional demo fact).","status":"allowed","sourcePath":"data/working/demo-brightline-facts.json","publicUse":"Allowed inside the canonical demo because service categories come from the cleaned fictional fact set.","allowedLocations":["/demo/brightline/","/demo/brightline/services/","Service schema","FAQPage schema","llms-full.txt"],"requiredQualifier":"No service details beyond the approved categories without new source facts."},{"id":"demo-brightline-license-claim","claim":"Registered and insured for exterior contracting work, fictional registration EX-204-118.","status":"allowed","sourcePath":"data/working/demo-brightline-facts.json","publicUse":"Allowed inside the canonical demo because the fictional registration and insurance facts are recorded in the source chain.","allowedLocations":["/demo/brightline/proof/","LocalBusiness schema"],"requiredQualifier":"Must stay framed as fictional demo content."},{"id":"demo-brightline-review-claim","claim":"Four customers provided written permission to publish their reviews (fictional demo proof).","status":"allowed","sourcePath":"data/working/demo-brightline-facts.json","publicUse":"Allowed inside the canonical demo because each review carries a fictional permission note in the working fact set.","allowedLocations":["/demo/brightline/proof/","Review schema"],"requiredQualifier":"Review count must match the permissioned set exactly."},{"id":"demo-brightline-fastest-claim","claim":"Fastest gutter service in the region.","status":"blocked","sourcePath":"data/working/demo-brightline-facts.json","publicUse":"Blocked because the comparative speed claim has no measurable evidence even inside the fictional fact set.","allowedLocations":[],"requiredQualifier":"Requires an approved benchmark, methodology, market definition, and date range."},{"id":"demo-brightline-review-volume-claim","claim":"Five-star rated by hundreds of customers.","status":"blocked","sourcePath":"data/working/demo-brightline-facts.json","publicUse":"Blocked because only four permissioned reviews exist in the demo source chain.","allowedLocations":[],"requiredQualifier":"Requires an approved review source whose count and rating match the claim."},{"id":"demo-logpilot-feature-claim","claim":"Retains logs for configurable 30/90/365-day windows with immutable retention locks and CSV/JSON export (fictional demo fact).","status":"allowed","sourcePath":"data/working/demo-logpilot-facts.json","publicUse":"Allowed inside the canonical demo because the fictional engineering-confirmed feature facts mark these boundaries public-safe.","allowedLocations":["/demo/logpilot/","/demo/logpilot/product/","/demo/logpilot/use-cases/","SoftwareApplication schema","llms-full.txt"],"requiredQualifier":"Must stay framed as fictional demo content; no capability beyond the confirmed feature facts."},{"id":"demo-logpilot-integration-claim","claim":"Integrates with the six verified platforms listed on the integrations page (fictional demo fact).","status":"allowed","sourcePath":"data/working/demo-logpilot-facts.json","publicUse":"Allowed inside the canonical demo because the six integrations carry fictional engineering verification; the two unverified ones are excluded everywhere.","allowedLocations":["/demo/logpilot/","/demo/logpilot/integrations/","SoftwareApplication schema"],"requiredQualifier":"Integration count must match the verified list exactly."},{"id":"demo-logpilot-comparison-claim","claim":"Comparison pages state dated factual feature differences with caveats (fictional demo policy).","status":"allowed","sourcePath":"data/working/demo-logpilot-facts.json","publicUse":"Allowed because the comparison policy itself is the fact being demonstrated; individual comparisons carry their as-of dates inline.","allowedLocations":["/demo/logpilot/comparison/","FAQPage schema"],"requiredQualifier":"Every comparison row needs an as-of date; superiority adjectives are banned."},{"id":"demo-logpilot-unverified-integrations-claim","claim":"Integrates with two additional platforms currently in development.","status":"blocked","sourcePath":"data/working/demo-logpilot-facts.json","publicUse":"Blocked because the integrations are unverified in the fictional engineering confirmation.","allowedLocations":[],"requiredQualifier":"Requires verification evidence before any public mention."},{"id":"demo-logpilot-superiority-claim","claim":"More secure than every legacy log vendor.","status":"blocked","sourcePath":"data/working/demo-logpilot-facts.json","publicUse":"Blocked as an unsupported competitor superiority claim; the comparison policy allows only dated factual differences.","allowedLocations":[],"requiredQualifier":"No superiority language regardless of evidence; restate as a dated factual difference."}],"pageUsage":[{"route":"/services/","sourceBrief":"data/derived/example-page-brief.json","visibleClaims":["example-service-area-claim","example-service-list-claim"],"blockedClaims":["fastest-response-claim","hundreds-five-star-reviews-claim"],"seoRequirements":["Use approved service categories","State service area without unsupported superiority claims","Use production canonical URL"],"schemaRequirements":["Service facts must be visible on page","FAQPage facts must come from visible FAQs","LocalBusiness facts must match cleaned source facts"],"aeoRequirements":["Answer service scope directly","Preserve caveats near any claims requiring proof"]},{"route":"/demo/brightline/","sourceBrief":"data/derived/demo-brightline-page-brief.json","visibleClaims":["demo-brightline-service-area-claim","demo-brightline-service-list-claim"],"blockedClaims":["demo-brightline-fastest-claim","demo-brightline-review-volume-claim"],"seoRequirements":["State the fictional boundary visibly","Answer who, where, and what directly","Use unique demo metadata"],"schemaRequirements":["LocalBusiness facts must match the demo working facts","FAQPage facts must come from visible FAQs"],"aeoRequirements":["Direct answers for services offered, where served, and how to contact","No blocked superiority or volume phrasing"]},{"route":"/demo/logpilot/","sourceBrief":"data/derived/demo-logpilot-page-brief.json","visibleClaims":["demo-logpilot-feature-claim","demo-logpilot-integration-claim"],"blockedClaims":["demo-logpilot-unverified-integrations-claim","demo-logpilot-superiority-claim"],"seoRequirements":["State the fictional boundary visibly","Category and buyer clarity in title and H1","Unique demo metadata"],"schemaRequirements":["SoftwareApplication facts must match the demo working facts","No integration beyond the verified six"],"aeoRequirements":["Direct answers for what it does, who it serves, and what it does not do","No superiority or in-development phrasing"]},{"route":"/demo/brightline/proof/","sourceBrief":"data/derived/demo-brightline-page-brief.json","visibleClaims":["demo-brightline-review-claim","demo-brightline-license-claim"],"blockedClaims":["demo-brightline-review-volume-claim"],"seoRequirements":["Proof titles use approved outcome language","Review count matches the permissioned set"],"schemaRequirements":["Review schema only for visible permissioned reviews","Registration facts match the working fact set"],"aeoRequirements":["Proof claims keep their permission and date context"]}],"claimInstrumentation":{"objective":"Attach claim IDs directly to rendered copy, schema endpoints, and LLM summaries so unsupported claim use is machine-checkable.","pageSectionClaims":[{"route":"/services/","selector":"[data-claim-id]","attribute":"data-claim-id","claimIds":["example-service-area-claim","example-service-list-claim"],"why":"The services page is the fixture page where visible service area and service scope claims must be source-backed."},{"route":"/demo/brightline/","selector":"[data-claim-id]","attribute":"data-claim-id","claimIds":["demo-brightline-service-area-claim","demo-brightline-service-list-claim"],"why":"The demo homepage carries the entity, area, and service claims that the rest of the demo depends on."},{"route":"/demo/logpilot/","selector":"[data-claim-id]","attribute":"data-claim-id","claimIds":["demo-logpilot-feature-claim","demo-logpilot-integration-claim"],"why":"The SaaS demo homepage carries the feature and integration claims that the rest of the demo depends on."},{"route":"/demo/brightline/proof/","selector":"[data-claim-id]","attribute":"data-claim-id","claimIds":["demo-brightline-review-claim","demo-brightline-license-claim"],"why":"Proof claims are the highest-risk demo claims and must stay attached to their permissioned sources."}],"schemaClaimIds":[{"route":"/services/","endpoint":"/services/schema.json","claimIds":["example-service-area-claim","example-service-list-claim"],"why":"Service and area facts in schema must map to the same allowed claim IDs visible on the page."},{"route":"/contact/","endpoint":"/contact/schema.json","claimIds":["example-service-area-claim"],"why":"LocalBusiness/contact facts must keep service-area claims source-backed."},{"route":"/demo/brightline/","endpoint":"/demo/brightline/schema.json","claimIds":["demo-brightline-service-area-claim","demo-brightline-service-list-claim","demo-brightline-review-claim"],"why":"Demo schema facts must map to the same allowed claim IDs visible on the demo pages."},{"route":"/demo/logpilot/","endpoint":"/demo/logpilot/schema.json","claimIds":["demo-logpilot-feature-claim","demo-logpilot-integration-claim"],"why":"SaaS demo schema facts must map to the same allowed claim IDs visible on the demo pages."}],"llmSummaryClaimIds":["example-service-area-claim","example-service-list-claim","demo-brightline-service-area-claim","demo-brightline-service-list-claim","demo-logpilot-feature-claim"],"blockedClaimIds":["fastest-response-claim","hundreds-five-star-reviews-claim","demo-brightline-fastest-claim","demo-brightline-review-volume-claim","demo-logpilot-unverified-integrations-claim","demo-logpilot-superiority-claim"],"qaGates":["npm run qa:aeo","npm run qa:all"]},"qaRequirements":["Every artifact path must exist.","Every allowed claim must name at least one allowed location.","Every blocked claim must have no allowed locations.","Every page usage item must reference known claim IDs.","Rendered claim-bearing sections must expose known data-claim-id values.","Schema endpoints must include only allowed claimId or claimIds values.","LLM summaries must list allowed claim IDs and avoid blocked claim IDs.","Schema, SEO, AEO, and page copy may not use blocked claims."]},"product_roadmap":[{"priority":1,"id":"step-by-step-agent-walkthroughs","title":"Step-by-step agent walkthroughs","valueMultiplier":"Turns vague website work into deterministic operating behavior.","objective":"Every major website-building task decomposes into objective, why, detailed steps, required evidence, pass/warn/fail criteria, and good/bad examples.","why":"Agents often complete the headline request and miss hidden work. The system must force the reasoning path so quality does not depend on agent intuition.","executionItems":["Create a reusable walkthrough data model.","Convert current workflows into detailed walkthroughs.","Add pass, warning, and fail criteria for each walkthrough.","Attach example evidence paths and relevant QA commands.","Expose walkthroughs through the manifest and a dedicated endpoint."],"stressTests":["Give an agent only the main URL and confirm it can enumerate the required steps for SEO, AEO, buildout, and handoff.","Remove one required detail from a walkthrough and confirm QA fails.","Ask an agent to adapt a site type and confirm it cites the walkthrough before editing."],"acceptanceCriteria":["Every roadmap area has objective, why, steps, evidence, and pass/fail criteria.","The manifest exposes the walkthrough model.","QA validates that no major area is only a vague objective statement."],"objectiveAlignment":"Directly supports the system mission by making the agent inspect, plan, build, validate, and improve without prior context."},{"priority":2,"id":"machine-readable-contracts","title":"Machine-readable contracts","valueMultiplier":"Lets agents consume the system reliably without scraping prose.","objective":"Expose every critical concept as structured JSON with matching schemas and validation.","why":"Agents need stable contracts for routes, files, examples, QA, tasks, roadmap, and future evaluation rubrics.","executionItems":["Maintain /agent-manifest.json as the top-level index.","Keep /file-map.json, /qa-contract.json, /examples.json, /agent-tasks.json, and /product-roadmap.json aligned.","Add JSON Schema for each endpoint.","Validate endpoint shapes in qa:aeo.","Document contract-change rules in AGENTS and playbook."],"stressTests":["Fetch every machine endpoint and validate JSON shape.","Break one endpoint schema intentionally in a fixture and confirm validation catches it.","Confirm all file-map paths resolve on disk."],"acceptanceCriteria":["Every machine endpoint has a schema.","qa:aeo validates all required contract fields.","Future agents can identify all machine endpoints from /agent-manifest.json."],"objectiveAlignment":"Supports context discovery from the main URL and prevents drift between human docs and agent-readable data."},{"priority":3,"id":"good-bad-example-library","title":"Good and bad example library","valueMultiplier":"Turns external site audits into reusable training data.","objective":"Create a structured library of site studies with patterns to reuse, failures to avoid, evidence paths, and checks to add.","why":"Agents learn faster from concrete examples. A good example without its failure modes is incomplete training data.","executionItems":["Define a site-study schema.","Add Nectiv as the first site study.","Capture good patterns, bad patterns, why each matters, and how to detect each one.","Link each pattern to roadmap tasks or QA checks.","Add future examples across local service, SaaS, agency, content hub, and poor AI-generated sites."],"stressTests":["Ask an agent what to copy from Nectiv and what to avoid.","Confirm each site-study issue maps to a check, task, or explicit non-action.","Confirm evidence paths exist for each saved site study."],"acceptanceCriteria":["Site studies are structured and machine-readable.","At least one good and one bad pattern exists for each study.","The system can generate QA improvements from site-study findings."],"objectiveAlignment":"Improves the reference layer by grounding standards in real-world evidence."},{"priority":4,"id":"seo-aeo-evaluation-layer","title":"SEO/AEO evaluation layer","valueMultiplier":"Makes the system capable of judging websites, not just describing them.","objective":"Build a repeatable SEO/AEO evaluation suite covering crawlability, indexability, metadata, schema, LLM endpoints, and domain behavior.","why":"Small technical gaps can break search and model consumption even when a site looks polished.","executionItems":["Add apex/www/http/https/TLS checks.","Compare sitemap URLs against crawled indexable URLs.","Check robots, canonicals, titles, descriptions, H1s, and indexability.","Validate schema by page type.","Require llms.txt and llms-full.txt where AEO/AI-search claims exist.","Classify crawler-visible 403s separately from confirmed broken links."],"stressTests":["Run against Nectiv and confirm the known issues are detected.","Run against the local starter build and confirm expected pass state.","Create fixture pages with missing H1/meta/schema and confirm failures are specific."],"acceptanceCriteria":["SEO/AEO checks produce machine-readable findings.","Findings include severity, why, evidence, and remediation.","The suite distinguishes fail, warning, and manual-verification states."],"objectiveAlignment":"Strengthens the evaluation layer and directly supports launch readiness."},{"priority":5,"id":"source-to-site-traceability","title":"Source-to-site traceability","valueMultiplier":"Prevents unsupported claims and makes generated websites auditable.","objective":"Track every public claim from raw source to cleaned fact, derived brief, page copy, schema, and QA evidence.","why":"Agents can invent proof, credentials, metrics, pricing, or service scope unless source truth is enforced.","executionItems":["Expand source-retention fixtures.","Create claim objects with source, allowed-use status, public copy, and schema mapping.","Add page briefs that cite cleaned facts.","Add QA checks for claim/proof traceability on proof-heavy pages.","Document privacy and permission boundaries."],"stressTests":["Insert an unsupported metric into a fixture brief and confirm review catches it.","Ask an agent to build a proof page and confirm it references source facts.","Confirm private/raw data is not surfaced in public outputs."],"acceptanceCriteria":["Every example claim has a source or an explicit placeholder status.","Proof/case-study patterns require source evidence.","Handoff reports include unresolved claim risks."],"objectiveAlignment":"Supports trustworthy buildout and avoids hallucinated website claims."},{"priority":6,"id":"site-type-build-playbooks","title":"Site-type build playbooks","valueMultiplier":"Lets agents choose the right operating path for different business models.","objective":"Create detailed playbooks for local service, B2B SaaS, professional services, ecommerce/product, content hub, proof hub, AI/AEO authority, and agent-facing documentation sites.","why":"A good website pattern changes by business model. A local service site, SaaS site, and proof hub should not share the same page map or schema defaults.","executionItems":["Define required pages for each site type.","Define schema, metadata, internal-link, proof, and conversion requirements.","Map each playbook to examples and QA commands.","Add source-input requirements for each site type.","Expose playbooks as structured JSON."],"stressTests":["Ask an agent to choose a playbook from a short business brief.","Confirm the chosen playbook lists pages, schema, source needs, and QA.","Compare two site types and confirm their requirements differ."],"acceptanceCriteria":["Each site type has detailed requirements and rationale.","Each playbook maps to page patterns and QA checks.","Agents can select and justify a playbook."],"objectiveAlignment":"Moves the execution layer from generic site advice to business-specific build systems."},{"priority":7,"id":"page-pattern-library","title":"Reusable page pattern library","valueMultiplier":"Gives agents page-level contracts instead of blank-page generation.","objective":"Define patterns for homepage, service, product/technology, comparison, case study, proof, FAQ, glossary/entity, article, contact, AI instructions, privacy, and security pages.","why":"Most website quality failures happen at page level: wrong heading, wrong schema, missing proof, weak internal links, or unsupported claims.","executionItems":["Create a page-pattern data model.","Define required sections and schema for each page type.","Add SEO/AEO requirements per page type.","Add good/bad examples for each pattern.","Add page-pattern validation hooks where possible."],"stressTests":["Ask an agent to create a page from a pattern and inspect whether all required sections appear.","Remove a required section from a fixture and confirm QA or review flags it.","Compare visible content against schema facts."],"acceptanceCriteria":["Every core page type has a pattern contract.","Pattern contracts include why, evidence, pass/fail, and examples.","Page patterns are linked from relevant playbooks."],"objectiveAlignment":"Improves build quality by making page creation systematic."},{"priority":8,"id":"browser-visual-qa","title":"Automated browser and visual QA","valueMultiplier":"Catches layout and interaction failures that static crawls cannot see.","objective":"Add browser checks for desktop/mobile rendering, clipping, overlap, navigation, visible headings, and screenshot evidence.","why":"A technically valid site can still fail for users or agents if text clips, controls overlap, or navigation breaks.","executionItems":["Create browser test runner scripts.","Capture desktop and mobile screenshots for core routes.","Check for visible H1, nav, footer, and primary content.","Add heuristics for clipped or overlapping text.","Store screenshots and findings under reports/browser/."],"stressTests":["Run browser QA at mobile and desktop widths.","Introduce a fixture with clipped text and confirm failure.","Confirm screenshot paths are recorded in handoff evidence."],"acceptanceCriteria":["Browser QA is repeatable locally.","Screenshots are saved for core routes.","Visual failures produce actionable findings."],"objectiveAlignment":"Completes the evaluation layer beyond static crawl and build checks."},{"priority":9,"id":"crawl-evidence-artifacts","title":"Crawl evidence as a first-class artifact","valueMultiplier":"Makes launch and audit decisions evidence-backed.","objective":"Standardize crawl execution, exports, summaries, and before/after evidence.","why":"Without saved crawl evidence, agents repeatedly rediscover the same issues and cannot prove readiness.","executionItems":["Create a crawl report format.","Record target, date, settings, exports, findings, and residual risk.","Add summary parsers for Screaming Frog exports.","Add before/after comparison guidance.","Link crawl artifacts from handoff reports."],"stressTests":["Run a crawl and verify required exports exist.","Parse crawl overview into structured findings.","Confirm a missing export fails the report completeness check."],"acceptanceCriteria":["Crawl evidence has a standard path and summary shape.","Critical crawl findings are machine-readable.","Handoff reports cite crawl evidence."],"objectiveAlignment":"Improves evaluation and source-of-truth continuity."},{"priority":10,"id":"agent-backlog-intelligence","title":"Agent backlog intelligence","valueMultiplier":"Lets future agents continue product work without asking what is next.","objective":"Turn /agent-tasks.json into a serious execution queue with priority, rationale, dependencies, acceptance criteria, risks, and evidence links.","why":"The system should always explain what remains incomplete and how to improve it safely.","executionItems":["Expand task fields beyond title/status.","Add dependencies, risk, evidence, and expected output.","Map tasks to roadmap items.","Add task validation to QA.","Add completed-task evidence links."],"stressTests":["Ask an agent to choose the next task and justify the choice.","Confirm every task maps to a roadmap item.","Confirm no high-priority task lacks acceptance criteria."],"acceptanceCriteria":["Every task has enough detail to execute.","Backlog ordering reflects product priorities.","Completed tasks include evidence."],"objectiveAlignment":"Supports continuous improvement without hidden open loops."},{"priority":11,"id":"design-system-contracts","title":"Design system contracts","valueMultiplier":"Makes design agent-operable instead of just attractive.","objective":"Define design tokens, component rules, layout standards, accessibility constraints, and screenshot pass/fail criteria.","why":"Design work should improve clarity and usability without breaking the agent-readable technical surface.","executionItems":["Create design principles tied to site purpose.","Define tokens for typography, spacing, color, and layout.","Define component usage rules.","Add responsive behavior requirements.","Validate screenshots after visual changes."],"stressTests":["Apply design changes and confirm agent pages remain readable.","Check mobile and desktop screenshots.","Confirm UI changes do not hide machine endpoint discovery."],"acceptanceCriteria":["Design rules are documented and structured.","Components have usage guidance.","Visual QA passes after design changes."],"objectiveAlignment":"Adds polish only after the technical operating system remains intact."},{"priority":12,"id":"aeo-geo-model-context","title":"AEO/GEO model context","valueMultiplier":"Makes websites easier for answer engines and agents to understand.","objective":"Standardize model-readable context: AI instructions, LLM files, entity summaries, answer-ready sections, tables, FAQs, schema maps, and source-backed facts.","why":"AEO/GEO work requires explicit context surfaces, not only traditional HTML pages.","executionItems":["Define AI instructions page pattern.","Enhance llms.txt and llms-full.txt requirements.","Add entity-summary and answer-ready content rules.","Add table/FAQ/schema guidance for citation-worthy facts.","Compare model-readable context against visible content."],"stressTests":["Ask an agent to summarize the site from LLM endpoints only.","Confirm model-readable facts match visible source-backed facts.","Run a missing-LLM-endpoint fixture and confirm failure."],"acceptanceCriteria":["AEO pages expose direct answers and source-backed facts.","LLM endpoints are complete and current.","Agent-facing pages are treated as first-class SEO assets."],"objectiveAlignment":"Strengthens the agent-readiness and answer-engine layer."},{"priority":13,"id":"why-explanations-everywhere","title":"Why explanations everywhere","valueMultiplier":"Improves agent compliance by explaining the reason behind each check.","objective":"Attach rationale to every checklist item, QA finding, roadmap task, and page pattern requirement.","why":"Agents are more reliable when they understand why a step exists and what breaks if it is skipped.","executionItems":["Audit existing checks for missing rationale.","Add why fields to tasks, playbooks, page patterns, and QA findings.","Document failure modes beside each check.","Add schema validation for required rationale fields.","Use Nectiv examples to show why small technical gaps matter."],"stressTests":["Remove a rationale field and confirm schema/QA catches it.","Ask an agent why a check exists and confirm it can answer from the manifest.","Confirm final reports include why for major findings."],"acceptanceCriteria":["No major requirement is rationale-free.","Machine endpoints expose why fields.","Reports explain impact, not just status."],"objectiveAlignment":"Supports the detailed walkthrough rule and makes the system teach, not merely assert."},{"priority":14,"id":"real-site-comparisons","title":"Comparison against real sites","valueMultiplier":"Continuously improves the system through external evidence.","objective":"Create repeatable site-study workflows for excellent, average, and poor websites across categories.","why":"The operating system should learn from real-world SEO/AEO patterns rather than staying theoretical.","executionItems":["Define site-study intake process.","Crawl and inspect each target.","Classify good patterns and failure modes.","Convert findings into roadmap tasks or QA checks.","Maintain a site-study index."],"stressTests":["Run the workflow on Nectiv and at least one contrasting weak site.","Confirm each study produces reusable checks.","Confirm study evidence is saved and discoverable."],"acceptanceCriteria":["Every site study has evidence, analysis, and extracted lessons.","Studies feed the roadmap or examples library.","Agents can compare patterns across studies."],"objectiveAlignment":"Keeps the reference layer grounded in live market examples."},{"priority":15,"id":"handoff-reports","title":"Handoff reports","valueMultiplier":"Makes work durable across agents and sessions.","objective":"Create a standard final report format for builds, audits, fixes, verification, residual risks, and next steps.","why":"Without a handoff artifact, future agents lose context and users cannot judge readiness.","executionItems":["Define handoff report schema.","Include changed files, verification, crawl/browser evidence, unresolved risks, and next tasks.","Add templates for audit-only, buildout, launch, and fix reports.","Link handoff reports from agent tasks.","Validate report completeness before ready state."],"stressTests":["Generate a handoff after a crawl audit.","Generate a handoff after a site build fixture.","Confirm missing evidence or unresolved risk is visible."],"acceptanceCriteria":["Every substantial task can produce a standard handoff.","Reports include evidence and residual risk.","Future agents can resume from the report."],"objectiveAlignment":"Completes the operating loop: inspect, build, validate, and hand off."}],"real_site_comparisons":{"objective":"Make real-site learning repeatable by comparing target sites against reference studies with explicit dimensions, evidence, scoring, and follow-up tasks.","why":"Agents can overfit to one attractive site or ignore useful failures. A comparison contract forces them to separate reusable patterns, context-specific choices, and issues that should become QA or backlog work.","comparisonDimensions":[{"id":"entity-focus","label":"Entity and topical focus","why":"Strong sites make it clear what entity, market, services, and proof surfaces answer systems should associate with them.","evidenceSources":["/site-studies.json","/seo-aeo-evaluation.json","/aeo-geo-context.json"],"scoringQuestion":"Does the site reinforce a coherent entity and topic set without unsupported sprawl?"},{"id":"machine-readable-surface","label":"Machine-readable surface","why":"Agent and answer-engine readiness depends on llms files, schemas, sitemaps, crawl evidence, and context endpoints.","evidenceSources":["/llms.txt","/llms-full.txt","/schemamap.xml","/schema.json","/crawl-evidence.json"],"scoringQuestion":"Can a crawler or agent discover the site's purpose, facts, schema, and evidence without guessing?"},{"id":"crawl-and-domain-health","label":"Crawl and domain health","why":"A polished site can still fail common hostnames, metadata, H1s, response codes, or indexability checks.","evidenceSources":["/crawl-evidence.json","reports/crawl/","reports/domain/"],"scoringQuestion":"Do core crawl and domain variants produce clean evidence?"},{"id":"source-and-claim-safety","label":"Source and claim safety","why":"The best examples are not worth copying if they encourage unsupported claims or private-source leakage.","evidenceSources":["/source-traceability.json","data/working/","data/derived/"],"scoringQuestion":"Can visible claims, schema facts, and answer summaries be traced to approved source evidence?"},{"id":"design-operability","label":"Design operability","why":"Design should improve comprehension and evidence discovery instead of hiding the operating contract.","evidenceSources":["/design-system-contracts.json","/browser-visual-qa.json","reports/browser/"],"scoringQuestion":"Does the visual layer preserve scanning, responsiveness, accessibility, and QA evidence?"}],"scoringModel":[{"score":0,"meaning":"Missing or contradicted by evidence."},{"score":1,"meaning":"Present but weak, incomplete, or unsupported."},{"score":2,"meaning":"Adequate and source-backed, with clear follow-up."},{"score":3,"meaning":"Strong reusable pattern with evidence and low residual risk."}],"comparisonProfiles":[{"id":"nectiv-to-agent-reference","referenceStudyId":"nectiv-digital-seo-aeo-2026-06-04","target":"Agent Website Reference","why":"Nectiv provides a strong SEO/AEO pattern set plus concrete gaps that this reference should prevent through contracts and QA.","reusablePatterns":["Focused AI-search/AEO entity architecture","Commercial service pages mapped to specific buying jobs","Technology and method pages that make differentiation inspectable","Stable schema entities across page types"],"gapsToPrevent":["Missing llms.txt or llms-full.txt on AI-search positioned sites","www/TLS domain variant failures","Indexable pages missing H1 or meta description","Crawler-visible media or internal 4xx issues"],"mappedContracts":["/site-studies.json","/seo-aeo-evaluation.json","/crawl-evidence.json","/aeo-geo-context.json","/why-explanations.json"],"followUpTasks":["add-production-domain-and-crawl-evidence-runners","add-nectiv-derived-seo-aeo-checks","expand-site-study-library-across-site-types"]},{"id":"specification-website-to-agent-reference","referenceStudyId":"specification-website-agent-reference-2026-06-09","target":"Agent Website Reference","why":"Specification Website is a direct reference for the kind of agent-facing discovery, well-known surfaces, API hints, security headers, and documentation IA this product should learn from.","reusablePatterns":["LLM and well-known discovery surfaces are advertised through headers and routes","MCP, A2A, API catalog, sitemap index, RSS, and security policy are discoverable without visual browsing","Documentation IA uses stable category and detail routes","Security and policy headers are part of the public contract"],"gapsToPrevent":["External standards links aging into 404 or crawler-blocked states without classification","Documentation overview/detail pages duplicating title and H1 intent without rationale","API or agent endpoints being misclassified as broken HTML routes because method behavior is not tested separately"],"mappedContracts":["/site-studies.json","/real-site-comparisons.json","/aeo-geo-context.json","/crawl-evidence.json","/why-explanations.json"],"followUpTasks":["add-aeo-geo-model-context-fixtures","add-crawl-stress-suite","expand-site-study-library-across-site-types"]}],"comparisonWorkflow":["Choose a reference study from /site-studies.json.","Choose a target site or current build surface.","Score each comparison dimension from 0 to 3 with evidence.","Separate reusable patterns from context-specific patterns and anti-patterns.","Map each gap to a QA check, contract change, backlog task, or explicit non-action.","Record residual risk and evidence paths before claiming the comparison is complete."],"qaGates":["npm run qa:aeo","npm run qa:seo","npm run qa:crawl","npm run qa:browser","npm run qa:all"],"stressTests":["Compare a strong reference site and ensure at least one reusable pattern maps to a local contract.","Compare a weak reference site and ensure at least one anti-pattern maps to a QA check or task.","Remove the referenced site study and confirm QA fails.","Score a dimension without evidence and reject the comparison.","Ask an agent to justify the next task using the comparison profile."],"passCriteria":["Comparison dimensions are explicit and evidence-backed.","At least one comparison profile references an existing site study.","Profiles list reusable patterns and gaps to prevent.","Profiles map to local contracts and follow-up tasks.","QA validates referenced study IDs and roadmap/task links."],"warningCriteria":["A comparison has evidence but no follow-up task.","A reusable pattern is too brand-specific to adapt safely.","A score is plausible but lacks a cited evidence path.","A gap is context-specific and should become a non-action rather than a rule."],"failCriteria":["A comparison profile references a missing site study.","A comparison score has no evidence source.","A gap is identified but not mapped to a check, task, contract, or non-action.","An agent copies brand, copy, or assets from a reference site."],"objectiveAlignment":"Turns real-site research into durable operating-system improvements instead of informal inspiration."},"contract_registry":[{"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."}],"source_retention_model":[{"stage":"raw","directory":"data/sources/raw/","purpose":"Immutable source material exactly as received or captured.","example":"data/sources/raw/specification-website-llms-2026-06-02.txt"},{"stage":"manifest","directory":"data/sources/manifests/","purpose":"Human-readable provenance notes describing source origin, date, permissions, and use constraints.","example":"data/sources/manifests/example-client-discovery.md"},{"stage":"working","directory":"data/working/","purpose":"Cleaned, normalized, or public-safe facts derived from raw sources.","example":"data/working/example-client-facts.json"},{"stage":"derived","directory":"data/derived/","purpose":"Generated briefs, content outlines, QA summaries, and implementation-ready artifacts.","example":"data/derived/example-page-brief.json"}],"qa_contract":[{"command":"npm run qa:routes","checks":["Core HTML routes return 200","Machine endpoints return 200","Internal links return 200","Sitemap URLs resolve"]},{"command":"npm run qa:seo","checks":["Unique titles","Valid descriptions","Canonical URLs","One H1","Open Graph parity","Favicon","JSON-LD"]},{"command":"npm run qa:aeo","checks":["llms.txt","llms-full.txt","schemamap.xml","Schema endpoint JSON","Contract registry","Site studies","SEO/AEO evaluation","Source traceability","Organization/WebSite facts","FAQ/LocalBusiness where expected"]},{"command":"npm run qa:browser","checks":["Desktop screenshots","Mobile screenshots","Visible H1","Horizontal overflow","Viewport overflow","Potential text clipping report","Landmark/name/alt/duplicate-id/focus heuristics","Screenshot baseline visual diff with mutation control","Keyboard focus navigation per desktop route","axe-core WCAG 2.2 AA accessibility scan (2.0/2.1/2.2 tag set)"]},{"command":"npm run qa:crawl","checks":["Required crawl inventory exports","Screaming Frog issue export summary","Critical response-code findings","Crawl evidence report under reports/crawl/"]},{"command":"npm run qa:agent","checks":["Main URL orientation simulation","SEO/AEO walkthrough selection","Crawl/browser readiness simulation","Handoff continuation simulation"]},{"command":"npm run qa:contracts","checks":["Live contract registry endpoints","Schema/source existence","Missing endpoint fixture","Missing schema fixture","Missing source fixture","Missing evidence fixture","Execution-track document statuses match /agent-tasks.json","Execution-track drift fixtures fail as expected"]},{"command":"npm run qa:copy","checks":["Weak copy fixtures fail control checks","Improved copy includes required conversion signals","Required principles map to the copy contract","Forbidden phrases do not survive transformation","Report saved under reports/copy-stress/"]},{"command":"npm run qa:crawl-stress","checks":["Static export re-crawled from homepage, sitemap, and manifest seeds","Broken internal links fail with referrers","Redirect chains beyond budget fail","Documented response-time and response-size budgets enforced","Sitemap URLs unreachable from the homepage fail","Synthetic negative controls fail as expected"]},{"command":"npm run qa:playbooks","checks":["Every site-type playbook has a simulated build fixture","Required inputs are provided or explicitly waived","Planned pages map to known page patterns and required schema","Published claims carry simulated source IDs and blocked claims carry reasons","Playbook QA gates and stress tests are covered","Unresolved risks are declared","Negative controls fail in expected ways"]},{"command":"npm run qa:perf","checks":["Local LCP/CLS measured per route against budgets","HTML/CSS/JS/image/font asset budgets enforced","Images require dimensions; head scripts may not block; stylesheet count capped","Zero-JS default with explicit exception list","Synthetic budget-violation controls fail as expected"]},{"command":"npm run qa:demo","checks":["Demo source chain files exist","Demo pages implement the full playbook page model","Required schema types render in JSON-LD","Visible claims carry allowed ledger claim IDs","Blocked phrases stay off pages, schema, and LLM surfaces","Fictional boundary stays visible","Negative controls fail as expected"]},{"command":"npm run qa:domain","checks":["Local static route readiness","Machine route readiness","Required security headers configured in public/_headers","Optional QA_PRODUCTION_URL apex/www/http/https/TLS variant evidence","Optional QA_PRODUCTION_URL live security-header verification"]},{"command":"npm run qa:nectiv","checks":["LLM surfaces for AI/AEO claims","Indexable H1/description/canonical guardrails","Sitemap/core-route parity","Crawler-visible critical URL findings","Production-domain evidence warning"]},{"command":"npm run qa:handoff","checks":["Generated handoff report","QA evidence summaries","Residual risks","Next actions from /agent-tasks.json"]},{"command":"npm run qa:all","checks":["Spec audit","Astro check","Build","Route QA","SEO QA","Browser visual QA","Performance budget QA","Crawl evidence QA","Crawl stress QA","AEO QA","Agent simulation QA","Contract drift QA","Copy stress QA","Page-pattern fixture QA","Playbook simulation QA","Demo build QA","Domain/static QA","Generated handoff QA"]}],"agent_tasks":[{"id":"add-contract-schema-validation","status":"done","priority":"high","title":"Validate agent JSON contracts","rationale":"Agents need predictable endpoint shapes before deeper automation and stress testing.","files":["public/schemas/","scripts/qa-aeo.mjs"],"completionCriteria":["JSON schema files exist","QA validates endpoint shapes","File-map paths resolve"]},{"id":"add-contract-registry","status":"done","priority":"high","title":"Add formal machine-readable contract registry","rationale":"Agents need a direct map from each formal JSON endpoint to its schema, source file, owner, validation command, evidence, and failure mode.","files":["src/data/agent-reference.ts","src/pages/contract-registry.json.ts","public/schemas/contract-registry.schema.json","scripts/qa-aeo.mjs"],"completionCriteria":["Registry is exposed in /agent-manifest.json and /contract-registry.json","Every registry endpoint and schema returns 200","Every registry source path exists","QA fails if a formal JSON endpoint is missing from the registry"]},{"id":"add-browser-regression-suite","status":"done","priority":"high","title":"Add browser regression and screenshot checks","rationale":"The reference needs automated visual confidence before design-system work. Browser QA now captures desktop/mobile screenshots and checks visible headings plus overflow conditions.","files":["scripts/qa-browser.mjs","reports/browser/","src/pages/browser-visual-qa.json.ts","public/schemas/browser-visual-qa.schema.json","package.json"],"completionCriteria":["Desktop and mobile screenshots are captured","Main routes are checked for clipping and overlap","Failures are reproducible locally","Browser QA report is saved under reports/browser/"]},{"id":"expand-browser-qa-with-visual-diff-and-accessibility","status":"done","priority":"high","title":"Expand browser QA with visual diff and accessibility checks","rationale":"qa:browser now compares every route/viewport screenshot against committed baselines under tests/browser/baselines/ with pixelmatch (QA_UPDATE_BASELINES=1 accepts intentional changes, and a mutated-screenshot control proves the diff engine detects change), tabs through every desktop route asserting keyboard operability and visible focus indicators, and runs axe-core WCAG 2.0 A/AA scans on every route/viewport. Its first axe run caught scrollable table regions without keyboard access on /repo-map/, fixed with focusable labeled regions.","files":["scripts/qa-browser.mjs","reports/browser/","tests/browser/baselines/","src/data/agent-reference.ts","package.json"],"completionCriteria":["Screenshot baselines can be compared","Keyboard/focus checks run on core routes","Accessibility findings are reported","Failures include reproducible route/viewport evidence"]},{"id":"add-objective-detail-walkthrough-contract","status":"done","priority":"high","title":"Require every major objective to decompose into detailed checks and rationale","rationale":"This system is for agents building websites. Agents need explicit step-by-step instructions with the why behind each step, not a single broad objective that leaves the work implied.","files":["src/data/agent-reference.ts","docs/system-purpose.md","docs/agent-playbook.md","src/pages/agent-manifest.json.ts","src/pages/walkthroughs.json.ts","public/schemas/walkthroughs.schema.json"],"completionCriteria":["Each roadmap area has objective, why, steps, evidence, pass criteria, warning criteria, fail criteria, stress tests, and objective alignment","Agent manifest and /walkthroughs.json expose the detailed walkthrough model","QA and schemas fail when required walkthrough detail is missing"]},{"id":"stress-test-walkthrough-model-with-agent-simulation","status":"done","priority":"high","title":"Stress test walkthrough model with simulated agent runs","rationale":"The walkthrough contract now has generated agent-simulation evidence proving a future agent can start from the main URL, recover the operating model, choose relevant walkthroughs, and cite handoff evidence without chat context.","files":["scripts/qa-agent-simulation.mjs","reports/agent-simulation/","src/data/agent-reference.ts"],"completionCriteria":["A simulated agent can enumerate roadmap priorities from /agent-manifest.json","A simulated agent can choose the right walkthrough for SEO/AEO, buildout, crawl QA, and handoff prompts","Stress-test reports are saved and linked from future handoff evidence"]},{"id":"stress-test-contract-registry-with-drift-fixtures","status":"done","priority":"high","title":"Stress test contract registry with drift fixtures","rationale":"The registry now has live contract checks and fixture-based negative tests proving missing endpoints, schemas, source files, and evidence fail in predictable ways.","files":["scripts/qa-contract-drift.mjs","reports/contracts/","src/data/agent-reference.ts"],"completionCriteria":["Broken endpoint fixture fails","Broken schema fixture fails","Missing source fixture fails","Stress-test report explains the failure modes future agents should recognize"]},{"id":"add-good-bad-site-study-library","status":"done","priority":"high","title":"Add structured good/bad real-site study library","rationale":"Agents need concrete examples that include both patterns worth reusing and failures worth preventing, with evidence paths and checks to add.","files":["src/data/agent-reference.ts","src/pages/site-studies.json.ts","public/schemas/site-studies.schema.json","scripts/qa-aeo.mjs"],"completionCriteria":["At least one real-site study exists","Every study has strong patterns and avoid patterns","Evidence files resolve on disk","Linked roadmap IDs are valid"]},{"id":"add-seo-aeo-evaluation-layer","status":"done","priority":"high","title":"Add structured SEO/AEO evaluation layer","rationale":"Agents need a repeatable evaluation suite that explains each SEO/AEO check, why it matters, which command proves it, and which checks still require production crawl or domain evidence.","files":["src/data/agent-reference.ts","src/pages/seo-aeo-evaluation.json.ts","public/schemas/seo-aeo-evaluation.schema.json","scripts/qa-aeo.mjs","scripts/qa-seo.mjs","scripts/qa-routes.mjs"],"completionCriteria":["Evaluation endpoint exists","Manifest exposes evaluation checks","Implemented checks name executable QA commands","Planned checks state required evidence paths","QA validates evaluation shape and status"]},{"id":"add-crawl-evidence-contract-and-summarizer","status":"done","priority":"high","title":"Add crawl evidence contract and export summarizer","rationale":"Agents need crawl outputs to become durable machine-readable evidence instead of loose CSV files or one-off notes.","files":["src/pages/crawl-evidence.json.ts","public/schemas/crawl-evidence.schema.json","scripts/qa-crawl.mjs","data/derived/example-crawl-export/","reports/crawl/"],"completionCriteria":["Crawl evidence endpoint exists","Manifest exposes required exports and severity rules","qa:crawl summarizes Screaming Frog exports","qa:all runs crawl evidence QA","Reports are saved under reports/crawl/"]},{"id":"add-production-domain-and-crawl-evidence-runners","status":"done","priority":"high","title":"Add production domain and crawl evidence runners","rationale":"Domain/static QA now checks local routes and production discovery surfaces when QA_PRODUCTION_URL is provided. The crawl runner writes a deterministic plan during normal QA and can execute Screaming Frog through the approved wrapper against either the local static build or the deployed canonical URL.","files":["scripts/qa-domain.mjs","scripts/run-crawl-evidence.mjs","reports/domain/","reports/crawl/","src/data/agent-reference.ts"],"completionCriteria":["Domain runner checks apex/www/http/https/TLS and discovery surfaces when a production URL exists","Screaming Frog wrapper can run against static export or production URL","Runner plan and reports are saved under reports/","Normal QA verifies runner shape without unexpectedly launching Screaming Frog"]},{"id":"add-source-to-site-traceability-contract","status":"done","priority":"high","title":"Add source-to-site traceability contract","rationale":"Agents need a machine-readable source chain before public claims, schema facts, metadata, or LLM summaries can be treated as safe.","files":["src/data/agent-reference.ts","src/pages/source-traceability.json.ts","public/schemas/source-traceability.schema.json","scripts/qa-aeo.mjs","data/"],"completionCriteria":["Traceability endpoint exists","Artifact paths resolve","Allowed claims name allowed locations","Blocked claims have no allowed locations","Page usage references known claim IDs"]},{"id":"add-page-level-claim-id-instrumentation","status":"done","priority":"high","title":"Add page-level claim ID instrumentation","rationale":"The traceability ledger now maps claim IDs to visible page sections, schema endpoints, and LLM summary claim IDs, and qa:aeo fails on unknown, missing, or blocked claim usage.","files":["src/pages/services.astro","src/pages/services/schema.json.ts","src/pages/contact/schema.json.ts","src/pages/llms-full.txt.ts","src/data/agent-reference.ts","scripts/qa-aeo.mjs"],"completionCriteria":["Visible claim sections reference claim IDs","Schema facts reference claim IDs where possible","QA fails if a blocked claim ID is used publicly","LLM summaries avoid blocked claim IDs"]},{"id":"add-site-type-build-playbooks","status":"done","priority":"high","title":"Add executable site-type build playbooks","rationale":"Agents need more than example categories. They need build order, required inputs, page models, SEO/AEO rules, traceability rules, QA gates, stress tests, and completion criteria by site type.","files":["src/data/agent-reference.ts","src/pages/site-type-playbooks.json.ts","public/schemas/site-type-playbooks.schema.json","scripts/qa-aeo.mjs"],"completionCriteria":["Every example has a playbook","Every playbook includes page model and schema requirements","Every playbook includes qa:all, stress tests, and completion criteria","QA validates playbook/example alignment"]},{"id":"stress-test-site-type-playbooks-with-simulated-builds","status":"done","priority":"high","title":"Stress test site-type playbooks with simulated builds","rationale":"Every playbook now has a fictional simulated build fixture covering prompt, input decisions, pattern-mapped pages, claim publish/block decisions, planned QA gates, stress-test responses, and unresolved risks, validated by qa:playbooks with negative controls that fail on missing inputs, unknown patterns, missing schema, unsourced claims, missing QA gates, and zero-risk dishonesty.","files":["scripts/qa-playbook-simulation.mjs","data/derived/playbook-simulations/playbook-simulation-fixtures.json","reports/playbooks/","src/data/agent-reference.ts","package.json"],"completionCriteria":["Each playbook has a simulated build prompt","Simulation reports capture selected inputs, pages, claim decisions, QA gates, and unresolved risks","Failures become playbook improvements or tasks"]},{"id":"add-reusable-page-pattern-library","status":"done","priority":"high","title":"Add reusable page pattern library","rationale":"Agents need page-level contracts, not just site-level playbooks. Each page type should define required sections, schema, SEO/AEO, traceability, QA gates, anti-patterns, stress tests, and done criteria.","files":["src/data/agent-reference.ts","src/pages/page-patterns.json.ts","public/schemas/page-patterns.schema.json","scripts/qa-aeo.mjs"],"completionCriteria":["Page-pattern endpoint exists","At least six page patterns exist","Every pattern includes schema, QA gates, anti-patterns, stress tests, and completion criteria","QA validates page-pattern shape"]},{"id":"add-conversion-copy-lab","status":"done","priority":"high","title":"Add conversion copy lab and agent copy workflow","rationale":"Agents need explicit copy strategy, weak and strong examples, ethical source boundaries, and conversion-focused writing checks before they create client website copy.","files":["src/pages/copy-lab.astro","src/pages/conversion-copy.json.ts","public/schemas/conversion-copy.schema.json","data/sources/manifests/hormozi-conversion-copy-study-2026-06-06.md","src/data/agent-reference.ts","scripts/qa-aeo.mjs"],"completionCriteria":["Copy lab page exists","Machine endpoint exposes copy principles, source boundaries, examples, workflow, anti-patterns, and QA gates","Source study manifest cites public sources","QA validates the copy contract"]},{"id":"stress-test-conversion-copy-transformations","status":"done","priority":"high","title":"Stress test conversion copy transformations with weak-copy fixtures","rationale":"The copy lab should prove that agents can transform weak prompts into specific, mechanism-aware, proof-aware copy while rejecting generic, fake-urgent, and unsupported phrasing.","files":["scripts/qa-copy-stress.mjs","data/derived/copy-stress/copy-stress-fixtures.json","reports/copy-stress/copy-stress-report.json","src/data/agent-reference.ts","package.json"],"completionCriteria":["Weak-copy fixtures exist","Improved-copy fixtures include required conversion signals","Bad-copy controls fail for the expected reasons","qa:copy writes a report and runs inside qa:all"]},{"id":"add-offer-ecosystem-endpoint","status":"done","priority":"high","title":"Add offer ecosystem funnel endpoint","rationale":"Agents need a dedicated system for mapping AI tools, communities, workshops, playbooks, pricing tiers, qualification gates, referral engines, and disclaimers into one coherent website funnel.","files":["src/pages/offer-ecosystem.json.ts","public/schemas/offer-ecosystem.schema.json","src/data/agent-reference.ts","scripts/qa-aeo.mjs"],"completionCriteria":["Offer ecosystem endpoint exists","Funnel layers include role, why, page elements, proof needs, and guardrails","Funnel paths reference known layers","QA validates endpoint and schema coverage"]},{"id":"add-infrastructure-decision-system","status":"done","priority":"high","title":"Add tiered infrastructure decision system","rationale":"Agents need to walk through infrastructure choices by requirement tier and concrete scenario examples instead of choosing hosting, CMS, auth, data, analytics, payments, DNS, or deployment defaults by habit.","files":["src/pages/infrastructure-decisions.json.ts","public/schemas/infrastructure-decisions.schema.json","src/data/agent-reference.ts","scripts/qa-aeo.mjs"],"completionCriteria":["Infrastructure endpoint exists","Decision areas include tiers, tradeoffs, questions, and guardrails","Site-type recommendations include defaults and upgrade triggers","Scenario examples cover GitHub, Cloudflare, Astro, Next.js, Stripe, CMS, auth, analytics, forms, and deployment tradeoffs","QA validates required infrastructure coverage"]},{"id":"stress-test-page-patterns-with-route-fixtures","status":"done","priority":"high","title":"Stress test page patterns with route fixtures","rationale":"Each page-pattern contract now has a concrete Astro fixture route plus a machine-readable fixture inventory and QA runner that checks route renderability, one H1, visible sections, source notes, schema notes, good/bad examples, agent instructions, and pattern mapping.","files":["src/pages/fixtures/page-patterns/","src/pages/page-pattern-fixtures.json.ts","public/schemas/page-pattern-fixtures.schema.json","scripts/qa-page-pattern-fixtures.mjs","reports/page-pattern-fixtures/","src/data/agent-reference.ts"],"completionCriteria":["Each pattern has a fixture route","Fixture routes pass metadata, section, schema-note, traceability-note, and good/bad example checks","Report captures checked routes and completion evidence"]},{"id":"expand-site-study-library-across-site-types","status":"done","priority":"high","title":"Expand site-study library across strong and weak website types","rationale":"The library now includes six studies spanning agency SEO/AEO, agent-facing specification/documentation, personal consultant, SaaS/product, content-led expert consultant, and an intentionally poor local-service fixture with evidence paths and mapped checks.","files":["src/data/agent-reference.ts","reports/crawl/","data/derived/site-studies/"],"completionCriteria":["At least six site studies exist","At least one study covers agent-facing specification/documentation surfaces","Each study includes good and bad patterns","Each study maps findings to roadmap items or QA checks","Studies include at least one intentionally poor example"]},{"id":"add-real-site-comparison-contract","status":"done","priority":"high","title":"Add real-site comparison contract","rationale":"Agents need a repeatable way to compare target sites against reference studies, score dimensions, separate reusable patterns from gaps, and convert findings into tasks.","files":["src/pages/real-site-comparisons.json.ts","public/schemas/real-site-comparisons.schema.json","src/data/agent-reference.ts","scripts/qa-aeo.mjs"],"completionCriteria":["Comparison endpoint exists","At least one profile references an existing site study","Profiles map to contracts and follow-up tasks","QA validates dimensions, profiles, study IDs, and task IDs"]},{"id":"add-crawl-stress-suite","status":"done","priority":"high","title":"Add crawl and endpoint stress testing","rationale":"qa:crawl-stress now re-crawls the static export with a built-in license-free crawler on every QA run: it follows internal links from the homepage, seeds sitemap and manifest endpoints, enforces documented response-time/size/redirect budgets from /crawl-evidence.json, fails on broken links and orphaned sitemap URLs, and proves its rules with synthetic negative controls. Its first run caught four sample routes present in the sitemap but unreachable from the homepage.","files":["scripts/qa-crawl-stress.mjs","reports/crawl/crawl-stress-report.json","src/data/agent-reference.ts","public/schemas/crawl-evidence.schema.json","package.json"],"completionCriteria":["Static export crawl is repeatable","Endpoint response budgets are documented","Broken links and redirect chains fail QA"]},{"id":"reconcile-execution-track-with-task-ledger","status":"done","priority":"high","title":"Keep the execution-track document verifiably aligned with the task ledger","rationale":"The execution-track document had drifted: copy/offer and agent-simulation work was complete in the ledger but still marked next in the doc, which would have sent a fresh agent into redundant work. The doc now lists backing task IDs per item, and qa:contracts parses it and fails when a doc status contradicts /agent-tasks.json, with negative fixtures proving the failure paths.","files":["docs/site-expansion-execution-track.md","scripts/qa-contract-drift.mjs","reports/contracts/","src/data/agent-reference.ts"],"completionCriteria":["Execution-track items list their backing task IDs","qa:contracts fails when a doc status contradicts the task ledger","Drift fixtures prove done-while-open, open-while-done, and unknown-task failures"]},{"id":"add-nectiv-derived-seo-aeo-checks","status":"done","priority":"high","title":"Add Nectiv-derived SEO/AEO checks to the evaluation layer","rationale":"The Nectiv crawl lessons now run as a dedicated guardrail suite covering LLM surfaces, indexable H1/description/canonical requirements, sitemap coverage, crawl critical findings, and explicit production-domain evidence warnings.","files":["scripts/qa-nectiv-lessons.mjs","reports/seo-aeo/","src/data/agent-reference.ts","reports/crawl/","reports/domain/"],"completionCriteria":["QA checks production-domain evidence state","QA compares sitemap URLs with configured indexable core pages","QA requires llms.txt and llms-full.txt when AEO/AI-search claims exist","QA flags indexable pages without H1, meta description, or canonical","QA distinguishes crawler-visible critical findings from production-domain evidence warnings"]},{"id":"add-agent-backlog-intelligence-contract","status":"done","priority":"high","title":"Add agent backlog intelligence contract","rationale":"The backlog needs to tell future agents what to do next, why, what it maps to, what risk it carries, and which evidence proves completion.","files":["src/pages/agent-tasks.json.ts","public/schemas/agent-tasks.schema.json","src/data/agent-reference.ts","scripts/qa-aeo.mjs"],"completionCriteria":["Agent tasks expose roadmap IDs","Next actions are generated in priority order","Tasks include risk, dependencies, expected output, QA gate, evidence links, and acceptance criteria","QA validates backlog shape and roadmap mapping"]},{"id":"add-design-system-contract-layer","status":"done","priority":"high","title":"Add backend design-system contract layer","rationale":"Future visual work needs machine-readable rules for tokens, components, accessibility, responsive behavior, anti-patterns, QA gates, and stress tests before UI polish begins.","files":["src/pages/design-system-contracts.json.ts","public/schemas/design-system-contracts.schema.json","src/data/agent-reference.ts","scripts/qa-aeo.mjs"],"completionCriteria":["Design contract endpoint exists","Manifest and llms-full expose design rules","Contract registry includes ownership and schema","QA validates tokens, component rules, anti-patterns, and QA gates"]},{"id":"add-aeo-geo-model-context-fixtures","status":"done","priority":"high","title":"Add AEO/GEO model context contract and fixtures","rationale":"Future agents need answer-engine prompt fixtures, context surfaces, citation rules, blocked-claim checks, and evidence records before this can claim AEO/GEO readiness.","files":["src/pages/aeo-geo-context.json.ts","public/schemas/aeo-geo-context.schema.json","data/derived/aeo-geo-context/","src/data/agent-reference.ts","scripts/qa-aeo.mjs"],"completionCriteria":["AEO/GEO context endpoint exists","Prompt and answer evidence fixtures exist","Manifest and llms-full expose model context","QA validates context surfaces, fixture paths, citation rules, and QA gates"]},{"id":"add-why-explanations-contract","status":"done","priority":"high","title":"Add why-explanations contract","rationale":"Agents need explicit rationale surfaces, quality rules, anti-patterns, QA coverage, and stress tests so they do not treat broad objectives as enough detail.","files":["src/pages/why-explanations.json.ts","public/schemas/why-explanations.schema.json","src/data/agent-reference.ts","scripts/qa-aeo.mjs"],"completionCriteria":["Why explanations endpoint exists","Manifest and llms-full expose rationale rules","QA validates required surfaces and rationale coverage","Contract registry lists failure mode and evidence"]},{"id":"add-handoff-report-contract","status":"done","priority":"high","title":"Add handoff report contract","rationale":"Future agents need a final report structure that captures outcome, changed artifacts, verification evidence, residual risks, next actions, and open background work.","files":["src/pages/handoff-reports.json.ts","public/schemas/handoff-reports.schema.json","reports/handoff/example-handoff-report.json","src/data/agent-reference.ts","scripts/qa-aeo.mjs"],"completionCriteria":["Handoff endpoint exists","Example handoff report fixture exists","Required sections cover outcome, changes, verification, evidence, risks, and next actions","QA validates fixture path and section coverage"]},{"id":"add-handoff-report-format","status":"done","priority":"high","title":"Generate real handoff reports from completed runs","rationale":"The handoff contract now has a generator that reads current QA, crawl, browser, backlog, domain/static, contract-drift, and agent-simulation evidence into a durable continuation report.","files":["scripts/qa-handoff.mjs","reports/handoff/","docs/agent-playbook.md","src/data/agent-reference.ts"],"completionCriteria":["A script generates dated handoff reports","Reports cite current QA, browser, crawl, source, and schema evidence","Open risks and next tasks are machine-readable"]},{"id":"close-strategy-layer-gaps","status":"done","priority":"high","title":"Close the strategy-layer gaps: search intent, funnel measurement, i18n decisions, cheap orientation index","rationale":"The audit graded several disciplines as operationally thin. The SEO endpoint now carries a search-intent mapping strategy (intent types with demo examples, one-intent-per-page workflow, internal-link architecture rules); the offer ecosystem gained a measurement layer with per-layer instrumentation and failing-when thresholds; infrastructure decisions gained an internationalisation area with a deliberately-monolingual tier documenting this site's own choice; /agent-index.json gives token-constrained agents an 8.5KB complete index instead of the 400KB aggregate manifest; and the sitemap now ships lastmod.","files":["src/data/agent-reference.ts","src/pages/seo-aeo-evaluation.json.ts","src/pages/agent-index.json.ts","public/schemas/agent-index.schema.json","src/pages/sitemap.xml.ts","src/pages/llms.txt.ts"],"completionCriteria":["Intent strategy published with demo-grounded examples","Every funnel layer has an instrument and a failing-when threshold","i18n decision area exists with the monolingual choice documented","agent-index under 25KB with full endpoint parity","Sitemap entries carry lastmod"]},{"id":"publish-qa-evidence-and-aeo-baseline","status":"done","priority":"high","title":"Publish QA evidence at live URLs and record the first real AEO baseline","rationale":"The system promised evidence over assertion while keeping every report on the workstation. /evidence/index.json now publishes twelve dated QA reports (workstation paths redacted, one accepted run behind by design, refreshed automatically by deploy.sh), and the AEO context gained four demo-grounded prompt fixtures plus a dated site-grounded baseline answer-evidence record that is honest about being pre-indexing.","files":["scripts/publish-evidence.mjs","public/evidence/","public/schemas/evidence-index.schema.json","data/derived/aeo-geo-context/demo-prompt-set.json","data/derived/aeo-geo-context/baseline-answer-evidence-2026-06-10.json","src/data/agent-reference.ts","deploy.sh"],"completionCriteria":["Evidence index and all reports return 200 on the live site","Workstation paths are redacted from published artifacts","Six prompt fixtures cover reference and both demos","A dated answer-evidence record exists with honest pre-indexing limits"]},{"id":"add-saas-demo-and-brand-tokens","status":"done","priority":"high","title":"Add the LogPilot SaaS demo and per-brand design tokens","rationale":"The system needed proof on a second, harder site type and proof that the token system produces design. LogPilot now executes the B2B SaaS playbook end to end (source chain, five pattern-mapped routes, ledger claims with two blocked SaaS temptations: unverified integrations and superiority language), and both demos carry distinct brand identities implemented purely as token overrides — Brightline steel-blue light, LogPilot dark SaaS — with axe contrast passing on both. Conversion copy gained four public-domain frameworks (AIDA, PAS, 4U, JTBD) and vertical-diverse transformations tied to the demos.","files":["src/pages/demo/logpilot/","src/utils/demo-schema.ts","src/styles/global.css","src/layouts/BaseLayout.astro","data/sources/manifests/demo-logpilot-discovery.md","data/working/demo-logpilot-facts.json","data/derived/demo-logpilot-page-brief.json","src/data/agent-reference.ts"],"completionCriteria":["Second demo passes qa:demo with its playbook page model","Blocked SaaS claims provably stay off all surfaces","Both demo brands are token-only overrides passing axe contrast","Copy system carries multiple independent frameworks and vertical examples"]},{"id":"make-design-tokens-real-values","status":"done","priority":"high","title":"Publish real design token values with drift enforcement","rationale":"The design tokens were sentences, not values. The contract now publishes 25 tokens with exact light/dark values (palette, type scale, spacing, radius, elevation, font stack) sourced from CSS custom properties in global.css, plus value-level media and motion rules. qa:aeo parses the stylesheet on every run and fails when any published token drifts from the CSS, proven by mutation testing.","files":["src/styles/global.css","src/data/agent-reference.ts","scripts/qa-aeo.mjs"],"completionCriteria":["Tokens publish exact values with CSS variable names","Type and spacing scales are CSS variables consumed by the live styles","qa:aeo fails on token drift (mutation-tested)","Media and motion rules carry values and budgets, not adjectives"]},{"id":"add-accessibility-contract","status":"done","priority":"high","title":"Add standalone WCAG 2.2 AA accessibility contract","rationale":"Accessibility guidance was scattered across design and QA files and targeted WCAG 2.0. /accessibility-contract.json now states the 2.2 AA target with value-level rules (contrast ratios, 24px target size, focus visibility, landmarks, names), qa:browser scans with the full 2.0/2.1/2.2 tag set, and the contract carries an honest automated-coverage caveat plus a manual review checklist.","files":["src/pages/accessibility-contract.json.ts","public/schemas/accessibility-contract.schema.json","scripts/qa-browser.mjs","src/data/agent-reference.ts"],"completionCriteria":["Contract endpoint with schema and registry coverage","axe runs the 2.2 tag set with zero critical/serious violations","Value rules name numbers, not adjectives","Manual review checklist included"]},{"id":"add-performance-budget-contract","status":"done","priority":"high","title":"Add performance budgets with measured enforcement","rationale":"Performance was the largest missing discipline: the system taught SEO, schema, copy, and QA while page speed remained unbudgeted. /performance-budgets.json now publishes Core Web Vitals targets, asset budgets (zero-JS default with explicit exceptions), and page rules, and qa:perf measures local LCP/CLS per route via Playwright, enforces every budget against the built output, and proves its rules with synthetic violation controls.","files":["src/pages/performance-budgets.json.ts","public/schemas/performance-budgets.schema.json","scripts/qa-performance.mjs","reports/performance/","src/data/agent-reference.ts","package.json"],"completionCriteria":["Budgets endpoint with schema and registry coverage","qa:perf measures LCP/CLS per route and enforces asset budgets","Negative controls fail as expected","qa:perf runs inside qa:all"]},{"id":"refresh-human-readable-agent-docs","status":"done","priority":"high","title":"Refresh human-readable agent docs against the current system","rationale":"docs/agent-playbook.md now covers the full current QA contract in run order with the why behind each suite, the simulated-build/crawl-stress/visual-baseline/drift-check systems, the canonical demo as the reference implementation to diff against, and the copy/offer/infrastructure reading steps; the execution tracker statuses are drift-checked against the task ledger by qa:contracts.","files":["docs/agent-playbook.md","docs/system-purpose.md","docs/product-roadmap.md","docs/site-expansion-execution-track.md"],"completionCriteria":["Playbook covers the full current QA contract and order of operations","Each major step explains why it exists","Docs reference the simulated-build, crawl-stress, visual-baseline, and drift-check systems","Execution tracker statuses match the task ledger"]},{"id":"build-canonical-demo-site","status":"done","priority":"high","title":"Build the canonical demo site end to end","rationale":"The fictional Brightline Gutter Co. demo now executes the local service playbook end to end: source manifest, working facts, and page brief under data/, five pattern-mapped routes under /demo/brightline/ with metadata, JSON-LD, and claim instrumentation wired into the traceability ledger, a /demo-build.json record with schema and registry coverage, and qa:demo validating pages, claims, blocked phrases, and the fictional boundary with five negative controls.","files":["src/pages/demo/brightline/","src/pages/demo-build.json.ts","public/schemas/demo-build.schema.json","data/sources/manifests/demo-brightline-gutter-discovery.md","data/working/demo-brightline-facts.json","data/derived/demo-brightline-page-brief.json","scripts/qa-demo-build.mjs","src/data/agent-reference.ts"],"completionCriteria":["Demo executes a site-type playbook with source manifest, working facts, and derived brief","Demo routes ship metadata, schema endpoints, and claim instrumentation","Demo is covered by sitemap, browser, crawl-stress, and SEO QA","A demo QA gate validates the build against its playbook simulation record"]},{"id":"prepare-cloudflare-pages-deployment","status":"done","priority":"high","title":"Prepare the gated Cloudflare Pages deployment path","rationale":"Deployment is human-gated, so everything up to the gate is now prepared: docs/deployment-runbook.md records the decisions Aaron must make and the full deploy/evidence sequence, deploy.sh refuses to run without explicit confirmation, account ID, project, and canonical URL and verifies repo, build, and sitemap before deploying, public/_headers ships the full security header set including HSTS, and qa:domain fails locally when a required header drifts and verifies live response headers when QA_PRODUCTION_URL is set.","files":["docs/deployment-runbook.md","deploy.sh","public/_headers","scripts/qa-domain.mjs"],"completionCriteria":["Runbook documents gated decisions, deploy sequence, and post-deploy evidence","deploy.sh refuses to run without explicit confirmation, account, project, and canonical URL","Required security headers are enforced by qa:domain locally and live","Deploy remains impossible without Aaron's explicit approval"]},{"id":"deploy-canonical-reference-and-capture-production-evidence","status":"done","priority":"medium","title":"Deploy the reference to a canonical URL and capture production evidence","rationale":"Deployed to Cloudflare Pages (project agent-template-website) with the custom domain agents.valyou.solutions live. Production qa:domain passes including live security-header verification, and the licensed Screaming Frog production crawl completed with zero findings after its first runs caught and fixed two real issues: Cloudflare email-obfuscation rewriting emails into 404ing /cdn-cgi/ links with injected JS (fixed with email_off boundaries), and a transient single-URL timeout (verified healthy).","files":["docs/deployment-runbook.md","deploy.sh","scripts/qa-domain.mjs","scripts/run-crawl-evidence.mjs","reports/domain/","reports/crawl/"],"completionCriteria":["Canonical deployment exists","QA_PRODUCTION_URL=<canonical-url> npm run qa:domain passes including live security headers","QA_PRODUCTION_URL=<canonical-url> npm run crawl:production evidence is saved","Production findings become tasks"]},{"id":"address-second-cold-audit-findings","status":"next","priority":"high","title":"Act on the second zero-context audit of the live site","rationale":"After the quality campaign (performance budgets, WCAG 2.2 contract, real tokens, two branded demos, published evidence, intent/measurement/i18n layers), the system needs fresh zero-context audit agents to re-grade every category against the live deployment. Any category still below B+ becomes the next improvement round; a clean audit closes the campaign loop.","files":["reports/","src/data/agent-reference.ts"],"completionCriteria":["Two independent zero-context audits of the live site recorded","Every audited category at B+ or higher, or findings converted to tasks","Audit-driven fixes verified by qa:all"]},{"id":"run-live-aeo-geo-visibility-scan","status":"later","priority":"medium","title":"Run a guarded live answer-engine visibility scan","rationale":"AEO/GEO fixtures prove evidence shape, not live model behavior. A checkpointed prompt scan through approved accounts with cost guardrails would turn answer-engine positioning from theory into recorded citations and gaps.","files":["data/derived/aeo-geo-context/","reports/"],"completionCriteria":["Scan runs within approved cost/error guardrails","Prompt fixtures map to recorded live answers","Citation gaps become tasks","No unsupported visibility claims are added to public surfaces"]},{"id":"expand-design-system-contract","status":"done","priority":"medium","title":"Layer in design-system examples","rationale":"The design system now has concrete fixture routes for endpoint rows, QA command blocks, evidence cards, pattern tables, and status badges, with good/bad examples, component states, responsive constraints, and browser QA evidence.","files":["src/styles/global.css","src/pages/fixtures/design-system/","src/data/agent-reference.ts","reports/browser/"],"completionCriteria":["Tokens are documented","Components have usage rules","Design fixtures exist","Agent pages remain readable","Browser QA screenshots include design fixtures"]}]}