@brandon_m_behring/book-scaffold-astro 4.26.3 → 4.27.0

package/pages/search.astro

@@ -11,10 +11,11 @@
  * `astro dev`. See README for dev-search workflow.
  */
 import Base from '../layouts/Base.astro';
+import { normalizeBase } from '../src/lib/nav-href';
 
 // #142: Pagefind writes its bundle to dist/pagefind/, served under the deploy
 // base — so the asset URLs must prefix BASE_URL or they 404 under a non-root base.
-const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 ---
 
 <Base

package/pages/tips.astro

@@ -10,6 +10,7 @@
  * page (doesn't fail the build).
  */
 import Base from '../layouts/Base.astro';
+import { normalizeBase } from '../src/lib/nav-href';
 
 // 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
@@ -27,7 +28,7 @@ const loadError = tipsEntry
   : 'src/data/tips.json not found — run `npx book-scaffold build-tips` to generate.';
 
 // #142: chapter back-links must prefix the deploy base.
-const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 ---
 <Base title="Tips" description="Numbered tips from this book, drawn from <Tip> instances in chapters.">
   <article class="prose">

package/recipes/01-add-math.md

@@ -1,27 +1,26 @@
 # Recipe 01 — Add math to your book (KaTeX)
 
-**Profile**: academic (gated by `BOOK_PROFILE=academic`)
+**Profiles**: academic + research-portfolio (the presets that flag `katex: true`)
 
-**TL;DR**: Math is wired but disabled by default. Set `BOOK_PROFILE=academic` and the build adds `remark-math` + `rehype-katex` (strict mode) with the SSM macro library at `src/lib/katex-macros.ts`.
+**TL;DR**: Math is wired but profile-gated. Compose your book from `academicStyle` (or `researchPortfolioStyle`) and `defineBookConfig` adds `remark-math` + `rehype-katex` (strict mode) with the scaffold's 37-macro `ssmMacros` library. Extend per-book with `defineBookConfig({ katexMacros })` — never by editing package source.
 
 ## How it works
 
-The conditional integration lives at the top of `astro.config.mjs`:
-- Reads `process.env.BOOK_PROFILE ?? 'minimal'`
-- For `academic`: dynamically imports `remark-math`, `rehype-katex`, and `ssmMacros`; adds them to the markdown pipeline
-- KaTeX CSS (`katex/dist/katex.min.css`) is always loaded by `Base.astro` — academic books need it; minimal/tools books carry the cost (~60 KB) without rendering math (the CSS is inert without matching DOM)
+All the wiring lives inside the package (`defineBookConfig`), not in your config file:
+
+- `defineBookConfig` resolves the composed preset from your `styles` chain (falling back to `BOOK_PRESET`/`BOOK_PROFILE` from the environment or `.env`).
+- For katex-flagged presets it dynamically imports `remark-math` + `rehype-katex` and registers them with `strict: 'error'` and the merged macro set (`ssmMacros` + your `katexMacros`).
+- The integration injects `katex/dist/katex.min.css` **only** for katex presets (`package/src/integration.ts`) — tools/minimal books don't carry the ~60 KB.
+- `katex`, `remark-math`, `rehype-katex` are **optional peerDependencies**: math books install them (`npm i katex remark-math rehype-katex`); other profiles skip them entirely.
 
 ## Enable math in your book
 
-1. Set `BOOK_PROFILE=academic` at run time:
-   ```bash
-   BOOK_PROFILE=academic npm run dev      # local hot-reload
-   BOOK_PROFILE=academic npm run build    # production build
-   ```
-   Or persist it in `.env`:
-   ```
-   BOOK_PROFILE=academic
+1. Use a katex preset in `astro.config.mjs` (a fresh `create-book --preset=academic` scaffold already does):
+   ```js
+   import { defineBookConfig, academicStyle } from '@brandon_m_behring/book-scaffold-astro';
+   export default await defineBookConfig({ styles: [academicStyle], site: 'https://…' });
    ```
+   Keep `.env`'s `BOOK_PRESET`/`BOOK_PROFILE` in sync — the content-collection schemas resolve the preset from it.
 
 2. Author math in MDX with `$...$` (inline) and `$$...$$` (display):
    ```mdx
@@ -33,39 +32,52 @@ The conditional integration lives at the top of `astro.config.mjs`:
    $$
    ```
 
-3. Strict mode is on by default (`strict: 'error'` in `rehypeKatex` options). Unknown macros, malformed expressions, and unsupported AMS environments fail the build with a precise error. This is intentional — catch typos at write-time, not in production.
+3. Strict mode is on by default (`strict: 'error'`). Unknown macros, malformed expressions, and unsupported AMS environments fail the build with a precise error. This is intentional — catch typos at write-time, not in production.
 
 ## Macro library
 
-`src/lib/katex-macros.ts` defines 36 macros:
+The package ships `ssmMacros` — **37 macros** (`package/src/lib/katex-macros.ts`):
+
 - 20 SSM-specific from the post-transformers academic reference: `\statevec`, `\statemat`, `\inputmat`, `\outputmat`, `\feedmat`, `\stepsize`, `\discA`, `\discB`, `\seqlen`, `\statedim`, `\inputdim`, `\scanop`, `\elemwise`, `\monodromy`, `\floquet`, `\lyapexp`, `\jacobian`, `\ddt`, `\pderiv`, `\spectralradius`
 - 16 general math: `\R`, `\C`, `\N`, `\Z`, `\E`, `\Prob`, `\norm`, `\ip`, `\abs`, `\argmax`, `\argmin`, `\diag`, `\tr`, `\spec`, `\rank`, `\bigO`
 - 1 compatibility alias: `\bm` → `\boldsymbol` (KaTeX doesn't ship `\bm`)
 
-To extend for your book, edit `src/lib/katex-macros.ts` and add new entries to the `ssmMacros` object:
+**Read or spread it** (v4.27.0+, #177) — from the main entry, or the `./lib` subpath:
+
 ```ts
-export const ssmMacros = {
-  // existing macros...
-  '\\mybook': '\\mathbb{B}',           // 0-arg macro
-  '\\myfunc': '\\mathrm{my}(#1)',      // 1-arg macro
-};
+import { ssmMacros } from '@brandon_m_behring/book-scaffold-astro';
+```
+
+**Extend for your book — the supported path** (#22). `katexMacros` is shallow-merged **on top of** `ssmMacros`, so your entries win on collision:
+
+```js
+export default await defineBookConfig({
+  styles: [academicStyle],
+  site: 'https://…',
+  katexMacros: {
+    '\\ate': '\\tau',                 // 0-arg macro
+    '\\propensity': 'e(#1)',          // 1-arg macro
+  },
+});
 ```
 
+Do **not** edit `katex-macros.ts` — it lives inside `node_modules` and your changes vanish on the next install. If a macro is general enough for every book, file an issue instead.
+
 ## Common gotchas
 
 - **`\bm{x}` doesn't ship with KaTeX.** The macro library aliases it to `\boldsymbol{x}` (visually identical in stix-two / Computer Modern fonts).
 - **`\psmallmatrix` not supported by KaTeX.** Convert to `\begin{pmatrix} ... \end{pmatrix}` in your MDX source.
-- **Equation auto-numbering across a document is not supported by KaTeX.** Each `$$...$$` block is independent. Use `\tag{N}` for explicit numbering, or a per-chapter remark plugin (deferred; see PROFILES_DESIGN.md §6).
+- **Equation auto-numbering across a document is not supported by KaTeX.** Each `$$...$$` block is independent. Use `\tag{N}` for explicit numbering; a per-chapter remark plugin is tracked as #146.
 - **`{,}` (LaTeX thousands separator) breaks MDX** — MDX parses `{...}` as a JSX expression. Use `1,000` not `1{,}000`.
 - **Math inside JSX components needs care.** `<Theorem>$x^2$</Theorem>` works because remark-math runs after MDX parses JSX, but escape any `{` or `}` in arguments.
 
 ## Canonical files
 
-- `astro.config.mjs:14-32` — profile branch + plugin wiring
-- `src/lib/katex-macros.ts` — full macro library (36 entries)
-- `src/layouts/Base.astro:24-30` — KaTeX CSS import
-- `package.json` — `katex ^0.16`, `remark-math ^6`, `rehype-katex ^7` deps
+- `package/src/lib/katex-macros.ts` — the 37-entry `ssmMacros` library
+- `package/src/config.ts` — profile-gated remark/rehype wiring + the `katexMacros` merge
+- `package/src/integration.ts` — KaTeX CSS injection for katex presets
+- your `astro.config.mjs` — `styles: [academicStyle]` + optional `katexMacros`
 
 ## Reference implementation
 
-[`~/Claude/post_transformers/guides/web/`](../) at commit `111ba26` (math first wired) through `2eaef5d` (current). The reference book has 6 academic chapters using these macros and exercises every edge case the scaffold supports.
+[`~/Claude/post_transformers/guides/web/`](../) — the academic reference book has 6 chapters using these macros and exercises every edge case the scaffold supports.

package/recipes/04-component-library.md

@@ -42,19 +42,29 @@ For full theorem-like environments (proof scaffolding, numbering), use `<Theorem
 
 ## Theorem family (academic profile)
 
-`src/components/Theorem.astro` — unified component for nine LaTeX-style environments via the `type` prop:
+`src/components/Theorem.astro` — unified component for nine LaTeX-style environments via the canonical `kind` prop (`type` remains a legacy alias):
 
 ```mdx
-<Theorem type="theorem" id="thm:zoh-stability" label="ZOH stability">
+<Theorem kind="theorem" id="thm:zoh-stability" name="ZOH stability">
 The bilinear discretization preserves stability iff $|\lambda \Delta t| < 1$.
 </Theorem>
 
-<Theorem type="proof">
+<Theorem kind="proof">
 Direct algebra on the bilinear map.
 </Theorem>
 ```
 
-Supported `type` values: `theorem`, `proposition`, `lemma`, `corollary`, `definition`, `example`, `exercise`, `remark`, `proof`. Each gets its own bar color and numbering counter.
+Supported kinds: `theorem`, `proposition`, `lemma`, `corollary`, `definition`, `example`, `exercise`, `remark`, `proof`. Each gets its own bar color. By default all kinds share one amsthm-style sequence, preserving the v4.26-and-earlier contract. To give each kind an independent sequence, set the persistent book/style option:
+
+```js
+export default await defineBookConfig({
+  styles: [academicStyle],
+  numberStyle: 'per-kind', // or declare it in a composed defineStyle(...)
+  site: 'https://example.invalid',
+});
+```
+
+`build-labels` evaluates the real Astro config and records the resolved strategy. An explicit `label=` override is custom and unnumbered, so it consumes no counter in either mode. Omission defaults to `shared`, including legacy projects with no resolvable scaffold integration.
 
 ## Utility components (any profile)
 

package/recipes/05-deploy-cloudflare.md

@@ -28,6 +28,50 @@
 
 URL: `https://<project-name>.<your-account>.workers.dev`.
 
+## Default security headers
+
+The scaffold integration emits `dist/_headers` at the end of every Astro
+build. Cloudflare Static Assets reads that file for both Workers and Pages
+deployments. The default applies:
+
+- `Strict-Transport-Security`
+- `X-Content-Type-Options`
+- `Referrer-Policy`
+- `Permissions-Policy`
+- `Content-Security-Policy`
+
+The CSP includes the allowances the shipped book UI needs: inline theme and
+drawer scripts, Astro inline component styles, Pagefind WebAssembly,
+Cloudflare Web Analytics, and images from the book itself, data URIs, or any
+HTTPS origin.
+
+Use a consumer file when you need route-specific rules or full ownership:
+
+```text
+# public/_headers
+/private/*
+  Cache-Control: no-store
+```
+
+Astro copies `public/_headers` to `dist/_headers`; the integration detects it
+and leaves it unchanged. To retain the four non-CSP defaults but replace the
+entire CSP, configure the book:
+
+```js
+export default await defineBookConfig({
+  styles: [academicStyle],
+  site: 'https://my-book.example',
+  securityHeaders: {
+    contentSecurityPolicy:
+      "default-src 'self'; img-src 'self' data: https://images.example; object-src 'none'",
+  },
+});
+```
+
+That value is a complete replacement, not an additive fragment. Set
+`securityHeaders: false` if the deployment platform or another integration
+owns the headers and you do not ship `public/_headers`.
+
 ## The `cd` prefix for monorepo Astro projects
 
 When `wrangler.toml` lives in a subdirectory (e.g. `guides/web/wrangler.toml`), Cloudflare runs commands from the repo root by default. Wrangler can't find its config there → deploy fails with "Could not detect a directory containing static files".

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

@@ -2,11 +2,11 @@
 
 **Profile**: any (layout is profile-agnostic; sidebar groups chapters differently per profile).
 
-**TL;DR**: Three-tier Tufte width (65/80/90ch) + 28/24/26ch sidenote column + left chapter-nav sidebar at ≥1024px. Mobile (<48rem) collapses to single column with inline sidenote asides; sidebar hides. All pure CSS, zero JS.
+**TL;DR**: Three-tier Tufte width (65/80/90ch) + 28/24/26ch sidenote column + left chapter-nav sidebar at ≥1024px. Mobile (<48rem) collapses to single column with inline sidenote asides; sidebar hides. The layout is pure CSS; optional chrome controls hydrate independently.
 
 ## The three layers
 
-1. **Floating chrome** (top-right, `position: fixed`): theme toggle + search + tools-profile islands (`ToolFilter`, `VersionSelector`) when `BOOK_PROFILE !== 'academic'`.
+1. **Floating chrome** (top-right, `position: fixed`): theme toggle + search + the `ToolFilter` island when `BOOK_PROFILE !== 'academic'`. `VersionSelector` is manual opt-in because its links must come from a real deployment manifest (see below).
 2. **Left sidebar** (`Sidebar.astro`): chapter nav grouped by part. Sticky to top, ≤100vh, independently scrollable. Hidden below 64rem (1024px).
 3. **Main content** (`.prose`): Tufte 2-column. Main text at `--measure-main`, sidenote column at `--measure-side`, both responsive to viewport tier.
 
@@ -45,6 +45,29 @@ Re-tune with Playwright + `browser_take_screenshot` at the four viewports above
 
 Default is `showSidebar={true}`. Set it false on full-bleed surfaces — landing pages, splash screens, search results — that have no chapter context (`Base.astro` still emits the page's single `<main>` landmark in that branch). Every chapter route inherits the default (true).
 
+## Opt-in version selector
+
+`Base.astro` does not mount a version selector or manufacture version URLs. If
+your deployment publishes multiple versions, mount the exported Preact island
+where your book's navigation belongs and pass the real destinations directly:
+
+```astro
+---
+import VersionSelector from '@brandon_m_behring/book-scaffold-astro/components/VersionSelector';
+
+const versions = [
+  { href: '/', label: 'Latest', date: '2026-07-13', current: true },
+  { href: '/versions/v4.26/', label: 'v4.26', date: '2026-06-30' },
+];
+---
+
+<VersionSelector versions={versions} client:idle />
+```
+
+Each entry requires `href`, `label`, and `date`; `current` is optional. An
+omitted or empty `versions` array renders nothing, so incomplete deployment
+metadata cannot turn placeholder releases into live navigation.
+
 ## Customizing the sidebar
 
 `Sidebar.astro` reads `import.meta.env.BOOK_PROFILE` to decide grouping:

package/recipes/09-validation.md

@@ -2,7 +2,7 @@
 
 **Profile**: any (Cite checks skip under non-academic).
 
-**TL;DR**: `npm run validate` runs `scripts/validate.mjs` against all chapter MDX files. Catches typo'd bibkeys / XRef ids / Figure paths / internal links that `astro build` would either miss or surface with poor context. Auto-runs as `prebuild`; recommend wiring into pre-commit too.
+**TL;DR**: `npm run validate` runs `scripts/validate.mjs` against all chapter MDX files. It first regenerates missing `labels.json` and `references.json`, then catches typo'd bibkeys / XRef ids / Figure paths / internal links that `astro build` would either miss or surface with poor context. Auto-runs as `prebuild`; recommend wiring into pre-commit too.
 
 ## What gets checked
 
@@ -13,13 +13,19 @@
 | `<Figure src="/...">` file exists under `public/` | all | Figure.astro emits a broken-image icon for missing files; build doesn't fail. |
 | `[text](/internal-link)` resolves to known chapter slug or top-level route | all | Astro won't fail on dead internal links. Warning, not error (regex misses dynamic routes). |
 | `<CodeRef path="..." line={N} />` path exists + line in bounds | all, if `BOOK_REPO_ROOT` set | Catches stale line numbers after code refactors in the paired experiments/ repo. |
-| `<Theorem>` has a resolvable `kind=` (or legacy `type=`); an id'd theorem resolves in `labels.json` (#121, #126) | all | An absent kind throws at build with less context; an unindexed id silently renders the heading unnumbered. |
+| `<Theorem>` has a resolvable `kind=` (or legacy `type=`); an id'd theorem resolves in `labels.json`; a literal `n=` agrees with the index (#121, #126, #176) | all | An absent kind throws at build with less context; an unindexed id silently renders the heading unnumbered; a stale literal `n=` contradicts the heading/XRefs. Dynamic expressions and `label=` overrides are skipped. |
 | `<BookLink book= to=>` both present; `book=` registered in `siblingBooks` (#96) | all | Pre-flights the component's build-time throw across all files at once. |
 | Questions collection: unique `id`s + `domain` in `examDomains` (#112); `<Rationale appendix>` carries `for=` (#114, v4.21.0) | all, when `src/content/questions/` exists | Duplicate ids break the appendix/flashcards cross-ref key; an unregistered domain throws one-at-a-time at build; an appendix rationale without its anchor target throws at build. |
 | `los[].anchor` ↔ `{/* anchor: <slug> */}` prose markers agree both ways (#130, v4.20.0) | all, when frontmatter has `los:` | A declared objective whose prose marker is missing/misspelled (or an orphan marker) builds green otherwise — frontmatter↔prose drift only a hand audit would catch. |
 
 Validate also emits two **non-blocking shadow-route warnings** (exit code unaffected): a consumer-owned `src/pages/chapters/[...slug].astro` without `routes: { chapters: false }` (v4.6.0, #76), and a consumer-owned `src/pages/index.astro` without `routes: { landing: false }` (v4.20.0, #129 — Astro has announced this collision becomes a hard error). See [recipe 18](./18-chapter-route-ownership.md).
 
+## Missing generated artifacts
+
+`src/data/labels.json` and `src/data/references.json` are derived and normally gitignored. v4.27+ `validate` self-heals either missing file unconditionally by invoking the package's own `build-labels` or `build-bib` command before loading data. Existing files are untouched. A failed child command stops validation with the child's original diagnostic and exit status.
+
+`build-bib` resolves `BOOK_BIB_PATH` from the process environment first, then the project-root `.env`, then `./bibliography.bib`. A project with no bibliography still gets a deterministic empty `references.json`.
+
 ## What is NOT checked (already covered elsewhere)
 
 - **Frontmatter Zod validation** — `astro build` syncs content collections first; Zod errors there.
@@ -34,8 +40,9 @@ The validator's job is to fill the gaps `astro build` leaves, not duplicate it.
 // package.json
 {
   "scripts": {
-    "validate": "node scripts/validate.mjs",
-    "prebuild": "npm run build:assets && npm run validate"
+    "prevalidate": "npm run build:bib --if-present && npm run build:labels --if-present",
+    "validate": "book-scaffold validate",
+    "prebuild": "npm run validate --if-present"
   }
 }
 ```
@@ -61,7 +68,9 @@ For pre-commit: add to `.pre-commit-config.yaml`:
 
 ## Preset / chaptersBase resolution (v4.7.0+, #75)
 
-The validator resolves both `preset` and `chaptersBase` by consulting multiple sources in a documented order. Notable v4.7.0 addition: the v4.5+ canonical form
+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. 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.
+
+`chaptersBase` resolution still consults `BOOK_CHAPTERS_DIR`, content configuration, then `src/content/chapters`. The v4.5+ canonical form is:
 
 ```ts
 // src/content.config.ts
@@ -80,13 +89,13 @@ Full precedence chain documented in [`PACKAGE_DESIGN.md §8 — Preset + chapter
 Exit code = total error count. On success:
 
 ```
-validate: ✓ 6 chapter(s) checked (profile=academic); no errors.
+validate: ✓ 6 chapter(s) checked (profile=academic, number-style=shared); no errors.
 ```
 
 On failure, all issues listed at once with `file:line msg`:
 
 ```
-validate: ✗ 17 error(s) in 6 chapter(s) (profile=academic):
+validate: ✗ 17 error(s) in 6 chapter(s) (profile=academic, number-style=shared):
   week05.mdx:102  Unknown XRef id "w4:prop:zoh-stability" — not in labels.json
   week11.mdx:37  Unknown XRef id "ch:week13" — not in labels.json
   ...
@@ -115,13 +124,13 @@ Keep the script regex-based; resist the urge to pull in MDX AST parsing. The scr
 
 - **Regex false negatives**: multi-line `<Cite\n  key="...">` won't match. Authors should keep component attributes on one line; the build catches the residual cases.
 - **`<Figure src>` with `BOOK_FIGURES_PATH` override**: the validator checks `public/figures/<...>` (post-build location), not the source `figures/` directory. Run `npm run build:figures` before `npm run validate` if assets are stale.
-- **`labels.json` empty**: every XRef fires an error. Until you have a labels-building step (Phase 2.6 in post-transformers, deferred at scaffold v2.0), avoid `<XRef>` in chapter content — use direct markdown links instead.
+- **`labels.json` exists but is stale**: self-healing only regenerates missing artifacts. Run `npm run build:labels` after changing IDs, kinds, slugs, or `numberStyle`.
 
 ## Canonical files
 
 - `scripts/validate.mjs` — the validator
 - `src/data/references.json` — emitted by `scripts/build-bib.mjs` (recipe 02)
-- `src/data/labels.json` — placeholder; populated by future labels-building step
+- `src/data/labels.json` — emitted by `scripts/build-labels.mjs`
 - `src/components/{Cite,XRef,Figure,CodeRef}.astro` — components whose contracts validate.mjs enforces
 
 ## Reference implementation

package/recipes/15-defining-styles.md

@@ -46,7 +46,7 @@ defineStyle({
   extraIntegrations?: readonly AstroIntegration[];
   mdxComponentsModule?: string;
   markdown?: AstroUserConfig['markdown'];
-  deploy?: 'pages' | 'workers';      // v4.0.0 NEW (#50)
+  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
 });
 ```
@@ -158,7 +158,10 @@ defineBookConfig({ styles: [researchPortfolioStyle], ... });
 defineBookConfig({ styles: [BUILTIN_STYLES['research-portfolio']], ... });
 ```
 
-Each built-in style has a `name` matching its preset, a `preset` field, and sane `deploy` defaults (academic/tools/minimal → 'workers'; course-notes/research-portfolio → 'pages').
+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).
 
 ---
 

package/recipes/19-prevalidate-hook.md

@@ -1,113 +1,59 @@
-# Recipe 19 — `prevalidate` npm hook (v4.6.0+)
+# Recipe 19 — generated data before validation (v4.27+)
 
-`book-scaffold validate` checks `<Cite key="...">` against `src/data/references.json` (academic profile) and `<XRef id="...">` against `src/data/labels.json`. Both JSON files are **derived artifacts** regenerated from `bibliography.bib` + chapter MDX by `book-scaffold build-bib` + `book-scaffold build-labels`. Both are gitignored.
+`book-scaffold validate` checks citations and cross-references against two derived, normally gitignored files:
 
-When `npm run validate` runs **standalone** (e.g., a reusable deploy workflow runs only the validate command, without the full `npm run build` chain), the prereq scripts don't fire and the validator chokes on apparently-missing keys.
+- `src/data/references.json`, emitted by `book-scaffold build-bib`
+- `src/data/labels.json`, emitted by `book-scaffold build-labels`
 
-The `prevalidate` npm lifecycle hook is the canonical fix: it auto-runs the prereqs whenever `npm run validate` is invoked, regardless of how validate is called.
-
----
-
-## TL;DR
-
-```json
-{
-  "scripts": {
-    "prevalidate": "npm run build:bib && npm run build:labels --if-present",
-    "validate": "book-scaffold validate"
-  }
-}
-```
-
-`npm run validate` → automatically runs `prevalidate` first (build:bib + build:labels) → then runs `validate`. CI and local behave identically; no separate `ci:validate` wrapper script needed.
-
----
-
-## Why the workaround was needed
-
-`brandon-behring/deploy-workflows@v1` (the reusable Cloudflare Workers deploy) runs `npm run <validate-command>` between `npm ci` and `npm run build`. Without the `prevalidate` hook OR an explicit wrapper script, the validate step ran against missing artifacts.
-
-The Phase 1c first-deploy of `ssm-foundations` (2026-05-26) hit this — validate emitted 25+ "Unknown bibkey" errors that pointed at chapter content instead of the missing `references.json` artifact. The deploy-time fix shipped as a `ci:validate` wrapper:
+Every profile can use theorem/Figure IDs and XRefs, so every generated book now carries the same npm lifecycle:
 
 ```json
 {
   "scripts": {
-    "ci:validate": "npm run build:bib && npm run build:labels --if-present && npm run validate"
+    "prevalidate": "npm run build:bib --if-present && npm run build:labels --if-present",
+    "validate": "book-scaffold validate",
+    "prebuild": "npm run validate --if-present"
   }
 }
 ```
 
-…with `validate-command: ci:validate` in `.github/workflows/deploy.yml`. This worked but introduced consumer-side ceremony for what is structurally a scaffold-level convention.
-
-The cleaner long-term fix is the `prevalidate` npm-lifecycle hook (this recipe). v4.6.0's `create-book` automatically scaffolds it for academic + research-portfolio profiles.
-
----
+`npm run validate` runs `prevalidate` automatically. `npm run build` runs `prebuild`, which delegates to that same path. Academic, tools, minimal, course-notes, and research-portfolio scaffolds use this identical contract.
 
-## Migration: from `ci:validate` to `prevalidate`
+## Direct CLI calls self-heal too
 
-Existing consumers (DML, ssm, dlai when it ships) that adopted the `ci:validate` wrapper during 2026-05-26 deploys can migrate when they bump to scaffold `^4.6.0`. Three-file mechanical change per consumer:
+An npm hook cannot protect `npx book-scaffold validate` or a direct bin invocation. Starting in v4.27, the validator itself regenerates each missing artifact before loading it:
 
-### 1. `package.json` — rename `ci:validate` → `prevalidate`
+1. Missing `labels.json` invokes `build-labels`.
+2. Missing `references.json` invokes `build-bib`, even when no default `bibliography.bib` exists; that valid no-bibliography case emits `{}`.
+3. Existing files are not rewritten.
+4. A child failure stops validation and preserves the original child diagnostic and non-zero status.
 
-```diff
- {
-   "scripts": {
--    "ci:validate": "npm run build:bib && npm run build:labels --if-present && npm run validate",
-+    "prevalidate": "npm run build:bib && npm run build:labels --if-present",
-     "validate": "book-scaffold validate"
-   }
- }
-```
+This makes fresh checkouts deterministic without hiding stale existing data. After changing theorem IDs, kinds, slugs, bibliography entries, or `numberStyle`, explicitly rerun the corresponding build command.
 
-Note the renamed script no longer needs to call `validate` itself — npm's lifecycle invokes it automatically after `prevalidate` completes.
+## Bibliography path precedence
 
-### 2. `.github/workflows/deploy.yml` — revert `validate-command`
+Books with a shared or non-root bibliography can set:
 
-```diff
- jobs:
-   deploy:
-     uses: brandon-behring/deploy-workflows/.github/workflows/deploy-astro-worker.yml@v2
-     secrets: inherit
-     with:
-       working-directory: web
--      validate-command: ci:validate
-+      validate-command: validate
-       enable-pr-previews: true
+```dotenv
+BOOK_BIB_PATH=../shared/references.bib
 ```
 
-The reusable workflow's `validate-command` now points at the native `validate` script; the `prevalidate` hook handles its own prereqs transparently.
+`build-bib` resolves the process environment first, then the project-root `.env`, then `./bibliography.bib`. Relative paths are resolved from the book root. This same precedence applies when validation invokes `build-bib` during self-healing.
 
-### 3. Simplify `prebuild` (optional)
+## Migrating older consumers
 
-If the consumer's `prebuild` still has the long chain:
+Replace custom `ci:validate` wrappers and profile-conditional hooks with the uniform scripts above. A reusable deploy workflow can call the normal `validate` script; no wrapper needs to repeat the artifact chain.
 
 ```diff
  {
    "scripts": {
--    "prebuild": "npm run build:bib --if-present && npm run build:labels --if-present && npm run validate --if-present",
-+    "prebuild": "npm run validate --if-present",
-     "build": "astro build && pagefind --site dist"
+-    "ci:validate": "npm run build:bib && npm run build:labels && npm run validate",
++    "prevalidate": "npm run build:bib --if-present && npm run build:labels --if-present",
+     "validate": "book-scaffold validate",
+-    "prebuild": "npm run build:bib && npm run build:labels && npm run validate"
++    "prebuild": "npm run validate --if-present"
    }
  }
 ```
 
-Now `npm run build` → triggers `prebuild` (which runs `validate`) → triggers `prevalidate` (which runs the prereqs) → validate runs cleanly. Single source of truth for the prereq chain.
-
----
-
-## When `prevalidate` is NOT needed
-
-Profiles that don't run cite-key or XRef validation don't need `prevalidate`. Specifically:
-
-- `tools`, `minimal`: no `<Cite>` resolution against `references.json`.
-- `course-notes`: depends on whether the consumer uses `<Cite>` (some do for source-tier attribution).
-
-For these profiles, `book-scaffold validate` operates on chapter structure + XRef IDs only; `prevalidate` would be a no-op. The v4.6.0 create-book template adds `prevalidate` ONLY for academic + research-portfolio.
-
----
-
-## Why this matters
-
-Recipe 19 is part of [issue #76](https://github.com/brandon-behring/book-scaffold-astro/issues/76)'s v4.6 bundle. Companion: [recipe 18 — chapter-route ownership](./18-chapter-route-ownership.md), which fixes another silent-CI surface from the same Phase 1c first-deploys.
-
-The `prevalidate` convention also closes [issue #77](https://github.com/brandon-behring/book-scaffold-astro/issues/77) — the v4.6 validator now emits a single re-framed error pointing at this recipe when `references.json` is missing, replacing the noisy 25-symptom output.
+The historical profile split is intentionally gone: non-academic profiles still need labels, and an empty bibliography build is a supported no-op that creates the importable empty artifact.

package/scripts/build-bib.mjs

@@ -39,6 +39,7 @@
 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';
 
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold build-bib
@@ -49,7 +50,8 @@ AND sources/manifest.yaml -> src/data/sources.json (tools-profile sources for
 the /references page). Either input may be absent.
 
 Env:
-  BOOK_BIB_PATH      Override path to .bib file (default: ./bibliography.bib).
+  BOOK_BIB_PATH      Override path to .bib file (process env wins, then root
+                     .env; default: ./bibliography.bib).
 
 Options:
   --help, -h         Print this message and exit (non-mutating).
@@ -64,11 +66,13 @@ import '@citation-js/plugin-bibtex';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = process.cwd();
+const dotenv = readEnvFile(PROJECT_ROOT);
 
 // Default: bibliography.bib at scaffold root.
 // Override via BOOK_BIB_PATH=path/to/your.bib (absolute or relative to cwd).
-const BIB_PATH = process.env.BOOK_BIB_PATH
-  ? resolve(process.cwd(), process.env.BOOK_BIB_PATH)
+const configuredBibPath = process.env.BOOK_BIB_PATH ?? dotenv.BOOK_BIB_PATH;
+const BIB_PATH = configuredBibPath
+  ? resolve(PROJECT_ROOT, configuredBibPath)
   : resolve(PROJECT_ROOT, 'bibliography.bib');
 const OUT_PATH = resolve(PROJECT_ROOT, 'src/data/references.json');
 const SOURCES_PATH = resolve(PROJECT_ROOT, 'sources/manifest.yaml');