@brandon_m_behring/book-scaffold-astro 4.3.0 → 4.4.0

package/bin/book-scaffold.mjs

@@ -18,6 +18,7 @@ const handlers = {
   'build-bib': '../scripts/build-bib.mjs',
   'build-figures': '../scripts/build-figures.mjs',
   'build-tips': '../scripts/build-tips.mjs',
+  'build-exercises': '../scripts/build-exercises.mjs',
   'render-notebooks': '../scripts/render-notebooks.mjs',
 };
 
@@ -29,6 +30,7 @@ Sub-commands:
   build-bib          BibTeX -> CSL JSON for the <Cite> component.
   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).
   render-notebooks   ipynb -> HTML via Jupyter nbconvert.
 
   --help, -h         This message.

package/components/ExerciseSolutions.astro

@@ -1,22 +1,97 @@
 ---
 /**
- * ExerciseSolutions — chapter-end wrapper that provides the section
- * heading + container for <Solution> elements (v4.3.0, closes #71).
+ * ExerciseSolutions — chapter-end wrapper (v4.3.0 #71 + v4.4.0 auto mode).
  *
- * Author places this at chapter end and fills it with <Solution for="...">
- * elements. The wrapper provides:
- *   - <h2>Exercise solutions</h2> heading
- *   - Container styling (separates the section visually from preceding prose)
- *   - Anchor (`#exercise-solutions`) so the section is linkable
+ * Two modes:
  *
- * v4.3.0 design: manual <Solution> placement (no auto-collection of
- * <Exercise> content). Auto-collection deferred to v4.4.0+ if real
- * demand surfaces — would require MDX AST traversal at build time.
+ *   1. Manual (default; v4.3.0): author places <Solution for="..."> elements
+ *      inside the wrapper. Full control; works with no build script.
+ *
+ *      <ExerciseSolutions>
+ *        <Solution for="ex-1">Solution text.</Solution>
+ *      </ExerciseSolutions>
+ *
+ *   2. Auto (v4.4.0): reads src/data/exercises.json (emitted by
+ *      `book-scaffold build-exercises`), scopes by the current chapter
+ *      (derived from Astro.url.pathname), and renders an auto-generated
+ *      list of exercise problem statements with placeholder solution
+ *      slots. Author fills solutions by hand-editing the rendered HTML
+ *      OR by switching back to manual mode.
+ *
+ *      <ExerciseSolutions auto />
+ *
+ * Auto mode requires:
+ *   - `routes.chapters: true` (or a custom `/chapters/<slug>/` route pattern)
+ *   - `book-scaffold build-exercises` run before astro build (typically wired
+ *     into the `prebuild` script in package.json)
+ *
+ * Graceful skip: when exercises.json is missing OR no exercises found for
+ * the current chapter, auto mode renders an empty section with a hint.
  *
  * Family: book-genre (cross-profile).
  */
+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
+   *  uses the manual-slot mode from v4.3.0. */
+  auto?: boolean;
+}
+const { auto = false } = Astro.props;
+
+// Derive current chapter slug from URL when in auto mode. Astro.url.pathname
+// for `/chapters/<slug>/` returns `/chapters/<slug>/`; strip prefix+suffix.
+let chapterSlug = '';
+let exercises: Array<{ id: string; problem: string }> = [];
+let autoError: string | null = null;
+
+if (auto) {
+  const path = Astro.url.pathname;
+  const m = path.match(/^\/chapters\/([^/]+)\//);
+  chapterSlug = m ? m[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 }>> }>(
+      '/src/data/exercises.json',
+      { eager: true },
+    );
+    const exEntry = exModules['/src/data/exercises.json'];
+    if (!exEntry) {
+      autoError = `src/data/exercises.json not found — run \`npx book-scaffold build-exercises\` first.`;
+    } else {
+      exercises = exEntry.default[chapterSlug] ?? [];
+    }
+  }
+}
 ---
 <section class="exercise-solutions" id="exercise-solutions">
   <h2 class="exercise-solutions-heading">Exercise solutions</h2>
