File system map
Where agents should look in the repo
Use this page with /file-map.json. The page explains the important files; the JSON endpoint is easier for automated traversal.
Agent orientation
| Path | Purpose |
|---|---|
AGENTS.md | Non-negotiable repo rules for future agents. |
docs/system-purpose.md | North-star definition of what this system is, is not, and must prove. |
docs/product-roadmap.md | Priority-ordered product roadmap for executing every value multiplier. |
docs/site-expansion-execution-track.md | Durable execution track for filling out the site with studies, fixtures, infrastructure, design, copy, simulations, stress tests, docs, and demo builds. |
docs/agent-playbook.md | Full adaptation workflow and definition of done. |
docs/deployment-runbook.md | Gated Cloudflare Pages deployment path: required decisions, deploy sequence, and post-deploy production evidence. |
deploy.sh | Guarded deploy script; refuses to run without explicit confirmation, account ID, Pages project, and canonical URL. |
README.md | Human-readable starter overview and command list. |
Site identity and routing
| Path | Purpose |
|---|---|
src/site.config.ts | Site name, URL, contact data, address, social profiles, and AI policy. |
src/data/navigation.ts | Primary navigation. |
src/data/agent-reference.ts | Agent-facing pages, machine endpoints, examples, QA contract, workflows, and file map. |
astro.config.mjs | Astro config, site URL, and trailing slash behavior. |
Machine-readable endpoints
| Path | Purpose |
|---|---|
src/pages/agent-manifest.json.ts | Structured agent entry manifest. |
src/pages/file-map.json.ts | Structured repo file map. |
src/pages/qa-contract.json.ts | Structured quality contract. |
src/pages/examples.json.ts | Structured examples catalog. |
src/pages/agent-tasks.json.ts | Structured future-agent backlog. |
src/pages/product-roadmap.json.ts | Structured product roadmap endpoint. |
src/pages/walkthroughs.json.ts | Structured step-by-step walkthrough endpoint. |
src/pages/contract-registry.json.ts | Formal JSON contract registry endpoint. |
src/pages/site-studies.json.ts | Structured real-site study endpoint. |
src/pages/seo-aeo-evaluation.json.ts | Structured SEO/AEO evaluation endpoint. |
src/pages/source-traceability.json.ts | Structured source-to-site traceability endpoint. |
src/pages/site-type-playbooks.json.ts | Structured site-type build playbook endpoint. |
src/pages/page-patterns.json.ts | Structured reusable page-pattern endpoint. |
src/pages/page-pattern-fixtures.json.ts | Structured inventory of concrete page-pattern fixture routes. |
src/pages/fixtures/design-system/ | Concrete design-system fixture routes for agent-operable UI patterns. |
src/pages/conversion-copy.json.ts | Structured conversion copy system endpoint. |
src/pages/offer-ecosystem.json.ts | Structured offer-ecosystem funnel endpoint. |
src/pages/infrastructure-decisions.json.ts | Structured infrastructure decision system endpoint. |
src/pages/browser-visual-qa.json.ts | Structured browser visual QA contract endpoint. |
src/pages/crawl-evidence.json.ts | Structured crawl evidence contract endpoint. |
src/pages/design-system-contracts.json.ts | Structured design-system contract endpoint. |
src/pages/aeo-geo-context.json.ts | Structured AEO/GEO model context contract endpoint. |
src/pages/why-explanations.json.ts | Structured why-explanations contract endpoint. |
src/pages/real-site-comparisons.json.ts | Structured real-site comparison contract endpoint. |
src/pages/handoff-reports.json.ts | Structured handoff report contract endpoint. |
src/pages/llms.txt.ts | Concise LLM index. |
src/pages/llms-full.txt.ts | Expanded LLM summary. |
src/pages/sitemap.xml.ts | Sitemap generation. |
src/pages/schemamap.xml.ts | Schema discovery map. |
src/pages/robots.txt.ts | Crawler policy. |
Quality automation
| Path | Purpose |
|---|---|
scripts/spec-audit.mjs | Static required-file audit. |
scripts/qa-routes.mjs | Route, link, and sitemap checks. |
scripts/qa-seo.mjs | Metadata, canonical, H1, OG, and JSON-LD checks. |
scripts/qa-aeo.mjs | LLM endpoint, schema endpoint, and AEO contract checks. |
scripts/qa-browser.mjs | Browser screenshot, viewport overflow, visible H1, accessibility heuristic, and visual report checks. |
scripts/qa-crawl.mjs | Screaming Frog CSV export summarizer and crawl evidence report checks. |
scripts/qa-copy-stress.mjs | Stress tests weak-to-stronger conversion copy transformations against the copy contract. |
scripts/qa-page-pattern-fixtures.mjs | Stress tests concrete page-pattern fixture routes, section coverage, pattern mapping, and report evidence. |
scripts/qa-playbook-simulation.mjs | Stress tests every site-type playbook with simulated builds and negative controls for inputs, patterns, schema, claims, QA gates, and risk honesty. |
scripts/qa-crawl-stress.mjs | License-free static-export crawler enforcing link health, redirect budgets, sitemap reachability, and response budgets with synthetic negative controls. |
scripts/publish-evidence.mjs | Publishes the latest accepted QA reports to public/evidence/ with workstation paths redacted. |
scripts/qa-performance.mjs | Measures local LCP/CLS per route via Playwright and enforces asset budgets and page rules with negative controls. |
scripts/qa-demo-build.mjs | Validates the canonical demo build against its playbook, simulation record, claim ledger, schema requirements, and blocked phrases with negative controls. |
scripts/qa-agent-simulation.mjs | Simulates future-agent use from the main URL and saves scenario evidence. |
scripts/qa-contract-drift.mjs | Runs live contract checks plus negative drift fixtures for endpoints, schemas, sources, and evidence. |
scripts/qa-domain.mjs | Checks local static route readiness and optional production domain variants via QA_PRODUCTION_URL. |
scripts/qa-handoff.mjs | Generates a current handoff report from QA, contract, crawl, browser, domain, and agent-simulation evidence. |
scripts/qa-nectiv-lessons.mjs | Turns Nectiv-derived SEO/AEO lessons into dedicated local guardrail checks and production-evidence warnings. |
scripts/qa-common.mjs | Shared static server and parsing helpers for QA scripts. |
Source retention
| Path | Purpose |
|---|---|
data/sources/raw/ | Immutable raw source archive. |
data/sources/manifests/ | Source manifests and provenance notes. |
data/working/ | Cleaned or transformed source material. |
data/derived/ | Generated briefs, summaries, copy, and QA outputs. |
data/sources/manifests/example-client-discovery.md | Example source manifest for a fictional site build. |
data/working/example-client-facts.json | Example cleaned public-safe fact set derived from raw inputs. |
data/derived/example-page-brief.json | Example page brief connecting source facts to page, schema, SEO, and AEO requirements. |
data/derived/example-crawl-export/ | Example Screaming Frog-style crawl exports used by qa:crawl. |
data/derived/aeo-geo-context/ | Example prompt and answer-evidence fixtures for AEO/GEO model context checks. |
data/derived/copy-stress/copy-stress-fixtures.json | Weak-to-stronger copy stress fixtures used by qa:copy. |
data/derived/playbook-simulations/playbook-simulation-fixtures.json | Fictional simulated build fixtures for every site-type playbook used by qa:playbooks. |
data/sources/manifests/demo-brightline-gutter-discovery.md | Fictional source manifest for the canonical demo build. |
data/working/demo-brightline-facts.json | Cleaned fictional facts and blocked claims for the canonical demo build. |
data/derived/demo-brightline-page-brief.json | Page brief connecting demo facts to routes, patterns, schema, claims, and QA gates. |
src/pages/demo/brightline/ | Canonical demo routes: a fictional local-service site executing the local service playbook end to end. |
src/pages/demo/logpilot/ | Second canonical demo: a fictional B2B SaaS site executing the B2B SaaS playbook with its own brand tokens. |
data/sources/manifests/demo-logpilot-discovery.md | Fictional source manifest for the SaaS demo build. |
data/working/demo-logpilot-facts.json | Cleaned fictional facts and blocked claims for the SaaS demo build. |
data/derived/demo-logpilot-page-brief.json | Page brief for the SaaS demo build. |
reports/demo/ | Generated canonical demo build QA evidence. |
reports/performance/ | Generated performance budget and Core Web Vitals measurement evidence. |
data/sources/manifests/hormozi-conversion-copy-study-2026-06-06.md | Public source-study manifest for conversion copy patterns inspired by Alex Hormozi and Acquisition.com. |
reports/browser/ | Generated browser QA screenshots, visual diff images, and layout/keyboard/accessibility report. |
tests/browser/baselines/ | Committed screenshot baselines for visual diff; update intentionally with QA_UPDATE_BASELINES=1 npm run qa:browser. |
reports/crawl/ | Generated crawl evidence reports and saved crawl summaries. |
reports/seo-aeo/ | Generated SEO/AEO guardrail reports, including Nectiv-derived lesson checks. |
reports/agent-simulation/ | Generated future-agent simulation evidence from main URL scenarios. |
reports/contracts/ | Generated contract drift and negative-fixture evidence. |
reports/copy-stress/ | Generated copy stress-test evidence. |
reports/page-pattern-fixtures/ | Generated page-pattern fixture route stress-test evidence. |
reports/playbooks/ | Generated site-type playbook simulated-build stress-test evidence. |
reports/domain/ | Generated static route and optional production domain evidence. |
reports/handoff/example-handoff-report.json | Example handoff report fixture for final closeout evidence. |
reports/handoff/generated-handoff-report.json | Generated current handoff report from the latest QA evidence. |
Contract schemas
| Path | Purpose |
|---|---|
public/schemas/agent-manifest.schema.json | Validates the top-level agent manifest shape. |
public/schemas/file-map.schema.json | Validates file-map groups and paths. |
public/schemas/qa-contract.schema.json | Validates QA command contract. |
public/schemas/examples.schema.json | Validates reusable example blueprints. |
public/schemas/agent-tasks.schema.json | Validates future-agent backlog items. |
public/schemas/product-roadmap.schema.json | Validates product roadmap items. |
public/schemas/walkthroughs.schema.json | Validates roadmap walkthrough items. |
public/schemas/contract-registry.schema.json | Validates the formal contract registry. |
public/schemas/site-studies.schema.json | Validates real-site study items. |
public/schemas/seo-aeo-evaluation.schema.json | Validates SEO/AEO evaluation checks. |
public/schemas/source-traceability.schema.json | Validates source-to-site traceability records. |
public/schemas/site-type-playbooks.schema.json | Validates site-type build playbooks. |
public/schemas/page-patterns.schema.json | Validates reusable page patterns. |
public/schemas/page-pattern-fixtures.schema.json | Validates concrete page-pattern route fixtures. |
public/schemas/conversion-copy.schema.json | Validates conversion copy system. |
public/schemas/offer-ecosystem.schema.json | Validates offer-ecosystem funnel system. |
public/schemas/infrastructure-decisions.schema.json | Validates infrastructure decision system. |
public/schemas/browser-visual-qa.schema.json | Validates browser visual QA contract. |
public/schemas/crawl-evidence.schema.json | Validates crawl evidence contract. |
public/schemas/design-system-contracts.schema.json | Validates design-system contract. |
public/schemas/aeo-geo-context.schema.json | Validates AEO/GEO model context contract. |
public/schemas/why-explanations.schema.json | Validates why-explanations contract. |
public/schemas/real-site-comparisons.schema.json | Validates real-site comparison contract. |
public/schemas/handoff-reports.schema.json | Validates handoff report contract. |