@brandon_m_behring/book-scaffold-astro 3.0.0-alpha.0

package/recipes/03-asset-pipelines.md

@@ -0,0 +1,84 @@
+# Recipe 03 — Asset pipelines (figures + notebooks)
+
+**Profile**: any (build:figures and build:notebooks both graceful-skip when source dirs / tools are absent).
+
+**TL;DR**: Put PDFs in `figures/`, Jupyter notebooks in `notebooks/`. `npm run dev` / `npm run build` runs both pipelines via the `build:assets` prebuild hook. Output: `public/figures/*.svg` (PDF→SVG via `pdftocairo`) and `public/notebooks/*.html` (ipynb→HTML via `uv run jupyter nbconvert`).
+
+## How each pipeline works
+
+### Figures — `scripts/build-figures.mjs`
+
+- **Source**: `figures/` at scaffold root (override via `BOOK_FIGURES_PATH` env var; e.g. `BOOK_FIGURES_PATH=../shared/figures` to share with a LaTeX sibling)
+- **Output**: `public/figures/<same-subdir-structure>/<stem>.svg`
+- **Tool**: `pdftocairo` (poppler-utils) with `pdftoppm` fallback for malformed SVG
+- **Idempotency**: skips when SVG mtime >= PDF mtime
+- **Graceful skip**: if `pdftocairo` or `pdftoppm` not on PATH (Cloudflare build container), warns and exits 0 — committed SVGs under `public/figures/` are served as-is
+
+### Notebooks — `scripts/render-notebooks.mjs`
+
+- **Source**: `notebooks/*.ipynb` at scaffold root (override via `BOOK_NOTEBOOKS_PATH`)
+- **Output**: `public/notebooks/<stem>.html`
+- **Tool**: `uv run jupyter nbconvert --template=basic` (override the `uv` working dir via `BOOK_UV_CWD` if your venv lives elsewhere)
+- **Style scoping**: each rendered notebook wrapped in `<div class="notebook-frame">` to prevent nbconvert's embedded `<style>` from bleeding into site CSS
+- **Stub skipping**: notebooks under 1500 bytes (configurable via `NOTEBOOK_STUB_BYTES`) are skipped — useful for placeholder notebooks that haven't been authored yet
+- **Graceful skip**: if `uv` not on PATH, warns and exits 0
+
+## Use figures in chapter MDX
+
+After build, link to the SVG via `<Figure>`:
+
+```mdx
+import Figure from '../../components/Figure.astro';
+
+<Figure
+  src="/figures/intro/eigenvalues.svg"
+  caption="Eigenvalue structure of the example matrix."
+  id="intro-fig-eigenvalues"
+/>
+```
+
+`Figure` is a CORE component (recipe 04). The validator (recipe 09) checks that every `<Figure src="...">` exists on disk after build.
+
+## Link to notebook companions
+
+The `ChapterHeader` component (recipe 04) accepts a `notebook_path` frontmatter field that auto-links to the rendered HTML:
+
+```yaml
+---
+title: "Chapter 1"
+notebook_path: notebooks/chapter01.ipynb
+---
+```
+
+Renders a "View executable companion" link in the chapter header.
+
+## Cloudflare deploy quirk: committed artifacts
+
+Cloudflare Workers build containers don't have `pdftocairo` or `uv` installed. Two options for academic books deploying there:
+
+1. **Commit derived artifacts** (recommended for low-friction deploy):
+   - Edit `.gitignore`: remove the `public/figures/` and `public/notebooks/` lines.
+   - Run `npm run build:assets` locally; commit the generated outputs.
+   - CI's prebuild gracefully skips (tools missing), serves committed artifacts.
+   - Trade-off: ~3 MB of binary artifacts in git history.
+
+2. **Install poppler + uv in CI**: prepend `apt-get install -y poppler-utils && curl -LsSf https://astral.sh/uv/install.sh | sh && ...` to the build command. More setup; cleaner repo.
+
+post_transformers chose option 1 (see commit `f7fa75d`).
+
+## Common gotchas
+
+- **Notebooks should be output-free** for a clean rendered HTML — clear outputs before committing, or use `nbstripout` as a pre-commit hook. Cells with embedded outputs render those outputs in the HTML; this may or may not be what you want.
+- **Stub-size threshold** at 1500 bytes is empirical from post_transformers — adjust via `NOTEBOOK_STUB_BYTES` if your placeholder notebooks are larger.
+- **`pdftocairo` produces a tiny SVG** for some PDF inputs (vector layers ungrouped, etc.). The script auto-falls back to `pdftoppm -r 200 -png` at 200 DPI when SVG output is < 200 bytes.
+
+## Canonical files
+
+- `scripts/build-figures.mjs:23-32` — path resolution + env overrides
+- `scripts/render-notebooks.mjs:30-46` — same
+- `package.json` `prebuild` / `predev` / `build:assets` — orchestration
+- `.gitignore` — toggles whether artifacts are committed
+
+## Reference implementation
+
+[`~/Claude/post_transformers/guides/web/`](../) ships both pipelines pointed at `../figures/` and `../notebooks/` via env vars in its `package.json` scripts. The post_transformers repo commits its generated `public/figures/` and `public/notebooks/` (the Cloudflare workaround), see commit `f7fa75d`.