-  <div class="exercise-solutions-body"><slot /></div>
+  {!auto && (
+    <div class="exercise-solutions-body"><slot /></div>
+  )}
+  {auto && autoError && (
+    <p class="exercise-solutions-hint">{autoError}</p>
+  )}
+  {auto && !autoError && exercises.length === 0 && (
+    <p class="exercise-solutions-hint">
+      No <code>&lt;Exercise&gt;</code> instances found in chapter <code>{chapterSlug}</code>.
+      Run <code>npx book-scaffold build-exercises</code> after adding exercises.
+    </p>
+  )}
+  {auto && !autoError && exercises.length > 0 && (
+    <div class="exercise-solutions-body">
+      {exercises.map((ex) => (
+        <div class="solution" id={`solution-${ex.id}`}>
+          <div class="solution-header">
+            <strong class="solution-label">Exercise {ex.id}</strong>
+            <a href={`#exercise-${ex.id}`} class="solution-backlink">↑ Exercise</a>
+          </div>
+          <blockquote class="solution-problem">{ex.problem}</blockquote>
+          <p class="solution-placeholder"><em>Add your solution here.</em></p>
+        </div>
+      ))}
+    </div>
+  )}
 </section>

package/components/TipsCard.astro

@@ -13,13 +13,13 @@
  * empty container with a note (doesn't fail the build). Consumers who
  * don't use the tips feature can include the component without prep.
  */
-let tips: Array<{ n: number; title: string; chapter: string; preview: string }> = [];
-try {
-  const mod = await import('../../../src/data/tips.json', { with: { type: 'json' } });
-  tips = (mod.default ?? []) as typeof tips;
-} catch {
-  // tips.json not generated yet — render empty card with hint.
-}
+// v4.4.0 fix: project-root-relative import via Vite's import.meta.glob
+// (the previous `../../../src/data/tips.json` failed in node_modules contexts).
+const tipsModules = import.meta.glob<{ default: Array<{ n: number; title: string; chapter: string; preview: string }> }>(
+  '/src/data/tips.json',
+  { eager: true },
+);
+const tips = tipsModules['/src/data/tips.json']?.default ?? [];
 ---
 <aside class="tips-card" role="contentinfo">
   <h2 class="tips-card-title">Tips</h2>

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Q as volatilityLevels, h as ChaptersRenderer, n as Style } from './types-B8Js3qF0.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, R as ResearchPortfolioChapter, m as RouteToggles, S as StatusBadge, o as StyleInput, T as ToolsChapter, V as VolatilityBadge, p as academicChapterSchema, q as academicParts, r as changeKinds, s as changelogSchema, t as chapterStatus, u as composeStyles, v as courseNotesChapterSchema, w as defineProfile, x as defineStyle, y as minimalChapterSchema, z as normalizeFrontmatterConfig, D as patternCategories, E as patternsSchema, G as researchPortfolioChapterSchema, H as resolvePreset, I as resolveProfile, J as sourceTiers, K as sourceTiersResearch, L as sourcesSchema, N as toolSlugs, O as toolsChapterSchema } from './types-B8Js3qF0.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Q as volatilityLevels, h as ChaptersRenderer, n as Style } from './types-BhlCranN.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, R as ResearchPortfolioChapter, m as RouteToggles, S as StatusBadge, o as StyleInput, T as ToolsChapter, V as VolatilityBadge, p as academicChapterSchema, q as academicParts, r as changeKinds, s as changelogSchema, t as chapterStatus, u as composeStyles, v as courseNotesChapterSchema, w as defineProfile, x as defineStyle, y as minimalChapterSchema, z as normalizeFrontmatterConfig, D as patternCategories, E as patternsSchema, G as researchPortfolioChapterSchema, H as resolvePreset, I as resolveProfile, J as sourceTiers, K as sourceTiersResearch, L as sourcesSchema, N as toolSlugs, O as toolsChapterSchema } from './types-BhlCranN.js';
 import 'astro/zod';
 
 declare function defineBookConfig(opts: BookConfigOptions): Promise<AstroUserConfig>;

package/dist/index.mjs

