# Agent Website Reference

An agent-facing website operating system for learning, executing, and validating high-quality website builds.

This is an agent-facing website reference. It exists so an agent can start at the main URL, discover the repo structure, inspect data files and generated endpoints, understand quality expectations, and learn patterns for building strong websites.

## Agent Pages

- Agent Start: /agent-start/ - Entry route for agents: what this repo is, how to inspect it, and the fastest path to competence.
- Repo Map: /repo-map/ - Human-readable and machine-oriented map of source files, generated endpoints, docs, data, and QA evidence.
- Standards: /standards/ - Website Specification category map translated into implementation responsibilities for this starter.
- Workflows: /workflows/ - Step-by-step workflows for adapting, validating, crawling, and handing off a serious website.
- Examples: /examples/ - Pattern examples agents can reuse for local service, B2B SaaS, professional services, proof, and FAQ pages.
- Copy Lab: /copy-lab/ - Conversion copy principles, good/bad examples, source boundaries, and agent workflow based on public offer/copy pattern study.
- Page Pattern Fixtures: /fixtures/page-patterns/ - Concrete route fixtures that turn page-pattern contracts into inspectable Astro pages with metadata, schema, traceability, and QA expectations.
- Design System Fixtures: /fixtures/design-system/ - Concrete design-system fixtures for endpoint rows, QA command blocks, evidence cards, pattern tables, and status badges.
- QA Contract: /qa-contract/ - Executable quality contract behind qa:routes, qa:seo, qa:aeo, and qa:all.

## Machine Endpoints

- /agent-manifest.json: Top-level machine-readable index of pages, files, standards, workflows, examples, and QA commands.
- /file-map.json: Structured map of important source files and generated endpoints.
- /qa-contract.json: Machine-readable definition of route, SEO, AEO, build, and crawl expectations.
- /examples.json: Structured example pattern catalog.
- /agent-tasks.json: Structured future-agent backlog for improving this reference before real implementation work.
- /product-roadmap.json: Structured product roadmap for executing every value multiplier to completion.
- /walkthroughs.json: Step-by-step execution walkthroughs for every roadmap value multiplier.
- /contract-registry.json: Formal registry of JSON contracts, schemas, source owners, validation evidence, and failure modes.
- /site-studies.json: Structured good/bad real-site studies with audit evidence and agent checks.
- /seo-aeo-evaluation.json: Structured SEO/AEO evaluation checks, proof commands, evidence expectations, and automation status.
- /source-traceability.json: Structured source-to-site claim ledger, artifact chain, and proof policy.
- /site-type-playbooks.json: Structured build playbooks for local service, SaaS, professional services, proof, and answer-ready resource sites.
- /page-patterns.json: Structured reusable page-pattern contracts for service, proof, resource, contact, home, and schema-backed pages.
- /page-pattern-fixtures.json: Structured route fixture inventory proving each page-pattern contract can drive an actual Astro route.
- /conversion-copy.json: Structured conversion copy system with principles, copy types, good/bad examples, source boundaries, workflow, and QA gates.
- /offer-ecosystem.json: Structured offer-ecosystem funnel contract for AI tools, communities, workshops, playbooks, pricing tiers, qualification gates, referrals, and disclaimers.
- /infrastructure-decisions.json: Structured infrastructure decision system for hosting, rendering, CMS, data, auth, media, search, analytics, forms, payments, DNS/CDN, observability, and deployment tiers.
- /browser-visual-qa.json: Structured browser visual QA contract for screenshots, viewports, layout checks, and report evidence.
- /crawl-evidence.json: Structured crawl evidence contract for Screaming Frog exports, summary reports, and readiness criteria.
- /design-system-contracts.json: Structured design-system contract for tokens, components, accessibility, anti-patterns, QA gates, and stress tests.
- /aeo-geo-context.json: Structured AEO/GEO model context contract for answer-engine prompts, citations, source boundaries, and stress tests.
- /why-explanations.json: Structured rationale contract for where explanations, tradeoffs, evidence, and failure modes are required.
- /real-site-comparisons.json: Structured real-site comparison contract for reference studies, scoring dimensions, evidence, and follow-up tasks.
- /handoff-reports.json: Structured handoff report contract for final evidence, risks, next actions, and closeout records.
- /agent-index.json: Lightweight orientation index (reading order plus endpoint list) for token-constrained agents; the cheapest complete index.
- /evidence/index.json: Published QA evidence index from the latest accepted run; every entry links a live report artifact.
- /accessibility-contract.json: WCAG 2.2 AA accessibility contract: value rules, enforcement method, manual checklist, anti-patterns.
- /performance-budgets.json: Core Web Vitals targets, asset budgets, page rules, and measurement method enforced by qa:perf.
- /demo-build.json: Canonical demo build record: fictional source chain, playbook execution, pages, claims, and QA gates.
- /demo/brightline/schema.json: Machine-readable schema facts for the fictional local-service demo with claim IDs.
- /demo/logpilot/schema.json: Machine-readable schema facts for the fictional B2B SaaS demo with claim IDs.
- /llms.txt: Concise LLM entry point.
- /llms-full.txt: Longer LLM-readable repo and site summary.
- /schemamap.xml: Schema endpoint discovery map.
- /sitemap.xml: Indexable route discovery.
- /robots.txt: Crawler and AI-use policy hints.
- /schemas/agent-manifest.schema.json: JSON Schema for /agent-manifest.json.
- /schemas/file-map.schema.json: JSON Schema for /file-map.json.
- /schemas/qa-contract.schema.json: JSON Schema for /qa-contract.json.
- /schemas/examples.schema.json: JSON Schema for /examples.json.
- /schemas/agent-tasks.schema.json: JSON Schema for /agent-tasks.json.
- /schemas/product-roadmap.schema.json: JSON Schema for /product-roadmap.json.
- /schemas/walkthroughs.schema.json: JSON Schema for /walkthroughs.json.
- /schemas/contract-registry.schema.json: JSON Schema for /contract-registry.json.
- /schemas/site-studies.schema.json: JSON Schema for /site-studies.json.
- /schemas/seo-aeo-evaluation.schema.json: JSON Schema for /seo-aeo-evaluation.json.
- /schemas/source-traceability.schema.json: JSON Schema for /source-traceability.json.
- /schemas/site-type-playbooks.schema.json: JSON Schema for /site-type-playbooks.json.
- /schemas/page-patterns.schema.json: JSON Schema for /page-patterns.json.
- /schemas/page-pattern-fixtures.schema.json: JSON Schema for /page-pattern-fixtures.json.
- /schemas/conversion-copy.schema.json: JSON Schema for /conversion-copy.json.
- /schemas/offer-ecosystem.schema.json: JSON Schema for /offer-ecosystem.json.
- /schemas/infrastructure-decisions.schema.json: JSON Schema for /infrastructure-decisions.json.
- /schemas/browser-visual-qa.schema.json: JSON Schema for /browser-visual-qa.json.
- /schemas/crawl-evidence.schema.json: JSON Schema for /crawl-evidence.json.
- /schemas/design-system-contracts.schema.json: JSON Schema for /design-system-contracts.json.
- /schemas/aeo-geo-context.schema.json: JSON Schema for /aeo-geo-context.json.
- /schemas/why-explanations.schema.json: JSON Schema for /why-explanations.json.
- /schemas/real-site-comparisons.schema.json: JSON Schema for /real-site-comparisons.json.
- /schemas/handoff-reports.schema.json: JSON Schema for /handoff-reports.json.
- /schemas/demo-build.schema.json: JSON Schema for /demo-build.json.
- /schemas/performance-budgets.schema.json: JSON Schema for /performance-budgets.json.
- /schemas/accessibility-contract.schema.json: JSON Schema for /accessibility-contract.json.
- /schemas/evidence-index.schema.json: JSON Schema for /evidence/index.json.
- /schemas/agent-index.schema.json: JSON Schema for /agent-index.json.