package/recipes/04-component-library.md

@@ -0,0 +1,118 @@
+# Recipe 04 — Component library
+
+**Profile**: components are profile-flavored. Tools family always available; academic family available when `BOOK_PROFILE=academic`. Utility components (Cite, XRef, Figure, …) work in any profile.
+
+**TL;DR**: Two callout families coexist (per Q3). Authors `import` what they need. The scaffold doesn't force migration of existing tools-profile books to academic, or vice versa.
+
+## Callout families
+
+### Tools family (8 components, default in `BOOK_PROFILE=tools`)
+
+`src/components/callouts/`:
+
+| Component | Use for | Visual |
+|---|---|---|
+| `SkillBox` | A skill the reader practices | green left-bar (tip) |
+| `CaseStudy` | Concrete worked example with date stamp | blue left-bar (info) |
+| `ConceptBox` | Term + crisp definition | plum left-bar (authority) |
+| `KeyIdea` | Bold short principle | gold left-bar (insight) |
+| `TryThis` | Reader exercise / activity | green left-bar (tip) |
+| `Recovery` | Anti-pattern + fix | rose left-bar (warning) |
+| `Convergence` | Multiple tools agree (with `tools` array) | gold left-bar |
+| `Divergence` | Tools disagree (with `axis` label) | gold dashed left-bar |
+
+### Academic family (10 components, default in `BOOK_PROFILE=academic`)
+
+`src/components/callouts/`:
+
+| Component | Use for |
+|---|---|
+| `NoteBox` | Aside / clarification |
+| `ExampleBox` | Worked example |
+| `DynConnect` | Cross-chapter conceptual link |
+| `InsightBox` | High-level "why this matters" |
+| `WarnBox` | Reader pitfall |
+| `CounterBox` | Counter-example / wrong-but-instructive |
+| `TipBox` | Practical advice |
+| `OpenQuestion` | Research gap |
+| `PaperBox` | Reference to a specific paper |
+| `ResultBox` | Theorem / proposition / lemma headline |
+
+For full theorem-like environments (proof scaffolding, numbering), use `<Theorem>` (below).
+
+## Theorem family (academic profile)
+
+`src/components/Theorem.astro` — unified component for nine LaTeX-style environments via the `type` prop:
+
+```mdx
+<Theorem type="theorem" id="thm:zoh-stability" label="ZOH stability">
+The bilinear discretization preserves stability iff $|\lambda \Delta t| < 1$.
+</Theorem>
+
+<Theorem type="proof">
+Direct algebra on the bilinear map.
+</Theorem>
+```
+
+Supported `type` values: `theorem`, `proposition`, `lemma`, `corollary`, `definition`, `example`, `exercise`, `remark`, `proof`. Each gets its own bar color and numbering counter.
+
+## Utility components (any profile)
+
+`src/components/`:
+
+| Component | Purpose | Example |
+|---|---|---|
+| `Cite` | Inline citation linked to `/references` | `<Cite key="gu2024mamba" page="3" />` |
+| `XRef` | Cross-reference to a labeled element | `<XRef id="thm:zoh-stability" />` |
+| `Figure` | Image + caption + id | `<Figure src="/figures/week04/eigenvalues.svg" caption="…" id="fig-eig" />` |
+| `MarginNote` | Right-margin annotation (Tufte-style) | `<MarginNote>side comment</MarginNote>` |
+| `Sidenote` | Auto-numbered marginalia | `<Sidenote>numbered note</Sidenote>` |
+| `WeekRef` | Jump-link to a week chapter | `<WeekRef week={4} />` |
+| `CodeRef` | GitHub-deep-link to file:line | `<CodeRef path="experiments/jax/foo.py" line={42} />` |
+| `CodeBlock` | Embed code-file range with syntax highlight | `<CodeBlock src="…" lines="10-30" />` |
+| `Tag` | Inline volatility/topic tag | `<Tag>stable-principle</Tag>` |
+| `StatusBadge` | Render frontmatter `status` value with color | `<StatusBadge status={frontmatter.status} />` |
+| `ChapterHeader` | Auto-rendered metadata block (week, part, status, companion links) | placed at top of each chapter automatically by Chapter.astro |
+
+## Conditional imports
+
+Authors are responsible for importing what they use. The scaffold doesn't auto-import; this keeps build output clean and makes intent explicit:
+
+```mdx
+---
+title: "Week 4 — Discretization"
+week: 4
+part: ssm-core
+status: implemented
+---
+import NoteBox from '../../components/callouts/NoteBox.astro';
+import Theorem from '../../components/Theorem.astro';
+import Cite from '../../components/Cite.astro';
+
+<NoteBox>This is the heart of S4.</NoteBox>
+
+<Theorem type="theorem">…</Theorem>
+
+The HiPPO theory <Cite key="gu2020hippo" /> shows that …
+```
+
+## Mixing families
+
+You can use tools-family callouts in an academic book or vice versa — nothing stops you. The "default family" per profile is only about what `examples/chapter-template-*.mdx` import for you. Drop in a `<SkillBox>` in an academic chapter when it fits.
+
+## Common gotchas
+
+- **Path depth**: chapters in `src/content/chapters/foo.mdx` import via `../../components/...`. If you nest chapters in a subfolder (`src/content/chapters/week04/intro.mdx`), use `../../../components/...`.
+- **Cite throws on unknown bibkey**: this is intentional (recipe 02). Run `npm run build:bib` after editing `bibliography.bib`.
+- **XRef silently renders `[?label]` for unknown ids**: the validator (recipe 09) catches these — don't rely on visual inspection.
+- **Theorem id collisions across chapters**: include a chapter prefix (e.g. `id="w4:thm:zoh"` not `id="thm:zoh"`).
+
+## Canonical files
+
+- `src/components/callouts/` — both families, 18 components total
+- `src/components/Theorem.astro` — unified theorem-like environment
+- `src/components/{Cite,XRef,Figure,…}.astro` — utility components (10 total)
+
+## Reference implementation
+
+[`~/Claude/post_transformers/guides/web/src/content/chapters/`](../../post_transformers/guides/web/src/content/chapters/) — 6 chapters exercising the academic family. [`~/Claude/book-template-astro/src/content/chapters/`](../../book-template-astro/src/content/chapters/) — 23 chapters exercising the tools family.

