refactor: cut over to the Astro build

Merges refactor/task-20-cutover. Task 20 steps 1, 2, and 5; publishing is
not included.

The hand-written site is gone: 32 files deleted, including app.js,
responsive.css, and all ten route index.html files. Twelve more could not
be deleted -- the Astro pages import them and the build fails without
them -- so they moved to legacy/ verbatim, outside the reach of
check-tokens.mjs, which sweeps src/ and would demand a token migration
these files have not had.

Before anything was deleted, rendered-text-diff swept all ten routes plus
both Portuguese pages at full parity, 0 missing and 0 extra. That
comparison stops being possible once the legacy files are gone, which is
why it ran first. computed-style-diff on /full-guide/ is unchanged at 32.

verify.mjs no longer reads app.js and holds at 84 assertions.
audit-ui.mjs reads dist/. Docs across README, AGENTS.md, GATES.md, the
architecture context, and the operations guide now describe the built
site rather than the hand-written one.

origin/pages is unchanged at 37a1e480c6.
The publish job is still gated to manual dispatch.

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

.agents/context/architecture.md

@@ -1,45 +1,47 @@
-# Context: architecture, current and target
+# Context: architecture
 
-## Current (no build step)
+## Current (Astro, static output)
 
-Ten hand-written HTML pages, each linking its own CSS and one ES module:
+Ten routes, one `src/pages/` entry each, built to `dist/`:
 
-| 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                                           |
+| Route                | Page                            | Islands                                         |
+| -------------------- | ------------------------------- | ----------------------------------------------- |
+| `/`                  | `src/pages/index.astro`         | —                                               |
+| `/full-guide/`       | `src/pages/full-guide.astro`    | `GuideSelector`, `LanguageToggle`, `CopyPrompt` |
+| `/summary/`          | `src/pages/summary.astro`       | —                                               |
+| `/models/`           | `src/pages/models.astro`        | —                                               |
+| `/agents/`           | `src/pages/agents.astro`        | —                                               |
+| `/skills/`           | `src/pages/skills.astro`        | `SkillPackageExplorer`                          |
+| `/rules/`            | `src/pages/rules.astro`         | `RulesInteractive`                              |
+| `/skills-review/`    | `src/pages/skills-review.astro` | `legacy/skills-review/app.js`                   |
+| `/hands-on/starter/` | `public/` lab fixture           | own                                             |
+| `/hands-on/rules/`   | `public/` lab fixture           | 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 is still unmigrated
 
-### What each big file actually is
+`legacy/` holds the parts the migration did not componentize. They are not dead
+files — the pages listed above import them, and the build fails without them.
 
-- **`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/`.
+- **`legacy/styles/guide.css`** (was `styles.css`) — the editorial visual
+  system, imported by `full-guide.astro`.
+- **`legacy/styles/audit.css`** (was `full-guide/audit.css`) — responsive audit
+  overrides, imported by `full-guide.astro`.
+- **`legacy/styles/chapters.css`** — imported by `ChapterLayout.astro`.
+- **`legacy/styles/skills.css`**, **`skills-review.css`**, **`change-lens.css`**
+  — imported by their respective pages.
+- **`legacy/skills-review/`** — `app.js` and the module graph under it
+  (`catalog.js`, `submitted-catalog.js`, `files.js`, `submitted-files.js`,
+  `vote.js`). `catalog.js` + `submitted-catalog.js` are the review desk's real
+  data model, 24 entries; they are a content collection in all but name.
 
-## Target (Astro)
+These sit outside `src/` deliberately: `check-tokens.mjs` sweeps `src`, and
+these files are full of raw hex and unnamed breakpoints. Moving one into `src/`
+means migrating it to tokens in the same change, not adding an exclusion.
+
+`responsive.css`, `landing.css`, `app.js`, `rules/app.js`, `rules/styles.css`,
+and `skills/app.js` were deleted at cutover: their content lives in components.
+
+## Layout
 
 ```
 src/
@@ -52,15 +54,15 @@ public/
   hands-on/           lab fixtures copied verbatim, never processed
 ```
 
-### Non-negotiables for the target
+### Non-negotiables
 
 - **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
+- **Zero JS by default.** Seven of the ten pages ship no JavaScript. They must
+  still ship none. Islands are opt-in, per component, and justified.
+- **`hands-on/` stays vanilla.** It lives 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.