## Contract Registry

- /agent-manifest.json: schema=/schemas/agent-manifest.schema.json; source=src/pages/agent-manifest.json.ts; owner=Reference Layer; validate=npm run qa:aeo
- /file-map.json: schema=/schemas/file-map.schema.json; source=src/pages/file-map.json.ts; owner=Reference Layer; validate=npm run qa:aeo
- /qa-contract.json: schema=/schemas/qa-contract.schema.json; source=src/pages/qa-contract.json.ts; owner=Evaluation Layer; validate=npm run qa:aeo
- /examples.json: schema=/schemas/examples.schema.json; source=src/pages/examples.json.ts; owner=Reference Layer; validate=npm run qa:aeo
- /agent-tasks.json: schema=/schemas/agent-tasks.schema.json; source=src/pages/agent-tasks.json.ts; owner=Execution Layer; validate=npm run qa:aeo
- /product-roadmap.json: schema=/schemas/product-roadmap.schema.json; source=src/pages/product-roadmap.json.ts; owner=Execution Layer; validate=npm run qa:aeo
- /walkthroughs.json: schema=/schemas/walkthroughs.schema.json; source=src/pages/walkthroughs.json.ts; owner=Execution Layer; validate=npm run qa:aeo
- /contract-registry.json: schema=/schemas/contract-registry.schema.json; source=src/pages/contract-registry.json.ts; owner=Reference Layer; validate=npm run qa:aeo
- /site-studies.json: schema=/schemas/site-studies.schema.json; source=src/pages/site-studies.json.ts; owner=Reference Layer; validate=npm run qa:aeo
- /seo-aeo-evaluation.json: schema=/schemas/seo-aeo-evaluation.schema.json; source=src/pages/seo-aeo-evaluation.json.ts; owner=Evaluation Layer; validate=npm run qa:aeo
- /source-traceability.json: schema=/schemas/source-traceability.schema.json; source=src/pages/source-traceability.json.ts; owner=Reference Layer; validate=npm run qa:aeo
- /site-type-playbooks.json: schema=/schemas/site-type-playbooks.schema.json; source=src/pages/site-type-playbooks.json.ts; owner=Execution Layer; validate=npm run qa:aeo
- /page-patterns.json: schema=/schemas/page-patterns.schema.json; source=src/pages/page-patterns.json.ts; owner=Execution Layer; validate=npm run qa:aeo
- /page-pattern-fixtures.json: schema=/schemas/page-pattern-fixtures.schema.json; source=src/pages/page-pattern-fixtures.json.ts; owner=Execution Layer; validate=npm run qa:fixtures
- /browser-visual-qa.json: schema=/schemas/browser-visual-qa.schema.json; source=src/pages/browser-visual-qa.json.ts; owner=Evaluation Layer; validate=npm run qa:browser
- /crawl-evidence.json: schema=/schemas/crawl-evidence.schema.json; source=src/pages/crawl-evidence.json.ts; owner=Evaluation Layer; validate=npm run qa:crawl -- --export-dir <crawl-export-dir>
- /design-system-contracts.json: schema=/schemas/design-system-contracts.schema.json; source=src/pages/design-system-contracts.json.ts; owner=Reference Layer; validate=npm run qa:aeo
- /aeo-geo-context.json: schema=/schemas/aeo-geo-context.schema.json; source=src/pages/aeo-geo-context.json.ts; owner=Evaluation Layer; validate=npm run qa:aeo
- /why-explanations.json: schema=/schemas/why-explanations.schema.json; source=src/pages/why-explanations.json.ts; owner=Reference Layer; validate=npm run qa:aeo
- /real-site-comparisons.json: schema=/schemas/real-site-comparisons.schema.json; source=src/pages/real-site-comparisons.json.ts; owner=Evaluation Layer; validate=npm run qa:aeo
- /handoff-reports.json: schema=/schemas/handoff-reports.schema.json; source=src/pages/handoff-reports.json.ts; owner=Execution Layer; validate=npm run qa:aeo
- /conversion-copy.json: schema=/schemas/conversion-copy.schema.json; source=src/pages/conversion-copy.json.ts; owner=Content Strategy Layer; validate=npm run qa:aeo
- /offer-ecosystem.json: schema=/schemas/offer-ecosystem.schema.json; source=src/pages/offer-ecosystem.json.ts; owner=Content Strategy Layer; validate=npm run qa:aeo
- /infrastructure-decisions.json: schema=/schemas/infrastructure-decisions.schema.json; source=src/pages/infrastructure-decisions.json.ts; owner=Infrastructure Strategy Layer; validate=npm run qa:aeo
- /agent-index.json: schema=/schemas/agent-index.schema.json; source=src/pages/agent-index.json.ts; owner=Reference Layer; validate=npm run qa:aeo
- /evidence/index.json: schema=/schemas/evidence-index.schema.json; source=scripts/publish-evidence.mjs; owner=Quality Layer; validate=npm run qa:aeo
- /accessibility-contract.json: schema=/schemas/accessibility-contract.schema.json; source=src/pages/accessibility-contract.json.ts; owner=Quality Layer; validate=npm run qa:browser
- /performance-budgets.json: schema=/schemas/performance-budgets.schema.json; source=src/pages/performance-budgets.json.ts; owner=Quality Layer; validate=npm run qa:perf
- /demo-build.json: schema=/schemas/demo-build.schema.json; source=src/pages/demo-build.json.ts; owner=Execution Layer; validate=npm run qa:demo

