@brandon_m_behring/book-scaffold-astro 4.30.0 → 5.0.0

package/recipes/24-figure-authoring-standard.md

@@ -0,0 +1,241 @@
+# Recipe 24 — Figure authoring standard
+
+**Profile**: any profile that publishes diagrams, plots, or TikZ figures.
+
+**TL;DR**: Use `--fig-*` when a color means something and `--series-1` through
+`--series-8` when colors only distinguish data series. Author exported figures
+with the canonical hex plus a separate opacity; `build:figures` maps those
+colors to theme-aware CSS variables. Every figure needs a useful caption and
+accessible description, and color must never be the only way to read it.
+
+## 1. Choose the right color contract
+
+Semantic colors keep the same meaning across a book:
+
+| Token | Meaning | Light | Dark | Export hex |
+|---|---|---|---|---|
+| `--fig-blue` | default, lightweight, informational | `#3B6FA0` | `#7297BB` | `#3B6FA0` |
+| `--fig-green` | positive or successful outcome | `#4A7E3F` | `#7DA275` | `#4A7E3F` |
+| `--fig-rose` | caution or problem | `#C06858` | `#D29287` | `#C06858` |
+| `--fig-plum` | authority, control, or heaviest weight | `#8A4E82` | `#AB80A5` | `#8A4E82` |
+| `--fig-gold` | packaging, coordination, or convergence | `#9D7D34` | `#D2B575` | `#C09840` |
+| `--fig-crimson` | failure or severe problem | `#A03838` | `#BB7070` | `#A03838` |
+| `--fig-ink` | labels, essential outlines, axes | `#1A1A19` | `#E8E5DD` | `#1A1A19` or black |
+| `--fig-paper` | figure background | `#FDFCF9` | `#1A1816` | `#FDFCF9` or white |
+| `--fig-grid` | essential gridlines and secondary structure | `#8C8981` | `#746E67` | `#B5B3AA` or a mid-neutral |
+
+`--fig-gold` resolves to a slightly darker gold in the light theme so an
+essential stroke clears 3:1 against `--fig-paper`. The export rewrite still
+recognizes the canonical `#C09840` authoring value.
+
+Categorical plots use the stable Okabe–Ito order:
+
+| Ordinal | Token | Canonical color |
+|---:|---|---|
+| 1 | `--series-1` | orange `#E69F00` |
+| 2 | `--series-2` | sky blue `#56B4E9` |
+| 3 | `--series-3` | bluish green `#009E73` |
+| 4 | `--series-4` | yellow `#F0E442` |
+| 5 | `--series-5` | blue `#0072B2` |
+| 6 | `--series-6` | vermillion `#D55E00` |
+| 7 | `--series-7` | reddish purple `#CC79A7` |
+| 8 | `--series-8` | theme ink (canonical authoring color: black) |
+
+Series 1–7 use the same canonical value in light and dark; each already clears
+3:1 against the dark figure paper. Series 8 changes with `--fig-ink`.
+
+Assign series in that order and keep the ordinal attached to the same series
+when a chart or theme changes. Never use `--series-*` to mean good, bad,
+warning, or success; those meanings belong to `--fig-*`.
+
+After PDF export, canonical series-8 black is indistinguishable from labels and
+axes. The rewrite therefore maps it to structural ink; `--series-8` aliases the
+same `--fig-ink` value, so it still renders correctly in both themes. Use
+`var(--series-8)` directly in a CSS-native SVG if you need to override that
+ordinal independently.
+
+## 2. CSS-native SVG: the preferred hand-authored form
+
+Use variables directly. Pale fills should be computed from the current figure
+paper, while their solid borders carry the category:
+
+```svg
+<svg role="img" aria-labelledby="pipeline-title pipeline-desc"
+     viewBox="0 0 420 140" xmlns="http://www.w3.org/2000/svg">
+  <title id="pipeline-title">A three-stage publishing pipeline</title>
+  <desc id="pipeline-desc">
+    Draft flows to review and then publication. Review is the only caution stage.
+  </desc>
+  <style>
+    .label { fill: var(--fig-ink); font: 16px sans-serif; }
+    .edge { fill: none; stroke: var(--fig-ink); stroke-width: 2; }
+    .draft {
+      fill: color-mix(in srgb, var(--fig-blue) 14%, var(--fig-paper));
+      stroke: var(--fig-blue);
+    }
+    .review {
+      fill: color-mix(in srgb, var(--fig-rose) 14%, var(--fig-paper));
+      stroke: var(--fig-rose);
+    }
+    .published {
+      fill: color-mix(in srgb, var(--fig-green) 14%, var(--fig-paper));
+      stroke: var(--fig-green);
+    }
+    .node { stroke-width: 3; }
+  </style>
+  <!-- geometry omitted -->
+</svg>
+```
+
+When this is a local SVG rendered by `<Figure>`, the host page supplies the
+variables and its light/dark toggle changes the figure immediately. An SVG
+loaded from another origin cannot inherit host variables.
+
+For a categorical chart, use `stroke: var(--series-1)`, then `--series-2`, and
+so on. Give every line a second channel too: different dashes, markers, or a
+direct text label.
+
+## 3. TikZ and matplotlib exports
+
+PDF cannot carry CSS variables. `build:figures` therefore recognizes the exact
+Warm–Tol and Okabe–Ito authoring colors in the generated SVG and maps them back
+to variables. Unknown saturated colors stay exactly as authored.
+
+The important rule is **base color plus separate opacity**. Do not use a
+pre-blended low-chroma color such as `figblue!13`: after PDF export it is only
+an anonymous near-white RGB and can be mistaken for figure paper.
+
+TikZ:
+
+```latex
+\definecolor{figblue}{HTML}{3B6FA0}
+\definecolor{figrose}{HTML}{C06858}
+\definecolor{seriesone}{HTML}{E69F00}
+
+\node[
+  draw=figblue,
+  fill=figblue,
+  fill opacity=.14,
+  text opacity=1,
+  line width=1.2pt,
+] (draft) {Draft};
+\node[draw=figrose, fill=figrose, fill opacity=.14, text opacity=1] (review) {Review};
+\draw[seriesone, very thick, dashed] plot coordinates {(0,0) (1,2) (2,3)};
+```
+
+Matplotlib:
+
+```python
+import matplotlib.pyplot as plt
+
+FIG = {
+    "blue": "#3B6FA0",
+    "rose": "#C06858",
+    "green": "#4A7E3F",
+}
+SERIES = [
+    "#E69F00", "#56B4E9", "#009E73", "#F0E442",
+    "#0072B2", "#D55E00", "#CC79A7", "#000000",
+]
+
+fig, ax = plt.subplots()
+# Keep the canvas transparent: the host's --fig-paper must show through after
+# PDF → SVG conversion instead of baking a light-only rectangle into the plot.
+fig.patch.set_alpha(0)
+ax.set_facecolor("none")
+ax.fill_between(x, low, high, color=FIG["blue"], alpha=.14)
+ax.plot(x, mean, color=FIG["blue"], linewidth=2)
+ax.plot(x, baseline, color=SERIES[0], linestyle="--", marker="o", label="Baseline")
+fig.savefig(
+    "figures/results/summary.pdf",
+    format="pdf",
+    transparent=True,
+    bbox_inches="tight",
+)
+```
+
+Then run `npm run build:figures` to preserve the vector PDF→SVG path. Export a
+raster (`.png`) only when the source is true pixel data, such as a photograph
+or instrument raster. Lines, text, markers, and diagram geometry should remain
+vector PDF/SVG. Re-run the command after upgrading the scaffold so
+already-generated SVGs receive new mappings; the rewrite is idempotent.
+
+## 4. Accessible name and description
+
+Use `<Figure>` as the accessibility boundary:
+
+```mdx
+<Figure
+  src="/figures/results/summary.svg"
+  id="fig-results-summary"
+  caption="Review catches most defects before publication."
+  alt="Three-stage publishing pipeline"
+  desc="Draft flows right to review, then publication. The review node is marked as a caution stage, and the publication node is marked as a successful outcome."
+/>
+```
+
+- `caption` states the point the reader should take from the figure.
+- `alt` is a short accessible name, not a duplicate of every visible label.
+- `desc` gives reading order, relationships, trend, and any conclusion carried
+  by position, shape, line style, or color.
+- For a local pipeline SVG, `<Figure>` replaces stale `<title>`/`<desc>` nodes
+  with these props and wires `aria-labelledby` automatically.
+- Raster and remote images remain `<img>` elements, so give them complete alt
+  text and put any longer explanation in adjacent prose.
+
+Do not write “blue means success” as the only description. Name the category
+and the redundant cue: “the successful outcome is the green node with a check
+mark.”
+
+## 5. Contrast and color-vision rules
+
+Okabe–Ito is color-vision-deficiency-friendly; that does not make every hue a
+high-contrast thin line on light paper. In particular, orange, sky blue,
+yellow, and reddish purple need redundant encoding.
+
+- Never encode a distinction by color alone. Add marker shape, dash pattern,
+  direct labels, texture, or position.
+- Use `--fig-ink` for axes, text, arrowheads, and essential outlines.
+- Give pale semantic areas a solid `--fig-*` border. The semantic strokes and
+  `--fig-grid` clear WCAG's 3:1 non-text contrast threshold in both themes.
+- Outline small categorical marks with `--fig-ink`; use thicker/dashed lines
+  and markers for categorical series that do not clear 3:1 by color alone.
+- Do not reorder `--series-*` in dark mode. `--series-8` follows theme ink so
+  the neutral series remains visible rather than staying literal black.
+
+## 6. Dual-theme release gate
+
+Before publishing a new figure:
+
+1. Run `npm run build:figures` and confirm the SVG contains one
+   `data-diagram-map` style block.
+2. Render it through `<Figure>` with explicit light and dark page themes.
+3. Open the standalone SVG with both OS color schemes; its embedded defaults
+   should also switch.
+4. Check labels, axes, arrowheads, boundaries, and all series at the smallest
+   published size.
+5. Inspect a grayscale or common CVD simulation and verify that markers,
+   dashes, labels, or shapes preserve every distinction.
+6. Confirm the caption and screen-reader description communicate the takeaway
+   without relying on color names.
+
+If automatic recoloring is genuinely wrong for a special TikZ figure, add a
+`%! no-theme` line to its `.tex` source and supply a fully authored light/dark
+solution yourself. That escape hatch opts out of both palette and neutral
+mapping.
+
+## Canonical files
+
+- `src/lib/figure-palette.mjs` — sole palette manifest + generated CSS/theme renderers
+- `styles/tokens.css` — public `--fig-*`, `--series-*`, and compatibility tokens
+- `src/lib/figure.mjs` — exact palette recognition and SVG theme injection
+- `scripts/sync-figure-tokens.mjs` — checks or refreshes the generated token block
+- `scripts/build-figures.mjs` — PDF/TikZ conversion pipeline
+- `components/Figure.astro` — inlining plus accessible `<title>`/`<desc>`
+- `tests/figure-palette.test.mjs` — token, mapping, theme, and contrast contract
+
+## See also
+
+- [Recipe 03 — Asset pipelines](03-asset-pipelines.md)
+- [Recipe 04 — Component library](04-component-library.md)
+- [Recipe 16 — TikZ figures](16-tikz-figures.md)