package/recipes/05-deploy-cloudflare.md

@@ -0,0 +1,74 @@
+# Recipe 05 — Deploy to Cloudflare Workers + Static Assets
+
+**Profile**: any (deploy mechanism is profile-agnostic).
+
+**TL;DR**: Cloudflare unified Pages → Workers + Static Assets (late 2025). For new static sites, use the Workers flow: `wrangler.toml` + `npx wrangler deploy`. Legacy Pages OAuth still works for existing projects; see "Legacy Pages alternative" below.
+
+## Setup (one-time, ~10 minutes in the dashboard)
+
+1. **Sign up** at cloudflare.com (free tier covers everything: 500 builds/month, unlimited bandwidth, unlimited sites).
+
+2. **Workers & Pages → Create → Connect to Git**:
+   - Authorize Cloudflare's GitHub app
+   - Grant repo access (scope to just your book repo)
+
+3. **Configure build**:
+   - **Project name**: hyphens only (e.g. `my-book-guide`) — becomes the subdomain
+   - **Production branch**: `main`
+   - **Build command**: `npm install && npm run build`
+     (or `cd guides/web && npm install && npm run build` for monorepo setups)
+   - **Deploy command**: `npx wrangler deploy`
+     (or `cd guides/web && npx wrangler deploy` for monorepo)
+
+4. **Customize `wrangler.toml`** at scaffold root (or your Astro project root):
+   - Edit `name = "your-book-name"` to match the dashboard project name
+   - `[assets] directory = "./dist/"` — should match Astro's build output
+
+5. **Save and Deploy.** First build takes ~5-7 minutes (mostly npm install). After: every push to main auto-deploys.
+
+URL: `https://<project-name>.<your-account>.workers.dev`.
+
+## The `cd` prefix for monorepo Astro projects
+
+When `wrangler.toml` lives in a subdirectory (e.g. `guides/web/wrangler.toml`), Cloudflare runs commands from the repo root by default. Wrangler can't find its config there → deploy fails with "Could not detect a directory containing static files".
+
+Fix: prefix both **build** and **deploy** commands with `cd <subdir> &&` so they execute in the same working directory as `wrangler.toml`. Build commands also need this since they produce the `./dist/` that wrangler.toml's `[assets]` reads.
+
+## Build-container quirks: poppler + uv missing
+
+Cloudflare's build container ships Node + npm but **not** `pdftocairo` (poppler-utils) or `uv` (Python venv manager). If your book uses the figure or notebook pipelines (recipe 03):
+
+- The scripts already graceful-skip on missing tools — build won't fail
+- **But** the public/figures/ and public/notebooks/ directories will be empty
+- Two solutions documented in recipe 03; the recommended one is committing the derived artifacts (remove their lines from .gitignore)
+
+## Legacy Pages alternative
+
+For accounts still on the Pages-only flow (or by explicit preference):
+
+- Use the `.github/workflows/deploy.yml` template that ships in v2.0 (legacy path)
+- Add `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` GitHub secrets
+- Token created at **My Profile → API Tokens → Create Custom Token** with permissions: `Account / Cloudflare Pages / Edit`
+- Push to main triggers the workflow
+
+This path doesn't use `wrangler.toml`. URL: `<project>.pages.dev`.
+
+## Common gotchas
+
+- **First deploy 404s** — Cloudflare takes ~30s after the deploy completes to propagate DNS. Refresh after a minute.
+- **Build succeeds but deploy fails with "Could not detect static files"** — `wrangler.toml` is in a subdir; the deploy command needs the `cd` prefix.
+- **Project name with underscores** breaks the subdomain. Always hyphens (e.g. `my-book` not `my_book`).
+- **Deploy command field doesn't exist in older dashboard UI** — Cloudflare migrated the dashboard; some older accounts see only "Build command" and skip Deploy. In that case, `npx wrangler deploy` runs automatically after the build command if `wrangler.toml` is present.
+
+## Custom domain
+
+See `recipes/10-custom-domain.md`.
+
+## Canonical files
+
+- `wrangler.toml` at scaffold root — Workers + Static Assets config
+- `.github/workflows/deploy.yml` (preserved from v1) — legacy Pages OAuth path
+
+## Reference implementation
+
+[`~/Claude/post_transformers/guides/web/wrangler.toml`](../../post_transformers/guides/web/wrangler.toml) — production-deployed to `post-transformers-guide.brandon-m-behring.workers.dev` since 2026-05-18.