## File-System Entry Points

- AGENTS.md
- README.md
- docs/system-purpose.md
- docs/product-roadmap.md
- docs/site-expansion-execution-track.md
- docs/agent-playbook.md
- docs/checklists/specification-website-map.md
- docs/checklists/launch-qa.md
- src/data/agent-reference.ts
- scripts/qa-routes.mjs
- scripts/qa-seo.mjs
- scripts/qa-aeo.mjs

## Source Retention Model

- raw: data/sources/raw/ - Immutable source material exactly as received or captured. Example: data/sources/raw/specification-website-llms-2026-06-02.txt
- manifest: data/sources/manifests/ - Human-readable provenance notes describing source origin, date, permissions, and use constraints. Example: data/sources/manifests/example-client-discovery.md
- working: data/working/ - Cleaned, normalized, or public-safe facts derived from raw sources. Example: data/working/example-client-facts.json
- derived: data/derived/ - Generated briefs, content outlines, QA summaries, and implementation-ready artifacts. Example: data/derived/example-page-brief.json

## Source Traceability

- allowed: example-service-area-claim - data/working/example-client-facts.json
- allowed: example-service-list-claim - data/working/example-client-facts.json
- blocked: fastest-response-claim - data/working/example-client-facts.json
- blocked: hundreds-five-star-reviews-claim - data/working/example-client-facts.json
- allowed: demo-brightline-service-area-claim - data/working/demo-brightline-facts.json
- allowed: demo-brightline-service-list-claim - data/working/demo-brightline-facts.json
- allowed: demo-brightline-license-claim - data/working/demo-brightline-facts.json
- allowed: demo-brightline-review-claim - data/working/demo-brightline-facts.json
- blocked: demo-brightline-fastest-claim - data/working/demo-brightline-facts.json
- blocked: demo-brightline-review-volume-claim - data/working/demo-brightline-facts.json
- allowed: demo-logpilot-feature-claim - data/working/demo-logpilot-facts.json
- allowed: demo-logpilot-integration-claim - data/working/demo-logpilot-facts.json
- allowed: demo-logpilot-comparison-claim - data/working/demo-logpilot-facts.json
- blocked: demo-logpilot-unverified-integrations-claim - data/working/demo-logpilot-facts.json
- blocked: demo-logpilot-superiority-claim - data/working/demo-logpilot-facts.json

