ai-for-dummies/plans/astro-refactor/HANDOVER.md

Handover — Astro refactor, session of 2026-09-05

Phase 0 is done, merged, and green. Tasks 01–04 are all in main. The project now runs on pnpm, not npm. Nothing has been pushed: main is 23 commits ahead of origin/main.

Where the work is

Branch	Head	State
main	see git log	01–04 merged, gate green under pnpm
refactor/task-01-scaffold	71021e6	merged
refactor/task-02-tokens	c9ec9e3	merged
refactor/task-03-verification-net	2e79aac	merged
refactor/task-04-content-schema	b554f87	merged (gate verified before merge)

All four merged with --no-ff and zero conflicts. The four worktrees in ~/Projects/af-task-0* still exist and still hold npm-era node_modules; they are stale. ~/Projects/af-task-02/before/ still holds 29 MB of misplaced untracked screenshots — delete or move them before removing that worktree.

What each task actually produced

01 — scaffold (Codex). Astro 5.5 with base: '/ai-for-dummies', strict TS, BaseLayout.astro, summary.astro as the single smoke page, lint/format/husky configs, .gitea/workflows/, rewritten publishing section in docs/operations-guide.md, hands-on/ copied verbatim into public/. Build passes, gate passes, hooks verified live, 42/42 assertions intact.

02 — tokens (Gemini). src/styles/tokens.css and src/styles/base.css only — 43 lines. It did not touch the legacy CSS, deliberately: rewriting styles.css would break verify.mjs's exact-string assertions. So the three drifting palettes are now resolved in the new token layer, while the live site still runs on the old values. That is the correct scope, but it means the consolidation is not proven visually yet.

03 — verification net (Codex). .agents/scripts/visual-regression.mjs, rendered-text snapshots for all 10 routes, and PNG baselines at 4 widths in .agents/snapshots/before/ and before-reduced-motion/ (~8 MB, committed on purpose — they are the regression baseline).

04 — content schema (MiniMax). src/content/config.ts with eight empty collections and a strict localized({en, pt}) helper. No content moved; that is tasks 05 and 06.

Things I fixed that the plan got wrong

• AGENTS.md listed package-lock.json under Never touch, meaning never hand-edit. Task 01 read it as never create and shipped with --package-lock=false. npm ci — which is how every worktree spun up at the time — cannot work without it. Wording corrected; lockfile committed.
• The first lockfile was reconstructed from a node_modules installed without one, so its entries had no resolved/integrity and npm ci failed with ETARGET tinyglobby@0.2.17. Regenerated from a clean install.
• .husky/commit-msg rejected build: and revert:. Both are standard conventional types. Added.
• launch.sh read the agent name with [a-z-]*, which cannot match content-i18n-migrator. Tasks 04/05/06 silently fell back to astro-architect. Fixed to [a-z0-9-]* and made it fail loudly instead of guessing. Task 04 was relaunched under the right agent.

Things the agents got wrong, and what I did

• Task 03 went outside its brief. It rewrote scripts/audit-ui.mjs to ban external CSS dependencies — a sound check that the pre-existing malformed @font-face in styles.css violates, so it left the gate red for every downstream task. Reverted in 2e79aac; the snapshot net was kept. The check should come back once the font decision is made.
• Task 03 rebased instead of branching, flattening task 01's merge into four duplicate commits with new SHAs — the same divergent-history trap that broke the pages branch. Replayed onto the proper base; task 01 is an ancestor again. Worth adding to .agents/rules/git-worktrees.md: never rebase a task branch onto anything.
• Task 02 left 29 MB of screenshots in ~/Projects/af-task-02/before/ — untracked, and in the wrong place (.agents/snapshots/ is the right one). Its report claims the screenshot box is unticked while the files exist. Delete them or move them; do not commit them where they are.

Still open from task 01's own report

• Real-host smoke test of /ai-for-dummies/summary/ never ran — the branch is not merged and CI has not published. This is the #1 production-only failure mode in the whole migration. Do it before trusting any page work.
• No Playwright locally, so screenshot comparison could not run in CI.

The decision that is still yours

styles.css:1 has an @font-face whose src: points at a Google Fonts stylesheet, not a font file. Manrope and DM Mono have therefore never rendered; the site has always been Arial and generic monospace. Self-hosting them during the migration would silently redesign the site. Task 02 defaulted to matching what renders today. Decide explicitly, then task 19 can restore the external-CSS assertion. See .agents/context/design-system.md.

Next steps, in order

1. Decide the font question (see below). It blocks task 19 and it is the only thing here that needs a human.
2. Push main — nothing has left this machine yet. Safe now: the publish job is workflow_dispatch-only, so pushing no longer overwrites the live site. Watch that first CI run; the act-runner has never executed a job.
3. Once CI is green, do the real-host smoke test of /ai-for-dummies/summary/. This is still the #1 production-only failure mode in the migration and it has not been done. Publish manually via the workflow's publish input, on a throwaway basis, or accept the risk until task 20.
4. Clean up the four merged worktrees and branches.
5. Fan out phase 1 and 2:

   .agents/scripts/launch.sh 05 content-guide   --base main
   .agents/scripts/launch.sh 06 content-review  --base main
   .agents/scripts/launch.sh 07 primitives      --base main
   

   All three are unblocked now that 02 and 04 are in main. After 07 lands, 08–11 run four at a time.

Carried over from the phase 0 review

Found while reviewing the four diffs, none of it blocking, none of it fixed:

• public/hands-on/ is a byte-identical copy of hands-on/ with no sync mechanism. Two trees will drift. Symlink, or copy as a build step.
• --bp-* tokens cannot work. CSS custom properties do not resolve inside @media queries. The real enforcement is check-tokens.mjs's ALLOWED_BREAKPOINTS allowlist; the variables are decoration and will mislead whoever writes the first responsive component.
• tokens.css has no font tokens at all, and the scale skips --step-2 and --step-3. Downstream of the font decision.
• visual-regression.mjs has no compare mode. It only captures. It is out of CI for that reason — see .agents/rules/gates.md.
• src/content/config.ts uses the legacy type: 'data' API. Astro 5 auto-converts it to a glob loader and it works; prefer explicit file()/glob() loaders in src/content.config.ts when 05/06 touch it.

Running an agent

.agents/scripts/launch.sh <nn> <slug> [--base ref] [--cli codex|agy|mm] [--fg]

Routing is automatic: Codex for 01/03/15/16/19, agy (Gemini 3.1 Pro) for 02/18, mm (Claude Code against MiniMax-M3) for the rest. All three launch with permission prompts disabled, because a blocked edit in an unattended run just hangs. Logs land in .agents/logs/ (gitignored).

Task 07 is the routing calibration point. It is small and easy to judge. Check it before committing to MiniMax for the other twelve.