package/recipes/README.md

@@ -26,9 +26,10 @@ Terse pointers into canonical code for the most common book-authoring workflows.
 | 18 | [Chapter route ownership](18-chapter-route-ownership.md) | any | When to override the auto-injected `/chapters/[...slug]/` route |
 | 19 | [Prevalidate hook](19-prevalidate-hook.md) | any | Wire `prevalidate` to run `build:bib` + `build:labels` before `validate` |
 | 20 | [Anki deck export (consumer-side)](20-anki-export.md) | any (esp. course-notes, research-portfolio) | Roll-your-own `<AnkiCard>` + extractor; scaffold deliberately doesn't ship this |
-| 21 | [Multiple guides in one app](21-multi-guide-single-app.md) | any | `generateId` namespacing over one collection; flat-slug footgun; interim until multibook (#80) |
-| 22 | [Responsive navigation and multi-book routing](22-responsive-nav-and-multibook-routing.md) | any | Mobile/desktop nav, base-aware route ownership, and the interim multi-book routing contract |
+| 21 | [Multiple books in one app](21-multi-guide-single-app.md) | any | First-class `defineBookCorpus`: routes, scoped data/search, `--book`, and v4 migration |
+| 22 | [Responsive navigation and custom routing](22-responsive-nav-and-multibook-routing.md) | any | Mobile/desktop nav and the v4-compatible consumer-owned route-token API |
 | 23 | [Interactive demo substrate](23-interactive-demo-substrate.md) | any | Opt-in Preact shell, slider, stat cards, theme colors, a11y, and reduced motion |
+| 24 | [Figure authoring standard](24-figure-authoring-standard.md) | any | Warm–Tol semantics, Okabe–Ito series, dual-theme exports, contrast, and accessible descriptions |
 
 ## How to read recipes
 

package/scripts/build-bib.mjs

@@ -40,6 +40,8 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readEnvFile } from './read-env.mjs';
+import { loadResolvedBookConfig } from './resolve-book-config.mjs';
+import { mergeCorpusArtifact, resolveBookSelection } from './corpus-tooling.mjs';
 
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold build-bib
@@ -54,6 +56,7 @@ Env:
                      .env; default: ./bibliography.bib).
 
 Options:
