Agent Start
Entry route for agents: what this repo is, how to inspect it, and the fastest path to competence.
/agent-start/ Start here
Agent orientation path
Follow this sequence when an agent is pointed at the main URL and needs to understand the repo without human explanation.
- Read /agent-index.json first: it is the cheapest complete index with the recommended reading order. Fetch the full aggregate /agent-manifest.json (~400KB) only when you need everything inlined at once.
- Read /file-map.json to understand where behavior lives in the repository.
- If you have the repository checked out, read
AGENTS.mdanddocs/agent-playbook.md; they are repo files, not web routes. Working from the URL alone, the same operating rules are expressed across the machine endpoints above, and the QA evidence they produce is published at /evidence/index.json. - Read /standards/ and /qa-contract/.
- Review /examples/ and the two demo builds before creating a new site pattern.
- With the repository: run
npm run qa:allbefore claiming the site is ready. Without it: verify the published evidence at /evidence/index.json is current.
Core pages
Navigation map for agents
Repo Map
Human-readable and machine-oriented map of source files, generated endpoints, docs, data, and QA evidence.
/repo-map/ Standards
Website Specification category map translated into implementation responsibilities for this starter.
/standards/ Workflows
Step-by-step workflows for adapting, validating, crawling, and handing off a serious website.
/workflows/ Examples
Pattern examples agents can reuse for local service, B2B SaaS, professional services, proof, and FAQ pages.
/examples/ Copy Lab
Conversion copy principles, good/bad examples, source boundaries, and agent workflow based on public offer/copy pattern study.
/copy-lab/ Page Pattern Fixtures
Concrete route fixtures that turn page-pattern contracts into inspectable Astro pages with metadata, schema, traceability, and QA expectations.
/fixtures/page-patterns/ Design System Fixtures
Concrete design-system fixtures for endpoint rows, QA command blocks, evidence cards, pattern tables, and status badges.
/fixtures/design-system/ QA Contract
Executable quality contract behind qa:routes, qa:seo, qa:aeo, and qa:all.
/qa-contract/ Machine-readable first
Endpoints an agent should fetch directly
| Endpoint | Purpose |
|---|---|
| /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. |
Primary workflow
Agent orientation
- 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.