@brandon_m_behring/book-scaffold-astro 4.31.0 → 5.1.0

package/CLAUDE.md

@@ -31,9 +31,46 @@ the consuming book knows which versions are actually deployed. Import it from
 navigation belongs. It renders nothing for an omitted or empty manifest;
 `Base.astro` never invents or auto-mounts version links.
 
+## Corpus mode (v5, opt-in)
+
+A corpus is one Astro application and one homogeneous preset/Style chain with
+an ordered `defineBookCorpus` manifest. The same branded manifest must be passed
+to `defineBookConfig({ corpus })` and `defineBookSchemas({ corpus })`; do not
+copy or reconstruct it between entrypoints.
+
+Corpus chapters live at `src/content/<book>/<local-path>.{md,mdx}`. The
+registered first path segment is the book identity and generates an entry id
+`<book>/<local-id>` plus URL `/chapters/<book>/<local-id>/`. Do not add required
+`book:` frontmatter or hand-write a `generateId`; a legacy `book:` value may
+remain only when it matches the path. Questions and glossary entries use
+`src/content/{questions,glossary}/<book>/...` and the same namespacing rule.
+Consequently, `questions`, `glossary`, and `frontmatter` are reserved book ids:
+those directories belong to scaffold content collections, not chapter owners.
+
+Keep every lookup book-scoped: navigation/previous-next, labels, references,
+tips, exercises, questions, and glossary entries must select the current
+manifest book. Corpus JSON is `{ schemaVersion: 1, books: { [id]: payload } }`;
+single-book JSON remains flat. The content-derived `build-labels`, `build-bib`,
+`build-tips`, `build-exercises`, and `validate` commands accept `--book <id>`
+in corpus mode. `qa` defaults to all manifest books, accepts either one exact
+`--book <id>` or `--all`, and rejects `--book` in single-book mode. Figures and
+notebooks remain application-wide.
+
+Convergence collateral lives at `changelog/<book>/patterns.yaml` and
+`changelog/<book>/tools/*.yaml`; root-level v4 collateral is single-book only.
+Flashcard persistence is automatically namespaced by deployment base and book.
+
+Canonical corpus routes are `/`, `/chapters/`, `/<book>/`,
+`/chapters/<book>/`, `/chapters/<book>/<slug>/`, `/search/` (optionally
+`?book=<id>`), and `/<book>/<apparatus>/`, all under Astro `base`. Corpus mode
+owns `chapterRoute`, `bookField`, `apparatusRoute`, and `apparatusRoutes`. An
+omitted manifest `apparatus` inherits enabled app routes; `[]` disables all for
+that book. Search uses one Pagefind index with a `book` filter. See Recipe 21
+before changing corpus content, routing, or data scripts.
+
 ## Frontmatter schemas
 
-**Universal field (v4.9.0):** every profile accepts an optional `slug:` string that overrides the URL. A file `99-appendix.mdx` with `slug: appendix` is served at `/chapters/appendix/` — Astro's glob loader maps frontmatter `slug` → `entry.id`, and cross-references (`<XRef>`, via `build-labels`) resolve to the same path. Omit it and the URL falls back to the filename. Use it to keep numbered filenames for ordering while publishing clean URLs.
+**Universal field (v4.9.0):** every profile accepts an optional `slug:` string that overrides the URL. In single-book mode, a file `99-appendix.mdx` with `slug: appendix` is served at `/chapters/appendix/`; in corpus mode, `evaluation/99-appendix.mdx` is served at `/chapters/evaluation/appendix/`. The loader and `build-labels` resolve the same id. Omit `slug` to use the nested filename path.
 
 ### Academic profile (`src/content.config.ts:academicChapterSchema`)
 
