AGENTS.md — web/

Applies to web/. Inherits the root AGENTS.md. Scope-specific deltas only.

Site boundary

web/ is the marketing site served at /. Package manifests own dependencies; tools/build-site.py --journeys-only generates the committed journeys this site uses. The *.generated.json renderer inputs are gitignored, not committed: a pre* hook regenerates them, so npm scripts here need python3 as well as Node. Use npm run <script> — a direct npx astro build skips npm's lifecycle, so it skips generation and fails on an unresolved import. Never hand-edit a generated input.

Action-changing traps

• Anchor on the prime journey before changing what this surface says. docs/design/journeys/team-orientation-future-state.md is the standing, gate-approved map for a team learning the whole system. It is one person across five stages, not several personas: stages 1-3 — evaluate, prove on real work, win buy-in — are this surface, and stages 4-5 are docs-site/. Read it before deciding a reader, an action goal, or a section's job, and reconcile a contradiction there rather than only in a content brief. Changing a stage's actions or residual pains needs re-gating through approve-journey; docs/design/README.md carries the gate state. The content brief at docs/design/content/marketing-home.md is downstream of the map, not a substitute for it.
• Build marketing before docs: the web build cleans repository build/.
• Markdown content uses relative cross-site links; origin-root paths fail under a subpath deployment.
• Keep pack docsUrl and journeyUrl populated when those materials exist.
• Use the e2e gate command, not the unrestricted browser suite, for deploy checks.
• Gate browser: the Playwright-managed Chromium playwright.config.ts declares; never substitute channel="chrome", which is not the engine the deploy is judged on.
• A missing browser is routine, not a finding — tools/repo/frontend_runtime.py browsers reports the resolved cache, install-browsers provisions it. Never record install state here: it is machine-local and inverts without warning.
• Full Playwright runs rewrite tracked snapshots; stage files explicitly, never git add -A.
• Run python3 tools/lint-npm-allow-scripts.py; when it fires, add a reviewed allowScripts entry or repin the dependency so it dedupes to a reviewed version.
• Keep web/package.json's fsevents@2.3.3 override. It was added because Playwright pinned fsevents to 2.3.2 exactly, and the override collapsed that nested copy. Playwright stopped declaring fsevents at 1.63.0. Vite's ~2.3.3 is now the only demand, and the lockfile already resolves 2.3.3, so the override changes nothing today. It is kept for the next re-resolution: allowScripts reviews the exact pair fsevents@2.3.3, and when 2.3.4 ships, ~2.3.3 takes it and fails that gate.
• Under an agent, astro dev and astro preview fork a detached server and return at once with JSON output — except under --ignore-lock on any platform (astro 7.3.3) and except on Windows (7.3.4), which both stay foreground. Agent detection still forces JSON everywhere, so either case gets the JSON and a server that never returns; on Windows --background still forks. --background with --ignore-lock is a hard error on every platform. The corollary is why this gets closed as "works for me": a human running the identical command in the identical worktree will not reproduce it, because the fork is keyed on agent detection rather than on anything about the command or the tree. Report it with that stated, or the first reply is a screenshot of it working. The gate is insulated (playwright.config.ts sets ASTRO_PREVIEW_BACKGROUND); a hand-run npm run preview is not, and leaves a live orphan recorded in .astro/ that blocks the next start on any port. preview's foreground path ignores --force despite its own error text recommending it, so stopping it is the only route, and deleting the record frees nothing: npm exec --prefix web -- astro preview stop --root web. --root is load-bearing — astro resolves the project from the working directory, not from --prefix.
• This site sets no markdown config, so it renders through astro's default processor while docs-site/ pins the legacy unified() one. The two co-deployed sites are deliberately on different engines; do not assume output parity when moving content between them.
• Define the viewport meta tag once in src/components/layout/SiteLayout.astro; never duplicate it.
• CSS token enforcement is stylelint + stylelint-declaration-strict-value + postcss-html, declared in web/package.json; stylelint.config.mjs owns which literals stay legal and why. It gates pull requests through build-check.yml's gate-css-tokens job and runs locally inside make test, so a newly hardcoded colour or font size reds a PR rather than only a local run.

Essential commands

npm run build --prefix web
npm run test:e2e:gate --prefix web
npm run lint:css --prefix web

Deeper pointers

The canonical local build order is docs-site Build. Current site architecture belongs in docs/architecture/; component details belong beside their implementation and tests.