# 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.