## Claim Instrumentation

- page sections=/services/:example-service-area-claim,example-service-list-claim; /demo/brightline/:demo-brightline-service-area-claim,demo-brightline-service-list-claim; /demo/logpilot/:demo-logpilot-feature-claim,demo-logpilot-integration-claim; /demo/brightline/proof/:demo-brightline-review-claim,demo-brightline-license-claim
- schema=/services/schema.json:example-service-area-claim,example-service-list-claim; /contact/schema.json:example-service-area-claim; /demo/brightline/schema.json:demo-brightline-service-area-claim,demo-brightline-service-list-claim,demo-brightline-review-claim; /demo/logpilot/schema.json:demo-logpilot-feature-claim,demo-logpilot-integration-claim
- llm summary allowed=example-service-area-claim, example-service-list-claim, demo-brightline-service-area-claim, demo-brightline-service-list-claim, demo-logpilot-feature-claim
- blocked=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

## QA Commands

- npm run qa:routes: Core HTML routes return 200; Machine endpoints return 200; Internal links return 200; Sitemap URLs resolve
- npm run qa:seo: Unique titles; Valid descriptions; Canonical URLs; One H1; Open Graph parity; Favicon; JSON-LD
- npm run qa:aeo: 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
- npm run qa:browser: 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)
- npm run qa:crawl: Required crawl inventory exports; Screaming Frog issue export summary; Critical response-code findings; Crawl evidence report under reports/crawl/
- npm run qa:agent: Main URL orientation simulation; SEO/AEO walkthrough selection; Crawl/browser readiness simulation; Handoff continuation simulation
- npm run qa:contracts: 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
- npm run qa:copy: 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/
- npm run qa:crawl-stress: 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
- npm run qa:playbooks: 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
- npm run qa:perf: 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
- npm run qa:demo: 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
- npm run qa:domain: 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
- npm run qa:nectiv: LLM surfaces for AI/AEO claims; Indexable H1/description/canonical guardrails; Sitemap/core-route parity; Crawler-visible critical URL findings; Production-domain evidence warning
- npm run qa:handoff: Generated handoff report; QA evidence summaries; Residual risks; Next actions from /agent-tasks.json
- npm run qa:all: 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

## Browser Visual QA

- command=npm run qa:browser
- report=reports/browser/browser-visual-report.json
- screenshots=reports/browser/screenshots/
- viewports=desktop:1440x1000, mobile:390x844
- routes=/, /agent-start/, /repo-map/, /standards/, /workflows/, /examples/, /copy-lab/, /fixtures/page-patterns/, /fixtures/design-system/, /qa-contract/, /demo/brightline/, /demo/brightline/services/, /demo/brightline/service-areas/, /demo/brightline/proof/, /demo/brightline/contact/, /demo/logpilot/, /demo/logpilot/product/, /demo/logpilot/use-cases/, /demo/logpilot/integrations/, /demo/logpilot/comparison/

## Crawl Evidence

- command=npm run qa:crawl -- --export-dir <crawl-export-dir>
- report=reports/crawl/crawl-evidence-report.json
- wrapper=workspace-local licensed Screaming Frog wrapper (private; invoked by scripts/run-crawl-evidence.mjs, never published)
- required=crawl_overview.csv, internal_all.csv
- issues=response_codes_client_error_(4xx).csv, response_codes_server_error_(5xx).csv, response_codes_no_response.csv, h1_missing.csv, meta_description_missing.csv

## AEO GEO Context

- surfaces=llm-entry-surfaces, schema-entity-surfaces, source-boundary-surfaces, evaluation-surfaces
- prompts=service-scope-answer, brightline-service-area-answer, logpilot-capability-answer, logpilot-comparison-caveat-answer, reference-system-orientation-answer, local-entity-answer
- fixtures=data/derived/aeo-geo-context/example-prompt-set.json, data/derived/aeo-geo-context/demo-prompt-set.json, data/derived/aeo-geo-context/demo-prompt-set.json, data/derived/aeo-geo-context/demo-prompt-set.json, data/derived/aeo-geo-context/demo-prompt-set.json, data/derived/aeo-geo-context/example-prompt-set.json
- qa=npm run qa:seo, npm run qa:aeo, npm run qa:crawl, npm run qa:all