@@ -378,8 +378,10 @@ var academicProfile = defineProfile({
     // tools-profile-specific
     frontmatter: false,
     // opt-in per book; see #7
-    tips: false
+    tips: false,
     // v4.3.0 #70: opt-in per book; requires build-tips
+    exercises: false
+    // v4.4.0: opt-in per book; requires build-exercises
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
@@ -494,8 +496,10 @@ var toolsProfile = defineProfile({
     // tools profile ships convergence dashboard
     frontmatter: false,
     // opt-in per book; see #7
-    tips: false
+    tips: false,
     // v4.3.0 #70: opt-in per book
+    exercises: false
+    // v4.4.0: opt-in per book
   },
   styles: [
     "tokens.css",
@@ -574,8 +578,10 @@ var minimalProfile = defineProfile({
     convergence: false,
     frontmatter: false,
     // opt-in per book; see #7
-    tips: false
+    tips: false,
     // v4.3.0 #70: opt-in per book
+    exercises: false
+    // v4.4.0: opt-in per book
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   // v3.7.0 (#35): minimal aliases tools schema; fallback renderer field-dispatches if a consumer opts into routes.chapters
@@ -595,8 +601,10 @@ var courseNotesProfile = defineProfile({
     convergence: false,
     frontmatter: false,
     // opt-in per book; see #7
-    tips: false
+    tips: false,
     // v4.3.0 #70: opt-in per book
+    exercises: false
+    // v4.4.0: opt-in per book
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   // v3.7.0 (#35): course-notes schema has tools-style fields (chapter, volatility, sources) — fallback renderer dispatches via tools renderer
@@ -617,8 +625,10 @@ var researchPortfolioProfile = defineProfile({
     // tools-profile-specific
     frontmatter: true,
     // portfolios universally need title/disclosure/banner pages
-    tips: false
+    tips: false,
     // v4.3.0 #70: opt-in per book
+    exercises: false
+    // v4.4.0: opt-in per book
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
@@ -820,6 +830,9 @@ var ROUTE_REGISTRY = {
   // v4.3.0 (#70): cross-volume numbered-tips index. Opt-in via
   // routes.tips: true; pairs with build-tips script + <Tip> component.
   tips: { pattern: "/tips", file: "tips.astro" },
+  // v4.4.0: exercises index by chapter. Opt-in via routes.exercises: true;
+  // pairs with build-exercises script + <ExerciseSolutions auto /> mode.
+  exercises: { pattern: "/exercises", file: "exercises.astro" },
   // v3.4.0 (#7): consumer-collection-backed frontmatter route. Opt-in via
   // routes: { frontmatter: true } AND content.config.ts defining the
   // collection (use frontmatterCollection() helper from /schemas subpath).

package/dist/schemas.d.ts

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

package/dist/schemas.mjs

@@ -263,8 +263,10 @@ var academicProfile = defineProfile({
     // tools-profile-specific
     frontmatter: false,
     // opt-in per book; see #7
-    tips: false
+    tips: false,
     // v4.3.0 #70: opt-in per book; requires build-tips
+    exercises: false
+    // v4.4.0: opt-in per book; requires build-exercises
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
@@ -379,8 +381,10 @@ var toolsProfile = defineProfile({
     // tools profile ships convergence dashboard
     frontmatter: false,
     // opt-in per book; see #7
-    tips: false
+    tips: false,
     // v4.3.0 #70: opt-in per book
+    exercises: false
+    // v4.4.0: opt-in per book
   },
   styles: [
     "tokens.css",
@@ -459,8 +463,10 @@ var minimalProfile = defineProfile({
     convergence: false,
     frontmatter: false,
     // opt-in per book; see #7
-    tips: false
+    tips: false,
     // v4.3.0 #70: opt-in per book
+    exercises: false
+    // v4.4.0: opt-in per book
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   // v3.7.0 (#35): minimal aliases tools schema; fallback renderer field-dispatches if a consumer opts into routes.chapters
@@ -480,8 +486,10 @@ var courseNotesProfile = defineProfile({
     convergence: false,
     frontmatter: false,
     // opt-in per book; see #7
-    tips: false
+    tips: false,
     // v4.3.0 #70: opt-in per book
+    exercises: false
+    // v4.4.0: opt-in per book
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   // v3.7.0 (#35): course-notes schema has tools-style fields (chapter, volatility, sources) — fallback renderer dispatches via tools renderer
@@ -502,8 +510,10 @@ var researchPortfolioProfile = defineProfile({
     // tools-profile-specific
     frontmatter: true,
     // portfolios universally need title/disclosure/banner pages
-    tips: false
+    tips: false,
     // v4.3.0 #70: opt-in per book
+    exercises: false
+    // v4.4.0: opt-in per book
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,

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.3.0",
+  "version": "4.4.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

package/pages/exercises.astro

@@ -0,0 +1,65 @@
+---
+/**
+ * Auto-injected /exercises route (v4.4.0).
+ *
+ * Gated on `routes.exercises: true`. Reads `src/data/exercises.json`
+ * (emitted by `book-scaffold build-exercises`); renders ordered list
+ * grouped by chapter with deep links into the chapter routes.
+ *
+ * Graceful skip: if exercises.json doesn't exist, renders an instructions
+ * page (doesn't fail the build).
+ */
+import Base from '../layouts/Base.astro';
+
+// 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-
+// rooted in Vite's resolver and works across all consumer build contexts.
+const exModules = import.meta.glob<{ default: Record<string, Array<{ id: string; problem: string }>> }>(
+  '/src/data/exercises.json',
+  { eager: true },
+);
+const exEntry = exModules['/src/data/exercises.json'];
+const byChapter = exEntry?.default ?? {};
+const loadError = exEntry
+  ? null
+  : 'src/data/exercises.json not found — run `npx book-scaffold build-exercises` to generate.';
+
+const chapters = Object.keys(byChapter).sort();
+const total = chapters.reduce((sum, c) => sum + byChapter[c].length, 0);
+---
+<Base title="Exercises" description="All exercises in this book, grouped by chapter with deep links.">
+  <article class="prose">
+    <h1>Exercises</h1>
+    {loadError && (
+      <p class="exercises-empty">{loadError}</p>
+    )}
+    {!loadError && total === 0 && (
+      <p class="exercises-empty">
+        No exercises defined yet. Add <code>&lt;Exercise id="..."&gt;...&lt;/Exercise&gt;</code> to a chapter
+        and run <code>npx book-scaffold build-exercises</code>.
+      </p>
+    )}
+    {total > 0 && (
+      <p class="exercises-summary">
+        {total} exercise{total === 1 ? '' : 's'} across {chapters.length} chapter{chapters.length === 1 ? '' : 's'}.
+      </p>
+    )}
+    {chapters.map((chapter) => (
+      <section class="exercises-chapter" id={`chapter-${chapter}`}>
+        <h2 class="exercises-chapter-title">
+          Chapter: <a href={`/chapters/${chapter}/`}>{chapter}</a>
+        </h2>
+        <ol class="exercises-list">
+          {byChapter[chapter].map((ex) => (
+            <li class="exercises-item">
+              <a href={`/chapters/${chapter}/#exercise-${ex.id}`} class="exercises-link">
+                <strong class="exercises-id">Exercise {ex.id}</strong>
+                <span class="exercises-preview">{ex.problem.slice(0, 120)}{ex.problem.length > 120 ? '…' : ''}</span>
+              </a>
+            </li>
+          ))}
+        </ol>
+      </section>
+    ))}
+  </article>
+</Base>

package/pages/tips.astro

@@ -11,14 +11,20 @@
  */
 import Base from '../layouts/Base.astro';
 
-let tips: Array<{ n: number; title: string; chapter: string; preview: string }> = [];
-let loadError: string | null = null;
-try {
-  const mod = await import('../../../src/data/tips.json', { with: { type: 'json' } });
-  tips = (mod.default ?? []) as typeof tips;
-} catch {
-  loadError = 'src/data/tips.json not found — run `npx book-scaffold build-tips` to generate.';
-}
+// 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
+// the auto-injected route was processed from node_modules (or any context
+// other than a workspace symlink). `/src/data/...` is consumer-project-rooted
+// in Vite's resolver and works across all consumer build contexts.
+const tipsModules = import.meta.glob<{ default: Array<{ n: number; title: string; chapter: string; preview: string }> }>(
+  '/src/data/tips.json',
+  { eager: true },
+);
+const tipsEntry = tipsModules['/src/data/tips.json'];
+const tips = tipsEntry?.default ?? [];
+const loadError = tipsEntry
+  ? null
+  : 'src/data/tips.json not found — run `npx book-scaffold build-tips` to generate.';
 ---
 <Base title="Tips" description="Numbered tips from this book, drawn from <Tip> instances in chapters.">
   <article class="prose">

package/scripts/build-exercises.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * scripts/build-exercises.mjs — emit src/data/exercises.json from <Exercise>
+ * instances in chapter MDX (v4.4.0, closes v4.3.0 backlog).
+ *
+ * Sister script to build-tips.mjs (v4.3.0). Scans chapters honoring
+ * loader.base override (via readChaptersBase from walk-mdx.mjs). Extracts
+ * <Exercise id="X">body</Exercise> via 4-branch regex (same quote-style
+ * portability lesson as build-tips). Emits a chapter-keyed object so the
+ * /exercises route + <ExerciseSolutions auto> can scope by chapter.
+ *
+ * Output shape:
+ *   {
+ *     "ch1-foundations": [
+ *       { "id": "ex-1", "problem": "Given..." },
+ *       { "id": "ex-2", "problem": "Refactor..." }
+ *     ],
+ *     ...
+ *   }
+ *
+ * Graceful no-op: if no <Exercise> instances exist, writes {} (doesn't
+ * fail builds for consumers who don't use the feature).
+ */
+import { writeFile, mkdir, readFile } from 'node:fs/promises';
+import { resolve, dirname, basename } from 'node:path';
+import { walkMdx, readChaptersBase } from './walk-mdx.mjs';
+
+const USAGE = `Usage: book-scaffold build-exercises
+
+Scan chapter MDX for <Exercise id="X">body</Exercise> occurrences; emit
+src/data/exercises.json keyed by chapter slug. Used by the /exercises
+auto-route + <ExerciseSolutions auto> mode when routes.exercises: true.
+
+Env:
+  BOOK_CHAPTERS_DIR        Override chapters dir (default: src/content/chapters).
+  BOOK_EXERCISES_OUT       Override output path (default: src/data/exercises.json).
+
+Options:
+  --help, -h               Print this message and exit (non-mutating).
+`;
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+
+const CWD = process.cwd();
+const CHAPTERS_DIR = await readChaptersBase(CWD);
+const OUTPUT_PATH = process.env.BOOK_EXERCISES_OUT ?? 'src/data/exercises.json';
+
+/**
+ * Extract <Exercise id="..."> tags and their body content from MDX.
+ *
+ * Returns array of { id, problem }. Problem is the full body content
+ * (trimmed + whitespace-normalized); the /exercises route + ExerciseSolutions
+ * auto truncate for display. Full content kept so consumers using
+ * `<ExerciseSolutions auto />` see the entire problem statement.
+ *
+ * Limitations (same as build-tips):
+ *   - Doesn't handle nested <Exercise> tags
+ *   - String attributes must use single OR double quotes (not template literals)
+ *   - id may not contain a literal quote of the same type used as delimiter
+ */
+function extractExercises(source) {
+  const exercises = [];
+  // 4-branch alternation (single/single, double/double, mixed) — no
+  // backreference for cross-runtime regex portability (v4.1.2 lesson).
+  // Since Exercise has only 1 attribute (id), we just need 2 branches.
+  const re = new RegExp(
+    [
+      `<Exercise\\s+id="([^"]+)"\\s*>([\\s\\S]*?)</Exercise>`,
+      `<Exercise\\s+id='([^']+)'\\s*>([\\s\\S]*?)</Exercise>`,
+    ].join('|'),
+    'g',
+  );
+  for (const match of source.matchAll(re)) {
+    const [, id1, body1, id2, body2] = match;
+    const id = id1 || id2;
+    const body = body1 || body2 || '';
+    if (!id) continue;
+    const problem = body.trim().replace(/\s+/g, ' ');
+    exercises.push({ id, problem });
+  }
+  return exercises;
+}
+
+async function main() {
+  const byChapter = {};
+  let totalExercises = 0;
+  let chaptersWithExercises = 0;
+
+  for await (const rel of walkMdx(CHAPTERS_DIR)) {
+    const chapterPath = resolve(CHAPTERS_DIR, rel);
+    const chapterSlug = basename(rel).replace(/\.mdx?$/, '');
+    let source;
+    try {
+      source = await readFile(chapterPath, 'utf8');
+    } catch {
+      continue;
+    }
+    const exercises = extractExercises(source);
+    if (exercises.length > 0) {
+      byChapter[chapterSlug] = exercises;
+      totalExercises += exercises.length;
+      chaptersWithExercises += 1;
+    }
+  }
+
+  const outPath = resolve(CWD, OUTPUT_PATH);
+  await mkdir(dirname(outPath), { recursive: true });
+  await writeFile(outPath, JSON.stringify(byChapter, null, 2) + '\n');
+  process.stdout.write(
+    `build-exercises: ${totalExercises} exercise${totalExercises === 1 ? '' : 's'} across ` +
+      `${chaptersWithExercises} chapter${chaptersWithExercises === 1 ? '' : 's'} → ${OUTPUT_PATH}\n`,
+  );
+}
+
+main().catch((err) => {
+  console.error('build-exercises: failed');
+  console.error(err.message ?? err);
+  process.exit(1);
+});
+
+// Export for tests.
+export { extractExercises };

package/src/profile-kit.ts

@@ -57,6 +57,14 @@ export interface RouteToggles {
    * defineBookConfig({ routes: { tips: true } }).
    */
   tips: boolean;
+  /**
+   * v4.4.0: auto-inject `/exercises` route listing all `<Exercise id="...">`
+   * instances from chapter MDX, grouped by chapter with deep links into
+   * the chapter routes. Requires running `book-scaffold build-exercises`
+   * (via prebuild) which emits src/data/exercises.json. Default `false` per
+   * profile — opt in via defineBookConfig({ routes: { exercises: true } }).
+   */
+  exercises: boolean;
 }
 
 /** Profile definition — declarative shape for one book profile. */

package/src/profiles/academic.ts

@@ -24,6 +24,7 @@ export const academicProfile = defineProfile({
     convergence: false,     // tools-profile-specific
     frontmatter: false,     // opt-in per book; see #7
     tips: false,            // v4.3.0 #70: opt-in per book; requires build-tips
+    exercises: false,       // v4.4.0: opt-in per book; requires build-exercises
   },
   styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
   katex: true,

package/src/profiles/course-notes.ts

@@ -26,6 +26,7 @@ export const courseNotesProfile = defineProfile({
     convergence: false,
     frontmatter: false,     // opt-in per book; see #7
     tips: false,            // v4.3.0 #70: opt-in per book
+    exercises: false,       // v4.4.0: opt-in per book
   },
   styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
   // v3.7.0 (#35): course-notes schema has tools-style fields (chapter, volatility, sources) — fallback renderer dispatches via tools renderer

package/src/profiles/minimal.ts

@@ -21,6 +21,7 @@ export const minimalProfile = defineProfile({
     convergence: false,
     frontmatter: false,     // opt-in per book; see #7
     tips: false,            // v4.3.0 #70: opt-in per book
+    exercises: false,       // v4.4.0: opt-in per book
   },
   styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
   // v3.7.0 (#35): minimal aliases tools schema; fallback renderer field-dispatches if a consumer opts into routes.chapters

package/src/profiles/research-portfolio.ts

@@ -37,6 +37,7 @@ export const researchPortfolioProfile = defineProfile({
     convergence: false,          // tools-profile-specific
     frontmatter: true,           // portfolios universally need title/disclosure/banner pages
     tips: false,                 // v4.3.0 #70: opt-in per book
+    exercises: false,            // v4.4.0: opt-in per book
   },
   styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
   katex: true,                   // math is common in research content

package/src/profiles/tools.ts

@@ -21,6 +21,7 @@ export const toolsProfile = defineProfile({
     convergence: true,      // tools profile ships convergence dashboard
     frontmatter: false,     // opt-in per book; see #7
     tips: false,            // v4.3.0 #70: opt-in per book
+    exercises: false,       // v4.4.0: opt-in per book
   },
   styles: [
     'tokens.css', 'layout.css', 'callouts.css', 'chapter.css',