From 9621ba44bfeb59a0a60b0705f8617b05e1c8c951 Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Sat, 5 Sep 2026 17:23:38 +0000 Subject: [PATCH 1/5] feat: migrate chapter pages models, agents, skills to Astro Migrate the three remaining chapter pages to Astro routes, sharing ChapterLayout and ChapterHero/TopBar/SiteFooter blocks. /summary/ already in place from task 12. - /models/ -> src/pages/models.astro (zero JS) - /agents/ -> src/pages/agents.astro (zero JS) - /skills/ -> src/pages/skills.astro (one island: SkillPackageExplorer) SkillPackageExplorer is the only JS across the four chapter pages; moves vanilla skills/app.js content verbatim into the island. Uses data-skill-file as the new hook (vanilla used data-package-file; verify.mjs still asserts that on the legacy index.html). Copy lives in src/content/chapters/{models,agents,skills}.json. All four pages pass empty-text snapshot diffs against .agents/snapshots/{models,agents,skills,summary}.txt. pnpm run verify green: verify.mjs (16 sections), audit-ui.mjs, and check-tokens.mjs (212 marked token-gap markers, 0 unsuppressed). Did not touch ChapterLayout, the verification suite, contents of the summary.astro file (it shipped with task 12), or the vanilla chapters' HTML files at the repo root (verify.mjs still reads those). --- .../islands/SkillPackageExplorer.astro | 309 ++++++++++++++++++ src/pages/agents.astro | 79 +++++ src/pages/models.astro | 80 +++++ src/pages/skills.astro | 69 ++++ 4 files changed, 537 insertions(+) create mode 100644 src/components/islands/SkillPackageExplorer.astro create mode 100644 src/pages/agents.astro create mode 100644 src/pages/models.astro create mode 100644 src/pages/skills.astro diff --git a/src/components/islands/SkillPackageExplorer.astro b/src/components/islands/SkillPackageExplorer.astro new file mode 100644 index 0000000..c6ccb35 --- /dev/null +++ b/src/components/islands/SkillPackageExplorer.astro @@ -0,0 +1,309 @@ +--- +// SkillPackageExplorer — the four-file skill-package picker. The interactive +// version of the `data-package-file` buttons that the vanilla skills page +// shipped, rewritten for the Astro chapter surface. The four package entries +// mirror skills/app.js so the migration preserves content 1:1; the buttons +// carry `data-skill-file` and the click handler swaps the preview panel +// contents client-side. +// +// Page is `client:visible` rather than `client:load`: the picker sits below +// the hero and grid; deferring until it scrolls into view keeps initial JS +// to zero for the above-the-fold content. The page ships zero JS for the +// hero/grid/footer parts — only the picker island hydrates. + +interface PackageFile { + id: 'skill' | 'references' | 'scripts' | 'assets'; + prefix: '├── ' | '└── '; + label: string; + /** Small caption under the file label, mirrors the vanilla source. */ + caption: string; + title: string; + body: string; + code: string; +} + +const packageFiles: PackageFile[] = [ + { + id: 'skill', + prefix: '├── ', + label: 'SKILL.md', + caption: 'trigger + workflow', + title: 'The operating contract', + body: 'The one file that should always be loaded. Define the exact trigger, the ordered workflow, safety limits, and the evidence the agent returns.', + code: '---\nname: review-ui\ndescription: Review a changed UI for focus, reflow, and motion.\n---\n\n1. Inspect the changed interaction.\n2. Run the UI checks.\n3. Return findings with evidence.', + }, + { + id: 'references', + prefix: '├── ', + label: 'references/', + caption: 'conditional facts', + title: 'Facts, only when needed', + body: 'Keep conditional detail out of the main instruction. A dialog pattern, framework caveat, or accessibility checklist belongs here when it is not needed for every review.', + code: 'references/\n└── accessibility.md\n ├── keyboard interaction patterns\n └── focus and reflow checklist', + }, + { + id: 'scripts', + prefix: '├── ', + label: 'scripts/', + caption: 'deterministic checks', + title: 'Mechanics that should not depend on memory', + body: 'Turn deterministic checks into runnable tools. The agent still judges the result, but it should not have to recreate a viewport test or filename rule by hand.', + code: 'scripts/\n└── check-reflow.mjs\n └── checks 320px, 1280px, and 4K widths', + }, + { + id: 'assets', + prefix: '└── ', + label: 'assets/', + caption: 'templates + examples', + title: 'Starting material, not hidden instructions', + body: 'Use assets for templates and examples a person or agent can copy. Keep them clearly named so package readers can choose the right starting point.', + code: 'assets/\n├── review-report.md\n└── focus-test-fixture.html', + }, +]; +--- + +
+
+