package/recipes/06-mobile-first-layout.md

@@ -0,0 +1,73 @@
+# Recipe 06 — Mobile-first Tufte layout + sidebar
+
+**Profile**: any (layout is profile-agnostic; sidebar groups chapters differently per profile).
+
+**TL;DR**: Three-tier Tufte width (65/80/90ch) + 28/24/26ch sidenote column + left chapter-nav sidebar at ≥1024px. Mobile (<48rem) collapses to single column with inline sidenote asides; sidebar hides. All pure CSS, zero JS.
+
+## The three layers
+
+1. **Floating chrome** (top-right, `position: fixed`): theme toggle + search + tools-profile islands (`ToolFilter`, `VersionSelector`) when `BOOK_PROFILE !== 'academic'`.
+2. **Left sidebar** (`Sidebar.astro`): chapter nav grouped by part. Sticky to top, ≤100vh, independently scrollable. Hidden below 64rem (1024px).
+3. **Main content** (`.prose`): Tufte 2-column. Main text at `--measure-main`, sidenote column at `--measure-side`, both responsive to viewport tier.
+
+## Three-tier width strategy
+
+Stock Tufte fixes `--measure-main` at 65ch (~520px). On 1440px+ monitors with a 16rem sidebar, that leaves ~600px of empty page margin — readable but wasteful. The scaffold tiers the measure:
+
+| Tier | Trigger | `--measure-main` | `--measure-side` | Sidebar | Notes |
+|---|---|---|---|---|---|
+| 1 (default) | ≥48rem | 65ch | 28ch | hidden | Laptop-friendly typographic measure |
+| 2 (sidebar) | ≥64rem | 65ch | 28ch | 16rem | Sidebar appears; main column unchanged |
+| 3 (wide) | ≥90rem (1440px) | 80ch | 24ch | 18rem | Wider sidebar + main column |
+| 4 (ultrawide) | ≥120rem (1920px) | 90ch | 26ch | 18rem | At Tufte's 90ch upper limit of comfortable reading |
+
+The 90ch ceiling is firm — beyond that, line length crosses the eye's tracking limit and readers lose place. Don't push higher.
+
+**Mobile (<48rem)**: sidenotes reflow inline as colored asides via `@media (max-width: 48rem)` in `layout.css`. Sidebar is `display: none` below 64rem so phones get pure single-column content.
+
+## Verification methodology (Playwright)
+
+Width tuning was empirical, not theoretical. The breakpoint values came from comparing rendered chapters at four viewports (375 / 1280 / 1440 / 1920px) and measuring main-column utilization. Final ratios:
+
+- 1280px: 70% (no sidebar) — comfortable
+- 1440px: 89% (with sidebar) — was 62% pre-fix
+- 1920px: 72% (with sidebar) — was 47% pre-fix
+
+Re-tune with Playwright + `browser_take_screenshot` at the four viewports above whenever the design changes. Snapshots committed to `audits/` if a major retune.
+
+## Per-page sidebar toggle
+
+```astro
+<Base title="..." showSidebar={false}>
+  <!-- landing pages, splash screens, search results — no nav -->
+</Base>
+```
+
+Default is `showSidebar={true}`. The landing page (`src/pages/index.astro`) sets false because it's a one-page demo with no chapter context. Every chapter route inherits the default (true).
+
+## Customizing the sidebar
+
+`Sidebar.astro` reads `import.meta.env.BOOK_PROFILE` to decide grouping:
+
+- **Academic profile**: groups by string-enum `part` (`foundations`/`ssm-core`/`beyond-ssm`/`integration`/`synthesis`). Sorts by `week`. Renders `W01`, `W02` prefixes.
+- **Tools/minimal profile**: groups by numeric `part`. Sorts by `chapter`. Renders `Ch1`, `Ch2` prefixes.
+
+Edit `siteTitle` / `siteSubtitle` constants at top of `Sidebar.astro` for branding. For per-page overrides, lift to Astro.props.
+
+## Common gotchas
+
+- **Sidebar shows under chapter content at exactly 1023px**: the breakpoint is `min-width: 64rem` = 1024px. At 1023px sidebar is hidden, chapter is full width. This is intentional — the cutoff is the rough boundary between tablet and laptop.
+- **Sidebar overflow on long chapter titles**: `.sidebar-chapter-title` wraps; the 2.4em prefix grid column stays fixed. If you need shorter, edit `Sidebar.astro` line `grid-template-columns: 2.4em 1fr` and increase the prefix column.
+- **Forgetting `class="layout-main"` on the main wrapper**: causes `.prose` to fight the grid. `Base.astro` handles this; don't bypass the layout wrapper.
+- **Custom-width pages**: if you need a layout outside Tufte (e.g. a dashboard), use `<Base showSidebar={false}>` and write your own container CSS. Don't reach into `.prose`.
+
+## Canonical files
+
+- `src/styles/tokens.css` — three-tier `--measure-main` / `--measure-side` via `@media (min-width: 90rem|120rem)`
+- `src/styles/layout.css` — `.layout-with-sidebar` grid + `.prose` Tufte rules + mobile sidenote reflow
+- `src/components/Sidebar.astro` — profile-aware chapter nav
+- `src/layouts/Base.astro` — `showSidebar` prop wiring
+
+## Reference implementation
+
+[`~/Claude/post_transformers/guides/web/`](../../post_transformers/guides/web/) deployed at `post-transformers-guide.brandon-m-behring.workers.dev`. Three-tier breakpoint tuned via commits `d9d085b` (initial Tufte) → `8f3c6b1` (sidebar) → final ratios verified at four viewports.