## Why Explanations

- surfaces=roadmap-items, walkthrough-steps, contract-registry, site-studies, qa-and-evaluation, source-and-claims, design-and-aeo-context
- rules=5
- anti-patterns=6
- qa=npm run qa:aeo, npm run qa:aeo, npm run qa:aeo, npm run qa:aeo, npm run qa:aeo

## Workflows

### 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
- 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.
Done when: Agent can describe repo purpose without chat context; Agent can identify canonical data and QA files; Agent knows which command proves baseline health

### 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
- 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.
Done when: No placeholder identity remains; Every public claim traces to source or approved brief; qa:all passes; Crawl/browser evidence is recorded

### 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
- 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.
Done when: Route is linked or intentionally discoverable; Metadata and schema match visible content; Relevant generated indexes are updated; Focused QA passes

### 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
- 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.
Done when: SEO QA passes; AEO QA passes; Structured facts match public page content; Agent endpoints explain the current site

### 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
- 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.
Done when: qa:all passes; Crawl evidence has no unresolved critical issues; Desktop and mobile screenshots show no clipping or overlap; Remaining risks are documented

### 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
- 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.
Done when: 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

## Example Patterns

- Local service website: pages=Home, Services, Service detail, Service area, Proof, FAQ, Contact; schema=LocalBusiness, Service, FAQPage, BreadcrumbList; source assumptions=Verified service list, Service-area list, Contact details, Licensing or qualification facts, Customer proof
- B2B SaaS website: pages=Home, Product, Use cases, Integrations, Comparison, Proof, Resources, Contact; schema=Organization, SoftwareApplication, Product, FAQPage, Article; source assumptions=Product positioning, Feature facts, Integration list, Security/compliance notes, Customer proof
- Professional services website: pages=Home, Services, Industries, About, Proof, Insights, Contact; schema=ProfessionalService, Person, Organization, FAQPage, Article; source assumptions=Service scope, Practitioner or team credentials, Industry experience, Client proof, Engagement process
- Proof page: pages=Proof index, Case study, Testimonials, Before-after evidence; schema=Review, CreativeWork, Article; source assumptions=Approved testimonials, Case-study facts, Before/after artifacts, Metrics with dates, Permission notes
- Answer-ready resource page: pages=Guide, Comparison, Glossary/entity page, FAQ; schema=Article, FAQPage, DefinedTerm, BreadcrumbList; source assumptions=Topic definitions, Approved recommendations, Comparison criteria, Public source references, Entity glossary

## Conversion Copy

- objective=Teach future agents how to write clear, proof-aware, conversion-focused website copy without copying another creator's proprietary language.
- sources=https://www.acquisition.com/, https://www.acquisition.com/training, https://www.acquisition.com/bio-alex, https://www.acquisition.com/books, https://www.acquisition.com/training/leads, https://ai.acquisition.com/, https://vantage.acquisition.com/, https://shop.acquisition.com/, https://acquisition.com/hubfs/The_Lost_Chapter-Your_First_Avatar.pdf
- principles=specific-dream-outcome, pain-before-platform, value-equation, offer-stack, mechanism-clarity, proof-before-claim, risk-reversal, ethical-urgency, cta-specificity, qualified-who-before-what, ecosystem-offer-architecture, ai-tool-trust, value-in-advance-journey, pricing-and-path-choice, disclaimer-near-outcome
- copy types=homepage-hero, offer-section, proof-section, objection-faq, lead-magnet, service-page, ai-tool-page, community-membership-page, qualification-gate, pricing-tier-section
- anti-patterns=clever-before-clear, feature-dump, fake-scarcity, proofless-superlatives, ai-slop-generalities, unbounded-ai-claims, ecosystem-confusion, qualification-theater, buried-disclaimer
- qa=npm run qa:aeo, npm run qa:seo, npm run qa:browser, npm run qa:all

## Offer Ecosystem

- objective=Teach agents how to turn multiple offer assets into one coherent website funnel instead of disconnected sections.
- layers=value-in-advance, ai-tools, community, workshops, playbooks, pricing-tiers, qualification-gates, referral-engine, disclaimers
- paths=education-to-tool-to-qualified-call, community-membership-with-tiers, implementation-ready-site-build
- anti-patterns=asset-pile, qualification-without-reason, tier-confusion, referral-without-terms, ai-without-review-boundary
- qa=npm run qa:aeo, npm run qa:copy, npm run qa:all

## Infrastructure Decisions

