@brandon_m_behring/book-scaffold-astro 4.30.0 → 5.0.0

package/pages/tips.astro

@@ -11,18 +11,31 @@
  */
 import Base from '../layouts/Base.astro';
 import { normalizeBase } from '../src/lib/nav-href';
+import bookConfig from 'virtual:book-scaffold/book-config';
+import { selectBookArtifact } from '../src/lib/corpus';
+
+interface Props { bookId?: string; }
+const { bookId } = Astro.props;
 
 // v4.4.0 fix: use Vite's import.meta.glob with a project-root-relative
 // path. The previous `../../../src/data/tips.json` resolution failed when
 // the auto-injected route was processed from node_modules (or any context
 // other than a workspace symlink). `/src/data/...` is consumer-project-rooted
 // in Vite's resolver and works across all consumer build contexts.
-const tipsModules = import.meta.glob<{ default: Array<{ n: number; title: string; chapter: string; preview: string }> }>(
+type TipIndexEntry = { n: number; title: string; chapter: string; preview: string };
+const tipsModules = import.meta.glob<{ default: unknown }>(
   '/src/data/tips.json',
   { eager: true },
 );
 const tipsEntry = tipsModules['/src/data/tips.json'];
-const tips = tipsEntry?.default ?? [];
+const tips = tipsEntry
+  ? selectBookArtifact<TipIndexEntry[]>(
+      tipsEntry.default,
+      bookConfig.corpus,
+      bookId,
+      'src/data/tips.json',
+    )
+  : [];
 const loadError = tipsEntry
   ? null
   : 'src/data/tips.json not found — run `npx book-scaffold build-tips` to generate.';
@@ -30,7 +43,7 @@ const loadError = tipsEntry
 // #142: chapter back-links must prefix the deploy base.
 const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 ---
-<Base title="Tips" description="Numbered tips from this book, drawn from <Tip> instances in chapters.">
+<Base title="Tips" description="Numbered tips from this book, drawn from <Tip> instances in chapters." bookId={bookId}>
   <article class="prose">
     <h1>Tips</h1>
     {loadError && (
@@ -51,7 +64,7 @@ const baseUrl = normalizeBase(import.meta.env.BASE_URL);
               <p class="tips-index-preview">{tip.preview}</p>
             )}
             <p class="tips-index-meta">
-              From <a href={`${baseUrl}chapters/${tip.chapter}/`}>{tip.chapter}</a>
+              From <a href={`${baseUrl}chapters/${bookId ? `${bookId}/` : ''}${tip.chapter}/`}>{tip.chapter}</a>
             </p>
           </li>
         ))}

package/recipes/03-asset-pipelines.md