@@ -108,7 +145,7 @@ Two callout families coexist. Authors import what they need.
 
 **Pedagogy family** (v4.1.0+, any profile, 4 components): `Pitfall` (rose; "common mistake" — distinct from `WarnBox`'s preemptive warning), `WorkedExample` (plum; collapsible `<details>` block with `#worked-example-{id}` anchor for deep links), `YouWillLearn` (gold; chapter-opener with optional `prerequisites` prop), `Diagnostic` (v4.19.0, #110; teal; pre-reading "Do I Know This Already?" DIKTA self-check — a slotted question list + a skip/skim/read routing rubric via `skimTo`, plus an optional collapsible answer key via `slot="answers"`). Slot bullets/code freely; render at any preset.
 
-**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginFigure`, `MarginNote`, `Sidenote`, `EvidenceTag`, `Newthought`, `Epigraph`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`, `BookLink` (v4.16.0+; cross-book link — `<BookLink book="design" to="…"/>` resolves `book` against `defineBookConfig({ siblingBooks })` and throws on an unknown book; #147 adds `{ url, labels }` entries so `validate` checks literal fragment targets against a vendored sibling `labels.json`, while legacy URL strings warn/skip target validation; `<XRef>` is in-book only — #96), `PocLayout` (v4.1.0+; wraps slot in a per-`kind` layout shell — 5 closed-union kinds; see `recipes/15-defining-styles.md`).
+**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginFigure`, `MarginNote`, `Sidenote`, `EvidenceTag`, `Newthought`, `Epigraph`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`, `BookLink` (cross-book link — a manifest-owned `book` resolves locally in corpus mode; otherwise it resolves through `defineBookConfig({ siblingBooks })`; #147 `{ url, labels }` entries let `validate` check external literal fragments against a vendored `labels.json`; `<XRef>` remains current-book only), `PocLayout` (v4.1.0+; wraps slot in a per-`kind` layout shell — 5 closed-union kinds; see `recipes/15-defining-styles.md`).
 
 **Cross-book heading indexes (#147):** `book-scaffold build-labels` indexes h2–h6 with Astro's heading collector (inline formatting/smartypants plus GitHub duplicate slugs), alongside the historical component IDs. Emitted hrefs are base-less and resolve the evaluated `chapterRoute` / `bookField`; nested content IDs keep their directory. Heading keys are opaque and path-qualified so the same fragment can exist in multiple chapters; `validate` matches exact normalized href values, while component keys stay backward-compatible for XRef. This makes a generated sibling `labels.json` usable for literal `<BookLink ... to="...#anchor">` validation without assuming `/chapters/`. h1 stays excluded as the chapter title.
 
@@ -166,6 +203,7 @@ npm install                  # once after clone
 npm run dev                  # localhost:4321
 npm run build                # astro build + pagefind index → dist/
 npm run validate             # pre-flight check (recipe 09)
+npm exec -- book-scaffold qa # content-readiness verdict (recipe 25)
 npm run build:bib            # rebuild references.json after .bib edit
 npm run pdf                  # render dist-pdf/book.pdf via Paged.js
 ```
@@ -192,6 +230,27 @@ A consumer `public/_headers` wins unchanged. Use
 or `securityHeaders: false` when another layer owns all headers. Recipe 05 has
 the full precedence and customization contract.
 
+## QA and content readiness
+
+Run `npm exec -- book-scaffold qa` after substantive content changes. It calls
+the same content-contract library as `validate`, then reports stable chapter,
+link, learning-objective, component, and JSON-fixture facts. Human output is
+the default. For CI use `npm --offline exec -- book-scaffold qa --format json`;
+JSON stdout contains only the schema-v1 result, while progress/fatal details go
+to stderr. Exit `0` means no blocking failure, `1` means a red selected/shared
+result, and `2` means the invocation or execution failed.
+
+In a corpus, omission checks every manifest book in order; `--book <id>` checks
+one and `--all` states the default explicitly. Schema v1 always includes a
+top-level `shared: { verdict, checks, diagnostics }` aggregate for corpus-wide
+fixture data. Its exact single-book value is
+`{ "verdict": "not_applicable", "checks": {}, "diagnostics": [] }`.
+
+Run `npm exec -- book-scaffold init-qa` only when a portfolio QA engine needs
+`guide_qa.yaml`. It emits one deterministic offline command per manifest book,
+or one implicit `book` entry without `--book`. It preserves an existing file;
+`--force` replaces that whole file and no other path. See Recipe 25.
+
 ## Validation
 
 `npm run validate` (also runs in prebuild) catches:

package/MIGRATION-v4-to-v5.md

@@ -0,0 +1,183 @@
+# Migrating from v4.x to v5.0.0
+
+**Audience**: existing users of `@brandon_m_behring/book-scaffold-astro@^4`.
+
+v5 makes two previously deprecated configuration changes and adds an opt-in
+book-corpus mode. Existing single-book routes and generated JSON stay unchanged;
+corpus mode is the only feature that changes their shape.
+
+## Required changes for every application
+
+### 1. Make the preset explicit
+
+v4 could fall back to `minimal` when no preset was configured. v5 fails instead,
+because a missing `.env` in CI must not silently select the wrong schema and
+rendering behavior.
+
+For `defineBookConfig`, include a built-in Style or a custom Style with a
+`preset`:
+
+```ts
+import {
+  defineBookConfig,
+  academicStyle,
+} from '@brandon_m_behring/book-scaffold-astro';
+
+export default await defineBookConfig({
+  styles: [academicStyle],
+  site: 'https://book.example/',
+});
+```
+
+Give `defineBookSchemas` the matching preset directly:
+
+```ts
+import { defineBookSchemas } from '@brandon_m_behring/book-scaffold-astro/schemas';
+
+export const { collections } = defineBookSchemas({ preset: 'academic' });
+```
+
+`BOOK_PRESET` in the process environment or project `.env` remains a supported
+shared source for a preset-less Style/schema call. `BOOK_PROFILE` and the
+`profile` schema option remain backward-compatible aliases. Prefer the canonical
+names in new configuration:
+
+```dotenv
+BOOK_PRESET=academic
+```
+
+The resolution order remains explicit argument, `BOOK_PRESET`, `BOOK_PROFILE`,
+then the same two keys in `.env`. There is no final default.
+
+### 2. Delete `deploy` from book and Style configuration
+
+Remove `deploy` from both locations if present:
+
+```diff
+ export const brandStyle = defineStyle({
+   name: 'brand',
+-  deploy: 'workers',
+ });
+
+ export default await defineBookConfig({
+   styles: [brandStyle, academicStyle],
+-  deploy: 'workers',
+   site: 'https://book.example/',
+ });
+```
+
+The v4 field was inert: it never changed an existing deployment and never chose
+the file emitted by `create-book`. v5 removes it from the types and built-in
+Styles; JavaScript configurations and v4 Style objects that still carry it fail
+with a migration error.
+
+Configure the real deployment surface instead:
+
+- edit `wrangler.toml` for Cloudflare Workers or Pages;
+- edit the deployment platform's project settings or workflow; and
+- keep `site` in `defineBookConfig` as the public canonical origin.
+
+`create-book --preset` still chooses an initial `wrangler.toml` shape for a new
+project. That scaffold-time choice is separate from book configuration.
+
+## Corpus opt-in
+
+Corpus mode is optional. A Recipe 21 multi-guide application migrates in six
+steps:
+
+1. Extract the ordered book metadata into one `defineBookCorpus` manifest.
+2. Pass that same manifest to `defineBookConfig` and `defineBookSchemas`.
+3. Remove the hand-written chapter collection and its custom `generateId`.
+4. Keep book folders under `src/content/`, or set one explicit `chaptersBase`
+   when the shared base lives elsewhere.
+5. Compare consumer-owned per-book index pages with the injected pages, then
+   remove the duplicates.
+6. Run every content-derived command (`build-labels`, `build-bib`,
+   `build-tips`, `build-exercises`, and `validate`); update scripts that read
+   generated corpus JSON to select a book from the versioned envelope. Figure
+   and notebook conversion remain application-wide.
+
+A minimal shared manifest looks like this:
+
+```ts
+// src/book-corpus.ts
+import { defineBookCorpus } from '@brandon_m_behring/book-scaffold-astro';
+
+export const corpus = defineBookCorpus({
+  preset: 'tools',
+  books: [
+    { id: 'evaluation', title: 'Evaluation Engineering' },
+    { id: 'llm-apps', title: 'LLM Application Engineering' },
+  ],
+});
+```
+
+```ts
+// astro.config.mjs
+import { defineBookConfig } from '@brandon_m_behring/book-scaffold-astro';
+import { corpus } from './src/book-corpus.js';
+
+export default await defineBookConfig({
+  corpus,
+  site: 'https://guides.example/',
+});
+```
+
+```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's preset is an explicit preset source. If a composed Style also
+sets a preset, it must match the manifest.
+
+Book ids may not be `questions`, `glossary`, or `frontmatter`; those names own
+shared scaffold collection roots beneath `src/content/`, rather than chapter
+directories. `defineBookCorpus` rejects such collisions before content sync.
+
+Existing Recipe 21 chapter URLs remain
+`/chapters/<book>/<slug>/`; no redirect is needed. In corpus mode, generated
+labels, references, tips, and exercise data use the versioned envelope:
+
+```json
+{
+  "schemaVersion": 1,
+  "books": {
+    "evaluation": {},
+    "llm-apps": {}
+  }
+}
+```
+
+Consumers must select the current book before looking up an entry.
+
+If the corpus exposes convergence dashboards, move the v4 root collateral into
+one directory per manifest id:
+
+```text
+changelog/<book>/patterns.yaml
+changelog/<book>/tools/*.yaml
+```
+
+Corpus routes never reuse a root-level pattern/timeline collection across
+books. Flashcard progress is automatically isolated under per-book storage
+keys; no authoring change is required.
+
+## Single-book compatibility
+
+A single-book application does not need `defineBookCorpus`. Its
+`/chapters/<slug>/` and `/chapters/` routes, flat apparatus routes, schemas, and
+generated JSON retain their v4 shapes. Only the explicit-preset requirement and
+the removed `deploy` field apply.
+
+## Upgrade checklist
+
+1. Remove every `deploy` key from book configs and shared Styles.
+2. Confirm both Astro config and content schemas resolve the intended preset.
+3. Run `npm run validate` and `npm run build`; the generated prevalidation hook
+   refreshes the applicable bibliography and label artifacts. Run optional
+   tips/exercises build scripts when the application enables those surfaces.
+4. For a corpus, inspect every book's routes and update generated-JSON readers.

package/README.md

@@ -18,7 +18,70 @@ Available presets are `academic`, `tools`, `minimal`, `course-notes`, and
 [repository README](https://github.com/brandon-behring/book-scaffold-astro)
 for the current release overview, and
 [PACKAGE_DESIGN.md](https://github.com/brandon-behring/book-scaffold-astro/blob/main/PACKAGE_DESIGN.md)
-for the complete API contract.
+for the complete API contract. Upgrading an existing v4 book? Follow
+[MIGRATION-v4-to-v5.md](./MIGRATION-v4-to-v5.md).
+
+v5 requires an explicit preset. A built-in/custom Style, schema option,
+`BOOK_PRESET`, or corpus manifest may supply it; an absent preset fails instead
+of silently selecting `minimal`. The deprecated v4 `deploy` book/Style field is
+removed—configure the real provider surface and Astro `site`/`base` instead.
+
+## Multi-book corpora
+
+Several books can share one app, deployment, preset/Style chain, and Pagefind
+index through one branded manifest:
+
+```ts
+import { defineBookCorpus } from '@brandon_m_behring/book-scaffold-astro';
+
+export const corpus = defineBookCorpus({
+  preset: 'research-portfolio',
+  books: [
+    { id: 'evaluation', title: 'Evaluation Engineering' },
+    { id: 'llm-apps', title: 'LLM Application Engineering' },
+  ],
+});
+```
+
+Pass that same `corpus` to `defineBookConfig` and `defineBookSchemas`.
+Namespaced chapters, apparatus routes, navigation, generated JSON, diagnostics,
+local `<BookLink>` targets, and Pagefind results remain book-scoped. See
+[Recipe 21](./recipes/21-multi-guide-single-app.md) for content layout, route
+ownership, `--book` tooling, shared sources, and migration.
+
+## Content readiness and CLI
+
+`book-scaffold qa` combines the existing validation contract with stable
+chapter, link, learning-objective, component, and JSON-fixture metrics. Human
+output is the default; schema-v1 JSON is deterministic and keeps stdout clean
+for CI:
+
+```bash
+npm exec -- book-scaffold qa
+npm --offline exec -- book-scaffold qa --format json
+npm exec -- book-scaffold init-qa
+```
+
+In corpus mode `qa` checks every manifest book by default, while `--book <id>`
+selects one exact id. `init-qa` creates the portfolio-engine interoperability
+file `guide_qa.yaml`; its generated checks use `npm --offline exec` and an
+existing file is preserved unless `--force` is explicit. See
+[Recipe 25](./recipes/25-qa-readiness.md) for verdicts, exit codes, the
+top-level `shared` aggregate, and CI wiring.
+
+The installed `book-scaffold` dispatcher owns these commands:
+
+| Command | Purpose |
+|---|---|
+| `validate` | Pre-flight authored content, references, figures, and links |
+| `qa` | Emit a human or schema-v1 readiness verdict |
+| `init-qa` | Generate deterministic `guide_qa.yaml` interoperability config |
+| `build-labels` | Build cross-reference and heading indexes |
+| `build-bib` | Build bibliography and source-manifest data |
+| `build-tips` | Build the tips index |
+| `build-exercises` | Build the exercises index |
+| `build-figures` | Convert and theme application-wide figure assets |
+| `render-notebooks` | Render application-wide notebook companions |
 
 Astro builds emit a Cloudflare-compatible `dist/_headers` with audited
 security defaults. A consumer-owned `public/_headers` wins unchanged;

package/bin/book-scaffold.mjs

@@ -14,6 +14,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const handlers = {
   validate: '../scripts/validate.mjs',
+  qa: '../scripts/qa.mjs',
+  'init-qa': '../scripts/init-qa.mjs',
   'build-labels': '../scripts/build-labels.mjs',
   'build-bib': '../scripts/build-bib.mjs',
   'build-figures': '../scripts/build-figures.mjs',
@@ -26,6 +28,8 @@ const HELP = `Usage: book-scaffold <sub-command> [args...]
 
 Sub-commands:
   validate           Pre-flight content validator (XRef ids, Cite keys, Figure srcs).
+  qa                 Content-health and readiness report (human or schema-v1 JSON).
+  init-qa            Generate deterministic guide_qa.yaml interoperability config.
   build-labels       Emit src/data/labels.json for cross-references (Phase C).
   build-bib          BibTeX -> references.json (+ sources/manifest.yaml -> sources.json).
   build-figures      PDF -> SVG via pdftocairo / pdftoppm fallback (+ TikZ in v4.2.0).

package/components/AssessmentTest.astro

@@ -32,6 +32,7 @@ import { assertKnownDomain } from '../src/lib/exam-domains';
 import { buildExamManifest, deriveDomainRouting } from '../src/lib/exam-manifest';
 import '../styles/exam-runner.css';
 import { normalizeBase } from '../src/lib/nav-href';
+import { corpusBookHasApparatusRoute, corpusBookIdFromPath } from '../src/lib/corpus';
 
 interface Props {
   /** Heading above the test. Defaults to "Assessment test". */
@@ -65,9 +66,17 @@ const questionModules = import.meta.glob('/src/content/questions/**/*.{md,mdx}',
   import: 'default',
   eager: true,
 });
-const hasQuestions = Object.keys(questionModules).length > 0;
+const currentBook = bookConfig.corpus
+  ? corpusBookIdFromPath(bookConfig.corpus, Astro.url.pathname, import.meta.env.BASE_URL)
+  : null;
+if (bookConfig.corpus && !currentBook) {
+  throw new Error('<AssessmentTest> requires a canonical corpus book route.');
+}
+const hasQuestions = currentBook
+  ? Object.keys(questionModules).some((path) => path.includes(`/questions/${currentBook}/`))
+  : Object.keys(questionModules).length > 0;
 
-const entries = hasQuestions ? await getAllQuestions() : [];
+const entries = hasQuestions ? await getAllQuestions(currentBook ?? undefined) : [];
 
 // Fail loud: an unregistered/typo'd domain must throw at build, not silently
 // skew the assessment's domain spread.
@@ -85,10 +94,22 @@ const scoreable = entries.filter(
 // deriveDomainRouting takes baseUrl as a param (not import.meta.env) because it
 // ships pre-compiled in dist/ where Vite's env replacement does not reach.
 const baseUrl = normalizeBase(import.meta.env.BASE_URL);
+const bookRoutePrefix = currentBook ? `${currentBook}/` : '';
 const manifest = buildExamManifest(entries);
-const domainRouting = deriveDomainRouting(entries, baseUrl);
-const practiceExamHref = (bookConfig.enabledRoutes ?? []).includes('practiceExam')
-  ? `${baseUrl}practice-exam`
+const domainRouting = deriveDomainRouting(entries, baseUrl, currentBook ?? undefined);
+const hasPracticeExam = bookConfig.corpus
+  ? Boolean(
+      currentBook &&
+      corpusBookHasApparatusRoute(
+        bookConfig.corpus,
+        currentBook,
+        'practice-exam',
+        bookConfig.apparatusRoutes,
+      ),
+    )
+  : (bookConfig.enabledRoutes ?? []).includes('practiceExam');
+const practiceExamHref = hasPracticeExam
+  ? `${baseUrl}${bookRoutePrefix}practice-exam`
   : null;
 
 const rendered = await Promise.all(

package/components/BookLink.astro

@@ -20,7 +20,7 @@
  *   <BookLink book="design" to="chapters/patterns/#layered">the layered pattern</BookLink>.
  */
 import bookConfig from 'virtual:book-scaffold/book-config';
-import { resolveBookHref } from '../src/lib/book-link';
+import { resolveBookHref, resolveCorpusBookHref } from '../src/lib/book-link';
 
 interface Props {
   book: string;
@@ -28,6 +28,9 @@ interface Props {
 }
 
 const { book, to } = Astro.props;
-const href = resolveBookHref(bookConfig.siblingBooks, book, to);
+const localBook = bookConfig.corpus?.books.some((candidate) => candidate.id === book) ?? false;
+const href = localBook
+  ? resolveCorpusBookHref(book, to, import.meta.env.BASE_URL)
+  : resolveBookHref(bookConfig.siblingBooks, book, to);
 ---
-<a href={href} rel="external noopener" class="book-link"><slot /></a>
+<a href={href} rel={localBook ? undefined : 'external noopener'} class="book-link"><slot /></a>

package/components/ChapterNav.astro

@@ -20,7 +20,7 @@ const chapterRoute = (bookConfig as { chapterRoute?: string }).chapterRoute ?? '
 const bookField = (bookConfig as { bookField?: string }).bookField ?? 'book';
 const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 
-const { prev, next } = await getNeighbors(currentId, { bookField });
+const { prev, next } = await getNeighbors(currentId, { bookField, corpus: bookConfig.corpus });
 // Resolve hrefs in frontmatter (casts here, never in the JSX expression container).
 const prevHref = prev
   ? chapterHref({ id: prev.id, data: prev.data as Record<string, unknown> }, chapterRoute, baseUrl, bookField)

package/components/Cite.astro

@@ -1,5 +1,11 @@
 ---
-import { normalizeBase } from '../src/lib/nav-href';
+import { apparatusHref, normalizeBase } from '../src/lib/nav-href';
+import bookConfig from 'virtual:book-scaffold/book-config';
+import {
+  corpusBookHasApparatusRoute,
+  corpusBookIdFromPath,
+  selectBookArtifact,
+} from '../src/lib/corpus';
 /**
  * Cite — renders a `\cite{bibkey}` LaTeX citation as a clickable
  * inline reference to the bibliography page.
@@ -33,12 +39,36 @@ type CslEntry = {
 
 // Resolve references.json from consumer's project root. Missing file -> empty
 // map -> any <Cite> throws below (strict per D3 — bibkeys must resolve at build).
-const refsModules = import.meta.glob<{ default: Record<string, CslEntry> }>(
+const refsModules = import.meta.glob<{ default: unknown }>(
   '/src/data/references.json',
   { eager: true },
 );
 const refsModule = refsModules['/src/data/references.json'];
-const map = (refsModule?.default ?? {}) as Record<string, CslEntry>;
+const currentBook = bookConfig.corpus
+  ? corpusBookIdFromPath(bookConfig.corpus, Astro.url.pathname, import.meta.env.BASE_URL)
+  : null;
+if (
+  bookConfig.corpus &&
+  (!currentBook ||
+    !corpusBookHasApparatusRoute(
+      bookConfig.corpus,
+      currentBook,
+      'references',
+      bookConfig.apparatusRoutes,
+    ))
+) {
+  throw new Error(
+    `<Cite key="${Astro.props.key}"> requires the current corpus book's references route.`,
+  );
+}
+const map = refsModule
+  ? selectBookArtifact<Record<string, CslEntry>>(
+      refsModule.default,
+      bookConfig.corpus,
+      currentBook,
+      'src/data/references.json',
+    )
+  : {};
 
 interface Props {
   key: string;
@@ -47,6 +77,9 @@ interface Props {
 
 const { key, page } = Astro.props;
 const baseUrl = normalizeBase(import.meta.env.BASE_URL);
+const referencesHref = bookConfig.corpus
+  ? apparatusHref('references', currentBook, '/:book/:route/', baseUrl)
+  : `${baseUrl}references`;
 const entry = map[key];
 if (!entry) {
   throw new Error(
@@ -68,6 +101,6 @@ else authorText = `${surname(authors[0])} et al.`;
 const year = entry.issued?.['date-parts']?.[0]?.[0] ?? 'n.d.';
 const yearText = page ? `${year}, p. ${page}` : `${year}`;
 ---
-<a href={`${baseUrl}references#${key}`} class="cite" title={entry.title ?? key}>
+<a href={`${referencesHref}#${key}`} class="cite" title={entry.title ?? key}>
   {authorText} ({yearText})
 </a>

package/components/ExerciseSolutions.astro

@@ -30,6 +30,10 @@
  *
  * Family: book-genre (cross-profile).
  */
+import bookConfig from 'virtual:book-scaffold/book-config';
+import { normalizeBase } from '../src/lib/nav-href';
+import { corpusBookIdFromPath, selectBookArtifact } from '../src/lib/corpus';
+
 interface Props {
   /** v4.4.0: if true, auto-collect exercises from src/data/exercises.json
    *  (scoped to the current chapter via Astro.url.pathname). Default false
@@ -46,14 +50,24 @@ let autoError: string | null = null;
 
 if (auto) {
   const path = Astro.url.pathname;
-  const m = path.match(/^\/chapters\/([^/]+)\//);
-  chapterSlug = m ? m[1] : '';
+  const baseUrl = normalizeBase(import.meta.env.BASE_URL);
+  const relativePath = path.startsWith(baseUrl)
+    ? path.slice(baseUrl.length)
+    : path.replace(/^\/+/, '');
+  const currentBook = bookConfig.corpus
+    ? corpusBookIdFromPath(bookConfig.corpus, path, baseUrl)
+    : null;
+  const corpusMatch = currentBook
+    ? relativePath.match(new RegExp(`^chapters/${currentBook}/(.+?)/?$`))
+    : null;
+  const singleMatch = relativePath.match(/^chapters\/([^/]+)\//);
+  chapterSlug = corpusMatch ? corpusMatch[1] : singleMatch ? singleMatch[1] : '';
   if (!chapterSlug) {
     autoError = `<ExerciseSolutions auto /> requires a /chapters/<slug>/ URL; got ${path}.`;
   } else {
     // v4.4.0 fix: project-root-relative import via Vite's import.meta.glob
     // (the previous `../../../src/data/exercises.json` failed in node_modules contexts).
-    const exModules = import.meta.glob<{ default: Record<string, Array<{ id: string; problem: string }>> }>(
+    const exModules = import.meta.glob<{ default: unknown }>(
       '/src/data/exercises.json',
       { eager: true },
     );
@@ -61,7 +75,13 @@ if (auto) {
     if (!exEntry) {
       autoError = `src/data/exercises.json not found — run \`npx book-scaffold build-exercises\` first.`;
     } else {
-      exercises = exEntry.default[chapterSlug] ?? [];
+      const byChapter = selectBookArtifact<Record<string, Array<{ id: string; problem: string }>>>(
+        exEntry.default,
+        bookConfig.corpus,
+        currentBook,
+        'src/data/exercises.json',
+      );
+      exercises = byChapter[chapterSlug] ?? [];
     }
   }
 }

package/components/Flashcards.tsx

@@ -25,18 +25,23 @@ import { useEffect, useRef, useState } from 'preact/hooks';
 import { shuffle } from '../src/lib/exam-engine';
 import type { FlashcardRef } from '../src/lib/flashcards';
 
-const STORAGE_KEY = 'book:flashcards:known';
+const DEFAULT_STORAGE_KEY = 'book:flashcards:known';
 
 interface Props {
   /** Deck manifest (buildFlashcardDeck output) — card ids + fronts only. */
   deck: FlashcardRef[];
+  /**
+   * Persistence namespace. Corpus routes pass a base- and book-specific key
+   * so repeated local glossary ids never share or erase another book's state.
+   */
+  storageKey?: string;
 }
 
 type Phase = 'idle' | 'deck';
 
-function readKnown(): Set<string> {
+function readKnown(storageKey: string): Set<string> {
   try {
-    const raw = localStorage.getItem(STORAGE_KEY);
+    const raw = localStorage.getItem(storageKey);
     if (!raw) return new Set();
     const parsed = JSON.parse(raw);
     if (!Array.isArray(parsed)) return new Set();
@@ -46,15 +51,18 @@ function readKnown(): Set<string> {
   }
 }
 
-function writeKnown(known: Set<string>): void {
+function writeKnown(storageKey: string, known: Set<string>): void {
   try {
-    localStorage.setItem(STORAGE_KEY, JSON.stringify([...known]));
+    localStorage.setItem(storageKey, JSON.stringify([...known]));
   } catch {
     /* localStorage unavailable — keep in-memory state only */
   }
 }
 
-export default function Flashcards({ deck }: Props) {
+export default function Flashcards({ deck, storageKey = DEFAULT_STORAGE_KEY }: Props) {
+  if (typeof storageKey !== 'string' || storageKey.trim().length === 0) {
+    throw new Error('Flashcards: storageKey must be a non-empty string.');
+  }
   const [phase, setPhase] = useState<Phase>('idle');
   const [order, setOrder] = useState<string[]>([]);
   const [pos, setPos] = useState(0);
@@ -67,12 +75,12 @@ export default function Flashcards({ deck }: Props) {
     // Intersect the stored bucket with the CURRENT deck: a term deleted from
     // the glossary would otherwise inflate "marked known" forever (even past
     // deck.length) — evict stale ids on mount and persist the cleaned set.
-    const stored = readKnown();
+    const stored = readKnown(storageKey);
     const deckIds = new Set(deck.map((c) => c.id));
     const cleaned = new Set([...stored].filter((id) => deckIds.has(id)));
-    if (cleaned.size !== stored.size) writeKnown(cleaned);
+    if (cleaned.size !== stored.size) writeKnown(storageKey, cleaned);
     setKnown(cleaned);
-  }, []);
+  }, [deck, storageKey]);
 
   function requireRoot(): HTMLElement {
     const r = ref.current?.closest<HTMLElement>('[data-flashcards-root]');
@@ -138,7 +146,7 @@ export default function Flashcards({ deck }: Props) {
     if (knewIt) next.add(id);
     else next.delete(id);
     setKnown(next);
-    writeKnown(next);
+    writeKnown(storageKey, next);
     if (pos < order.length - 1) goTo(pos + 1);
     else end();
   }
@@ -159,7 +167,7 @@ export default function Flashcards({ deck }: Props) {
   function resetKnown(): void {
     const next = new Set<string>();
     setKnown(next);
-    writeKnown(next);
+    writeKnown(storageKey, next);
   }
 
   if (deck.length === 0) {