@brandon_m_behring/book-scaffold-astro 4.8.0 → 4.10.0

package/CLAUDE.md

@@ -25,6 +25,8 @@ When in doubt, run `grep BOOK_PROFILE .env astro.config.mjs src/content.config.t
 
 ## 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.
+
 ### Academic profile (`src/content.config.ts:academicChapterSchema`)
 
 ```yaml
@@ -34,6 +36,7 @@ part: foundations        # required: foundations|ssm-core|beyond-ssm|integration
 title: "..."             # string, required
 status: implemented      # required: implemented|chapter_only|prose_only|code_only|reading_only|scaffolded|planned
 # optional:
+slug: ch01-introduction  # clean URL override; else filename → /chapters/<slug>/
 roadmap_lines: [10, 42]  # [start, end] line refs into roadmap.md
 code_path: experiments/jax/week01/foo.py
 tests_path: experiments/jax/week01/test_foo.py
@@ -54,7 +57,7 @@ volatility: architectural-pattern  # required: stable-principle|architectural-pa
 tools_compared: [claude-code]      # required, ≥1 of: claude-code|gemini-cli|codex-cli|cross-tool
 last_verified: 2026-05-18          # date, required
 sources: []                        # array of source-manifest keys
-# optional: description, draft, updated
+# optional: slug (clean URL override), description, draft, updated
 ---
 ```
 

package/bin/book-scaffold.mjs

@@ -27,7 +27,7 @@ const HELP = `Usage: book-scaffold <sub-command> [args...]
 Sub-commands:
   validate           Pre-flight content validator (XRef ids, Cite keys, Figure srcs).
   build-labels       Emit src/data/labels.json for cross-references (Phase C).
-  build-bib          BibTeX -> CSL JSON for the <Cite> component.
+  build-bib          BibTeX -> references.json (+ sources/manifest.yaml -> sources.json).
   build-figures      PDF -> SVG via pdftocairo / pdftoppm fallback (+ TikZ in v4.2.0).
   build-tips         Scan chapters for <Tip> instances; emit src/data/tips.json (v4.3.0).
   build-exercises    Scan chapters for <Exercise> instances; emit src/data/exercises.json (v4.4.0).

package/components/SourceArchive.astro

@@ -3,14 +3,14 @@
  * SourceArchive — renders every entry in sources/manifest.yaml grouped
  * by tier in descending authority (T1 → T4).
  *