+  --book <id>        In corpus mode, rebuild only one registered book.
   --help, -h         Print this message and exit (non-mutating).
 `;
 
@@ -77,8 +80,13 @@ const BIB_PATH = configuredBibPath
 const OUT_PATH = resolve(PROJECT_ROOT, 'src/data/references.json');
 const SOURCES_PATH = resolve(PROJECT_ROOT, 'sources/manifest.yaml');
 const SOURCES_OUT = resolve(PROJECT_ROOT, 'src/data/sources.json');
+let DIAGNOSTIC_SCOPE = null;
 
-async function buildReferences() {
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+async function buildReferences(selection) {
   // Graceful skip when the .bib file is absent (minimal/tools profile, or
   // an academic book that hasn't authored citations yet). Emits an empty
   // references.json so consumers can still `import refs from '...'`.
@@ -87,15 +95,10 @@ async function buildReferences() {
     bibText = await readFile(BIB_PATH, 'utf8');
   } catch (err) {
     if (err.code === 'ENOENT') {
-      console.log(
-        `build-bib: ${BIB_PATH.replace(PROJECT_ROOT + '/', '')} not found — ` +
-          `emitting empty references.json (no citations to process).`,
-      );
-      await mkdir(dirname(OUT_PATH), { recursive: true });
-      await writeFile(OUT_PATH, '{}\n', 'utf8');
-      return;
+      bibText = null;
+    } else {
+      throw err;
     }
-    throw err;
   }
   // v4.0.0 (closes #54): strip `%`-comment lines before passing to citation-js.
   // The plugin-bibtex lexer doesn't honor BibTeX's %-line-comment semantics —
@@ -107,13 +110,14 @@ async function buildReferences() {
   // BibTeX's real comment grammar is "% at the start of a line (after optional
   // whitespace) to end of line". Mid-line `%` (e.g., `note = {50% confidence}`)
   // is NOT a comment and is preserved.
-  const sanitizedBib = bibText
-    .split(/\r?\n/)
-    .map((line) => (line.trimStart().startsWith('%') ? '' : line))
-    .join('\n');
-
-  const cite = new Cite(sanitizedBib);
-  const data = cite.data;
+  const data = bibText === null
+    ? []
+    : new Cite(
+        bibText
+          .split(/\r?\n/)
+          .map((line) => (line.trimStart().startsWith('%') ? '' : line))
+          .join('\n'),
+      ).data;
 
   // Detect duplicates the way biber would (citation-js silently
   // overwrites the earlier entry, which is the opposite of what we want).
@@ -124,19 +128,53 @@ async function buildReferences() {
     seen.add(entry.id);
   }
   if (dupes.length > 0) {
-    console.error(`build-bib: ${dupes.length} duplicate bibkeys:`);
-    for (const id of dupes) console.error(`  - ${id}`);
+    const prefix = selection.corpus ? '[book:corpus] ' : '';
+    console.error(`${prefix}build-bib: ${dupes.length} duplicate bibkeys:`);
+    for (const id of dupes) console.error(`${prefix}build-bib:   - ${id}`);
     process.exit(1);
   }
 
   const byKey = Object.fromEntries(data.map((entry) => [entry.id, entry]));
 
+  if (selection.corpus) {
+    DIAGNOSTIC_SCOPE = 'corpus';
+  }
+  const output = selection.corpus
+    ? await mergeCorpusArtifact({
+        path: OUT_PATH,
+        corpus: selection.corpus,
+        requestedBook: selection.requestedBook,
+        values: new Map(selection.books.map((book) => [book.id, byKey])),
+        emptyValue: () => ({}),
+        artifact: 'src/data/references.json',
+        validateValue: isRecord,
+      })
+    : byKey;
   await mkdir(dirname(OUT_PATH), { recursive: true });
-  await writeFile(OUT_PATH, JSON.stringify(byKey, null, 2) + '\n', 'utf8');
+  await writeFile(OUT_PATH, JSON.stringify(output, null, 2) + '\n', 'utf8');
 
-  console.log(
-    `build-bib: ${data.length} entries -> ${OUT_PATH.replace(PROJECT_ROOT + '/', '')}`,
-  );
+  if (selection.corpus) {
+    for (const book of selection.books) {
+      console.log(
+        `[book:${book.id}] build-bib: ${data.length} entries -> ` +
+          OUT_PATH.replace(PROJECT_ROOT + '/', ''),
+      );
+    }
+    console.log(
+      `[book:corpus] build-bib: ${data.length * selection.books.length} namespaced entries ` +
+        `across ${selection.books.length} book${selection.books.length === 1 ? '' : 's'} -> ` +
+        OUT_PATH.replace(PROJECT_ROOT + '/', ''),
+    );
+  } else if (bibText === null) {
+    console.log(
+      `build-bib: ${BIB_PATH.replace(PROJECT_ROOT + '/', '')} not found — ` +
+        `emitting empty references.json (no citations to process).`,
+    );
+  } else {
+    console.log(
+      `build-bib: ${data.length} entries -> ${OUT_PATH.replace(PROJECT_ROOT + '/', '')}`,
+    );
+  }
 }
 
 // v4.10.0 (closes #85): tools-profile books keep their sources in
@@ -147,17 +185,24 @@ async function buildReferences() {
 // references.json. Absent manifest -> no file written (academic/minimal books
 // degrade to empty, exactly like a missing .bib). YAML is lazy-imported so the
 // --help / no-manifest paths stay dependency-free.
-async function buildSources() {
+async function buildSources(selection) {
   let yamlText;
   try {
     yamlText = await readFile(SOURCES_PATH, 'utf8');
   } catch (err) {
-    if (err.code === 'ENOENT') return; // no manifest — nothing to emit
-    throw err;
+    if (err.code === 'ENOENT') {
+      // A corpus artifact must be a complete, deterministic envelope. Clear
+      // stale source data when the shared manifest disappears; legacy
+      // single-book mode retains its historical no-file/no-write behavior.
+      if (!selection.corpus) return;
+      yamlText = null;
+    } else {
+      throw err;
+    }
   }
 
   const { parse } = await import('yaml');
-  const parsed = parse(yamlText);
+  const parsed = yamlText === null ? null : parse(yamlText);
   // The manifest is a YAML array of source objects. Keep only well-formed
   // entries (a string `id` is the citation key + the /references anchor target).
   // A blank or comments-only manifest parses to null/undefined/[].
@@ -165,21 +210,54 @@ async function buildSources() {
     ? parsed.filter((s) => s && typeof s.id === 'string')
     : [];
 
+  const output = selection.corpus
+    ? await mergeCorpusArtifact({
+        path: SOURCES_OUT,
+        corpus: selection.corpus,
+        requestedBook: selection.requestedBook,
+        values: new Map(selection.books.map((book) => [book.id, sources])),
+        emptyValue: () => [],
+        artifact: 'src/data/sources.json',
+        validateValue: Array.isArray,
+      })
+    : sources;
   await mkdir(dirname(SOURCES_OUT), { recursive: true });
-  await writeFile(SOURCES_OUT, JSON.stringify(sources, null, 2) + '\n', 'utf8');
-  console.log(
-    `build-bib: ${sources.length} source${sources.length === 1 ? '' : 's'} -> ` +
-      `${SOURCES_OUT.replace(PROJECT_ROOT + '/', '')}`,
-  );
+  await writeFile(SOURCES_OUT, JSON.stringify(output, null, 2) + '\n', 'utf8');
+  if (selection.corpus) {
+    for (const book of selection.books) {
+      console.log(
+        `[book:${book.id}] build-bib: ${sources.length} ` +
+          `source${sources.length === 1 ? '' : 's'} -> ` +
+          SOURCES_OUT.replace(PROJECT_ROOT + '/', ''),
+      );
+    }
+    console.log(
+      `[book:corpus] build-bib: ${sources.length * selection.books.length} namespaced ` +
+        `source${sources.length * selection.books.length === 1 ? '' : 's'} across ` +
+        `${selection.books.length} book${selection.books.length === 1 ? '' : 's'} -> ` +
+        SOURCES_OUT.replace(PROJECT_ROOT + '/', ''),
+    );
+  } else {
+    console.log(
+      `build-bib: ${sources.length} source${sources.length === 1 ? '' : 's'} -> ` +
+        `${SOURCES_OUT.replace(PROJECT_ROOT + '/', '')}`,
+    );
+  }
 }
 
 async function main() {
-  await buildReferences();
-  await buildSources();
+  const toolingConfig = await loadResolvedBookConfig(PROJECT_ROOT);
+  if (toolingConfig.corpus) DIAGNOSTIC_SCOPE = 'corpus';
+  const selection = resolveBookSelection(toolingConfig, process.argv.slice(2), 'build-bib');
+  await buildReferences(selection);
+  await buildSources(selection);
 }
 
 main().catch((err) => {
-  console.error(`build-bib: failed`);
-  console.error(err);
+  const message = String(err?.message ?? err);
+  const prefix = DIAGNOSTIC_SCOPE ? `[book:${DIAGNOSTIC_SCOPE}] ` : '';
+  console.error(
+    message.startsWith('[book:') ? message : `${prefix}build-bib: failed: ${message}`,
+  );
   process.exit(1);
 });

package/scripts/build-exercises.mjs

@@ -24,6 +24,13 @@
 import { writeFile, mkdir, readFile } from 'node:fs/promises';
 import { resolve, dirname, basename } from 'node:path';
 import { walkMdx, readChaptersBase } from './walk-mdx.mjs';
+import { loadResolvedBookConfig } from './resolve-book-config.mjs';
+import {
+  assertLegacyBookMatches,
+  frontmatterSlug,
+  mergeCorpusArtifact,
+  resolveBookSelection,
+} from './corpus-tooling.mjs';
 
 const USAGE = `Usage: book-scaffold build-exercises
 
