docs: add .agents workspace and the Astro refactor plan

Adds the agent-facing workspace and a 20-task plan for migrating the site
to Astro. Nothing here implements the refactor; these are briefs, rules and
templates that the task agents read.

- .agents/ holds context, rules, checklists, skills, specialist agents,
  component/page/config templates and gate scripts. It is vendor-neutral so
  MiniMax, Gemini and Codex can all read it; CLAUDE.md just points at
  AGENTS.md.
- .husky/ plus .lintstagedrc.json wire the three gate tiers. gate.sh locks on
  the shared git-common-dir so parallel worktrees serialise, and guards the
  assertion count in scripts/verify.mjs against a coverage drop.
- plans/astro-refactor/ carries the phase graph, per-task briefs and the
  model-routing recommendation.

These files must be tracked before fanning out: a worktree only checks out
tracked files, so an untracked plan is invisible to every agent working in one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.agents/context/design-system.md

@@ -0,0 +1,107 @@
+# Context: the design system (as it actually is)
+
+Read this before touching CSS. Everything here was extracted from the current
+files, not assumed.
+
+## There is no single palette. There are three.
+
+The same semantic names carry different values depending on which stylesheet
+loaded them:
+
+| Token | `styles.css`, `rules/styles.css` | `chapters.css`, `skills-review/styles.css` | `hands-on/*/styles.css` |
+| --- | --- | --- | --- |
+| `--paper` | `#f5f4f1` | `#f6f3ed` | `#f4f3ef` |
+| `--ink` | `#172f42` | `#122534` | `#173044` |
+| `--muted` | `#697b89` | `#65717a` | `#687d8c` |
+| `--line` | `#d8dee2` | `#d0d5d2` | `#d5dde1` |
+| `--blue` | `#527f9f` | `#215675` | `#5683a1` |
+| `--gold` | `#efc76b` | `#ebbf58` | `#efc86d` |
+| `--accent` | `#7c78a8` | — | — |
+| `--deep` | `#102536` | — | — |
+| `--red` | — | `#a7483f` (chapters only) | — |
+| `--violet` | — | `#6b668f` (review desk only) | — |
+
+Most deltas are a few units per channel — drift, not intent. `--blue` is the
+exception: `#527f9f` vs `#215675` is a visible difference and may be deliberate.
+
+**Decision required before any component work** (task 02). Options:
+
+- **Canonicalize** to one palette. Recommended. The sub-perceptual deltas
+  collapse; only `--blue` needs a human's eye on a before/after screenshot.
+- **Keep three named surfaces** (`--surface-guide`, `--surface-chapter`,
+  `--surface-lab`) if the drift turns out to be intentional per section.
+
+Do not "just pick one" silently in the middle of another task. This is its own
+reviewed change with visual diffs attached.
+
+## The typography you see is not the typography that was written
+
+`styles.css` line 1:
+
+```css
+@font-face{font-family:Manrope;src:url('https://fonts.googleapis.com/css2?family=DM+Mono&family=Manrope:wght@400;600;700;800&display=swap')}
+```
+
+`src:` points at a **CSS stylesheet**, not a font file. No browser can load a
+font from that, so:
+
+- every `font-family:Manrope,Arial,sans-serif` renders as **Arial**
+- every `font:… 'DM Mono',monospace` renders as the **generic monospace** face
+- there are no `@font-face` blocks anywhere else and zero font files in the repo
+- `scripts/audit-ui.mjs` only rejects external `<link>`/`<script>` tags, so this
+  slipped through the "dependency-free" audit
+
+**This is a trap for the refactor.** Self-hosting Manrope and DM Mono in Astro
+is the obvious "fix" — and it would change how every page looks, violating
+"maintain the same styles". Treat it as an explicit product decision:
+
+- **Keep current rendering**: delete the dead `@font-face`, replace the font
+  stacks with what actually renders today (`Arial, sans-serif` /
+  `ui-monospace, monospace`). Zero visual change. Honest CSS.
+- **Adopt the intended fonts**: self-host the woff2 files in `public/fonts/`,
+  add real `@font-face` with `font-display:swap`. Better-looking, but it is a
+  redesign and needs sign-off plus fresh screenshots.
+
+Default to the first unless a human says otherwise.
+
+## Type scale
+
+`Georgia, serif` is used deliberately for emphasis (`h1 em`, `.hero em`) and is
+real — it is a system font, so it does render. Keep it.
+
+Sizes are all `clamp()`, roughly:
+
+| Role | Value |
+| --- | --- |
+| Display / `h1` | `clamp(56px,9vw,126px)` |
+| Section `h2` | `clamp(36px,5vw,65px)` |
+| Sub-head | `clamp(24px,3vw,38px)` |
+| Pull-quote | `clamp(22px,3vw,36px)` |
+| Body | `15px/1.6` … `18px` |
+| Eyebrow / label | `10–11px` monospace, `letter-spacing:.08–.1em`, uppercase |
+
+There are 14+ distinct clamp triples doing near-identical jobs. Collapse to a
+named scale (`--step-0` … `--step-6`) during tokenization; the visual result
+should be unchanged within a pixel or two at common viewports.
+
+## Breakpoints
+
+Sixteen distinct max-widths are in use: 420, 520, 530, 560, 600, 620, 720, 800,
+850, 880, 900, 1000, 1050, 1100 — plus `min-width:1600px` and `min-width:2200px`.
+
+Collapse to a named set (suggested: 560 / 800 / 1100 / 1600 / 2200) and prove
+equivalence with screenshots at the *old* breakpoint values, since that is
+where regressions will hide.
+
+`@media(prefers-reduced-motion:reduce)` is already respected in several
+stylesheets. Keep it — see [`../rules/animation.md`](../rules/animation.md).
+
+## House style worth preserving
+
+The visual identity is editorial-print: flat colour blocks, hairline `1px`
+rules, uppercase monospace eyebrows with wide tracking, very tight negative
+letter-spacing on display type (`-.06em` … `-.08em`), grid layouts with `gap:1px`
+over a background colour to fake borders, and near-zero border-radius.
+
+That last trick (`gap:1px` + parent background) is used everywhere. It is
+intentional. Do not replace it with `border`.