@brandon_m_behring/book-scaffold-astro 4.26.2 → 4.27.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
-  "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "4.26.2",
+  "description": "Astro 6 + MDX toolkit for long-form technical books with five typed presets, Tufte typography, citations, search, PDF, and Cloudflare deployment.",
+  "version": "4.27.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -161,9 +161,11 @@
     "pedagogy",
     "examples",
     "CLAUDE.md",
+    "AGENTS.md",
     "README.md",
-    "LATEX_TO_MDX_MAPPING.md",
-    "examples"
+    "LICENSE",
+    "LICENSE-CONTENT",
+    "LATEX_TO_MDX_MAPPING.md"
   ],
   "scripts": {
     "build": "tsup",
@@ -195,6 +197,7 @@
     "@fontsource-variable/roboto": "^5.2.10",
     "@fontsource-variable/source-code-pro": "^5.2.7",
     "pagefind": "^1.5.2",
+    "vite": "^7.3.2",
     "yaml": "^2.9.0"
   },
   "devDependencies": {

package/pages/answers.astro

@@ -26,6 +26,7 @@ import { render } from 'astro:content';
 import bookConfig from 'virtual:book-scaffold/book-config';
 import { getAllQuestions, groupByChapter } from '../src/lib/questions';
 import { assertKnownDomain } from '../src/lib/exam-domains';
+import { normalizeBase } from '../src/lib/nav-href';
 
 // Presence-gate: only touch the collection when the directory holds files.
 const questionModules = import.meta.glob('/src/content/questions/**/*.{md,mdx}', {
@@ -51,7 +52,7 @@ const rendered = await Promise.all(
 const byChapter = groupByChapter(rendered);
 const total = rendered.length;
 // #142: practice-exam + chapter links must prefix the deploy base.
-const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 const practiceHref = (bookConfig.enabledRoutes ?? []).includes('practiceExam')
   ? `${baseUrl}practice-exam`
   : null;

package/pages/chapters.astro

@@ -26,9 +26,10 @@ import { getAllChapters, type Chapter } from '../src/lib/chapters';
 import { PROFILES } from '../src/profiles/index';
 import { fallbackChaptersRenderer } from '../src/profiles/renderers/fallback-chapters';
 import type { ChaptersRenderer, PartKey } from '../src/lib/chapters-renderer';
+import { normalizeBase } from '../src/lib/nav-href';
 
 // #142: prefix BASE_URL so chapter-card links stay inside a non-root deploy base.
-const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 
 const profileName = (import.meta.env.BOOK_PROFILE ?? 'minimal') as keyof typeof PROFILES;
 const profileDef = PROFILES[profileName];

package/pages/exercises.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 (same lesson as tips.astro). `/src/data/...` is consumer-project-
@@ -28,7 +29,7 @@ const chapters = Object.keys(byChapter).sort();
 const total = chapters.reduce((sum, c) => sum + byChapter[c].length, 0);
 
 // #142: chapter deep-links must prefix the deploy base.
-const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 ---
 <Base title="Exercises" description="All exercises in this book, grouped by chapter with deep links.">
   <article class="prose">

package/pages/index.astro

@@ -34,15 +34,16 @@
  */
 import Base from '../layouts/Base.astro';
 import bookConfig from 'virtual:book-scaffold/book-config';
+import { normalizeBase } from '../src/lib/nav-href';
 
 const title = bookConfig.title ?? 'book-scaffold-astro';
 const description = bookConfig.description;
 const portfolio = bookConfig.portfolio;
 const enabledRoutes = bookConfig.enabledRoutes;
 
-// Astro guarantees BASE_URL carries a trailing slash ('/' or '/foo/'), so
-// `${baseUrl}chapters/` resolves correctly under any deploy base (#142).
-const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+// Astro accepts bases with or without a trailing slash. Route every value
+// through the shared helper before composing links (#142, #182).
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 
 // Map from internal route name → display label + URL. Only routes that
 // produce a single landing-list entry are listed here (frontmatter is a

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
 });
 ```
@@ -122,7 +122,8 @@ Different fields have different merge semantics. Documented:
 
 | Field | Strategy |
 |---|---|
-| `name`, `preset`, `site`, `deploy`, `mdxComponentsModule` | Shallow override (last wins) |
+| `name`, `preset`, `site`, `deploy`, `mdxComponentsModule` | Shallow override (last defined wins) |
+| `releaseStatus` | Shallow override (last defined object replaces the whole earlier object); `false` suppresses an inherited banner |
 | `routes` | Per-route spread (each route key independently overridable) |
 | `routes.frontmatter` | Per-route spread; later value (boolean OR object) wholly replaces earlier |
 | `katexMacros` | Object spread (per-macro override) |
@@ -157,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).
 
 ---