- objective=Teach agents how to choose website infrastructure by decision tier instead of defaulting to a preferred platform.
- owner stack=source-control-and-collaboration:GitHub, edge-hosting-and-dns:Cloudflare, content-and-marketing-framework:Astro, app-framework:Next.js, payments:Stripe
- areas=rendering-and-hosting, content-management, data-and-state, identity-and-access, forms-and-lead-routing, media-and-assets, search-and-discovery, analytics-and-observability, payments-and-commerce, dns-cdn-security, deployment-and-handoff
- site types=local-service, b2b-saas, professional-services, agent-reference-or-docs
- scenarios=owner-stack-marketing-site, technical-docs-agent-reference, next-app-with-stripe-portal, content-team-cms-site, commerce-or-workshop-checkout
- anti-patterns=platform-first-thinking, premature-app-complexity, cms-without-governance, runtime-without-observability, hidden-ops-ownership
- qa=npm run qa:aeo, npm run qa:domain, npm run qa:crawl-runner, npm run qa:handoff, npm run qa:all

## Site Type Playbooks

- Local service website build playbook: example=local-service; pages=5; gates=npm run qa:all, Source traceability audit, Mobile contact path check, Screaming Frog crawl before launch
- B2B SaaS website build playbook: example=b2b-saas; pages=5; gates=npm run qa:all, Claim/proof traceability review, Structured data review, Comparison claim review
- Professional services website build playbook: example=professional-services; pages=5; gates=npm run qa:all, Credential/source review, Accessibility review for dense content, Author/entity schema review
- Proof library build playbook: example=proof-page; pages=3; gates=npm run qa:all, Permission/privacy review, Claim/source audit, Schema eligibility review
- Answer-ready resource build playbook: example=answer-ready-resource; pages=4; gates=npm run qa:all, Internal-link crawl, Schema review, Source/reference review

## Page Patterns

- Homepage entity summary: routes=/; schema=Organization, WebSite, LocalBusiness or domain-specific entity, FAQPage when visible FAQs exist
- Service or offer page: routes=/services/; schema=Service, BreadcrumbList, FAQPage when visible FAQs exist
- Proof evidence page: routes=/proof/; schema=Review when eligible, CreativeWork, Article or BreadcrumbList when appropriate
- Answer-ready resource page: routes=/resources/; schema=Article, FAQPage, DefinedTerm when defining an entity, BreadcrumbList
- Contact conversion page: routes=/contact/; schema=ContactPage, Organization or LocalBusiness
- Schema-backed detail page: routes=/services/schema.json, /proof/schema.json, /resources/schema.json, /contact/schema.json; schema=Organization, WebSite, Service, Article, FAQPage, BreadcrumbList, LocalBusiness as appropriate

## Page Pattern Fixtures

- Homepage Agent Entity Fixture: pattern=homepage-entity-summary; route=/fixtures/page-patterns/homepage-agent-entity/; gates=npm run qa:fixtures, npm run qa:seo, npm run qa:aeo
- Service Offer Scope Fixture: pattern=service-offer-page; route=/fixtures/page-patterns/service-offer-scope/; gates=npm run qa:fixtures, npm run qa:seo, npm run qa:aeo
- Proof Evidence Artifact Fixture: pattern=proof-evidence-page; route=/fixtures/page-patterns/proof-evidence-artifact/; gates=npm run qa:fixtures, npm run qa:crawl, npm run qa:aeo
- Answer Ready Resource Fixture: pattern=answer-ready-resource-page; route=/fixtures/page-patterns/answer-ready-resource/; gates=npm run qa:fixtures, npm run qa:aeo
- Contact Conversion Fixture: pattern=contact-conversion-page; route=/fixtures/page-patterns/contact-conversion/; gates=npm run qa:fixtures, npm run qa:seo, npm run qa:aeo
- Schema Backed Detail Fixture: pattern=schema-backed-detail-page; route=/fixtures/page-patterns/schema-backed-detail/; gates=npm run qa:fixtures, npm run qa:aeo

## Canonical Demo Build

### /demo/brightline/
- disclosure=Brightline Gutter Co. is fictional. Every identity, service, county, review, registration, and contact fact was invented for this demo and must never be reused as a real claim.
- playbook=local-service-build-playbook; simulation=local-service-simulated-build
- record=/demo-build.json; schema endpoint=/demo/brightline/schema.json; report=reports/demo/demo-build-report.json
- source chain=data/sources/manifests/demo-brightline-gutter-discovery.md -> data/working/demo-brightline-facts.json -> data/derived/demo-brightline-page-brief.json
- pages=/demo/brightline/ (homepage-entity-summary); /demo/brightline/services/ (service-offer-page); /demo/brightline/service-areas/ (schema-backed-detail-page); /demo/brightline/proof/ (proof-evidence-page); /demo/brightline/contact/ (contact-conversion-page)
- qa=npm run qa:demo, npm run qa:aeo, npm run qa:all

