Marcos Paulo
7f11b6e88e
`styles.css` line 1 carried a malformed rule for the life of the site:
@font-face{font-family:Manrope;src:url('https://fonts.googleapis.com/css2?...')}
`src:` in an @font-face must point at a font binary. That URL returns a CSS
stylesheet, so no browser could ever load a face from it. Every
`font-family:Manrope,Arial,sans-serif` fell through to Arial, and 'DM Mono' was
never declared as a family at all, so it fell through to generic monospace. The
intended typography has never once been seen.
Task 02 spotted this and was told to default to deleting the dead rule and
declaring the stacks that actually render. It recorded that decision, deferred
the deletion to "future component tasks", and nothing picked it up. The human
has now chosen the other branch: the real fonts.
Self-hosted rather than linked from fonts.googleapis.com because
scripts/audit-ui.mjs rejects any external <link>/<script>, and because the site
is presented in workshop rooms with unreliable networks. Latin and latin-ext
subsets only — the site is EN and PT-BR, so the cyrillic, greek and vietnamese
subsets Google also serves are dropped. Manrope ships as one variable file
covering 400-800. 89 KB total across six faces, all SIL OFL.
One public/fonts/fonts.css serves both trees, with relative url()s that each
consumer resolves against that file's own location: BaseLayout.astro links it
for Astro pages, the legacy root styles.css @imports it.
This changes how every page renders. That is the point, and it is the one
sanctioned visual change in the migration — screenshots taken before today show
Arial and are no longer a valid baseline. The three governing documents that
said "do not add a webfont" are updated so the next design-system-keeper does
not undo this.
Adds .stylelintignore, mirroring .prettierignore's legacy list for the same
reason: staging the minified styles.css to change one declaration produced ~180
declaration-block-single-line-max-declarations errors and blocked the commit.
public/fonts/fonts.css is deliberately excluded from that ignore list.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Astro refactor — plan
Status: not started. These are briefs, not work. Nothing in this plan has been implemented.
Goal: move ai-for-dummies from ten hand-written HTML pages to Astro, so that
adding a chapter is a component and a content entry rather than a copy-pasted
file — without changing how the site looks, what it says, or what it costs a
visitor to load.
Session state: see HANDOVER.md. Phase 0 is done and green
on four branches; nothing is merged or pushed.
Read before starting anything
| File | Why |
|---|---|
../../AGENTS.md |
entry point |
../../.agents/context/design-system.md |
three drifting palettes, a font that has never rendered |
../../.agents/context/verification.md |
42 assertions that will all break, and must not be deleted |
../../.agents/context/publishing.md |
Gitea Pages serves a branch and cannot build |
The three things most likely to go wrong
- Content loss that nobody notices. 50 KB of bilingual copy moves between files. Snapshot every route before migrating it — task 03 exists to make that possible and blocks all page work.
- Assertions deleted to make a red suite green. That converts a
content-loss bug into a passing build.
gate.shrefuses a coverage drop. - Base-path bugs. The site lives at
/ai-for-dummies/. It will work perfectly inpnpm run previewand 404 in production. Verify on the real host.
Phases
Phase 0 foundation 01 → (02 ∥ 03 ∥ 04)
Phase 1 content 05 ∥ 06 after 04
Phase 2 components 07 → (08 ∥ 09 ∥ 10 ∥ 11) after 02
Phase 3 pages 12 ∥ 13 ∥ 14 ∥ 17, then 15a ∥ 15b ∥ 15c ∥ 16, then 15d, 15e
Phase 4 polish 18 ∥ 19, then 20
| # | Task | Agent | Depends on | Parallel with |
|---|---|---|---|---|
| 01 | scaffold + gates | astro-architect | — | — |
| 02 | design tokens | design-system-keeper | 01 | 03, 04 |
| 03 | verification net | verification-engineer | 01 | 02, 04 |
| 04 | content schema | content-i18n-migrator | 01 | 02, 03 |
| 05 | guide content | content-i18n-migrator | 04 | 06 |
| 06 | review-desk content | content-i18n-migrator | 04 | 05 |
| 07 | primitives | component-builder | 02 | — |
| 08 | route cards | component-builder | 07 | 09, 10, 11 |
| 09 | chapter blocks | component-builder | 07 | 08, 10, 11 |
| 10 | guide blocks | component-builder | 07 | 08, 09, 11 |
| 11 | review-desk blocks | component-builder | 07 | 08, 09, 10 |
| 12 | landing page | page-migrator | 03, 08 | 13, 14, 17 |
| 13 | chapter pages ×4 | page-migrator | 03, 09 | 12, 14, 17 |
| 14 | rules page | page-migrator | 03, 09 | 12, 13, 17 |
| 15 | full guide — split into 15a–15e | — | — | — |
| 05b | interactiveCopy data | content-i18n-migrator | 05 | — |
| 15a | guide selector | component-builder | 05, 10 | 15b, 15c |
| 15b | copy prompt | component-builder | 05 | 15a, 15c |
| 15c | language toggle | content-i18n-migrator | 05 | 15a, 15b |
| 15d | assemble full guide | page-migrator | 05b, 10, 13, 15a–c | 16 |
| 15e | retire responsive.css | design-system-keeper | 15d, 16 | — |
| 16 | review desk | page-migrator | 06, 11, 13 | 15d |
| 17 | hands-on passthrough | astro-architect | 01 | 12, 13, 14 |
| 18 | motion pass | motion-designer | 15d, 16 | 19 |
| 19 | contract re-point | verification-engineer | 15d, 16 | 18 |
| 20 | cutover + cleanup | astro-architect | all | — |
Widest parallelism: four agents (tasks 08–11, then 12/13/14/17). More than that and they start contending on review capacity, not on files.
Running a task
.agents/scripts/worktree.sh start 08 route-cards
cd ../af-task-08
# agent reads: plans/astro-refactor/task-08-route-cards.md
# .agents/agents/component-builder.md (+ the skills it names)
The script runs pnpm install --frozen-lockfile and verify-hooks.sh for you.
That matters: .husky/_ is generated, not committed, so a hand-made worktree
has hooks configured but silently not running.
Finishing:
pnpm run gate # tier 2, same as pre-push
# reviewer agent reads the diff against .agents/checklists/before-merge.md
.agents/scripts/worktree.sh finish 08 route-cards
Which model to run each task
See MODEL-ROUTING.md.
These files must be committed
Worktrees check out tracked files. If this plan stays untracked, every worktree
you create will be missing it. Commit plans/ and .agents/ before fanning
out.