@brandon_m_behring/book-scaffold-astro 4.30.0 → 5.0.0

package/scripts/build-figures.mjs

@@ -25,21 +25,22 @@
  *
  * v4.11.0 (closes #84): each generated SVG gets a post-export rewrite
  * (recolorSvg) that injects role="img" + a CSS-variable theming layer so one
- * SVG serves light + dark. Neutral fills/strokes are remapped to
- * var(--diagram-ink|paper|grid, <original>) via injected attribute-selector
- * rules (the original attribute stays as the fallback); saturated accent colors
- * are left untouched. A `%! no-theme` line in the source .tex opts a figure out.
+ * SVG serves light + dark. Known Warm–Tol semantic and Okabe–Ito categorical
+ * colors are mapped to var(--fig-*|--series-*, <original>); neutral paints map
+ * to var(--diagram-ink|paper|grid, <original>). Unknown saturated colors stay
+ * authored. A `%! no-theme` line in the source .tex opts a figure out.
  * <Figure> inlines local SVGs so they track the in-page [data-theme] toggle.
  *
  * Idempotent: skips when the target SVG is newer than the source PDF (and the
  * recolor itself is a no-op on an already-themed SVG, so re-runs after an
  * upgrade safely theme pre-existing figures).
- * Run on `prebuild` so Astro always sees fresh figures.
+ * Run explicitly with `npm run build:figures`; optional system tools keep this
+ * authoring pipeline out of the generated project's `prebuild` hook.
  *
  * Graceful skip: when pdftocairo / pdftoppm aren't on PATH (e.g. Cloudflare
  * build container), the script warns and exits 0. Committed SVGs/PNGs under
- * public/figures/ are served as-is. Local devs with poppler-utils regenerate
- * from PDFs on every `npm run dev`.
+ * public/figures/ are served as-is. Local authors with poppler-utils regenerate
+ * from PDFs when source figures change.
  */
 import { readdir, stat, mkdir } from 'node:fs/promises';
 import { existsSync, statSync, readFileSync, writeFileSync } from 'node:fs';