### /demo/logpilot/
- disclosure=LogPilot is fictional. Every product, feature, integration, security, customer, and comparison fact was invented for this demo and must never be reused as a real claim.
- playbook=b2b-saas-build-playbook; simulation=b2b-saas-simulated-build
- record=/demo-build.json; schema endpoint=/demo/logpilot/schema.json; report=reports/demo/demo-build-report.json
- source chain=data/sources/manifests/demo-logpilot-discovery.md -> data/working/demo-logpilot-facts.json -> data/derived/demo-logpilot-page-brief.json
- pages=/demo/logpilot/ (homepage-entity-summary); /demo/logpilot/product/ (service-offer-page); /demo/logpilot/use-cases/ (answer-ready-resource-page); /demo/logpilot/integrations/ (schema-backed-detail-page); /demo/logpilot/comparison/ (answer-ready-resource-page)
- qa=npm run qa:demo, npm run qa:aeo, npm run qa:all

## Design System Contracts

- tokens=25
- components=5
- examples=endpoint-discovery-row:/fixtures/design-system/endpoint-discovery-row/, qa-command-block:/fixtures/design-system/qa-command-block/, evidence-card:/fixtures/design-system/evidence-card/, pattern-table:/fixtures/design-system/pattern-table/, status-badge-set:/fixtures/design-system/status-badge-set/
- qa=npm run qa:browser, npm run qa:seo, npm run qa:aeo, npm run qa:all
- anti-patterns=6

## Real Site Comparisons

- dimensions=entity-focus, machine-readable-surface, crawl-and-domain-health, source-and-claim-safety, design-operability
- profiles=nectiv-to-agent-reference, specification-website-to-agent-reference
- qa=npm run qa:aeo, npm run qa:seo, npm run qa:crawl, npm run qa:browser, npm run qa:all

## Handoff Reports

- default=reports/handoff/
- example=reports/handoff/example-handoff-report.json
- sections=outcome, changes-made, verification, evidence, risks, next-actions
- qa=npm run qa:all, npm audit --omit=dev

## Site Studies

- Nectiv Digital (2026-06-04): strong=4; avoid=5; evidence=data/derived/site-studies/nectiv-digital-2026-06-04/
- Specification Website (2026-06-09): strong=4; avoid=3; evidence=data/derived/site-studies/specification-website-2026-06-09/
- RyanPierce.ai (2026-05-21): strong=2; avoid=3; evidence=data/derived/site-studies/ryanpierce-ai-2026-05-21/
- The Prep Casa (2026-05-21): strong=2; avoid=3; evidence=data/derived/site-studies/the-prep-casa-2026-05-21/
- Jordan Browne-Moore (2026-06-04): strong=2; avoid=4; evidence=data/derived/site-studies/jordan-browne-moore-2026-06-03/
- Poor AI-Generated Service Site Fixture (2026-06-04): strong=1; avoid=3; evidence=data/derived/site-studies/poor-ai-generated-service-site/

## SEO AEO Evaluation

- implemented/critical: route-response-and-sitemap-coverage - npm run qa:routes
- implemented/critical: metadata-canonical-h1-parity - npm run qa:seo
- implemented/critical: llm-and-agent-endpoint-presence - npm run qa:aeo
- implemented/high: structured-data-entity-coverage - npm run qa:seo && npm run qa:aeo
- implemented/high: real-site-findings-to-qa-loop - npm run qa:aeo
- planned/critical: domain-variant-tls-and-redirects - planned: reports/domain/domain-variant-check.md
- planned/high: crawl-export-indexability-comparison - planned: reports/crawl/latest/analysis-notes.md
- implemented/high: nectiv-derived-guardrail-suite - npm run qa:nectiv

## Product Roadmap

- 1. Step-by-step agent walkthroughs: Turns vague website work into deterministic operating behavior.
- 2. Machine-readable contracts: Lets agents consume the system reliably without scraping prose.
- 3. Good and bad example library: Turns external site audits into reusable training data.
- 4. SEO/AEO evaluation layer: Makes the system capable of judging websites, not just describing them.
- 5. Source-to-site traceability: Prevents unsupported claims and makes generated websites auditable.
- 6. Site-type build playbooks: Lets agents choose the right operating path for different business models.
- 7. Reusable page pattern library: Gives agents page-level contracts instead of blank-page generation.
- 8. Automated browser and visual QA: Catches layout and interaction failures that static crawls cannot see.
- 9. Crawl evidence as a first-class artifact: Makes launch and audit decisions evidence-backed.
- 10. Agent backlog intelligence: Lets future agents continue product work without asking what is next.
- 11. Design system contracts: Makes design agent-operable instead of just attractive.
- 12. AEO/GEO model context: Makes websites easier for answer engines and agents to understand.
- 13. Why explanations everywhere: Improves agent compliance by explaining the reason behind each check.
- 14. Comparison against real sites: Continuously improves the system through external evidence.
- 15. Handoff reports: Makes work durable across agents and sessions.

## Agent Walkthroughs