package/recipes/07-chapter-shapes.md

@@ -0,0 +1,84 @@
+# Recipe 07 — Chapter shapes (skeleton patterns)
+
+**Profile**: profile-aware; pick the chapter shape that matches your book's pedagogy.
+
+**TL;DR**: Two opinionated chapter skeletons ship in `examples/`. Copy whichever matches your profile to `src/content/chapters/` and edit. Both are 1-file MDX templates with frontmatter pre-filled.
+
+## The two shapes
+
+### Academic (week-based)
+
+`examples/chapter-template-academic.mdx`:
+
+```
+1. Overview (½ page)        — what this week covers + why
+2. Theory                   — core math/definitions/theorems
+3. Examples (worked)        — concrete instances
+4. Reflections              — what the reader should walk away with
+5. Forward-map              — how this chapter connects to next week
+```
+
+Designed for textbook-style sequencing. Frontmatter required: `week`, `part` (enum), `status` (7-state).
+
+When to use: lecture-note format, curricular sequencing (W01 → W02 → … → W21), every chapter teaches a single body of math.
+
+### Tools (Koller-Friedman)
+
+`examples/chapter-template-tools.mdx`:
+
+```
+1. Representation           — what the artifact / concept LOOKS LIKE
+2. Operation                — what you DO with it
+3. Evolution                — what's converging / diverging across the field
+```
+
+Designed for comparative-practitioner books where multiple tools (Claude Code, Gemini CLI, Codex CLI, …) share an underlying capability that you're tracking over time.
+
+When to use: cross-tool reviews, "what does X look like in each tool", evolving-technology books with versioned content.
+
+Source: Koller & Friedman, *Probabilistic Graphical Models*, 2009 — chapter structure that separates static representation from operations on it from evolutionary dynamics. Adapted from PGM models to apply to tools.
+
+## Picking a shape
+
+| If your book is … | Use shape | Profile |
+|---|---|---|
+| A textbook with sequential dependency | Academic | `academic` |
+| Lecture notes (one topic per chapter) | Academic | `academic` |
+| Research synthesis (one paper or theorem per chapter) | Academic | `academic` |
+| A practitioner field-guide across multiple tools | Tools | `tools` |
+| A versioned tech survey with convergence tracking | Tools | `tools` |
+| A solo essay collection | either, lean Academic | `minimal` (uses tools schema) |
+
+## Hybrid books
+
+You're allowed to mix. The frontmatter Zod schema is what's enforced; the chapter shape is only a template. Build a chapter however you want as long as:
+
+1. Frontmatter passes its schema (`academicChapterSchema` or `toolsChapterSchema`).
+2. The rendered output fits the layout (don't break out of `.prose` without `.wide`).
+
+post_transformers uses academic for all 6 published chapters. book-template-astro uses tools for all 23. Mixing has not been tested in production — proceed with sense.
+
+## Customizing a shape
+
+Both templates are starting points. Common customizations:
+
+- **Add more sections**: append after Forward-map (academic) or after Evolution (tools). Use `<h2>` for top-level sections.
+- **Skip a section**: just delete it. Nothing in the scaffold requires Theory or Operation to exist.
+- **Add a sidebar of running examples**: use `<MarginNote>` for short notes, or `<aside class="wide">` for full-width sidebars.
+
+## Common gotchas
+
+- **Forgetting the import block**: each template imports the components it uses (NoteBox, Theorem, Cite for academic; SkillBox, KeyIdea, Convergence for tools). If you delete a section, also delete the unused import — astro warns but doesn't fail.
+- **Frontmatter `week` vs `chapter`**: academic uses `week`; tools uses `chapter`. The wrong key under the wrong profile is a Zod error caught at content-sync time.
+- **`status` field is required under academic**: pick one of `implemented` / `chapter_only` / `prose_only` / `code_only` / `reading_only` / `scaffolded` / `planned`. See `~/Claude/post_transformers/docs/STATUS.md` for the canonical state-machine.
+
+## Canonical files
+
+- `examples/chapter-template-academic.mdx` — week-based skeleton
+- `examples/chapter-template-tools.mdx` — Koller-Friedman skeleton
+- `pedagogy/kf-chapter-shape.md` — full KF pedagogy methodology
+
+## Reference implementation
+
+- Academic: [`~/Claude/post_transformers/guides/web/src/content/chapters/week04.mdx`](../../post_transformers/guides/web/src/content/chapters/week04.mdx) — exemplar
+- Tools: [`~/Claude/book-template-astro/src/content/chapters/05-context-as-currency.mdx`](../../book-template-astro/src/content/chapters/05-context-as-currency.mdx) — exemplar

package/recipes/08-decisions-ledger.md

@@ -0,0 +1,110 @@
+# Recipe 08 — Decisions ledger
+
+**Profile**: any (this recipe documents the scaffold-level decisions, not per-book).
+
+**TL;DR**: The scaffold encodes 15 design decisions from the v2.0 cross-book consolidation (2026-05-18). This recipe lists each decision, the reasoning, and when to deviate.
+
+The full master plan with discussion lives at `~/.claude/plans/i-want-to-investigate-recursive-yao.md`. The decisions ledger below is the operational summary.
+
+## Strategic decisions (Round 1)
+
+### D1. Canonical repo
+**Decision**: `book-scaffold-astro` is the evolved canonical template (not a new repo).
+**Reasoning**: One source of truth across multiple book projects.
+**Deviate when**: Never, while v2.0 is current. If you want a different scaffold, fork.
+
+### D2. Scope
+**Decision**: Full backport — KaTeX + asset pipelines + academic callouts. Opt-in via `BOOK_PROFILE`.
+**Reasoning**: Future academic books would otherwise have to re-invent the wheel.
+**Deviate when**: You want a strictly-minimal scaffold without the academic surface — pick `BOOK_PROFILE=tools` or `minimal`.
+
+## Cross-book decisions (Round 2)
+
+### D3 — Recipe shape (Q1)
+**Decision**: `BOOK_PROFILE` env var + `recipes/` markdown how-tos.
+**Reasoning**: Single repo, profile-aware integrations, human-readable docs.
+**Deviate when**: You need a `book.config.ts` file — document the migration in this ledger.
+
+### D4 — Citation workflow (Q2)
+**Decision**: Both BibTeX pipeline and YAML source manifest ship. `academic` defaults to BibTeX; `tools` defaults to YAML.
+**Deviate when**: You can override the profile default at any time — both are always available.
+
+### D5 — Callouts (Q3)
+**Decision**: Two callout families coexist. Authors `import` what they want.
+**Reasoning**: Don't force migration of book-template-astro's tools family or post_transformers' academic family.
+**Deviate when**: You want a single family — just don't import from the other.
+
+### D6 — Status taxonomy (Q4)
+**Decision**: Both schemas. `academic` → 7-state status; `tools` → volatility + T1-T4 source tiers.
+**Deviate when**: Your book needs neither — pick `minimal` and add your own frontmatter (schema is forgiving).
+
+### D7 — Chapter shapes (Q5)
+**Decision**: Two skeleton templates in `examples/`. Recipe 07 explains when to use which.
+**Deviate when**: Build your own shape — both templates are starting points, not laws.
+
+### D8 — Tufte width (Q6)
+**Decision**: Three-tier breakpoints: 65ch (default) → 80ch at 90rem → 90ch at 120rem.
+**Reasoning**: Empirically tuned via Playwright at 1280/1440/1920px — see recipe 06.
+**Deviate when**: Your book has unusually short or long content — edit `tokens.css` directly.
+
+### D9 — Deploy default (Q7)
+**Decision**: Cloudflare Workers + Static Assets via `wrangler.toml`.
+**Reasoning**: Cloudflare's official path post-Pages deprecation.
+**Deviate when**: Self-host / GitHub Pages / Vercel — `dist/` is a vanilla static bundle, swap the deploy mechanism. Legacy Pages OAuth flow still documented in recipe 05.
+
+### D10 — License (Q8)
+**Decision**: Dual — `LICENSE` (MIT, code) + `LICENSE-CONTENT` (CC-BY-4.0, prose).
+**Reasoning**: Matches post-transformers; reasonable defaults for tech books.
+**Deviate when**: You want different license — overwrite both files.
+
+## Distribution decisions (Round 3)
+
+### D11 — Migration path (Q9)
+**Decision**: Existing books (post-transformers, book-template-astro) freeze on current code. v2.0 is for new books only.
+**Reasoning**: Zero churn for existing books; low cost of bug-fix divergence.
+**Deviate when**: A third book project needs to consume scaffold patterns → trigger v3.0 (npm package).
+
+### D12 — AI authoring guides (Q10)
+**Decision**: Both `CLAUDE.md` (Claude Code auto-loads) + `AGENTS.md` (cross-tool) at scaffold root.
+**Deviate when**: Never — both stay. AGENTS.md can be a 3-line pointer to CLAUDE.md to avoid drift.
+
+### D13 — Recipe format (Q11)
+**Decision**: Terse pointers, 50-100 lines per recipe.
+**Reasoning**: Solo-author time budget; readers follow pointers into canonical code.
+**Deviate when**: A recipe genuinely needs more depth (the validator one is long because the design rationale matters).
+
+### D14 — Sample content (Q12)
+**Decision**: One profile-aware demo chapter (`week01-hello-world.mdx`) shipped by `create-book.sh`.
+**Reasoning**: Concrete starting point; reader deletes and replaces.
+**Deviate when**: Never — the demo is intentional even if the user deletes it immediately.
+
+## Polish decisions (Round 4)
+
+### D15 — Cross-project conventions (Q13)
+**Decision**: Scaffold's `CLAUDE.md` references the hub at `~/Claude/lever_of_archimedes/patterns/`.
+**Reasoning**: Hub stays canonical; scaffold inherits via reference.
+**Deviate when**: Your environment doesn't use the lever-of-archimedes hub — strip the inheritance block from CLAUDE.md.
+
+### D16 — Validation (Q14)
+**Decision**: `scripts/validate.mjs` ships at v2.0 (not deferred). ~150 lines. Wired into prebuild + recommended pre-commit.
+**Reasoning**: XRef/Figure/bibkey typos are common and silent — the validator is the only safety net.
+**Deviate when**: Never — disable individual checks via environment if needed (e.g. unset `BOOK_REPO_ROOT` to skip CodeRef path checks).
+
+### D17 — Custom domain (Q15)
+**Decision**: `recipes/10-custom-domain.md` ships at v2.0.
+**Deviate when**: Always include this recipe — custom domain is the most common post-deploy ask.
+
+## v3.0 (deferred)
+
+Not in v2.0:
+- npm package distribution (`@brandon-behring/book-scaffold-astro`) — trigger: third book OR external consumer
+- Profile-conditional subpath exports
+- Migration of post-transformers + book-template-astro to consume the package
+
+Until v3.0 triggers, accept that bug fixes don't auto-flow to existing books. Both books are currently low-churn.
+
+## How to use this ledger
+
+When a future change in the scaffold contradicts a decision above, update this ledger first. Don't change behavior silently — the ledger is the durable record of "why this is shaped like it is."
+
+Each decision has an issue-trail in `~/.claude/plans/i-want-to-investigate-recursive-yao.md` if you need full reasoning.

package/recipes/09-validation.md

@@ -0,0 +1,106 @@
+# Recipe 09 — Pre-flight validation
+
+**Profile**: any (Cite checks skip under non-academic).
+
+**TL;DR**: `npm run validate` runs `scripts/validate.mjs` against all chapter MDX files. Catches typo'd bibkeys / XRef ids / Figure paths / internal links that `astro build` would either miss or surface with poor context. Auto-runs as `prebuild`; recommend wiring into pre-commit too.
+
+## What gets checked
+
+| Check | Profile | Why this is needed (vs astro build alone) |
+|---|---|---|
+| `<Cite key="...">` resolves in `src/data/references.json` | academic | Cite.astro throws on the first unknown key. Validator surfaces ALL bad keys at once. |
+| `<XRef id="...">` resolves in `src/data/labels.json` | all | XRef.astro silently renders `[?label]` placeholders. Without this check, typos ship to readers. |
+| `<Figure src="/...">` file exists under `public/` | all | Figure.astro emits a broken-image icon for missing files; build doesn't fail. |
+| `[text](/internal-link)` resolves to known chapter slug or top-level route | all | Astro won't fail on dead internal links. Warning, not error (regex misses dynamic routes). |
+| `<CodeRef path="..." line={N} />` path exists + line in bounds | all, if `BOOK_REPO_ROOT` set | Catches stale line numbers after code refactors in the paired experiments/ repo. |
+
+## What is NOT checked (already covered elsewhere)
+
+- **Frontmatter Zod validation** — `astro build` syncs content collections first; Zod errors there.
+- **MDX renders** — `astro build` is the source of truth.
+- **KaTeX strict-mode** (academic profile) — rehype-katex throws on undefined macros during build.
+
+The validator's job is to fill the gaps `astro build` leaves, not duplicate it.
+
+## Wiring
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "validate": "node scripts/validate.mjs",
+    "prebuild": "npm run build:assets && npm run validate"
+  }
+}
+```
+
+For pre-commit: add to `.pre-commit-config.yaml`:
+
+```yaml
+- repo: local
+  hooks:
+    - id: book-validate
+      name: validate book content
+      entry: npm run validate --silent
+      language: system
+      pass_filenames: false
+      files: 'src/content/chapters/.*\.(md|mdx)$'
+```
+
+## Environment variables
+
+- `BOOK_PROFILE` — `academic` enables Cite-key checking; otherwise skipped.
+- `BOOK_REPO_ROOT` — absolute path to the paired code repo for CodeRef checks. Unset → skipped (the scaffold default; minimal/tools books rarely have a paired code repo).
+
+## Output
+
+Exit code = total error count. On success:
+
+```
+validate: ✓ 6 chapter(s) checked (profile=academic); no errors.
+```
+
+On failure, all issues listed at once with `file:line msg`:
+
+```
+validate: ✗ 17 error(s) in 6 chapter(s) (profile=academic):
+  week05.mdx:102  Unknown XRef id "w4:prop:zoh-stability" — not in labels.json
+  week11.mdx:37  Unknown XRef id "ch:week13" — not in labels.json
+  ...
+```
+
+Warnings (currently: internal-link unresolved) are printed to stderr but don't affect exit code.
+
+## Extending the validator
+
+The script is ~150 lines of regex-driven scanning. To add a check:
+
+1. Define a regex (`RE_FOO`).
+2. Loop `content.matchAll(RE_FOO)` per chapter.
+3. Push to `errors` (build-blocking) or `warnings` (informational).
+
+Examples of checks worth adding for specific books:
+
+- **Word-count budget** per chapter (catch runaway chapters early)
+- **Mandatory frontmatter fields** beyond the Zod schema (e.g. `last_verified` date older than 6 months → warning)
+- **Image alt text presence** (accessibility)
+- **No `TODO` strings in published chapters** (with frontmatter `status: implemented`)
+
+Keep the script regex-based; resist the urge to pull in MDX AST parsing. The script must stay <2 s for the pre-commit-hook use case.
+
+## Common gotchas
+
+- **Regex false negatives**: multi-line `<Cite\n  key="...">` won't match. Authors should keep component attributes on one line; the build catches the residual cases.
+- **`<Figure src>` with `BOOK_FIGURES_PATH` override**: the validator checks `public/figures/<...>` (post-build location), not the source `figures/` directory. Run `npm run build:figures` before `npm run validate` if assets are stale.
+- **`labels.json` empty**: every XRef fires an error. Until you have a labels-building step (Phase 2.6 in post-transformers, deferred at scaffold v2.0), avoid `<XRef>` in chapter content — use direct markdown links instead.
+
+## Canonical files
+
+- `scripts/validate.mjs` — the validator
+- `src/data/references.json` — emitted by `scripts/build-bib.mjs` (recipe 02)
+- `src/data/labels.json` — placeholder; populated by future labels-building step
+- `src/components/{Cite,XRef,Figure,CodeRef}.astro` — components whose contracts validate.mjs enforces
+
+## Reference implementation
+
+Tested against `~/Claude/post_transformers/guides/web/` (6 chapters, ~3000 lines of MDX): caught 17 unknown XRef ids that the empty labels.json had been hiding. Runtime: ~80 ms.