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. |
| /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 canonical demo site 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. |
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.0 A/AA accessibility scan
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: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
- 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