- 1. Step-by-step agent walkthroughs: steps=5; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.
- 2. Machine-readable contracts: steps=5; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.
- 3. Good and bad example library: steps=5; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.
- 4. SEO/AEO evaluation layer: steps=6; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.
- 5. Source-to-site traceability: steps=5; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.
- 6. Site-type build playbooks: steps=5; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.
- 7. Reusable page pattern library: steps=5; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.
- 8. Automated browser and visual QA: steps=5; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.
- 9. Crawl evidence as a first-class artifact: steps=5; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.
- 10. Agent backlog intelligence: steps=5; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.
- 11. Design system contracts: steps=5; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.
- 12. AEO/GEO model context: steps=5; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.
- 13. Why explanations everywhere: steps=5; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.
- 14. Comparison against real sites: steps=5; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.
- 15. Handoff reports: steps=5; evidence=Changed files or generated endpoint output., Relevant QA command output., Stress-test notes or report artifacts., Comparison back to docs/system-purpose.md.

## Future Agent Tasks

- done/high: add-contract-schema-validation - Validate agent JSON contracts
- done/high: add-contract-registry - Add formal machine-readable contract registry
- done/high: add-browser-regression-suite - Add browser regression and screenshot checks
- done/high: expand-browser-qa-with-visual-diff-and-accessibility - Expand browser QA with visual diff and accessibility checks
- done/high: add-objective-detail-walkthrough-contract - Require every major objective to decompose into detailed checks and rationale
- done/high: stress-test-walkthrough-model-with-agent-simulation - Stress test walkthrough model with simulated agent runs
- done/high: stress-test-contract-registry-with-drift-fixtures - Stress test contract registry with drift fixtures
- done/high: add-good-bad-site-study-library - Add structured good/bad real-site study library
- done/high: add-seo-aeo-evaluation-layer - Add structured SEO/AEO evaluation layer
- done/high: add-crawl-evidence-contract-and-summarizer - Add crawl evidence contract and export summarizer
- done/high: add-production-domain-and-crawl-evidence-runners - Add production domain and crawl evidence runners
- done/high: add-source-to-site-traceability-contract - Add source-to-site traceability contract
- done/high: add-page-level-claim-id-instrumentation - Add page-level claim ID instrumentation
- done/high: add-site-type-build-playbooks - Add executable site-type build playbooks
- done/high: stress-test-site-type-playbooks-with-simulated-builds - Stress test site-type playbooks with simulated builds
- done/high: add-reusable-page-pattern-library - Add reusable page pattern library
- done/high: add-conversion-copy-lab - Add conversion copy lab and agent copy workflow
- done/high: stress-test-conversion-copy-transformations - Stress test conversion copy transformations with weak-copy fixtures
- done/high: add-offer-ecosystem-endpoint - Add offer ecosystem funnel endpoint
- done/high: add-infrastructure-decision-system - Add tiered infrastructure decision system
- done/high: stress-test-page-patterns-with-route-fixtures - Stress test page patterns with route fixtures
- done/high: expand-site-study-library-across-site-types - Expand site-study library across strong and weak website types
- done/high: add-real-site-comparison-contract - Add real-site comparison contract
- done/high: add-crawl-stress-suite - Add crawl and endpoint stress testing
- done/high: reconcile-execution-track-with-task-ledger - Keep the execution-track document verifiably aligned with the task ledger
- done/high: add-nectiv-derived-seo-aeo-checks - Add Nectiv-derived SEO/AEO checks to the evaluation layer
- done/high: add-agent-backlog-intelligence-contract - Add agent backlog intelligence contract
- done/high: add-design-system-contract-layer - Add backend design-system contract layer
- done/high: add-aeo-geo-model-context-fixtures - Add AEO/GEO model context contract and fixtures
- done/high: add-why-explanations-contract - Add why-explanations contract
- done/high: add-handoff-report-contract - Add handoff report contract
- done/high: add-handoff-report-format - Generate real handoff reports from completed runs
- done/high: close-strategy-layer-gaps - Close the strategy-layer gaps: search intent, funnel measurement, i18n decisions, cheap orientation index
- done/high: publish-qa-evidence-and-aeo-baseline - Publish QA evidence at live URLs and record the first real AEO baseline
- done/high: add-saas-demo-and-brand-tokens - Add the LogPilot SaaS demo and per-brand design tokens
- done/high: make-design-tokens-real-values - Publish real design token values with drift enforcement
- done/high: add-accessibility-contract - Add standalone WCAG 2.2 AA accessibility contract
- done/high: add-performance-budget-contract - Add performance budgets with measured enforcement
- done/high: refresh-human-readable-agent-docs - Refresh human-readable agent docs against the current system
- done/high: build-canonical-demo-site - Build the canonical demo site end to end
- done/high: prepare-cloudflare-pages-deployment - Prepare the gated Cloudflare Pages deployment path
- done/medium: deploy-canonical-reference-and-capture-production-evidence - Deploy the reference to a canonical URL and capture production evidence
- next/high: address-second-cold-audit-findings - Act on the second zero-context audit of the live site
- later/medium: run-live-aeo-geo-visibility-scan - Run a guarded live answer-engine visibility scan
- done/medium: expand-design-system-contract - Layer in design-system examples