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/architecture.md

@@ -0,0 +1,75 @@
+# Context: architecture, current and target
+
+## Current (no build step)
+
+Ten hand-written HTML pages, each linking its own CSS and one ES module:
+
+| Route | Page | Script | Stylesheets |
+| --- | --- | --- | --- |
+| `/` | `index.html` | — | `chapters.css`, `landing.css` |
+| `/full-guide/` | `full-guide/index.html` | `app.js` (50 KB) | `styles.css`, `responsive.css`, `audit.css` |
+| `/summary/` | `summary/index.html` | — | `chapters.css` |
+| `/models/` | `models/index.html` | — | `chapters.css` |
+| `/agents/` | `agents/index.html` | — | `chapters.css` |
+| `/skills/` | `skills/index.html` | `skills/app.js` | `skills/styles.css` |
+| `/rules/` | `rules/index.html` | `rules/app.js` | `rules/styles.css` |
+| `/skills-review/` | `skills-review/index.html` | `skills-review/app.js` | `skills-review/styles.css`, `change-lens.css` |
+| `/hands-on/starter/` | lab fixture | own | own |
+| `/hands-on/rules/` | lab fixture | own | own |
+
+Weight is concentrated: `app.js` 50 KB, `responsive.css` 30 KB,
+`skills-review/catalog.js` 27 KB, `skills-review/submitted-catalog.js` 18 KB.
+
+### What each big file actually is
+
+- **`app.js`** — not really application code. It is a **bilingual content
+  database** (`phases`, `handsOnPrompts`, `modelGuide`, `skillSources`,
+  `skillInstallPrompts`, each keyed `{en, pt}`) plus ~12 small `render*`
+  functions that swap `innerHTML` on tab clicks. ~50 `en:` keys. The content
+  should become data; only the tab behaviour is interactive.
+- **`responsive.css`** — a 30 KB append-only layer of overrides bolted on top of
+  `styles.css`. Expect large parts to be dead once layout moves into components.
+  Do not port it verbatim.
+- **`skills-review/catalog.js`** — the real data model of the review desk: one
+  entry per submitted skill with `id`, `author`, `title`, `status`, `focus`,
+  `wins[]`, `improve[]`, `extras`, `improved` (full markdown). 24 entries across
+  `catalog.js` + `submitted-catalog.js`. This is already a content collection in
+  all but name.
+- **`skills-review/files.js` / `submitted-files.js`** — generated file manifests.
+- **`vote.js`** — the vote widget island; talks to `vote-service/`.
+
+## Target (Astro)
+
+```
+src/
+  content/            catalog entries, chapter copy, EN/PT strings (typed collections)
+  layouts/            BaseLayout, ChapterLayout, GuideLayout
+  components/         .astro by default; islands only where marked
+  styles/             tokens.css, base.css, then per-component styles
+  pages/              routes mirroring today's URLs exactly
+public/
+  hands-on/           lab fixtures copied verbatim, never processed
+```
+
+### Non-negotiables for the target
+
+- **URLs do not change.** `/full-guide/`, `/skills-review/`, `/hands-on/starter/`
+  and the rest must resolve exactly as they do now, trailing slash included.
+  Existing links (including `docs/`, SilverBullet, and shared URLs with
+  `?author=…&skill=…&view=…` query params) must keep working.
+- **Zero JS by default.** Seven of the ten pages ship no JavaScript today.
+  They must still ship none. Islands are opt-in, per component, and justified.
+- **`hands-on/` stays vanilla.** It goes in `public/` untouched. It is a lab
+  fixture, not a component.
+- **No external runtime requests.** `audit-ui.mjs` enforces this and it is part
+  of the site's thesis. Self-host anything you add.
+- **The review desk's query-param deep links keep working** — `?author=`,
+  `?skill=`, `?view=`, `?file=`, `?compare=`, `?render=`. They are documented in
+  the page footer and shared externally.
+
+## Companion service
+
+`vote-service/` is a Go API on its own Kubernetes deploy cycle, reached by the
+review desk over `window.SKILLS_REVIEW_VOTE_API`. The refactor does not touch
+it. Keep the global, or replace it with a build-time `PUBLIC_VOTE_API` env var —
+but if you do, update `vote-service/README.md` in the same change.