Agent Start
Entry route for agents: what this repo is, how to inspect it, and the fastest path to competence.
/agent-start/ Agent entry point
Start here to understand how this repo builds a serious website.
This site is not a marketing destination for humans. It is an inspection surface for agents. Use the routes and machine endpoints below to learn the repo, its quality contract, its files, and its reusable website patterns.
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 endpoints
Read these when navigating programmatically.
| 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. |
Common questions
Direct answers for orientation
What makes this starter different from a normal website template?
It ships with the operating rules, structured data patterns, machine-readable endpoints, and verification workflow agents need to build useful SEO and AEO sites.
Can this be adapted for local service and SaaS websites?
Yes. The default sections are intentionally reusable across service, product, proof, comparison, and resource pages.
What standard should agents check before adding a feature?
Agents should use The Website Specification as the baseline for foundations, SEO, accessibility, security, agent readiness, performance, privacy, resilience, and i18n.
Quality contract
Future agents should treat these commands as the minimum technical bar.
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