REVIEW-UI / SKILL PACKAGE

+ { + packageFiles.map((file, index) => ( + + )) + } +
+
+
+ + + + diff --git a/src/pages/agents.astro b/src/pages/agents.astro new file mode 100644 index 0000000..6caad73 --- /dev/null +++ b/src/pages/agents.astro @@ -0,0 +1,79 @@ +--- +// /agents/ — chapter page. Migrated from agents/index.html in task 13. +// Identical URL (/agents/), zero client JS, copy lives in +// src/content/chapters/agents.json. + +import { getEntry } from 'astro:content'; +import ChapterLayout from '../layouts/ChapterLayout.astro'; +import ChapterHero from '../components/blocks/ChapterHero.astro'; + +const base = import.meta.env.BASE_URL; +const chapter = await getEntry('chapters', 'agents'); +const lede = chapter.data.lede.en; +const title = chapter.data.title.en; +const eyebrow = chapter.data.eyebrow.en; +const cards = chapter.data.cards ?? []; +const sections = chapter.data.sections ?? []; +const treeSection = sections[0]; +const handoffSection = sections[1]; +--- + +]+>/g, '')}> + ← ROUTE MAP + 02 / AGENTS & TREES + field guide ↗ + + + +

{lede}

+ + +
+
+

{treeSection.eyebrow.en}

+

+

+
+ {treeSection.panelLabel.en} + {treeSection.panelCode.en} +
+
+ +
+ { + cards.map((card) => ( +
+ {card.label.en} +

{card.title.en}

+

{card.copy.en}

+
+ )) + } +
+ +
+
+

{handoffSection.eyebrow.en}

+

+

+
+ { + handoffSection.steps.map((step, index) => ( +
+ {String(index + 1).padStart(2, '0')} +
+ {step.label.en} + {step.copy.en} +
+
+ )) + } +
+
+ + + diff --git a/src/pages/models.astro b/src/pages/models.astro new file mode 100644 index 0000000..d910e47 --- /dev/null +++ b/src/pages/models.astro @@ -0,0 +1,80 @@ +--- +// /models/ — chapter page. Migrated from models/index.html in task 13. +// Identical URL (/models/), zero client JS, copy lives in +// src/content/chapters/models.json. The grid + panel + steps sections +// render the chapter-collections content with bilingual `en` strings. + +import { getEntry } from 'astro:content'; +import ChapterLayout from '../layouts/ChapterLayout.astro'; +import ChapterHero from '../components/blocks/ChapterHero.astro'; + +const base = import.meta.env.BASE_URL; +const chapter = await getEntry('chapters', 'models'); +const lede = chapter.data.lede.en; +const title = chapter.data.title.en; +const eyebrow = chapter.data.eyebrow.en; +const cards = chapter.data.cards ?? []; +const sections = chapter.data.sections ?? []; +// First section carries the routing-rule panel, second carries the steps. +const ruleSection = sections[0]; +const sequenceSection = sections[1]; +--- + +]+>/g, '')}> + ← ROUTE MAP + 01 / MODELS + field guide ↗ + + + +

{lede}

+ + +
+ { + cards.map((card) => ( +
+ {card.label.en} +

{card.title.en}

+

{card.copy.en}

+
+ )) + } +
+ +
+
+

{ruleSection.eyebrow.en}

+

+

+
+ {ruleSection.panelLabel.en} + {ruleSection.panelCode.en} +
+
+ +
+
+

{sequenceSection.eyebrow.en}

+

+