.agents/scripts/computed-style-diff.mjs

@@ -73,6 +73,8 @@ const PROPERTIES = [
   'overflow',
 ];
 
+// The legacy pages were deleted at cutover; run this from a pre-cutover
+// worktree, or the legacy side will 404.
 const legacyPath = route === 'index' ? 'index.html' : `${route}/index.html`;
 const astroPath = route === 'index' ? '' : `${route}/`;
 

.agents/scripts/rendered-text-diff.mjs

@@ -17,6 +17,10 @@
 // bilingual pair, so the two sides line up.
 //
 // Requires playwright (devDependency) and two static servers; it starts both.
+//
+// The legacy pages were deleted at cutover, so this needs a pre-cutover tree:
+//   git worktree add /tmp/vanilla <pre-cutover-sha>
+// and run from there, or run it from a checkout that still has them.
 import { spawn } from 'node:child_process';
 import { cpSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';

.agents/skills/astro-page/SKILL.md

@@ -12,8 +12,12 @@ description:
 
 The snapshot is the only objective evidence that no content was lost.
 
+The vanilla site was deleted at cutover. To compare against it, check the
+pre-cutover tree out into a scratch worktree first:
+
 ```bash
-pnpm run serve &                                  # vanilla site on :4173
+git worktree add /tmp/vanilla <pre-cutover-sha>
+(cd /tmp/vanilla && python3 -m http.server 4173) &
 node .agents/scripts/snapshot-route.mjs http://localhost:4173/models/ \
   > .agents/snapshots/models.txt
 ```

.agents/skills/design-tokens/SKILL.md

@@ -21,8 +21,10 @@ a bug.
 ```bash
 python3 - <<'PY'
 import re
-files=['styles.css','chapters.css','landing.css','rules/styles.css','skills/styles.css',
-       'skills-review/styles.css','hands-on/starter/styles.css','hands-on/rules/styles.css']
+files=['legacy/styles/guide.css','legacy/styles/chapters.css','legacy/styles/skills.css',
+       'legacy/styles/skills-review.css','legacy/styles/change-lens.css',
+       'legacy/styles/audit.css','public/hands-on/starter/styles.css',
+       'public/hands-on/rules/styles.css']
 seen={}
 for f in files:
     for m in re.finditer(r'--([a-z-]+):\s*([^;}]+)', open(f).read()):

.agents/skills/visual-regression/SKILL.md

@@ -33,8 +33,9 @@ with sync_playwright() as p:
     browser.close()
 ```
 
-Run once against the vanilla site (`pnpm run serve`), once against
-`pnpm run preview`. Keep both sets.
+Run once against `pnpm run preview`. To compare against the vanilla site, serve
+a pre-cutover worktree on :4173 first — those files are no longer on `main`.
+Keep both sets.
 
 ## Compare
 

.agents/snapshots/full-guide-pt.json

@@ -0,0 +1,104 @@
+[
+  "01 frota",
+  "02 worktrees",
+  "03 modelos",
+  "04 skills",
+  "05 criar",
+  "06 kit de campo",
+  "07 prática",
+  "ENGENHARIA DE IA <i></i> 01 / 2026",
+  "Uma apresentação para quem entrega software",
+  "Você não precisa de um exército de modelos. Precisa de um sistema: uma mente para enquadrar o trabalho, várias mãos para executá-lo e uma fronteira clara entre cada tarefa.",
+  "NOTA DE CAMPO / 001",
+  "Entregue o<br /><em>sistema.</em>",
+  "Skills · agentes · worktrees · evidências",
+  "modelo forte<br />para ambiguidade",
+  "workers delimitados<br />em paralelo",
+  "iterações<br />com evidências",
+  "Leia isto como um mapa de rota, não como uma receita de prompt.",
+  "REGRA ZERO",
+  "Modelo forte para ambiguidade.<br />Modelo leve para trabalho delimitado.",
+  "Uma pequena frota",
+  "coordenação antes do paralelismo",
+  "ORQUESTRADOR",
+  "Decide o que<br />precisa acontecer.",
+  "Componentes e estados visuais",
+  "Casos de aceitação",
+  "Guia e exemplos",
+  "O orquestrador preserva a intenção, escreve pequenos contratos e reúne resultados verificáveis. Ele não precisa digitar cada linha.",
+  "Por que a fronteira importa",
+  "uma tarefa vaga / três falhas previsíveis",
+  "Sopa de contexto",
+  "Cada worker lê tudo. Ninguém sabe quais fatos são essenciais.",
+  "Colisão de branches",
+  "Dois agentes usam o mesmo checkout. O caminho mais rápido vira resolução de conflitos.",
+  "Desvio confiante",
+  "O diff parece ótimo, mas ninguém verifica se resolveu o problema original.",
+  "O ciclo de subagentes",
+  "Clique em uma fase.<br /><em>Veja a passagem.</em>",
+  "Delegar é mover uma tarefa delimitada para um contexto menor — não abrir mão da responsabilidade.",
+  "O que atravessa contextos",
+  "brief → diff → evidência",
+  "Pacote",
+  "Contém",
+  "Por que importa",
+  "Git worktrees",
+  "Uma branch<br />por <em>mão.</em>",
+  "Um worktree é outro diretório ligado ao mesmo repositório. Cada agente recebe seu próprio checkout e índice; o histórico continua compartilhado.",
+  "Selecione um nó para inspecionar checkout, responsável e próxima ação.",
+  "topologia do repositório",
+  "<i></i> 4 checkouts",
+  "RAIZ",
+  "AGENTE DE UI",
+  "AGENTE DE TESTES",
+  "AGENTE DE DOCS",
+  "● limpo",
+  "3 arquivos · trabalhando",
+  "8 verificações · pronto",
+  "2 páginas · revisão",
+  "Roteamento de modelos",
+  "Não pague por<br />raciocínio onde precisa<br />de <em>ritmo.</em>",
+  "Escolha um trabalho para entender por que o perfil do modelo muda.",
+  "Trabalho",
+  "Perfil",
+  "Formato do prompt",
+  "Planejar",
+  "Construir",
+  "Explorar",
+  "Revisar",
+  "Skills",
+  "Escreva do jeito certo<br /><em>uma vez.</em>",
+  "Uma skill é um procedimento reutilizável. Ela pode carregar instruções, referências, scripts e assets. Não é memória mágica e não substitui critérios de aceitação.",
+  "01 / defina o gatilho",
+  "02 / carregue detalhes sob demanda",
+  "03 / devolva evidências",
+  "PACOTE DE SKILL",
+  "Skills comuns",
+  "escolha o comportamento antes do modelo",
+  "O kit de campo",
+  "Trabalhos diferentes.<br />Instintos <em>diferentes.</em>",
+  "Uma skill muda como o agente aborda o trabalho. Algumas moldam a comunicação. Outras impõem pesquisa, diagnóstico, revisão ou disciplina de conclusão. Selecione uma para inspecionar sua regra operacional.",
+  "SIMPLIFICAR",
+  "código mínimo que funciona",
+  "COMUNICAR",
+  "sinal sem excesso",
+  "CONCLUIR",
+  "gates e evidências",
+  "INVESTIGAR",
+  "fontes primárias primeiro",
+  "DIAGNOSTICAR",
+  "ciclo curto de feedback",
+  "REVISAR",
+  "padrões × especificação",
+  "ECONOMIZAR",
+  "comprima saídas ruidosas",
+  "UM LOADOUT PRÁTICO",
+  "<b>PLANEJAR</b> unlazy <i>→</i> <b>CONSTRUIR</b> ponytail-lite <i>→</i> <b>DIAGNOSTICAR</b> diagnosing-bugs <i>→</i> <b>REPORTAR</b> caveman",
+  "O PAPEL HUMANO",
+  "O agente pode ser autônomo na execução. Intenção, limites e evidências continuam sendo seus.",
+  "COMECE AQUI",
+  "Comece com um agente e uma skill. Adicione paralelismo apenas quando as tarefas forem realmente independentes.",
+  "Continue aprendendo",
+  "12 novas leituras + documentação primária",
+  "Aprofunde com documentação oficial, casos de produção, Medium e fluxos de praticantes. <a href=\"rules/\">Estudo de caso sobre regras e enforcement →</a> <a href=\"docs/references/README.md\">Referências primárias →</a> <a href=\"docs/references/additional-reading.md\">Trilha com 12 leituras →</a>"
+]