@@ -2,7 +2,12 @@
 
 **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`).
+**TL;DR**: Put PDFs in `figures/`, Jupyter notebooks in `notebooks/`, then run
+`npm run build:figures` and `npm run build:notebooks` explicitly. Output:
+`public/figures/*.svg` (PDF→SVG via `pdftocairo`) and
+`public/notebooks/*.html` (ipynb→HTML via `uv run jupyter nbconvert`). These
+optional system-tool pipelines are not part of `prebuild`; generated books run
+validation there instead.
 
 ## How each pipeline works
 
@@ -11,6 +16,7 @@
 - **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
+- **Theming**: canonical Warm–Tol / Okabe–Ito colors and neutral paints are mapped to theme-aware CSS variables; see [Recipe 24](24-figure-authoring-standard.md)
 - **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
 
@@ -58,8 +64,9 @@ Cloudflare Workers build containers don't have `pdftocairo` or `uv` installed. T
 
 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.
+   - Run `npm run build:figures` and `npm run build:notebooks` locally; commit
+     the generated outputs.
+   - CI serves the committed artifacts without needing either optional system tool.
    - 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.
@@ -71,12 +78,13 @@ post_transformers chose option 1 (see commit `f7fa75d`).
 - **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.
+- **Do not pre-blend semantic fills** (`warmblue!13`, for example). Export the canonical base color with a separate opacity so the SVG rewrite can preserve its role in dark mode. Recipe 24 has TikZ and matplotlib examples.
 
 ## 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
+- `package.json` `build:figures` / `build:notebooks` — explicit authoring commands
 - `.gitignore` — toggles whether artifacts are committed
 
 ## Reference implementation

package/recipes/09-validation.md

@@ -115,7 +115,7 @@ For pre-commit: add to `.pre-commit-config.yaml`:
 
 ## Preset / chaptersBase resolution (v4.7.0+, #75)
 
-The validator evaluates `astro.config.*` through Vite first. A resolved scaffold integration supplies the composed preset and `numberStyle`, so CLI tooling sees the same Style chain as the Astro build. The evaluated Astro `base` is read from that same config regardless of whether the scaffold integration is present; omission defaults to `/`. Without such an integration, the legacy preset chain remains: `--preset` → process `BOOK_PRESET`/`BOOK_PROFILE` → root `.env` → the literal value in `defineBookSchemas` → a warned `minimal` v4 compatibility fallback. Every selected value is checked against the five-preset enum; config-evaluation failures stop validation instead of silently using defaults.
+The validator evaluates `astro.config.*` through Vite first. A resolved scaffold integration supplies the composed preset and `numberStyle`, so CLI tooling sees the same Style chain as the Astro build. The evaluated Astro `base` is read from that same config regardless of whether the scaffold integration is present; omission defaults to `/`. Without such an integration, the preset chain remains: `--preset` → process `BOOK_PRESET`/`BOOK_PROFILE` → root `.env` → the literal value in `defineBookSchemas`. Every selected value is checked against the five-preset enum; an absent preset, an invalid value, or config-evaluation failure stops validation instead of silently selecting `minimal`.
 
 `chaptersBase` resolution still consults `BOOK_CHAPTERS_DIR`, content configuration, then `src/content/chapters`. The v4.5+ canonical form is:
 

package/recipes/15-defining-styles.md

@@ -46,7 +46,6 @@ defineStyle({
   extraIntegrations?: readonly AstroIntegration[];
   mdxComponentsModule?: string;
   markdown?: AstroUserConfig['markdown'];
-  deploy?: 'pages' | 'workers';      // RESERVED (#50, #180) — no runtime effect; wrangler shape is set at scaffold time by profile
   extra?: Record<string, unknown>;   // scoped consumer-side metadata
 });
 ```
@@ -122,7 +121,7 @@ Different fields have different merge semantics. Documented:
 
 | Field | Strategy |
 |---|---|
-| `name`, `preset`, `site`, `deploy`, `mdxComponentsModule` | Shallow override (last defined wins) |
+| `name`, `preset`, `site`, `mdxComponentsModule` | Shallow override (last defined wins) |
 | `releaseStatus` | Shallow override (last defined object replaces the whole earlier object); `false` suppresses an inherited banner |
 | `routes` | Per-route spread (each route key independently overridable) |
 | `routes.frontmatter` | Per-route spread; later value (boolean OR object) wholly replaces earlier |
@@ -158,10 +157,10 @@ defineBookConfig({ styles: [researchPortfolioStyle], ... });
 defineBookConfig({ styles: [BUILTIN_STYLES['research-portfolio']], ... });
 ```
 
-Each built-in style has a `name` matching its preset and a `preset` field. Its
-historical `deploy` value is reserved metadata only; it does not alter a
-generated or existing deployment. `create-book --preset` selects the initial
-`wrangler.toml`, after which the consumer owns that file (#180).
+Each built-in style has a `name` matching its preset and a `preset` field. In
+v5, a valid preset must resolve from a Style, corpus manifest, environment, or
+`.env`; there is no implicit `minimal` fallback. `create-book --preset` still
+selects the initial `wrangler.toml`, after which the consumer owns that file.
 
 ---
 
@@ -214,6 +213,7 @@ The v4.x release line is explicitly the iteration window for this API. Use it.
 ## See also
 
 - `MIGRATION-v3-to-v4.md` — step-by-step migration from v3 `preset:` shorthand
+- `MIGRATION-v4-to-v5.md` — explicit preset and removed `deploy` migration
 - `PACKAGE_DESIGN.md §4` — `defineBookConfig` API reference
 - `PACKAGE_DESIGN.md §4a` — `defineStyle` API reference
 - `recipes/12-where-to-file-issues.md` — the broader consumer-driven evolution loop this fits into

package/recipes/16-tikz-figures.md

@@ -4,7 +4,11 @@
 
 ## TL;DR
 
-Drop `figures/<topic>/diagram.tex` (standalone TikZ source). Run `npm run build:figures` (or it's wired into `prebuild`). Get `public/figures/<topic>/diagram.svg` ready to reference in MDX as `<Figure src="/figures/<topic>/diagram.svg" />`.
+Drop `figures/<topic>/diagram.tex` (standalone TikZ source). Run
+`npm run build:figures` explicitly; figure conversion is not wired into
+`prebuild` because TeX and Poppler are optional system tools. The command emits
+`public/figures/<topic>/diagram.svg`, ready to reference in MDX as
+`<Figure src="/figures/<topic>/diagram.svg" />`.
 
 ## The TikZ source
 
@@ -25,6 +29,13 @@ Use the `standalone` document class; configure for SVG via `tikz` option. Recomm
 
 The `border=2mm` adds a small margin around the figure so it doesn't crop right at the edge.
 
+For theme-aware color, define the canonical Warm–Tol or Okabe–Ito hex and use
+`fill opacity` rather than an xcolor pre-blend such as `warmblue!13`. The base
+color survives PDF export and `build-figures` can map it to `--fig-*` or
+`--series-*`; the pre-blended RGB cannot preserve its meaning. See
+[Recipe 24 — Figure authoring standard](24-figure-authoring-standard.md) for
+the palette, accessible description pattern, and dual-theme release gate.
+
 ## Discovery rule
 
 `build-figures` walks `figures/` (or `BOOK_FIGURES_PATH`) for both `.pdf` and `.tex` files. For each `.tex` source:
@@ -136,6 +147,6 @@ layout: wide      # widens --measure-main to 80ch; omit (or 'default') for the s
 
 ## See also
 
-- `recipes/06-figures.md` — overall figure pipeline + matplotlib/svg sources
+- `recipes/24-figure-authoring-standard.md` — palette, matplotlib/TikZ authoring, dark mode, and accessibility
 - `PACKAGE_DESIGN.md §7` — peer dependencies (lists `pdflatex` as optional system dep)
 - `PACKAGE_DESIGN.md §8` — `book-scaffold` CLI reference (build-figures subcommand)

package/recipes/20-anki-export.md

@@ -2,7 +2,7 @@
 
 **Profile**: any (most useful for `course-notes` and `research-portfolio`).
 
-**TL;DR**: The scaffold does **not** ship an `<AnkiCard>` component or an `extract-cards` CLI (see [PACKAGE_DESIGN.md §15a](../../PACKAGE_DESIGN.md#15a-deferred-scope-post-v4x) for why). This recipe shows how a consumer can roll their own — a small `<AnkiCard>` component plus a `scripts/extract-anki.mjs` extractor that walks the chapters collection and emits an Anki deck. ~120 lines of consumer-side code; no scaffold changes required.
+**TL;DR**: The scaffold does **not** ship an `<AnkiCard>` component or an `extract-cards` CLI (see [PACKAGE_DESIGN.md §15b](../../PACKAGE_DESIGN.md#15b-deferred-scope) for why). This recipe shows how a consumer can roll their own — a small `<AnkiCard>` component plus a `scripts/extract-anki.mjs` extractor that walks the chapters collection and emits an Anki deck. ~120 lines of consumer-side code; no scaffold changes required.
 
 If your book is the **third** independent consumer to want this, please open an issue at [book-scaffold-astro](https://github.com/brandon-behring/book-scaffold-astro/issues) — that's the signal we need to consider promoting this to scaffold-level surface.
 
@@ -141,34 +141,41 @@ The scaffold deliberately does **not** opine on the choice — the JSON is the c
 
 ## Step 4 — Per-book grouping (if needed)
 
-The example above emits one deck per book. If you have a multi-book corpus (per the DLAI Study Notes pattern), gate emission on a `book` discriminator in chapter frontmatter:
+The extractor above emits one ungrouped `cards.json` file. In first-class
+corpus mode, derive the book from the namespaced chapter path/id rather than
+repeating it in frontmatter:
 
 ```js
 const byBook = new Map();
 // ... inside the loop:
-const fm = parseFrontmatter(src);  // bring your own YAML parser
-const book = fm.book ?? 'main';
+const [book] = slug.split('/'); // <book>/<local-id>
 if (!byBook.has(book)) byBook.set(book, []);
 byBook.get(book).push({ ... });
 ```
 
-Then write one file per book key. Multi-book corpus routing is itself out of scope at v4.x ([deferred, see §15a](../../PACKAGE_DESIGN.md#15a-deferred-scope-post-v4x); tracked on #80) — if you need it, the same consumer-side pattern applies.
+Then write one file per registered book key. Recipe 21 documents the corpus
+manifest and namespaced-id contract; Anki extraction itself remains
+consumer-owned.
 
 ## Common gotchas
 
 - **Stable GUIDs**: if you omit `id`, the script falls back to `${slug}-${index}`. Adding/removing cards above an existing card will shift indices and break review history. **Always set explicit `id` props** for cards you want to survive content edits.
 - **Markdown in slots**: Anki accepts HTML; MDX renders the slot content to HTML before this extractor sees it, so most formatting carries through. KaTeX math is a special case — the extractor sees raw `$...$` LaTeX; either pre-render with KaTeX server-side before extraction, or use Anki's MathJax integration.
-- **Pagefind**: `<AnkiCard>` instances are indexed by Pagefront like any prose. If you don't want flashcard fronts in search results, wrap in `<aside data-pagefind-ignore>`.
+- **Pagefind**: `<AnkiCard>` instances are indexed by Pagefind like any prose. If you don't want flashcard fronts in search results, wrap in `<aside data-pagefind-ignore>`.
 - **Visual regression**: the component adds a styled block to every chapter that has cards. If you maintain visual baselines, regenerate them after first adoption.
 
 ## Why this isn't in the scaffold
 
-Per [PACKAGE_DESIGN.md §15a](../../PACKAGE_DESIGN.md#15a-deferred-scope-post-v4x): single consumer signal so far (DLAI), runtime dep concerns (`.apkg` is a SQLite-backed zip — needs an external builder), and the design space for per-book grouping is entangled with multi-book corpus routing (also deferred). When 2-3 consumers independently want this, it gets promoted.
+Per [PACKAGE_DESIGN.md §15b](../../PACKAGE_DESIGN.md#15b-deferred-scope):
+consumer signal remains limited and `.apkg` generation adds a non-trivial
+SQLite-backed archive dependency. Corpus grouping is now available, but those
+product/dependency questions still keep export outside the scaffold. When 2–3
+consumers independently want it, it can be reconsidered.
 
 ## Canonical files
 
 - This recipe (consumer pattern)
-- [PACKAGE_DESIGN.md §15a](../../PACKAGE_DESIGN.md#15a-deferred-scope-post-v4x) — deferral rationale
+- [PACKAGE_DESIGN.md §15b](../../PACKAGE_DESIGN.md#15b-deferred-scope) — deferral rationale
 
 ## Reference implementation
 

package/recipes/21-multi-guide-single-app.md

@@ -1,73 +1,322 @@
-# Recipe 21 — Multiple guides in one app (v4.20.0, #132)
+# Recipe 21 — One app, multiple books with `defineBookCorpus` (v5, #80)
 
-**Profile**: any (proven on research-portfolio).
+**Profile**: any, provided every book uses the same preset and Style chain.
 
-**TL;DR**: To host more than one guide/book in a single Astro app, keep ONE `chapters` collection rooted at `src/content/` and namespace every entry id by its guide folder via a `generateId` in the glob loader. The scaffold's existing rest-param route (`/chapters/[...slug]/`) then serves `/chapters/<guide>/<slug>/` for every guide with **no scaffold changes**. This is the blessed interim pattern until multibook (#80) ships first-class support.
+**TL;DR**: Define one ordered, branded corpus manifest and pass the same object
+to `defineBookConfig` and `defineBookSchemas`. Put chapters beneath
+`src/content/<book>/`. The scaffold derives book identity from that path,
+injects corpus and per-book routes, scopes navigation/search/generated data,
+and preserves the established `/chapters/<book>/<slug>/` URL.
 
-## The pattern
+## Define the corpus once
 
-Author each guide under its own folder:
+Keep the manifest in a Node-loadable module shared by both configuration
+entrypoints:
 
+```ts
+// src/book-corpus.ts
+import { defineBookCorpus } from '@brandon_m_behring/book-scaffold-astro';
+
+export const corpus = defineBookCorpus({
+  preset: 'research-portfolio',
+  books: [
+    {
+      id: 'evaluation',
+      title: 'Evaluation Engineering',
+      description: 'How to evaluate production LLM systems.',
+      apparatus: ['references', 'glossary'],
+    },
+    {
+      id: 'llm-app-engineering',
+      title: 'LLM Application Engineering',
+      description: 'Patterns for dependable LLM applications.',
+      // apparatus omitted: inherit the application-enabled apparatus set
+    },
+  ],
+});
+```
+
+```js
+// astro.config.mjs
+import {
+  defineBookConfig,
+  researchPortfolioStyle,
+} from '@brandon_m_behring/book-scaffold-astro';
+import { corpus } from './src/book-corpus.js';
+
+export default await defineBookConfig({
+  site: 'https://guides.example.com',
+  title: 'Engineering Guides',
+  styles: [researchPortfolioStyle],
+  routes: {
+    glossary: true,
+    practiceExam: true,
+  },
+  corpus,
+});
+```
+
+```ts
+// src/content.config.ts
+import { defineBookSchemas } from '@brandon_m_behring/book-scaffold-astro/schemas';
+import { corpus } from './book-corpus.js';
+
+export const { collections } = defineBookSchemas({ corpus });
 ```
+
+The manifest is an explicit preset source. If a composed Style also supplies a
+preset, it must match `corpus.preset`. Presets, Styles, Markdown plugins,
+integrations, `site`, Astro `base`, and `examDomains` are application-wide in
+v5; per-book variants are deliberately unsupported.
+
+`defineBookCorpus` validates and freezes the complete registry immediately:
+
+- `books` must be non-empty; its order is display/navigation order;
+- each `id` is unique and matches `[a-z0-9]+(?:-[a-z0-9]+)*`;
+- `assets`, `chapters`, `search`, `questions`, `glossary`, `frontmatter`,
+  `_astro`, `_og`, and `pagefind` are reserved; the three content names own
+  scaffold collection roots and cannot also identify chapter directories;
+- every title is non-blank; and
+- each `apparatus` list is duplicate-free and uses only known route names.
+
+## Author content by path
+
+Corpus chapters default to a shared `./src/content` base. Only registered book
+folders become chapters, so shared directories are not accidentally counted:
+
+```text
 src/content/
 ├── evaluation/
 │   ├── 01-why-evaluation.mdx
-│   └── ...
+│   └── design/02-metrics.mdx
 ├── llm-app-engineering/
-│   ├── 01-why-llm-app-engineering.mdx
-│   └── ...
-└── frontmatter/            ← shared, excluded below
+│   └── 01-architecture.mdx
+├── questions/
+│   ├── evaluation/q-measurement.mdx
+│   └── llm-app-engineering/q-retries.mdx
+├── glossary/
+│   ├── evaluation/calibration.mdx
+│   └── llm-app-engineering/idempotency.mdx
+└── frontmatter/                 # shared; never a chapter
+```
+
+Convergence collateral is book-owned too. Keep each registry and its tool
+timelines under the matching manifest id; two books may reuse pattern ids and
+tool filenames without sharing a dashboard:
+
+```text
+changelog/
+├── evaluation/
+│   ├── patterns.yaml
+│   └── tools/*.yaml
+└── llm-app-engineering/
+    ├── patterns.yaml
+    └── tools/*.yaml
 ```
 
-Point the collection at the shared base and namespace ids by guide:
+The legacy root paths `changelog/patterns.yaml` and `changelog/tools/*.yaml`
+remain the single-book convention. Corpus routes do not read those global
+collections.
+
+The loader emits `<book>/<local-id>` collection ids. The local id is the
+relative path below the book folder without `.md`/`.mdx`, unless frontmatter
+sets a string `slug`. For example:
+
+| Source | Entry id | Public chapter URL |
+|---|---|---|
+| `evaluation/01-intro.mdx` | `evaluation/01-intro` | `/chapters/evaluation/01-intro/` |
+| `evaluation/design/02-metrics.mdx` | `evaluation/design/02-metrics` | `/chapters/evaluation/design/02-metrics/` |
+| `evaluation/99-draft.mdx` with `slug: conclusion` | `evaluation/conclusion` | `/chapters/evaluation/conclusion/` |
+
+Do not add a required `book:` frontmatter field. The registered first path
+segment is authoritative. A legacy field may remain while migrating only when
+it agrees with the path; disagreement fails validation. The same local slug,
+label, question id, or glossary id may appear in different books, but duplicates
+inside one book still fail.
+
+Set `chaptersBase` only when the common content base lives elsewhere:
 
 ```ts
-// src/content.config.ts
-import { defineCollection } from 'astro:content';
-import { glob } from 'astro/loaders';
-import { researchPortfolioChapterSchema } from '@brandon_m_behring/book-scaffold-astro/schemas';
-
-const chapters = defineCollection({
-  loader: glob({
-    pattern: ['**/*.{md,mdx}', '!**/_*', '!frontmatter/**'],
-    base: './src/content',
-    generateId: ({ entry, data }) => {
-      const guide = entry.split('/')[0];
-      const slug =
-        (data && data.slug) || entry.replace(/\.[^.]+$/, '').split('/').pop();
-      return `${guide}/${slug}`; // → /chapters/<guide>/<slug>/
-    },
-  }),
-  schema: researchPortfolioChapterSchema,
-});
+defineBookSchemas({ corpus, chaptersBase: './guides/content' });
+```
 
-export const collections = { chapters };
+The registered book directories must remain direct children of that base.
+
+## Canonical routes
+
+Every generated href includes Astro's normalized deployment `base`. These
+patterns are shown without that prefix:
+
+| Surface | Route |
+|---|---|
+| Corpus landing | `/` |
+| Corpus chapter index | `/chapters/` |
+| Book landing | `/<book>/` |
+| Book chapter index | `/chapters/<book>/` |
+| Chapter | `/chapters/<book>/<slug>/` |
+| Corpus search | `/search/` and `/search/?book=<book>` |
+| Book apparatus | `/<book>/<route>/` |
+
+Draft chapters do not generate paths. Book and apparatus params come only from
+the manifest; arbitrary URL segments never become content selectors.
+
+Corpus mode owns `chapterRoute`, `bookField`, `apparatusRoute`, and
+`apparatusRoutes`, using `/chapters/:id/` and `/:book/:route/`. Do not set those
+legacy custom-routing fields in a corpus configuration. They remain available
+to single-book and consumer-owned v4-style routes. If a consumer filesystem
+page overrides an injected corpus page, it must preserve the same params,
+canonical URL, Pagefind metadata, and `base` handling.
+
+## Apparatus per book
+
+The closed public apparatus set is:
+
+```text
+references, print, convergence, tips, exercises, practice-exam,
+glossary, flashcards, answers
 ```
 
-The scaffold's auto-injected `pages/chapters/[...slug].astro` routes on `params: { slug: entry.id }` — a namespaced id rides through unchanged, so both guides render with zero route overrides.
+Application route defaults come from the preset and top-level `routes`
+overrides. Manifest values use public URL slugs (`practice-exam`), while the
+top-level route toggle remains camel-cased (`practiceExam`). For each book:
 
-## Gotcha 1 — the flat-slug footgun
+- omit `apparatus` to inherit the application-enabled subset;
+- set `apparatus: []` to expose none; or
+- list an explicit subset to expose only those routes.
 
-**Without** the `generateId`, Astro's glob loader keys entry ids off the frontmatter `slug` (or filename) and routes FLAT at `/chapters/<slug>/`. That silently requires slugs to be **globally unique across all guides** — two guides each having an `introduction` chapter is a route collision, surfaced as a confusing router warning rather than a clear error. The `generateId` namespacing makes slugs only need uniqueness *within* a guide, which is what authors expect.
+Naming a route that the application has disabled is a configuration error, not
+a dead link. Only books exposing a route receive its static path, and every
+apparatus renderer selects that book's questions, glossary entries, labels,
+references, tips, exercises, or convergence registry. Flashcard progress is
+persisted under a deployment-base and book-specific key, so repeated local
+term ids do not share or erase study state. `examDomains` remains one
+application-wide taxonomy in v5 even though question ids and pages are
+book-scoped.
 
-## Gotcha 2 — `validate` counts everything under the base
+## Search and links
 
-With `base: './src/content'`, `book-scaffold validate` walks the whole base — shared folders like `frontmatter/` are counted as "chapters" (e.g. `16 chapter(s)` for 13 + 2 real chapters + an authors page). The checks still run correctly per file; only the count is inflated. Excluding non-guide folders from the *loader* pattern does not affect the validator's walk. Guide-aware validation is part of the first-class multibook design (#80).
+One build creates one Pagefind index. Book pages are tagged with the current
+`book:<id>` filter; corpus landing content uses `surface:corpus`. `/search/`
+searches everything by default, accepts only registered `?book=<id>` values,
+and search opened from book chrome starts scoped to that book. Users can switch
+back to all books. Pagefind result URLs already include Astro `base`; do not
+rewrite them or build separate per-book indexes.
 
-## Gotcha 3 — the `/chapters/` index mixes guides
+Use `<BookLink>` for an explicit cross-book link. A manifest book resolves
+locally and an external `siblingBooks` key keeps its configured origin:
 
-The auto-injected `/chapters/` index lists every entry in the collection — i.e. all guides interleaved. If you want per-guide landing pages, add consumer-owned pages (e.g. `src/pages/evaluation/index.astro`) that `getCollection('chapters', (e) => e.id.startsWith('evaluation/'))`. A grouped-by-guide index is also on the #80 wishlist.
+```mdx
+<BookLink book="evaluation" to="chapters/metrics#calibration">
+  calibration metrics
+</BookLink>
+```
 
-## When to expect first-class support
+The local result is `/chapters/evaluation/metrics/#calibration` (plus Astro
+`base`). Other relative targets resolve below `/<book>/`. Empty, absolute,
+query-only, fragment-only, or traversal targets fail loudly. A key cannot be
+owned by both `corpus.books` and `siblingBooks`.
 
-This recipe is the interim, zero-scaffold-change path. Issue [#80 (multibook)](https://github.com/brandon-behring/book-scaffold-astro/issues/80) tracks a `books`/`guides` registry that would emit per-guide indexes, a guides landing, and guide-scoped `validate` (the original #15 is closed; #80 is the live v5.x tracker). It was deferred pending 2–3 independent consumers; `guides-ai-engineering` (#132) is the second — file your use case on #80 to add weight.
+## Generated data and `--book`
 
-## Canonical files
+Corpus outputs keep the existing `src/data/*.json` filenames but use a strict,
+versioned envelope:
+
+```json
+{
+  "schemaVersion": 1,
+  "books": {
+    "evaluation": {},
+    "llm-app-engineering": {}
+  }
+}
+```
+
+This applies to `labels.json`, `references.json`, `sources.json`, `tips.json`,
+and `exercises.json`. Payloads inside each book retain their established shape
+and deterministic ordering. Components select the current book before looking
+up a local key; there is no unscoped corpus alias.
+
+These content-derived commands accept `--book <id>` in corpus mode:
+
+```bash
+npx book-scaffold build-labels --book evaluation
+npx book-scaffold build-bib --book evaluation
+npx book-scaffold build-tips --book evaluation
+npx book-scaffold build-exercises --book evaluation
+npx book-scaffold validate --book evaluation
+```
 
-- `package/pages/chapters/[...slug].astro` — the rest-param route that makes namespaced ids "just work"
-- `package/scripts/walk-mdx.mjs` — `readChaptersBase` (how validate finds the base)
-- `package/recipes/12-where-to-file-issues.md` — multi-book corpus routing is a known scaffold-issue category
+Omit `--book` to process all books in manifest order. A selected producer run
+updates that key in an existing valid envelope and preserves the other
+registered keys; it rejects an existing malformed or manifest-mismatched
+envelope. A full run rewrites all keys. Unknown ids, repeated/missing selectors,
+and `--book` in a single-book project fail loudly. Figure and notebook
+conversion remain application-wide and do not take a book selector.
+
+Human diagnostics begin with `[book:<id>]`; explicitly named corpus totals use
+`[book:corpus]`. Identical local ids in two books are checked independently.
+
+### One bibliography and source manifest
+
+`bibliography.bib` (or `BOOK_BIB_PATH`) and `sources/manifest.yaml` remain
+root-level, corpus-wide authoring inputs in v5. `build-bib` parses each once and
+stores the result beneath every selected book key in `references.json` and
+`sources.json`. Renderers still select a book namespace before resolving a
+citation, so artifact access never becomes implicitly global.
+
+Per-book bibliography/source input files are not part of the v5 contract. A
+duplicate BibTeX key is therefore still an application-level authoring error.
+
+## Migrate the v4 Recipe 21 workaround
+
+The v4 recipe used a hand-written collection and `generateId`. Migrate it in
+six steps:
+
+1. Extract ordered book metadata into `defineBookCorpus`.
+2. Pass the same manifest to `defineBookConfig` and `defineBookSchemas`.
+3. Remove the hand-written chapter collection and custom `generateId`.
+4. Keep book folders under `src/content/`, or set one explicit shared
+   `chaptersBase`.
+5. Compare consumer-owned per-book index pages with the injected pages, then
+   remove duplicates.
+6. Run `build-labels`, `build-bib`, optional `build-tips`/`build-exercises`,
+   and `validate`; update scripts that read generated JSON to select from the
+   `books` envelope.
+
+Existing `/chapters/<book>/<slug>/` URLs do not change, so this migration needs
+no redirect layer. Remove legacy `book:` frontmatter when convenient; until
+then it must match the containing registered folder.
+
+## Single-book compatibility
+
+If a one-book application does not need corpus routes, leave corpus mode off.
+Its `src/content/chapters/` loader, `/chapters/<slug>/` and `/chapters/` routes,
+flat apparatus routes, and generated JSON shapes remain unchanged. `--book` is
+intentionally rejected. The separate v5 removals—an explicit preset and
+deletion of inert `deploy` configuration—are covered by
+[`MIGRATION-v4-to-v5.md`](../MIGRATION-v4-to-v5.md).
+
+## Verify
+
+```bash
+npx book-scaffold build-labels
+npx book-scaffold build-bib
+npx book-scaffold validate
+npm run build
+```
+
+Check `/`, `/chapters/`, both per-book landings and indexes, a chapter from each
+book, every enabled apparatus route, `/search/`, and `/search/?book=<id>`. Repeat
+under a non-root Astro `base` when the deployment uses one.
+
+## Canonical files
 
-## Reference implementation
+- `src/lib/corpus.ts` — manifest validation, identity, selectors, and artifact reader
+- `src/schemas-entry.ts` — manifest-scoped loaders and `<book>/<local-id>` ids
+- `src/integration.ts` + `pages/{book,chapters-book}.astro` — injected route ownership
+- `scripts/corpus-tooling.mjs` — `--book` selection and envelope validation
+- `MIGRATION-v4-to-v5.md` — release-wide v4 migration checklist
 
-`guides-ai-engineering` — two guides (Evaluation + LLM Application Engineering) on `@brandon_m_behring/book-scaffold-astro@4.14.2`; both `dist/chapters/evaluation/why-evaluation/index.html` and `dist/chapters/llm-app-engineering/why-llm-app-engineering/index.html` build from the scaffold's injected route.
+The original `guides-ai-engineering` two-guide layout is the compatibility
+fixture for this migration: its established chapter URLs are the reason the v5
+route remains `/chapters/<book>/<slug>/`.

package/recipes/22-responsive-nav-and-multibook-routing.md

@@ -1,4 +1,10 @@
-# Recipe 22 — Responsive navigation & multi-book routing (v4.26.0, #80)
+# Recipe 22 — Responsive navigation & custom routing (v4.26.0, #80)
+
+> **v5 corpus applications:** use
+> [Recipe 21](./21-multi-guide-single-app.md) and `defineBookCorpus`. Corpus
+> mode owns `chapterRoute`, `bookField`, `apparatusRoute`, and
+> `apparatusRoutes`; the custom fields below remain for single-book applications
+> and consumer-owned v4-style routes.
 
 The scaffold's navigation (left `Sidebar`, prev/next `ChapterNav`) is **book-aware**
 and **responsive**: it serves a single-book site unchanged, a multi-book consumer