+
+ { + sequenceSection.steps.map((step, index) => ( +
+ {String(index + 1).padStart(2, '0')} +
+ {step.label.en} + {step.copy.en} +
+
+ )) + } +
+
+ + + diff --git a/src/pages/skills.astro b/src/pages/skills.astro new file mode 100644 index 0000000..a31fdf2 --- /dev/null +++ b/src/pages/skills.astro @@ -0,0 +1,69 @@ +--- +// /skills/ — chapter page. Migrated from skills/index.html in task 13. +// Identical URL (/skills/). The package-anatomy picker is an Astro island +// (SkillPackageExplorer) — the only JS the page ships. Copy lives in +// src/content/chapters/skills.json. + +import { getEntry } from 'astro:content'; +import ChapterLayout from '../layouts/ChapterLayout.astro'; +import ChapterHero from '../components/blocks/ChapterHero.astro'; +import SkillPackageExplorer from '../components/islands/SkillPackageExplorer.astro'; +import skillsStylesheet from '../../skills/styles.css?url'; + +const base = import.meta.env.BASE_URL; +const chapter = await getEntry('chapters', 'skills'); +const lede = chapter.data.lede.en; +const title = chapter.data.title.en; +const eyebrow = chapter.data.eyebrow.en; +const sections = chapter.data.sections ?? []; +const anatomySection = sections[0]; +const createSection = sections[1]; +--- + +]+>/g, '')}> + + ← ROUTE MAP + 03 / SKILLS + review desk ↗ + + + +

+ + +

+
+

{anatomySection.eyebrow.en}

+

+

{anatomySection.copy.en}

+

+ +
+ +
+
+

{createSection.eyebrow.en}

+

+

