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/rules/astro.md

@@ -0,0 +1,72 @@
+# Rule: Astro
+
+Binding for every `.astro` file.
+
+## Zero JS is the default
+
+A component ships no JavaScript unless it has a `client:*` directive. Seven of
+this site's ten pages ship no JS today and must continue to.
+
+- Never add `client:load` without justifying it in the PR description.
+- Prefer, in order: no JS → `client:visible` → `client:idle` → `client:load`.
+- An island is a **leaf**, not a wrapper. Hydrate the tab panel, not the page.
+
+## Islands in this project
+
+Only these need interactivity. Anything else claiming island status is wrong:
+
+| Island | Why | Directive |
+| --- | --- | --- |
+| Guide phase/tab switchers | click-driven panel swap | `client:visible` |
+| Review desk catalog + file viewer | search, filter, fetch source files | `client:load` |
+| Vote widget | talks to `vote-service/` | `client:visible` |
+| Language toggle | swaps EN/PT across the page | `client:idle` |
+
+## Structure
+
+```astro
+---
+// 1. imports
+// 2. Props interface
+// 3. destructure Astro.props
+// 4. derived values — no side effects, no fetch in components
+---
+<!-- markup -->
+<style>/* component-scoped */</style>
+```
+
+- Typed props always: `interface Props { … }`, then `const { … } = Astro.props`.
+- Data loading belongs in `src/content/` collections or the page frontmatter,
+  not inside a component.
+- No barrel files (`index.ts` re-export hubs). They cost tree-shaking and invite
+  cycles.
+
+## Content collections
+
+All copy lives in `src/content/`, typed with a Zod schema in
+`src/content/config.ts`. The review desk's `catalog.js` maps onto a collection
+almost one-to-one — do that rather than importing a 27 KB JS file.
+
+## Styles
+
+- Component styles go in the component's `<style>` block. Astro scopes them.
+- Only tokens and true resets live in global CSS.
+- Do not port `responsive.css` verbatim. It is an override layer whose reason
+  for existing disappears once layout is componentized. Port what a component
+  needs, prove the rest is dead, delete it.
+
+## URLs and the base path
+
+The site is served from `/ai-for-dummies/`. Set `base` in `astro.config.mjs` and
+never hand-write an absolute internal path. Use `import.meta.env.BASE_URL`.
+
+Existing routes are load-bearing and must not change, including trailing
+slashes and the review desk's query params.
+
+## Never
+
+- No UI framework (React/Vue/Svelte) unless a task brief explicitly calls for it.
+  Astro components plus a little vanilla JS cover everything here.
+- No CSS framework. This site has a hand-built visual identity — see
+  [`theming.md`](theming.md).
+- No external runtime requests. Self-host. `audit-ui.mjs` enforces it.