@@ -36,6 +43,7 @@ Env:
   BOOK_EXERCISES_OUT       Override output path (default: src/data/exercises.json).
 
 Options:
+  --book <id>              In corpus mode, rebuild only one registered book.
   --help, -h               Print this message and exit (non-mutating).
 `;
 
@@ -45,8 +53,8 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
 }
 
 const CWD = process.cwd();
-const CHAPTERS_DIR = await readChaptersBase(CWD);
 const OUTPUT_PATH = process.env.BOOK_EXERCISES_OUT ?? 'src/data/exercises.json';
+let DIAGNOSTIC_SCOPE = null;
 
 /**
  * Extract <Exercise id="..."> tags and their body content from MDX.
@@ -85,39 +93,108 @@ function extractExercises(source) {
 }
 
 async function main() {
-  const byChapter = {};
-  let totalExercises = 0;
-  let chaptersWithExercises = 0;
+  const toolingConfig = await loadResolvedBookConfig(CWD);
+  if (toolingConfig.corpus) DIAGNOSTIC_SCOPE = 'corpus';
+  const selection = resolveBookSelection(
+    toolingConfig,
+    process.argv.slice(2),
+    'build-exercises',
+  );
+  DIAGNOSTIC_SCOPE = selection.corpus ? 'corpus' : null;
+  const chaptersRoot = await readChaptersBase(CWD, { corpus: selection.corpus });
+  const runs = selection.corpus
+    ? selection.books.map((book) => ({ book, dir: resolve(chaptersRoot, book.id) }))
+    : [{ book: null, dir: chaptersRoot }];
+  const values = new Map();
+  let corpusExercises = 0;
+  let corpusChapters = 0;
+
+  for (const run of runs) {
+    const byChapter = {};
+    let totalExercises = 0;
+    let chaptersWithExercises = 0;
 
-  for await (const rel of walkMdx(CHAPTERS_DIR)) {
-    const chapterPath = resolve(CHAPTERS_DIR, rel);
-    const chapterSlug = basename(rel).replace(/\.mdx?$/, '');
-    let source;
-    try {
-      source = await readFile(chapterPath, 'utf8');
-    } catch {
-      continue;
+    for await (const rel of walkMdx(run.dir)) {
+      const chapterPath = resolve(run.dir, rel);
+      let source;
+      try {
+        source = await readFile(chapterPath, 'utf8');
+      } catch {
+        continue;
+      }
+      if (run.book) {
+        assertLegacyBookMatches(
+          source,
+          run.book,
+          `[book:${run.book.id}] ${chapterPath.replace(`${CWD}/`, '')}`,
+        );
+      }
+      const fileLabel = run.book
+        ? `[book:${run.book.id}] ${chapterPath.replace(`${CWD}/`, '')}`
+        : chapterPath.replace(`${CWD}/`, '');
+      const chapterSlug = run.book
+        ? frontmatterSlug(source, fileLabel) ?? rel.replace(/\.mdx?$/, '')
+        : basename(rel).replace(/\.mdx?$/, '');
+      const exercises = extractExercises(source);
+      if (exercises.length > 0) {
+        byChapter[chapterSlug] = exercises;
+        totalExercises += exercises.length;
+        chaptersWithExercises += 1;
+      }
     }
-    const exercises = extractExercises(source);
-    if (exercises.length > 0) {
-      byChapter[chapterSlug] = exercises;
-      totalExercises += exercises.length;
-      chaptersWithExercises += 1;
+
+    if (run.book) {
+      values.set(run.book.id, byChapter);
+      corpusExercises += totalExercises;
+      corpusChapters += chaptersWithExercises;
+      process.stdout.write(
+        `[book:${run.book.id}] build-exercises: ${totalExercises} ` +
+          `exercise${totalExercises === 1 ? '' : 's'} across ${chaptersWithExercises} ` +
+          `chapter${chaptersWithExercises === 1 ? '' : 's'} → ${OUTPUT_PATH}\n`,
+      );
+    } else {
+      values.set('', byChapter);
+      corpusExercises = totalExercises;
+      corpusChapters = chaptersWithExercises;
     }
   }
 
   const outPath = resolve(CWD, OUTPUT_PATH);
+  const output = selection.corpus
+    ? await mergeCorpusArtifact({
+        path: outPath,
+        corpus: selection.corpus,
+        requestedBook: selection.requestedBook,
+        values,
+        emptyValue: () => ({}),
+        artifact: OUTPUT_PATH,
+        validateValue: (value) =>
+          value !== null && typeof value === 'object' && !Array.isArray(value),
+      })
+    : values.get('');
   await mkdir(dirname(outPath), { recursive: true });
-  await writeFile(outPath, JSON.stringify(byChapter, null, 2) + '\n');
-  process.stdout.write(
-    `build-exercises: ${totalExercises} exercise${totalExercises === 1 ? '' : 's'} across ` +
-      `${chaptersWithExercises} chapter${chaptersWithExercises === 1 ? '' : 's'} → ${OUTPUT_PATH}\n`,
-  );
+  await writeFile(outPath, JSON.stringify(output, null, 2) + '\n');
+  if (selection.corpus) {
+    process.stdout.write(
+      `[book:corpus] build-exercises: ${corpusExercises} ` +
+        `exercise${corpusExercises === 1 ? '' : 's'} across ${corpusChapters} ` +
+        `chapter${corpusChapters === 1 ? '' : 's'} and ${selection.books.length} ` +
+        `book${selection.books.length === 1 ? '' : 's'} → ${OUTPUT_PATH}\n`,
+    );
+  } else {
+    process.stdout.write(
+      `build-exercises: ${corpusExercises} exercise${corpusExercises === 1 ? '' : 's'} across ` +
+        `${corpusChapters} chapter${corpusChapters === 1 ? '' : 's'} → ${OUTPUT_PATH}\n`,
+    );
+  }
 }
 
 main().catch((err) => {
-  console.error('build-exercises: failed');
-  console.error(err.message ?? err);
+  const message = String(err?.message ?? err);
+  const prefix = DIAGNOSTIC_SCOPE ? `[book:${DIAGNOSTIC_SCOPE}] ` : '';
+  console.error(
+    message.startsWith('[book:') ? message : `${prefix}build-exercises: failed: ${message}`,
+  );
   process.exit(1);
 });