- * Used from Appendix D (`d-source-archive-index.mdx`) to replace the
- * static hand-maintained listing with an auto-generated view that
- * always reflects the manifest.
+ * Used by the auto-injected /references page (v4.10.0, #85) and by
+ * author-placed source-archive appendices, replacing a static hand-
+ * maintained listing with an auto-generated view that always reflects
+ * the manifest.
  *
  * Empty-tier behavior: renders an honest placeholder ("No sources at
- * this tier yet.") rather than hiding the section. This matches the
- * pedagogy of Appendix D — the archive is intentionally sparse in the
- * early book, and the gap is visible by design.
+ * this tier yet.") rather than hiding the section, so the tier taxonomy
+ * stays visible even before a tier has entries.
  */
 import { sourceTiers } from '@brandon_m_behring/book-scaffold-astro';
 import {
@@ -53,7 +53,7 @@ function year(d: Date | undefined): string | null {
 
         {empty ? (
           <p class="source-archive-empty">
-            No sources at this tier yet. Appendix D is intentionally sparse in the early book; this slot fills as chapters leave draft.
+            No sources at this tier yet.
           </p>
         ) : (
           <ol

package/components/XRef.astro

@@ -1,28 +1,31 @@
 ---
-/**
- * XRef — resolves a `\cref{label}` LaTeX reference to a hyperlink.
- *
- * Reads src/data/labels.json built by scripts/build-labels.mjs
- * (Phase 2.6). For each known id, the map provides:
- *   { href: "/chapters/week04#thm-w4-stability", display: "Theorem 4.2" }
- *
- * Runtime: renders `<a href>` for known ids; renders an inline `[?id]`
- * placeholder for unknown ids so the Astro dev server stays running while
- * chapters are being authored or labels are being added.
- *
- * CI: `book-scaffold validate` (Phase 2.6, shipped) catches unknown ids
- * and **fails the build with a non-zero exit code** before unresolved
- * placeholders can reach production. The placeholder is a dev-ergonomic
- * affordance, not a soft-degradation path on the deploy critical line.
- *
- * Bootstrapping note: when porting a book chapter-by-chapter, early
- * chapters that reference yet-to-be-ported targets need either plain-prose
- * substitutes or a temporarily-commented `{/* <XRef …/> */}` until the
- * target chapter (and its `id="…"` attributes) exists.
- *
- * Usage:
- *   By <XRef id="thm:w4:stability" />, the discretized eigenvalues …
- */
+// XRef — resolves a `\cref{label}` LaTeX reference to a hyperlink.
+//
+// Reads src/data/labels.json built by scripts/build-labels.mjs
+// (Phase 2.6). For each known id, the map provides:
+//   { href: "/chapters/week04#thm-w4-stability", display: "Theorem 4.2" }
+//
+// Runtime: renders `<a href>` for known ids; renders an inline `[?id]`
+// placeholder for unknown ids so the Astro dev server stays running while
+// chapters are being authored or labels are being added.
+//
+// CI: `book-scaffold validate` (Phase 2.6, shipped) catches unknown ids
+// and **fails the build with a non-zero exit code** before unresolved
+// placeholders can reach production. The placeholder is a dev-ergonomic
+// affordance, not a soft-degradation path on the deploy critical line.
+//
+// Bootstrapping note: when porting a book chapter-by-chapter, early
+// chapters that reference yet-to-be-ported targets need either plain-prose
+// substitutes or a temporarily-commented `{/* <XRef …/> */}` until the
+// target chapter (and its `id="…"` attributes) exists. MDX uses JSX-style
+// expression comments — the HTML `<` + bang + `--` form is NOT valid MDX.
+//
+// NB: these are `//` line comments, not a `/** */` block, on purpose — the
+// literal `*/` in the example above would otherwise close a block comment
+// early and break esbuild on every MDX import (the v4.9.0 fix).
+//
+// Usage:
+//   By <XRef id="thm:w4:stability" />, the discretized eigenvalues …
 type LabelEntry = { href: string; display: string };
 
 // Resolve labels.json from the consumer's project root (Vite resolves `/`

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Y as volatilityLevels, h as ChaptersRenderer, o as Style } from './types-DTQ2l6B6.js';
-export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, m as Provenance, R as ResearchPortfolioChapter, n as RouteToggles, S as StatusBadge, p as StyleInput, T as ToolsChapter, V as VolatilityBadge, q as academicChapterSchema, r as academicParts, s as changeKinds, t as changelogSchema, u as chapterStatus, v as citationBackstops, w as composeStyles, x as courseNotesChapterSchema, y as defineProfile, z as defineStyle, D as minimalChapterSchema, E as normalizeFrontmatterConfig, G as patternCategories, H as patternsSchema, I as provenanceObject, J as provenanceSchema, K as researchPortfolioChapterSchema, L as resolvePreset, N as resolveProfile, O as sourceTiers, Q as sourceTiersResearch, U as sourcesSchema, W as toolSlugs, X as toolsChapterSchema } from './types-DTQ2l6B6.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Y as volatilityLevels, h as ChaptersRenderer, o as Style } from './types-CULHImU4.js';
+export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, m as Provenance, R as ResearchPortfolioChapter, n as RouteToggles, S as StatusBadge, p as StyleInput, T as ToolsChapter, V as VolatilityBadge, q as academicChapterSchema, r as academicParts, s as changeKinds, t as changelogSchema, u as chapterStatus, v as citationBackstops, w as composeStyles, x as courseNotesChapterSchema, y as defineProfile, z as defineStyle, D as minimalChapterSchema, E as normalizeFrontmatterConfig, G as patternCategories, H as patternsSchema, I as provenanceObject, J as provenanceSchema, K as researchPortfolioChapterSchema, L as resolvePreset, N as resolveProfile, O as sourceTiers, Q as sourceTiersResearch, U as sourcesSchema, W as toolSlugs, X as toolsChapterSchema } from './types-CULHImU4.js';
 import 'astro/zod';
 
 /**

package/dist/index.mjs

@@ -184,6 +184,8 @@ var academicChapterSchema = z.object({
   week: z.number().int().min(1).max(99),
   part: z.enum(academicParts),
   title: z.string().min(1),
+  slug: z.string().optional(),
+  // v4.9.0: explicit URL slug override (else filename → entry.id)
   status: z.enum(chapterStatus),
   roadmap_lines: z.tuple([z.number().int(), z.number().int()]).optional(),
   code_path: z.string().optional(),
@@ -203,6 +205,8 @@ var academicChapterSchema = z.object({
 });
 var toolsChapterSchema = z.object({
   title: z.string().min(1),
+  slug: z.string().optional(),
+  // v4.9.0: explicit URL slug override (else filename → entry.id)
   part: z.number().int().min(0).max(10),
   chapter: z.number().int().min(0).max(99),
   volatility: z.enum(volatilityLevels),
@@ -226,6 +230,8 @@ var sourceTiersResearch = ["T1", "T2", "T3", "T4"];
 var courseNotesChapterSchema = z.object({
   // Identity
   title: z.string().min(1),
+  slug: z.string().optional(),
+  // v4.9.0: explicit URL slug override (else filename → entry.id)
   chapter: z.number().int().min(0).max(99),
   part: z.number().int().min(0).max(20).default(1),
   description: z.string().optional(),

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import { defineCollection } from 'astro:content';
-import { g as BookSchemasOptions } from './types-DTQ2l6B6.js';
+import { g as BookSchemasOptions } from './types-CULHImU4.js';
 import 'astro';
 import 'astro/zod';
 

package/dist/schemas.mjs

@@ -68,6 +68,8 @@ var academicChapterSchema = z.object({
   week: z.number().int().min(1).max(99),
   part: z.enum(academicParts),
   title: z.string().min(1),
+  slug: z.string().optional(),
+  // v4.9.0: explicit URL slug override (else filename → entry.id)
   status: z.enum(chapterStatus),
   roadmap_lines: z.tuple([z.number().int(), z.number().int()]).optional(),
   code_path: z.string().optional(),
@@ -87,6 +89,8 @@ var academicChapterSchema = z.object({
 });
 var toolsChapterSchema = z.object({
   title: z.string().min(1),
+  slug: z.string().optional(),
+  // v4.9.0: explicit URL slug override (else filename → entry.id)
   part: z.number().int().min(0).max(10),
   chapter: z.number().int().min(0).max(99),
   volatility: z.enum(volatilityLevels),
@@ -110,6 +114,8 @@ var sourceTiersResearch = ["T1", "T2", "T3", "T4"];
 var courseNotesChapterSchema = z.object({
   // Identity
   title: z.string().min(1),
+  slug: z.string().optional(),
+  // v4.9.0: explicit URL slug override (else filename → entry.id)
   chapter: z.number().int().min(0).max(99),
   part: z.number().int().min(0).max(20).default(1),
   description: z.string().optional(),

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.8.0",
+  "version": "4.10.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -142,15 +142,21 @@
     "test": "node --test tests/*.test.mjs"
   },
   "peerDependencies": {
-    "astro": "^6.1.7",
     "@astrojs/mdx": "^5.0.3",
     "@astrojs/preact": "^5.1.1",
+    "astro": "^6.1.7",
     "preact": "^10.29.1"
   },
   "peerDependenciesMeta": {
-    "katex": { "optional": true },
-    "rehype-katex": { "optional": true },
-    "remark-math": { "optional": true }
+    "katex": {
+      "optional": true
+    },
+    "rehype-katex": {
+      "optional": true
+    },
+    "remark-math": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@astrojs/sitemap": "^3.6.1",
@@ -158,7 +164,8 @@
     "@citation-js/plugin-bibtex": "^0.7.21",
     "@fontsource-variable/roboto": "^5.2.10",
     "@fontsource-variable/source-code-pro": "^5.2.7",
-    "pagefind": "^1.5.2"
+    "pagefind": "^1.5.2",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/pages/references.astro

@@ -1,16 +1,22 @@
 ---
 /**
- * /references — the book's bibliography page.
+ * /references — the book's bibliography + cited-sources page.
  *
- * Renders every entry in src/data/references.json (produced by
- * scripts/build-bib.mjs from guides/shared/references.bib). Each
- * entry gets an anchor ID matching its bibkey, so `<Cite key="gu2024mamba" />`
- * elsewhere on the site links to /references#gu2024mamba.
+ * Auto-injected on every profile (integration route table). Reads two
+ * independent inputs, each via a defensive `import.meta.glob` (missing file →
+ * empty, never a crash — same pattern <XRef> uses for labels.json):
  *
- * Sorted alphabetically by first-author surname, then by year.
- * arXiv-style notes are surfaced as direct links when present.
+ *   - src/data/references.json — BibTeX entries (academic), from build-bib.
+ *     Each entry's anchor matches its bibkey, so `<Cite key="…" />` links to
+ *     /references#<bibkey>.
+ *   - src/data/sources.json — sources/manifest.yaml entries (tools profile),
+ *     also from build-bib (v4.10.0, #85). Its presence is a profile-safe GATE
+ *     for the <SourceArchive> render: a falsy `&&` never instantiates the
+ *     component, so academic/minimal books (which have no `sources` content
+ *     collection) never call getCollection('sources').
  */
 import Base from '../layouts/Base.astro';
+import SourceArchive from '../components/SourceArchive.astro';
 
 type CslAuthor = { family?: string; given?: string; literal?: string };
 type CslEntry = {
@@ -29,8 +35,7 @@ type CslEntry = {
   note?: string;
 };
 
-// Resolve references.json from consumer's project root. Missing file -> empty
-// list (page renders an "empty bibliography" notice rather than crashing).
+// --- Bibliography: BibTeX → references.json (academic profile). ---
 const refsModules = import.meta.glob<{ default: Record<string, CslEntry> }>(
   '/src/data/references.json',
   { eager: true },
@@ -39,6 +44,18 @@ const refsModule = refsModules['/src/data/references.json'];
 const map = (refsModule?.default ?? {}) as Record<string, CslEntry>;
 const entries = Object.values(map);
 
+// --- Cited sources: sources/manifest.yaml → sources.json (tools profile).
+// Presence-only gate; the actual render reads the live `sources` collection
+// via <SourceArchive>, which only runs when this gate is true (so it is never
+// reached on profiles without a `sources` collection). ---
+const srcModules = import.meta.glob<{ default: unknown[] }>(
+  '/src/data/sources.json',
+  { eager: true },
+);
+const sourcesData = (srcModules['/src/data/sources.json']?.default ?? []) as unknown[];
+const hasSources = Array.isArray(sourcesData) && sourcesData.length > 0;
+const hasBib = entries.length > 0;
+
 const surname = (a: CslAuthor): string =>
   (a.family ?? a.literal ?? '').toLowerCase();
 
@@ -73,61 +90,95 @@ function arxivUrl(note?: string): string | null {
   const m = note.match(/arXiv:\s*(\S+)/i);
   return m ? `https://arxiv.org/abs/${m[1]}` : null;
 }
+
+const lede =
+  hasBib && hasSources
+    ? 'Every work cited in this book — the bibliography below, then the external sources grouped by tier.'
+    : hasBib
+      ? 'Every paper, book, and software citation in this book, sorted alphabetically by first-author surname. Click an entry’s anchor to share a deep link, or follow the arXiv / DOI / URL for the source.'
+      : hasSources
+        ? 'Every external source cited in this book, grouped by tier in descending authority.'
+        : 'This book has no references yet.';
 ---
-<Base
-  title="References — Post-Transformers"
-  description="Bibliography for the post_transformers guide, generated from guides/shared/references.bib."
->
+<Base title="References" description="Bibliography and cited sources for this book.">
   <article class="prose">
     <header>
       <h1>References</h1>
-      <p class="lede">
-        Every paper, book, and software citation in this guide, sorted
-        alphabetically by first-author surname. Click an entry's
-        anchor to share a deep link, or follow the arXiv / DOI / URL
-        for the source.
-      </p>
-      <p>
-        <small>
-          {entries.length} entries. Generated from
-          <code>guides/shared/references.bib</code> at build time via
-          <code>scripts/build-bib.mjs</code>.
-        </small>
-      </p>
+      <p class="lede">{lede}</p>
     </header>
 
-    <ol class="references-list">
-      {entries.map((e) => {
-        const y = year(e);
-        const arxiv = arxivUrl(e.note);
-        const primaryUrl = arxiv ?? e.URL ?? (e.DOI ? `https://doi.org/${e.DOI}` : null);
-        return (
-          <li id={e.id} class="reference-entry">
-            <span class="reference-key" aria-label="bibkey">[{e.id}]</span>
-            <span class="reference-text">
-              {formatAuthors(e.author)}
-              {y > 0 && <> ({y})</>}.
-              {' '}
-              <em>{e.title}</em>.
-              {e['container-title'] && <> {e['container-title']}.</>}
-              {e.publisher && !e['container-title'] && <> {e.publisher}.</>}
-              {e.volume && <> Vol. {e.volume}{e.issue && <>, no. {e.issue}</>}.</>}
-              {e.page && <> pp. {e.page}.</>}
-              {primaryUrl && (
-                <>
+    {!hasBib && !hasSources && (
+      <p class="references-empty">
+        No references yet. Add a <code>bibliography.bib</code> (academic) or
+        populate <code>sources/manifest.yaml</code> (tools), then run
+        <code>npm run build:bib</code>.
+      </p>
+    )}
+
+    {hasBib && (
+      <section class="references-bibliography">
+        {hasSources && <h2>Bibliography</h2>}
+        <ol class="references-list">
+          {entries.map((e) => {
+            const y = year(e);
+            const arxiv = arxivUrl(e.note);
+            const primaryUrl = arxiv ?? e.URL ?? (e.DOI ? `https://doi.org/${e.DOI}` : null);
+            return (
+              <li id={e.id} class="reference-entry">
+                <span class="reference-key" aria-label="bibkey">[{e.id}]</span>
+                <span class="reference-text">
+                  {formatAuthors(e.author)}
+                  {y > 0 && <> ({y})</>}.
                   {' '}
-                  <a href={primaryUrl} rel="external noopener">link</a>.
-                </>
-              )}
-            </span>
-          </li>
-        );
-      })}
-    </ol>
+                  <em>{e.title}</em>.
+                  {e['container-title'] && <> {e['container-title']}.</>}
+                  {e.publisher && !e['container-title'] && <> {e.publisher}.</>}
+                  {e.volume && <> Vol. {e.volume}{e.issue && <>, no. {e.issue}</>}.</>}
+                  {e.page && <> pp. {e.page}.</>}
+                  {primaryUrl && (
+                    <>
+                      {' '}
+                      <a href={primaryUrl} rel="external noopener">link</a>.
+                    </>
+                  )}
+                </span>
+              </li>
+            );
+          })}
+        </ol>
+      </section>
+    )}
+
+    {hasSources && (
+      <section class="references-sources">
+        <h2>Cited sources</h2>
+        <p class="references-sources-lede">
+          External sources cited inline via <code>&lt;Citation&gt;</code>, grouped
+          by tier in descending authority.
+        </p>
+        <SourceArchive />
+      </section>
+    )}
   </article>
 </Base>
 
 <style>
+  .references-empty {
+    color: var(--color-text-muted);
+    font-style: italic;
+    padding: var(--space-3);
+    background: var(--color-bg-subtle);
+    border-radius: var(--radius-sm);
+    text-indent: 0;
+  }
+  .references-sources {
+    margin-top: var(--space-6);
+  }
+  .references-sources-lede {
+    color: var(--color-text-muted);
+    font-size: var(--text-sm);
+    text-indent: 0;
+  }
   .references-list {
     list-style: none;
     padding: 0;

package/scripts/build-bib.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * scripts/build-bib.mjs — Bibliography pipeline (academic profile).
+ * scripts/build-bib.mjs — Bibliography + source-manifest pipeline.
  *
  * Reads bibliography.bib at scaffold root (BibTeX), parses via @citation-js,
  * emits src/data/references.json keyed by bibkey. The .bib path is
@@ -8,6 +8,12 @@
  * elsewhere (e.g. a shared `guides/shared/references.bib` outside the
  * Astro project — the post_transformers pattern).
  *
+ * v4.10.0 (#85): ALSO reads sources/manifest.yaml (tools-profile sources,
+ * cited inline via <Citation src>) and emits src/data/sources.json so the
+ * auto-injected /references page can surface them. The two steps are
+ * independent — a tools book with a manifest and no .bib still gets a
+ * populated /references.
+ *
  * Run on `prebuild` so every Astro build sees fresh bibliography data.
  * Idempotent: re-running with no .bib change produces a byte-identical
  * output (modulo timestamp, which we omit).
@@ -37,8 +43,10 @@ import { fileURLToPath } from 'node:url';
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold build-bib
 
-Bibliography pipeline (academic profile). Reads bibliography.bib (or
-BOOK_BIB_PATH if set), parses via @citation-js, emits src/data/references.json.
+Bibliography + source-manifest pipeline. Reads bibliography.bib (or
+BOOK_BIB_PATH if set) -> src/data/references.json (BibTeX via @citation-js),
+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).
@@ -63,8 +71,10 @@ const BIB_PATH = process.env.BOOK_BIB_PATH
   ? resolve(process.cwd(), process.env.BOOK_BIB_PATH)
   : resolve(PROJECT_ROOT, 'bibliography.bib');
 const OUT_PATH = resolve(PROJECT_ROOT, 'src/data/references.json');
+const SOURCES_PATH = resolve(PROJECT_ROOT, 'sources/manifest.yaml');
+const SOURCES_OUT = resolve(PROJECT_ROOT, 'src/data/sources.json');
 
-async function main() {
+async function buildReferences() {
   // Graceful skip when the .bib file is absent (minimal/tools profile, or
   // an academic book that hasn't authored citations yet). Emits an empty
   // references.json so consumers can still `import refs from '...'`.
@@ -125,6 +135,45 @@ async function main() {
   );
 }
 
+// v4.10.0 (closes #85): tools-profile books keep their sources in
+// sources/manifest.yaml (cited inline via <Citation src="id" />); the BibTeX
+// path above never sees them, so the auto-injected /references page rendered
+// blank. Emit those sources to src/data/sources.json so references.astro can
+// surface them via the same defensive import.meta.glob it uses for
+// references.json. Absent manifest -> no file written (academic/minimal books
+// degrade to empty, exactly like a missing .bib). YAML is lazy-imported so the
+// --help / no-manifest paths stay dependency-free.
+async function buildSources() {
+  let yamlText;
+  try {
+    yamlText = await readFile(SOURCES_PATH, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return; // no manifest — nothing to emit
+    throw err;
+  }
+
+  const { parse } = await import('yaml');
+  const parsed = parse(yamlText);
+  // The manifest is a YAML array of source objects. Keep only well-formed
+  // entries (a string `id` is the citation key + the /references anchor target).
+  // A blank or comments-only manifest parses to null/undefined/[].
+  const sources = Array.isArray(parsed)
+    ? parsed.filter((s) => s && typeof s.id === 'string')
+    : [];
+
+  await mkdir(dirname(SOURCES_OUT), { recursive: true });
+  await writeFile(SOURCES_OUT, JSON.stringify(sources, null, 2) + '\n', 'utf8');
+  console.log(
+    `build-bib: ${sources.length} source${sources.length === 1 ? '' : 's'} -> ` +
+      `${SOURCES_OUT.replace(PROJECT_ROOT + '/', '')}`,
+  );
+}
+
+async function main() {
+  await buildReferences();
+  await buildSources();
+}
+
 main().catch((err) => {
   console.error(`build-bib: failed`);
   console.error(err);

package/scripts/build-labels.mjs

@@ -15,10 +15,11 @@
  *   - tools profile: `chapter` field (number).
  *   - academic profile: `week` field (number).
  *
- * Slug used for the href = filename minus `.mdx`. The href shape mirrors
- * the consumer's pages router: `/chapters/<slug>#<id>`. Academic books
- * using `[...slug].astro` get the same shape since Astro slugifies
- * filenames identically.
+ * Slug used for the href: the chapter's frontmatter `slug:` if set,
+ * else filename minus `.mdx`. The href shape mirrors the consumer's pages
+ * router: `/chapters/<slug>#<id>`. Academic books using `[...slug].astro`
+ * get the same shape since Astro slugifies filenames identically when no
+ * frontmatter override is present.
  *
  * Optional override:
  *   <Theorem id="…" label="Custom display" />
@@ -178,7 +179,9 @@ async function main() {
     const source = await readFile(file, 'utf8');
     const fm = parseFrontmatter(source);
     const chapterNum = chapterNumberOf(fm);
-    const slug = basename(file).replace(/\.mdx?$/, '');
+    const slug = (typeof fm.slug === 'string' && fm.slug.length > 0)
+      ? fm.slug
+      : basename(file).replace(/\.mdx?$/, '');
 
     // Per-chapter counters reset for each file.
     const counters = {};

package/src/schemas.ts

@@ -116,6 +116,7 @@ export const academicChapterSchema = z.object({
   week: z.number().int().min(1).max(99),
   part: z.enum(academicParts),
   title: z.string().min(1),
+  slug: z.string().optional(),                 // v4.9.0: explicit URL slug override (else filename → entry.id)
   status: z.enum(chapterStatus),
   roadmap_lines: z.tuple([z.number().int(), z.number().int()]).optional(),
   code_path: z.string().optional(),
@@ -136,6 +137,7 @@ export const academicChapterSchema = z.object({
 
 export const toolsChapterSchema = z.object({
   title: z.string().min(1),
+  slug: z.string().optional(),                 // v4.9.0: explicit URL slug override (else filename → entry.id)
   part: z.number().int().min(0).max(10),
   chapter: z.number().int().min(0).max(99),
   volatility: z.enum(volatilityLevels),
@@ -178,6 +180,7 @@ export const sourceTiersResearch = ['T1', 'T2', 'T3', 'T4'] as const;
 export const courseNotesChapterSchema = z.object({
   // Identity
   title: z.string().min(1),
+  slug: z.string().optional(),                 // v4.9.0: explicit URL slug override (else filename → entry.id)
   chapter: z.number().int().min(0).max(99),
   part: z.number().int().min(0).max(20).default(1),
   description: z.string().optional(),