{"description":"Step-by-step walkthroughs for executing every roadmap value multiplier.","objective":"Prevent agents from treating broad objectives as sufficient by requiring detailed steps, why, evidence, pass/warn/fail criteria, stress tests, and objective alignment.","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."}]}