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-manifest.json for the machine-readable overview.
- Read /file-map.json to understand where behavior lives.
- Open
AGENTS.mdanddocs/agent-playbook.mdin the file system. - Read /standards/ and /qa-contract/.
- Review /examples/ before creating a new site pattern.
- Run
npm run qa:allbefore claiming the site is ready.
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.