Files

T

Marcos Paulo 580293867d refactor: retire the hand-written site

Deletes the pre-Astro pages, scripts, and stylesheets that the migration
replaced, and moves the ones it did not replace out of the way.

Deleted (32 files): app.js, responsive.css, landing.css, rules/app.js,
rules/styles.css, skills/app.js, the ten route index.html files, and the
root hands-on/ copy, which is byte-identical to public/hands-on/ -- the
one the build actually ships.

Moved to legacy/ (12 files): styles.css, full-guide/audit.css,
chapters.css, skills/styles.css, skills-review/styles.css,
skills-review/change-lens.css, and the skills-review/app.js module graph.
These are not dead. The Astro pages import them and the build fails
without them, which the plan had not accounted for. They go to legacy/
rather than src/ because check-tokens.mjs sweeps src, and these files are
full of raw hex and unnamed breakpoints: moving one into src/ should mean
migrating it to tokens in the same change, not adding a scan exclusion.
The prettier, stylelint, and eslint ignore lists that already named these
files at their old paths now name legacy/ instead.

verify.mjs no longer reads app.js. The 102 Portuguese strings were
extracted from its translations.pt object before deletion into
.agents/snapshots/full-guide-pt.json -- a legacy capture, not a snapshot
of the Astro build, so the assertion still compares against an
independent source. The brace-matching helper's assertion is replaced by
one that rejects an empty snapshot entry, without which trimming the
snapshot would make the presence check pass vacuously. Count stays at 84.

audit-ui.mjs reads the ten pages from dist/ and resolves Astro's
base-absolute hrefs against it.

Before deleting anything, rendered-text-diff was run across all ten
routes plus both Portuguese pages: every one at parity, 0 missing and 0
extra. That comparison is not repeatable once the legacy files are gone.
computed-style-diff on /full-guide/ stays at 32 differences, so the moves
are style-neutral.

Docs updated to match: README, AGENTS.md, GATES.md, the architecture
context, the operations guide's lab instructions, and the three skills
that told you to serve the vanilla site.

Publishing is not part of this commit.

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

2026-09-06 08:30:27 +00:00

2.4 KiB

Raw Blame History

name, description

name	description
astro-page	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:

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

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

Then, in order:

Move markup into the layout + components. Reuse existing components before creating new ones.
Move copy into src/content/. Both en and pt, copied literally — never retyped.
Move page CSS into component <style> blocks. Do not port responsive.css wholesale; take what this page needs and prove the rest dead.
Keep every data-* hook. verify.mjs asserts many of them by name (data-phase, data-tree, data-route, data-model-provider, …).
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

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.

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.

2.4 KiB Raw Blame History