@@ -56,8 +57,10 @@ Figure pipeline. PDF -> SVG via pdftocairo (PNG fallback via pdftoppm at
 Graceful-skip if pdftocairo / pdftoppm not on PATH.
 
 Each SVG is rewritten to be accessible + dark-mode-aware: role="img" plus
-var(--diagram-ink|paper|grid, orig) fills (a "%! no-theme" line in the
-source .tex opts out). <Figure> inlines local SVGs so they track the theme.
+exact Warm–Tol/Okabe–Ito palette mappings and neutral
+var(--diagram-ink|paper|grid, orig) mappings. Use base color + separate opacity,
+not a pre-blended tint. A "%! no-theme" line in the source .tex opts out.
+<Figure> inlines local SVGs so they track the theme.
 
 Env:
   BOOK_FIGURES_PATH   Override figures source (default: figures/).
@@ -202,7 +205,7 @@ const NO_THEME_RE = /^\s*%!\s*no-theme\b/m;
 /**
  * v4.11.0 (#84): apply the theming rewrite to a generated SVG in place.
  * No-op (returns false) if the file is absent or recolorSvg leaves it unchanged
- * (already themed / nothing neutral to remap). Idempotent.
+ * (already themed / nothing themeable to remap). Idempotent.
  */
 function themeIfSvg(svgPath, optOut) {
   if (!existsSync(svgPath)) return false;

package/scripts/build-labels.mjs

@@ -48,12 +48,18 @@
  *
  * Designed to run in <2 s on a medium book.
  */
-import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
-import { resolve, relative, join, dirname, sep } from 'node:path';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { resolve, relative, dirname, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createMarkdownProcessor } from '@astrojs/markdown-remark';
-import { readChaptersBase } from './walk-mdx.mjs';
+import { readChaptersBase, walkMdx } from './walk-mdx.mjs';
 import { loadResolvedBookConfig } from './resolve-book-config.mjs';
+import {
+  assertLegacyBookMatches,
+  mergeCorpusArtifact,
+  parseFrontmatter,
+  resolveBookSelection,
+} from './corpus-tooling.mjs';
 // #126: reuse the ONE kind vocabulary (theorem-label.ts → its own lean tsup
 // entry) so a <Theorem kind="proposition"> xref reads "Proposition N.M", not a
 // kind-blind "Theorem N.M" — and so an unknown/absent kind FAILS HERE (same
@@ -76,6 +82,7 @@ Env:
   BOOK_LABELS_OUT     Override output path (default: src/data/labels.json).
 
 Options:
+  --book <id>       In corpus mode, rebuild only one registered book.
   --help, -h          Print this message and exit (non-mutating).
 
 Numbering and chapter hrefs are read from evaluated defineBookConfig metadata.
@@ -87,16 +94,8 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   process.exit(0);
 }
 
-// v4.1.1 (closes #63): readChaptersBase honors BOOK_CHAPTERS_DIR env (when set)
-// then parses the consumer's content.config.{ts,mjs,js} for a `chapters`
-// collection `loader.base` override. Multi-guide consumers use
-// `src/content/<guide-slug>/` rather than the Astro 5 default.
-const CHAPTERS_DIR_ABS = await readChaptersBase(process.cwd());
-// build-labels uses CHAPTERS_DIR as a path relative to cwd elsewhere in the
-// script (joined with `walkMdx`). Convert the absolute path back to relative
-// for compatibility with the existing call sites.
-const CHAPTERS_DIR = relative(process.cwd(), CHAPTERS_DIR_ABS) || 'src/content/chapters';
 const OUTPUT_PATH = process.env.BOOK_LABELS_OUT ?? 'src/data/labels.json';
+let DIAGNOSTIC_SCOPE = null;
 
 /** Component names that participate in cross-referencing. */
 const LABELABLE_TYPES = [
@@ -118,27 +117,6 @@ const TYPE_DISPLAY = {
   CaseStudy: 'Case study',
 };
 
-// ===== Frontmatter parsing =====
-
-function splitFrontmatter(source) {
-  // Standard MDX/YAML frontmatter: `---\n…\n---`.
-  // Remove it before Markdown processing: YAML comments beginning with `#`
-  // must not become phantom headings.
-  const m = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
-  if (!m) return { frontmatter: {}, body: source };
-  const fm = {};
-  for (const line of m[1].split(/\r?\n/)) {
-    const kv = line.match(/^(\w+)\s*:\s*(.+?)\s*$/);
-    if (!kv) continue;
-    const [, key, raw] = kv;
-    // Strip quotes; coerce numeric scalars.
-    let val = raw.replace(/^["']|["']$/g, '');
-    if (/^-?\d+$/.test(val)) val = parseInt(val, 10);
-    fm[key] = val;
-  }
-  return { frontmatter: fm, body: source.slice(m[0].length) };
-}
-
 function chapterNumberOf(frontmatter) {
   // Tools profile uses `chapter`; academic uses `week`. Prefer chapter.
   if (typeof frontmatter.chapter === 'number') return frontmatter.chapter;
@@ -169,194 +147,221 @@ function extractAttr(attrsBlob, name) {
   return null;
 }
 
-// ===== Filesystem walk =====
-
-async function walkChapters(dir) {
-  const out = [];
-  let entries;
-  try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch (err) {
-    if (err.code === 'ENOENT') return out;
-    throw err;
-  }
-  for (const e of entries) {
-    const path = join(dir, e.name);
-    if (e.isDirectory()) {
-      out.push(...(await walkChapters(path)));
-      continue;
-    }
-    if (!e.isFile()) continue;
-    if (!/\.mdx?$/.test(e.name)) continue;
-    if (e.name.startsWith('_')) continue; // hidden by convention
-    out.push(path);
-  }
-  return out;
-}
-
 // ===== Main =====
 
 async function main() {
   const cwd = process.cwd();
-  const { numberStyle, chapterRoute, bookField } = await loadResolvedBookConfig(cwd);
-  const chaptersDir = resolve(cwd, CHAPTERS_DIR);
-  const files = await walkChapters(chaptersDir);
+  const toolingConfig = await loadResolvedBookConfig(cwd);
+  if (toolingConfig.corpus) DIAGNOSTIC_SCOPE = 'corpus';
+  const { numberStyle, chapterRoute, bookField } = toolingConfig;
+  const selection = resolveBookSelection(
+    toolingConfig,
+    process.argv.slice(2),
+    'build-labels',
+  );
+  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 }];
+
   // Syntax highlighting cannot affect heading metadata and is expensive to
   // initialize. Everything that does affect Astro heading text/IDs (GFM,
   // smartypants, rehypeHeadingIds/GitHubSlugger) retains Astro's defaults.
   const headingProcessor = await createMarkdownProcessor({ syntaxHighlight: false });
-
-  const labels = {};
   const tagRegex = buildTagRegex();
-  let totalIds = 0;
-  let chaptersWithIds = 0;
-
-  for (const file of files) {
-    const source = await readFile(file, 'utf8');
-    const { frontmatter: fm, body } = splitFrontmatter(source);
-    const chapterNum = chapterNumberOf(fm);
-    const contentId = relative(chaptersDir, file)
-      .split(sep)
-      .join('/')
-      .replace(/\.mdx?$/, '');
-    const entryId = (typeof fm.slug === 'string' && fm.slug.length > 0)
-      ? fm.slug
-      : contentId;
-    const chapterPath = chapterHref(
-      { id: entryId, data: fm },
-      chapterRoute,
-      '/',
-      bookField,
-    ).replace(/^\/+|\/+$/g, '');
-
-    const addLabel = (id, value) => {
-      if (labels[id]) {
-        // Duplicate id — surface but don't fail; consumer's validator catches
-        // collisions with full diagnostic context. Component IDs retain their
-        // historical precedence over an identically named heading anchor.
-        process.stderr.write(
-          `build-labels: WARN duplicate id "${id}" (first in ` +
-            `${labels[id].href.split('#')[0]}, now in ${entryId})\n`,
+  const values = new Map();
+  const stats = [];
+
+  for (const run of runs) {
+    const files = [];
+    for await (const file of walkMdx(run.dir)) files.push(resolve(run.dir, file));
+    const labels = {};
+    let totalIds = 0;
+    let chaptersWithIds = 0;
+
+    for (const file of files) {
+      const source = await readFile(file, 'utf8');
+      if (run.book) {
+        assertLegacyBookMatches(
+          source,
+          run.book,
+          `[book:${run.book.id}] ${relative(cwd, file)}`,
         );
       }
-      labels[id] = value;
-    };
-
-    // Per-chapter counters reset for each file.
-    const counters = {};
-    let foundInChapter = 0;
-
-    // #147: BookLink fragments normally target prose sections rather than
-    // labelable components. Astro owns both text extraction and GitHub-style
-    // slug collision behavior, so consume its heading metadata directly.
-    const rendered = await headingProcessor.render(body, {
-      fileURL: pathToFileURL(file),
-      frontmatter: fm,
-    });
-    for (const heading of rendered.metadata.headings) {
-      if (heading.depth < 2 || heading.depth > 6) continue;
-      foundInChapter += 1;
-      totalIds += 1;
-      const href = `${chapterPath}#${heading.slug}`;
-      // Heading fragments are only document-local: many chapters legitimately
-      // contain `#summary`. A path-qualified, opaque key preserves every one
-      // without colliding with component IDs or another chapter. BookLink
-      // validation resolves the exact href VALUE; consumers must not derive
-      // heading semantics from this internal key.
-      addLabel(`heading:${href}`, {
-        href,
-        display: heading.text,
-        number: null,
-      });
-    }
-
-    for (const match of source.matchAll(tagRegex)) {
-      const [, componentName, attrs] = match;
-      const id = extractAttr(attrs, 'id');
-      if (!id) continue;
-
-      foundInChapter += 1;
-      totalIds += 1;
-
-      // Resolve the display word only when it will actually be used. A `label=`
-      // override supplies its own display, so we neither compute nor (for
-      // <Theorem>) kind-validate it — computing would throw on a kindless
-      // override, the documented `<Theorem id label="…">` form. For <Theorem>
-      // the word is kind-aware and THROWS on an absent/unknown kind (the #121
-      // contract, one build step earlier than render). extractAttr returns null
-      // for an absent attr → normalize to undefined so theoremLabel reports
-      // "no kind=" rather than the misleading kind="null".
-      const labelOverride = extractAttr(attrs, 'label');
-      let word;
-      let theoremKind;
-      if (labelOverride == null) {
-        if (componentName === 'Theorem') {
-          try {
-            const resolvedLabel = theoremLabel({
-              kind: extractAttr(attrs, 'kind') ?? undefined,
-              type: extractAttr(attrs, 'type') ?? undefined,
-            });
-            word = resolvedLabel.fullLabel;
-            theoremKind = resolvedLabel.kind;
-          } catch (err) {
+      const fileLabel = run.book
+        ? `[book:${run.book.id}] ${relative(cwd, file)}`
+        : relative(cwd, file);
+      const { frontmatter: fm, body } = parseFrontmatter(source, fileLabel);
+      const chapterNum = chapterNumberOf(fm);
+      const contentId = relative(run.dir, file)
+        .split(sep)
+        .join('/')
+        .replace(/\.mdx?$/, '');
+      const localEntryId = (typeof fm.slug === 'string' && fm.slug.length > 0)
+        ? fm.slug
+        : contentId;
+      const entryId = run.book ? `${run.book.id}/${localEntryId}` : localEntryId;
+      const chapterPath = chapterHref(
+        { id: entryId, data: fm },
+        chapterRoute,
+        '/',
+        bookField,
+      ).replace(/^\/+|\/+$/g, '');
+
+      const addLabel = (id, value) => {
+        if (labels[id]) {
+          // Component IDs are book-local in corpus mode, so identical ids in
+          // another namespace do not collide.
+          const prefix = run.book ? `[book:${run.book.id}] ` : '';
+          if (run.book) {
             throw new Error(
-              `<Theorem id="${id}"> in ${relative(cwd, file)}: ${err.message}`,
+              `${prefix}duplicate label id "${id}" (first in ` +
+                `${labels[id].href.split('#')[0]}, now in ${entryId}).`,
             );
           }
-        } else {
-          word = TYPE_DISPLAY[componentName];
+          process.stderr.write(
+            `${prefix}build-labels: WARN duplicate id "${id}" (first in ` +
+              `${labels[id].href.split('#')[0]}, now in ${entryId})\n`,
+          );
         }
+        labels[id] = value;
+      };
+
+      // Per-chapter counters reset for each file.
+      const counters = {};
+      let foundInChapter = 0;
+
+      // #147: BookLink fragments normally target prose sections rather than
+      // labelable components. Astro owns both text extraction and GitHub-style
+      // slug collision behavior, so consume its heading metadata directly.
+      const rendered = await headingProcessor.render(body, {
+        fileURL: pathToFileURL(file),
+        frontmatter: fm,
+      });
+      for (const heading of rendered.metadata.headings) {
+        if (heading.depth < 2 || heading.depth > 6) continue;
+        foundInChapter += 1;
+        totalIds += 1;
+        const href = `${chapterPath}#${heading.slug}`;
+        addLabel(`heading:${href}`, {
+          href,
+          display: heading.text,
+          number: null,
+        });
       }
 
-      // label= is a custom, unnumbered display and therefore does not consume
-      // either the historical shared sequence or a per-kind sequence. This
-      // keeps later auto-numbered entries stable when prose-only labels move.
-      const counterKey =
-        numberStyle === 'per-kind' && componentName === 'Theorem'
-          ? `Theorem/${theoremKind}`
-          : componentName;
-      if (labelOverride == null) {
-        counters[counterKey] = (counters[counterKey] ?? 0) + 1;
+      for (const match of source.matchAll(tagRegex)) {
+        const [, componentName, attrs] = match;
+        const id = extractAttr(attrs, 'id');
+        if (!id) continue;
+
+        foundInChapter += 1;
+        totalIds += 1;
+
+        const labelOverride = extractAttr(attrs, 'label');
+        let word;
+        let theoremKind;
+        if (labelOverride == null) {
+          if (componentName === 'Theorem') {
+            try {
+              const resolvedLabel = theoremLabel({
+                kind: extractAttr(attrs, 'kind') ?? undefined,
+                type: extractAttr(attrs, 'type') ?? undefined,
+              });
+              word = resolvedLabel.fullLabel;
+              theoremKind = resolvedLabel.kind;
+            } catch (err) {
+              const prefix = run.book ? `[book:${run.book.id}] ` : '';
+              throw new Error(
+                `${prefix}<Theorem id="${id}"> in ${relative(cwd, file)}: ${err.message}`,
+              );
+            }
+          } else {
+            word = TYPE_DISPLAY[componentName];
+          }
+        }
+
+        const counterKey =
+          numberStyle === 'per-kind' && componentName === 'Theorem'
+            ? `Theorem/${theoremKind}`
+            : componentName;
+        if (labelOverride == null) {
+          counters[counterKey] = (counters[counterKey] ?? 0) + 1;
+        }
+
+        const number = labelOverride != null
+          ? null
+          : chapterNum != null
+            ? `${chapterNum}.${counters[counterKey]}`
+            : String(counters[counterKey]);
+        const display = labelOverride ?? `${word} ${number}`;
+
+        addLabel(id, {
+          href: `${chapterPath}#${id}`,
+          display,
+          number,
+        });
       }
 
-      // The bare counter string the heading reuses: Theorem.astro reads
-      // `number` by id and renders it, so heading == xref by construction.
-      // A `label=` override opts out of auto-numbering → number is null.
-      const number = labelOverride != null
-        ? null
-        : chapterNum != null
-          ? `${chapterNum}.${counters[counterKey]}`
-          : String(counters[counterKey]);
-      const display = labelOverride ?? `${word} ${number}`;
-
-      addLabel(id, {
-        // #142: base-less ref — XRef.astro prefixes BASE_URL at render so one
-        // labels.json serves any deploy base (root or path-proxied series).
-        href: `${chapterPath}#${id}`,
-        display,
-        number,
-      });
+      if (foundInChapter > 0) chaptersWithIds += 1;
     }
 
-    if (foundInChapter > 0) chaptersWithIds += 1;
+    // Emit deterministic output: keys sorted alphabetically within each book.
+    const sorted = {};
+    for (const key of Object.keys(labels).sort()) sorted[key] = labels[key];
+    values.set(run.book?.id ?? '', sorted);
+    stats.push({ book: run.book, totalIds, chaptersWithIds });
   }
 
-  // Emit deterministic output: keys sorted alphabetically.
-  const sorted = {};
-  for (const k of Object.keys(labels).sort()) sorted[k] = labels[k];
-
   const outputPath = resolve(cwd, OUTPUT_PATH);
+  const output = selection.corpus
+    ? await mergeCorpusArtifact({
+        path: outputPath,
+        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(outputPath), { recursive: true });
-  await writeFile(outputPath, JSON.stringify(sorted, null, 2) + '\n', 'utf8');
-
-  process.stdout.write(
-    `build-labels: ${totalIds} id${totalIds === 1 ? '' : 's'} across ` +
-      `${chaptersWithIds} chapter${chaptersWithIds === 1 ? '' : 's'} → ` +
-      `${OUTPUT_PATH} (number-style=${numberStyle})\n`,
-  );
+  await writeFile(outputPath, JSON.stringify(output, null, 2) + '\n', 'utf8');
+
+  if (selection.corpus) {
+    for (const stat of stats) {
+      process.stdout.write(
+        `[book:${stat.book.id}] build-labels: ${stat.totalIds} ` +
+          `id${stat.totalIds === 1 ? '' : 's'} across ${stat.chaptersWithIds} ` +
+          `chapter${stat.chaptersWithIds === 1 ? '' : 's'} → ${OUTPUT_PATH} ` +
+          `(number-style=${numberStyle})\n`,
+      );
+    }
+    const totalIds = stats.reduce((sum, stat) => sum + stat.totalIds, 0);
+    const totalChapters = stats.reduce((sum, stat) => sum + stat.chaptersWithIds, 0);
+    process.stdout.write(
+      `[book:corpus] build-labels: ${totalIds} id${totalIds === 1 ? '' : 's'} across ` +
+        `${totalChapters} chapter${totalChapters === 1 ? '' : 's'} and ` +
+        `${stats.length} book${stats.length === 1 ? '' : 's'} → ${OUTPUT_PATH} ` +
+        `(number-style=${numberStyle})\n`,
+    );
+  } else {
+    const [stat] = stats;
+    process.stdout.write(
+      `build-labels: ${stat.totalIds} id${stat.totalIds === 1 ? '' : 's'} across ` +
+        `${stat.chaptersWithIds} chapter${stat.chaptersWithIds === 1 ? '' : 's'} → ` +
+        `${OUTPUT_PATH} (number-style=${numberStyle})\n`,
+    );
+  }
 }
 
 main().catch((err) => {
-  process.stderr.write(`build-labels: fatal: ${err?.message ?? err}\n`);
+  const message = String(err?.message ?? err);
+  const prefix = DIAGNOSTIC_SCOPE ? `[book:${DIAGNOSTIC_SCOPE}] ` : '';
+  process.stderr.write(
+    message.startsWith('[book:') ? `${message}\n` : `${prefix}build-labels: fatal: ${message}\n`,
+  );
   process.exit(1);
 });

package/scripts/build-tips.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-tips
 
@@ -36,6 +43,7 @@ Env:
   BOOK_TIPS_OUT       Override output path (default: src/data/tips.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_TIPS_OUT ?? 'src/data/tips.json';
+let DIAGNOSTIC_SCOPE = null;
 
 /**
  * Extract <Tip n="..." title="..."> tags and their body content from MDX.
@@ -104,38 +112,102 @@ function extractTips(source, chapterSlug) {
 }
 
 async function main() {
-  const allTips = [];
-  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;
+  const toolingConfig = await loadResolvedBookConfig(CWD);
+  if (toolingConfig.corpus) DIAGNOSTIC_SCOPE = 'corpus';
+  const selection = resolveBookSelection(toolingConfig, process.argv.slice(2), 'build-tips');
+  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 corpusTotal = 0;
+
+  for (const run of runs) {
+    const allTips = [];
+    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}] ${resolve(CWD, chapterPath).replace(`${CWD}/`, '')}`,
+        );
+      }
+      const fileLabel = run.book
+        ? `[book:${run.book.id}] ${resolve(CWD, chapterPath).replace(`${CWD}/`, '')}`
+        : resolve(CWD, chapterPath).replace(`${CWD}/`, '');
+      const chapterSlug = run.book
+        ? frontmatterSlug(source, fileLabel) ?? rel.replace(/\.mdx?$/, '')
+        : basename(rel).replace(/\.mdx?$/, '');
+      allTips.push(...extractTips(source, chapterSlug));
+    }
+
+    // Sort by n; warn on duplicates (don't fail — the index page just shows duplicates).
+    allTips.sort((a, b) => a.n - b.n);
+    const seenN = new Set();
+    for (const tip of allTips) {
+      if (seenN.has(tip.n)) {
+        const prefix = run.book ? `[book:${run.book.id}] ` : '';
+        process.stderr.write(
+          `${prefix}build-tips: WARN duplicate Tip n="${tip.n}" (last wins on /tips index)\n`,
+        );
+      }
+      seenN.add(tip.n);
     }
-    allTips.push(...extractTips(source, chapterSlug));
-  }
 
-  // Sort by n; warn on duplicates (don't fail — the index page just shows duplicates).
-  allTips.sort((a, b) => a.n - b.n);
-  const seenN = new Set();
-  for (const tip of allTips) {
-    if (seenN.has(tip.n)) {
-      process.stderr.write(`build-tips: WARN duplicate Tip n="${tip.n}" (last wins on /tips index)\n`);
+    if (run.book) {
+      values.set(run.book.id, allTips);
+      corpusTotal += allTips.length;
+      process.stdout.write(
+        `[book:${run.book.id}] build-tips: ${allTips.length} ` +
+          `tip${allTips.length === 1 ? '' : 's'} → ${OUTPUT_PATH}\n`,
+      );
+    } else {
+      values.set('', allTips);
     }
-    seenN.add(tip.n);
   }
 
   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: Array.isArray,
+      })
+    : values.get('');
   await mkdir(dirname(outPath), { recursive: true });
-  await writeFile(outPath, JSON.stringify(allTips, null, 2) + '\n');
-  process.stdout.write(`build-tips: ${allTips.length} tip${allTips.length === 1 ? '' : 's'} → ${OUTPUT_PATH}\n`);
+  await writeFile(outPath, JSON.stringify(output, null, 2) + '\n');
+  if (selection.corpus) {
+    process.stdout.write(
+      `[book:corpus] build-tips: ${corpusTotal} ` +
+        `tip${corpusTotal === 1 ? '' : 's'} across ${selection.books.length} ` +
+        `book${selection.books.length === 1 ? '' : 's'} → ${OUTPUT_PATH}\n`,
+    );
+  } else {
+    const allTips = values.get('');
+    process.stdout.write(
+      `build-tips: ${allTips.length} tip${allTips.length === 1 ? '' : 's'} → ${OUTPUT_PATH}\n`,
+    );
+  }
 }
 
 main().catch((err) => {
-  console.error('build-tips: 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-tips: failed: ${message}`,
+  );
   process.exit(1);
 });