| 1 | # web — agent guidance |
| 2 | |
| 3 | The 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 |