AGENTS.md

1# web — agent guidance
2 
3The codewhale.net site (Next.js). Read the repo-root `AGENTS.md` first.
4 
5- **Facts derive from the repo.** `npm run prebuild` regenerates
6  `lib/facts.generated.ts` (version, crate/provider/tool counts, license) and
7  `npm run check:facts` fails if the committed copy drifts. Never hand-edit the
8  generated file; change the source of truth in the repo and regenerate.
9- **Gates** (all must pass; CI runs them):
10 
11```sh
12  npm ci && npm run prebuild && npm run check:facts && npm run check:docs \
13    && npm test && npm run lint && npm run build
14```
15 
16  `check:docs` verifies doc topics against real repo files, the version stamp,
17  and install snippets — stale docs fail here, not in production.
18- **Shared public copy lives in `web/lib/content/`.** Locale-aware `{ en, zh }`
19  modules are the single source for product vocabulary and the getting-started
20  path; pages render from them. Keep definitions verbatim with
21  `docs/public-surface-facts.json` / `docs/MODES.md` —
22  `web/lib/content/vocabulary.test.ts` pins this. New locales extend the pairs,
23  not the pages.
24- **Real-session media goes through `web/lib/media-manifest.ts`.** Never commit
25  placeholder or staged footage; a `pending` entry renders the visible
26  "recording pending release candidate" state via `components/session-media.tsx`.
27  Flipping to `published` requires the full asset set and the enforceable
28  file/byte/poster checks in `media-manifest.test.ts`.
29- `AGENT.md` (singular, next to this file) documents the community assistant —
30  maintainer-owned automation. Don't extend it without Hunter.
31