---
name: astro-page
description:
  Migrate one hand-written HTML page of the ai-for-dummies site to an Astro
  route without changing its URL, content, or JS budget. Use for any page-level
  migration task.
---

# Migrating a page to Astro

## Snapshot first, migrate second

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
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
```

Screenshot the same route at 560 / 800 / 1100 / 1600 px as well.

## Migrate

```bash
cp .agents/templates/pages/chapter.astro src/pages/models.astro
```

Then, in order:

1. Move markup into the layout + components. Reuse existing components before
   creating new ones.
2. Move copy into `src/content/`. Both `en` and `pt`, copied literally — never
   retyped.
3. Move page CSS into component `<style>` blocks. Do **not** port
   `responsive.css` wholesale; take what this page needs and prove the rest
   dead.
4. Keep every `data-*` hook. `verify.mjs` asserts many of them by name
   (`data-phase`, `data-tree`, `data-route`, `data-model-provider`, …).
5. Keep every ARIA attribute and the `<title>` / `<meta name="description">`.

## The URL must not change

Served from `/ai-for-dummies/`, so `base` is set in `astro.config.mjs`. Never
hand-write an internal absolute path; use `import.meta.env.BASE_URL`.

Trailing slashes matter. `/models/` must not become `/models`.

If the page honours query params (the review desk uses `?author=`, `?skill=`,
`?view=`, `?file=`, `?compare=`, `?render=`), they must still work — they are
documented in the page footer and shared externally.

## Prove it

```bash
pnpm run build
node .agents/scripts/snapshot-route.mjs dist/models/index.html > /tmp/after.txt
diff .agents/snapshots/models.txt /tmp/after.txt      # empty, or justify every line
node scripts/audit-ui.mjs
pnpm run verify
```

Then screenshots at the same four widths, and
[`../../checklists/before-page.md`](../../checklists/before-page.md).

## JS budget

A page that shipped zero JS must still ship zero. Check the build output. If
your migration added a `client:load` to a static page, you did it wrong.