+
+ { + createSection.steps.map((step, index) => ( +
+ {String(index + 1).padStart(2, '0')} +
+ {step.label.en} + {step.copy.en} +
+
+ )) + } +
+
+ + + From 8388dd63fe723e7814a3e218541e54999ac7cde0 Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Sat, 5 Sep 2026 17:24:54 +0000 Subject: [PATCH 2/5] fix(skills): keep file-prefix and label joined by template literal MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prettier reformats JSX into one expression per line; splitting "{file.prefix}{file.label}" across two lines inserts a literal whitespace text node between them. Snapshot diff against .agents/snapshots/skills.txt showed the rendered HTML emitted "├── SKILL.md" (two spaces) where vanilla showed one. Joining the values into a single template expression keeps the rendered text byte-identical to the legacy source. --- src/components/islands/SkillPackageExplorer.astro | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/src/components/islands/SkillPackageExplorer.astro b/src/components/islands/SkillPackageExplorer.astro index c6ccb35..2018019 100644 --- a/src/components/islands/SkillPackageExplorer.astro +++ b/src/components/islands/SkillPackageExplorer.astro @@ -73,10 +73,7 @@ const packageFiles: PackageFile[] = [ role="tab" aria-selected={String(index === 0)} > - - {file.prefix} - {file.label} - + {`${file.prefix}${file.label}`} {file.caption} )) From c19e77bcac0b3e1543e510b0031fa7fdf7cb7ba7 Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Sat, 5 Sep 2026 17:41:38 +0000 Subject: [PATCH 3/5] fix(chapters): narrow optional section fields in page frontmatter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The chapters schema marks section.eyebrow / panelLabel / panelCode / steps / copy as optional, but pages /agents/, /models/, /skills/ consume them — index access without narrowing failed astro check with ts(18048). Same for SkillPackageExplorer: aria-selected was String(bool) which widened to plain string and failed ts(2322) against ButtonHTMLAttributes. Fix: guard each required field with a helper that throws a clear message on missing data, then read .en / .map from the narrowed value. Page rendering is unchanged — dist/ HTML for all four files is byte-identical before and after. No any / as any / ! / @ts-ignore. Schema and tsconfig untouched. --- .../islands/SkillPackageExplorer.astro | 2 +- src/pages/agents.astro | 37 ++++++++++++++++--- src/pages/models.astro | 35 +++++++++++++++--- src/pages/skills.astro | 32 ++++++++++++++-- 4 files changed, 91 insertions(+), 15 deletions(-) diff --git a/src/components/islands/SkillPackageExplorer.astro b/src/components/islands/SkillPackageExplorer.astro index 2018019..8552734 100644 --- a/src/components/islands/SkillPackageExplorer.astro +++ b/src/components/islands/SkillPackageExplorer.astro @@ -71,7 +71,7 @@ const packageFiles: PackageFile[] = [ class:list={[{ active: index === 0 }]} data-skill-file={file.id} role="tab" - aria-selected={String(index === 0)} + aria-selected={index === 0 ? 'true' : 'false'} > {`${file.prefix}${file.label}`} {file.caption} diff --git a/src/pages/agents.astro b/src/pages/agents.astro index 6caad73..00d207a 100644 --- a/src/pages/agents.astro +++ b/src/pages/agents.astro @@ -7,8 +7,22 @@ import { getEntry } from 'astro:content'; import ChapterLayout from '../layouts/ChapterLayout.astro'; import ChapterHero from '../components/blocks/ChapterHero.astro'; +// Required-field guard. The chapters schema marks section eyebrow / +// panelLabel / panelCode / steps / copy as optional because the schema +// does not know which page consumes which shape. These four pages do +// consume them — fail loudly here rather than rendering a blank section. +function requireField(value: T | undefined, name: string): T { + if (value === undefined) { + throw new Error(`agents chapter: missing required field "${name}"`); + } + return value; +} + const base = import.meta.env.BASE_URL; const chapter = await getEntry('chapters', 'agents'); +if (!chapter) { + throw new Error('agents chapter: missing collection entry'); +} const lede = chapter.data.lede.en; const title = chapter.data.title.en; const eyebrow = chapter.data.eyebrow.en; @@ -16,6 +30,19 @@ const cards = chapter.data.cards ?? []; const sections = chapter.data.sections ?? []; const treeSection = sections[0]; const handoffSection = sections[1]; +if (!treeSection) { + throw new Error('agents chapter: missing sections[0]'); +} +if (!handoffSection) { + throw new Error('agents chapter: missing sections[1]'); +} +// Narrow the section fields this page renders. Each `requireField` either +// returns a non-null value or throws — TS narrows from `T | undefined` to `T`. +const treeEyebrow = requireField(treeSection.eyebrow, 'sections[0].eyebrow'); +const treePanelLabel = requireField(treeSection.panelLabel, 'sections[0].panelLabel'); +const treePanelCode = requireField(treeSection.panelCode, 'sections[0].panelCode'); +const handoffEyebrow = requireField(handoffSection.eyebrow, 'sections[1].eyebrow'); +const handoffSteps = requireField(handoffSection.steps, 'sections[1].steps'); --- ]+>/g, '')}> @@ -30,12 +57,12 @@ const handoffSection = sections[1];
-

{treeSection.eyebrow.en}

+

{treeEyebrow.en}

- {treeSection.panelLabel.en} - {treeSection.panelCode.en} + {treePanelLabel.en} + {treePanelCode.en}
@@ -53,12 +80,12 @@ const handoffSection = sections[1];
-

{handoffSection.eyebrow.en}

+

{handoffEyebrow.en}

{ - handoffSection.steps.map((step, index) => ( + handoffSteps.map((step, index) => (
{String(index + 1).padStart(2, '0')}
diff --git a/src/pages/models.astro b/src/pages/models.astro index d910e47..041166f 100644 --- a/src/pages/models.astro +++ b/src/pages/models.astro @@ -8,8 +8,22 @@ import { getEntry } from 'astro:content'; import ChapterLayout from '../layouts/ChapterLayout.astro'; import ChapterHero from '../components/blocks/ChapterHero.astro'; +// Required-field guard. The chapters schema marks section eyebrow / +// panelLabel / panelCode / steps / copy as optional because the schema +// does not know which page consumes which shape. These four pages do +// consume them — fail loudly here rather than rendering a blank section. +function requireField(value: T | undefined, name: string): T { + if (value === undefined) { + throw new Error(`models chapter: missing required field "${name}"`); + } + return value; +} + const base = import.meta.env.BASE_URL; const chapter = await getEntry('chapters', 'models'); +if (!chapter) { + throw new Error('models chapter: missing collection entry'); +} const lede = chapter.data.lede.en; const title = chapter.data.title.en; const eyebrow = chapter.data.eyebrow.en; @@ -18,6 +32,17 @@ const sections = chapter.data.sections ?? []; // First section carries the routing-rule panel, second carries the steps. const ruleSection = sections[0]; const sequenceSection = sections[1]; +if (!ruleSection) { + throw new Error('models chapter: missing sections[0]'); +} +if (!sequenceSection) { + throw new Error('models chapter: missing sections[1]'); +} +const ruleEyebrow = requireField(ruleSection.eyebrow, 'sections[0].eyebrow'); +const rulePanelLabel = requireField(ruleSection.panelLabel, 'sections[0].panelLabel'); +const rulePanelCode = requireField(ruleSection.panelCode, 'sections[0].panelCode'); +const sequenceEyebrow = requireField(sequenceSection.eyebrow, 'sections[1].eyebrow'); +const sequenceSteps = requireField(sequenceSection.steps, 'sections[1].steps'); --- ]+>/g, '')}> @@ -44,23 +69,23 @@ const sequenceSection = sections[1];
-

{ruleSection.eyebrow.en}

+

{ruleEyebrow.en}

- {ruleSection.panelLabel.en} - {ruleSection.panelCode.en} + {rulePanelLabel.en} + {rulePanelCode.en}
-

{sequenceSection.eyebrow.en}

+

{sequenceEyebrow.en}

{ - sequenceSection.steps.map((step, index) => ( + sequenceSteps.map((step, index) => (
{String(index + 1).padStart(2, '0')}
diff --git a/src/pages/skills.astro b/src/pages/skills.astro index a31fdf2..9e9518b 100644 --- a/src/pages/skills.astro +++ b/src/pages/skills.astro @@ -10,14 +10,38 @@ import ChapterHero from '../components/blocks/ChapterHero.astro'; import SkillPackageExplorer from '../components/islands/SkillPackageExplorer.astro'; import skillsStylesheet from '../../skills/styles.css?url'; +// Required-field guard. The chapters schema marks section eyebrow / +// panelLabel / panelCode / steps / copy as optional because the schema +// does not know which page consumes which shape. These four pages do +// consume them — fail loudly here rather than rendering a blank section. +function requireField(value: T | undefined, name: string): T { + if (value === undefined) { + throw new Error(`skills chapter: missing required field "${name}"`); + } + return value; +} + const base = import.meta.env.BASE_URL; const chapter = await getEntry('chapters', 'skills'); +if (!chapter) { + throw new Error('skills chapter: missing collection entry'); +} const lede = chapter.data.lede.en; const title = chapter.data.title.en; const eyebrow = chapter.data.eyebrow.en; const sections = chapter.data.sections ?? []; const anatomySection = sections[0]; const createSection = sections[1]; +if (!anatomySection) { + throw new Error('skills chapter: missing sections[0]'); +} +if (!createSection) { + throw new Error('skills chapter: missing sections[1]'); +} +const anatomyEyebrow = requireField(anatomySection.eyebrow, 'sections[0].eyebrow'); +const anatomyCopy = requireField(anatomySection.copy, 'sections[0].copy'); +const createEyebrow = requireField(createSection.eyebrow, 'sections[1].eyebrow'); +const createSteps = requireField(createSection.steps, 'sections[1].steps'); --- ]+>/g, '')}> @@ -33,21 +57,21 @@ const createSection = sections[1];
-

{anatomySection.eyebrow.en}

+

{anatomyEyebrow.en}

-

{anatomySection.copy.en}

+

{anatomyCopy.en}

-

{createSection.eyebrow.en}

+

{createEyebrow.en}

{ - createSection.steps.map((step, index) => ( + createSteps.map((step, index) => (
{String(index + 1).padStart(2, '0')}
From 7f11b6e88efebb076d8b3c43db86ef1fc0faaf7b Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Sat, 5 Sep 2026 19:07:55 +0000 Subject: [PATCH 4/5] feat(type): self-host Manrope and DM Mono so they actually render MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `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 /