@brandon_m_behring/book-scaffold-astro 4.3.0 → 4.5.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,8 +1,24 @@
 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-DLIpEgTm.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-DLIpEgTm.js';
 import 'astro/zod';
 
+/**
+ * v4.5.0: Default portfolio backlink baked into the scaffold. Rendered in
+ * the auto-injected `/` landing footer for every consumer that doesn't
+ * explicitly override `portfolio` in defineBookConfig.
+ *
+ * Single source of truth for the brandon-behring.dev URL across all
+ * consumers — update here, bump scaffold version, every consumer inherits
+ * on next build. This is the intentional Brandon-specific default
+ * discussed in plan §Phase 6-pre. Consumers outside the brandon-behring.dev
+ * ecosystem set `portfolio: false` (no link) or pass `{ url, label }` to
+ * override.
+ */
+declare const BRANDON_PORTFOLIO_DEFAULT: {
+    readonly url: "https://brandon-behring.dev";
+    readonly label: "brandon-behring.dev";
+};
 declare function defineBookConfig(opts: BookConfigOptions): Promise<AstroUserConfig>;
 
 declare function bookScaffoldIntegration(opts: BookScaffoldIntegrationOptions): AstroIntegration;
@@ -244,4 +260,4 @@ type TipsConfigInput = Omit<TipsConfig, typeof TipsConfigBrand | '__tipsConfigVe
  */
 declare function defineTips(opts: TipsConfigInput): TipsConfig;
 
-export { BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, type Freshness, type FreshnessStatus, Style, type TipsConfig, type TipsConfigInput, type VolatilityLevel, academicChaptersRenderer, academicStyle, bookScaffoldIntegration, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, researchPortfolioStyle, toolsChaptersRenderer, toolsStyle, volatilityLevels };
+export { BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, type Freshness, type FreshnessStatus, Style, type TipsConfig, type TipsConfigInput, type VolatilityLevel, academicChaptersRenderer, academicStyle, bookScaffoldIntegration, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, researchPortfolioStyle, toolsChaptersRenderer, toolsStyle, volatilityLevels };

package/dist/index.mjs

@@ -378,8 +378,12 @@ 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
+    landing: true
+    // v4.5.0: auto-inject minimal root landing; consumers override via src/pages/index.astro
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
@@ -494,8 +498,12 @@ 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
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   styles: [
     "tokens.css",
@@ -574,8 +582,12 @@ 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
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   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 +607,12 @@ 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
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   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 +633,12 @@ 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
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
@@ -820,6 +840,14 @@ 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" },
+  // v4.5.0: minimal root landing page. Reads title/description/portfolio/routes
+  // from vite.define-injected import.meta.env vars. Default-on per profile;
+  // consumers with their own src/pages/index.astro override (file-system route
+  // wins over injectRoute).
+  landing: { pattern: "/", file: "index.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).
@@ -837,7 +865,16 @@ function resolvePage(file) {
   return fileURLToPath(new URL(`../pages/${file}`, import.meta.url));
 }
 function bookScaffoldIntegration(opts) {
-  const { profile, routes: userOverrides = {}, extraStyles = [], mdxComponentsModule } = opts;
+  const {
+    profile,
+    routes: userOverrides = {},
+    extraStyles = [],
+    mdxComponentsModule,
+    // v4.5.0: landing-page data, propagated via vite.define to /index.astro.
+    title,
+    description,
+    portfolio
+  } = opts;
   const def = PROFILES[profile];
   const fmNormalized = normalizeFrontmatterConfig(userOverrides.frontmatter);
   const fmEnabled = fmNormalized?.enabled ?? def.routes.frontmatter;
@@ -878,12 +915,20 @@ function bookScaffoldIntegration(opts) {
         const consumerRoot = fileURLToPath(config.root);
         const resolvedMdxPath = resolveMdxComponentsPath(consumerRoot, mdxComponentsModule);
         const presetLiteral = JSON.stringify(profile);
+        const enabledRouteNames = Object.entries(enabledRoutes).filter(([, on]) => on).map(([name]) => name);
         updateConfig({
           vite: {
             plugins: [makeMdxComponentsVitePlugin(resolvedMdxPath)],
             define: {
               "import.meta.env.BOOK_PRESET": presetLiteral,
-              "import.meta.env.BOOK_PROFILE": presetLiteral
+              "import.meta.env.BOOK_PROFILE": presetLiteral,
+              // v4.5.0: landing-page data. JSON.stringify on undefined → 'undefined'
+              // (which evaluates to JavaScript undefined at use site); on object →
+              // the JSON literal; on false → 'false'.
+              "import.meta.env.BOOK_TITLE": JSON.stringify(title ?? null),
+              "import.meta.env.BOOK_DESCRIPTION": JSON.stringify(description ?? null),
+              "import.meta.env.BOOK_PORTFOLIO": JSON.stringify(portfolio ?? null),
+              "import.meta.env.BOOK_ROUTES_ENABLED": JSON.stringify(enabledRouteNames)
             }
           }
         });
@@ -893,6 +938,10 @@ function bookScaffoldIntegration(opts) {
 }
 
 // src/config.ts
+var BRANDON_PORTFOLIO_DEFAULT = {
+  url: "https://brandon-behring.dev",
+  label: "brandon-behring.dev"
+};
 function v3MigrationError(opts) {
   const v3Value = opts.preset ?? opts.profile;
   const v3FieldUsed = "preset" in opts ? "preset" : "profile";
@@ -973,6 +1022,7 @@ async function defineBookConfig(opts) {
       }
     ]);
   }
+  const resolvedPortfolio = opts.portfolio === false ? false : opts.portfolio ?? BRANDON_PORTFOLIO_DEFAULT;
   const integrations = [
     mdx(),
     preact(),
@@ -980,7 +1030,12 @@ async function defineBookConfig(opts) {
       profile,
       routes: mergedRoutes,
       mdxComponentsModule,
-      extraStyles: mergedExtraStyles
+      extraStyles: mergedExtraStyles,
+      // v4.5.0: pass landing-page data through to the integration so it can
+      // be exposed to the auto-injected /index.astro via vite.define.
+      title: opts.title,
+      description: opts.description,
+      portfolio: resolvedPortfolio
     }),
     ...mergedExtraIntegrations
   ];
@@ -1015,6 +1070,10 @@ async function defineBookConfig(opts) {
     extraStyles: _extraStyles,
     markdown: _markdown,
     katexMacros: _katexMacros,
+    // v4.5.0: strip new landing-related opts so they don't leak into AstroUserConfig.
+    title: _title,
+    description: _description,
+    portfolio: _portfolio,
     ...rest
   } = opts;
   void _styles;
@@ -1026,6 +1085,9 @@ async function defineBookConfig(opts) {
   void _extraStyles;
   void _markdown;
   void _katexMacros;
+  void _title;
+  void _description;
+  void _portfolio;
   const katexExternals = wantsKatex ? [] : ["remark-math", "rehype-katex", "katex"];
   const config = {
     site,
@@ -1102,6 +1164,7 @@ function defineTips(opts) {
 export {
   BOOK_PRESETS,
   BOOK_PROFILES,
+  BRANDON_PORTFOLIO_DEFAULT,
   BUILTIN_STYLES,
   BookConfigError,
   academicChapterSchema,

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-DLIpEgTm.js';
 import 'astro';
 import 'astro/zod';
 

package/dist/schemas.mjs

@@ -263,8 +263,12 @@ 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
+    landing: true
+    // v4.5.0: auto-inject minimal root landing; consumers override via src/pages/index.astro
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
@@ -379,8 +383,12 @@ 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
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   styles: [
     "tokens.css",
@@ -459,8 +467,12 @@ 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
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   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 +492,12 @@ 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
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   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 +518,12 @@ 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
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   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.5.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/index.astro

@@ -0,0 +1,111 @@
+---
+/**
+ * /index — minimal default landing page (v4.5.0).
+ *
+ * Auto-injected by bookScaffoldIntegration when routes.landing === true
+ * (default for every profile). Consumers with their own src/pages/index.astro
+ * override automatically — file-system routes win over injectRoute, no extra
+ * config needed.
+ *
+ * Reads book identity + portfolio + enabled-routes from vite.define-injected
+ * env vars (see integration.ts §4.5.0). Renders:
+ *   - h1 with book title (fallback: 'book-scaffold-astro')
+ *   - lead paragraph with description (omitted if not set)
+ *   - "Read" list of links to enabled scaffold routes (filtered to only
+ *     routes the integration actually injected; respects routes.<x>: false)
+ *   - portfolio backlink in the footer (omitted if portfolio: false)
+ *
+ * Override paths:
+ *   - Disable entirely: defineBookConfig({ routes: { landing: false } })
+ *   - Compose differently: create src/pages/index.astro in your consumer
+ *     repo (file wins; this page never renders)
+ *   - Change portfolio target: defineBookConfig({ portfolio: { url, label } })
+ *     or defineBookConfig({ portfolio: false })
+ */
+import Base from '../layouts/Base.astro';
+
+// Vite-injected at build time. JSON.stringify(value ?? null) is the
+// integration's convention; null means "not set", an object/string means real value.
+const title = (import.meta.env.BOOK_TITLE as string | null) ?? 'book-scaffold-astro';
+const description = import.meta.env.BOOK_DESCRIPTION as string | null;
+const portfolio = import.meta.env.BOOK_PORTFOLIO as { url: string; label: string } | false | null;
+const enabledRoutes = (import.meta.env.BOOK_ROUTES_ENABLED as string[] | undefined) ?? [];
+
+// Map from internal route name → display label + URL. Only routes that
+// produce a single landing-list entry are listed here (frontmatter is a
+// slug pattern; chaptersSlug is dynamic; landing IS this page).
+const ROUTE_LABELS: Record<string, { label: string; href: string }> = {
+  chapters:    { label: 'Chapters',     href: '/chapters/' },
+  search:      { label: 'Search',       href: '/search/' },
+  references:  { label: 'References',   href: '/references/' },
+  print:       { label: 'Print view',   href: '/print/' },
+  convergence: { label: 'Convergence',  href: '/convergence/' },
+  tips:        { label: 'Tips',         href: '/tips/' },
+  exercises:   { label: 'Exercises',    href: '/exercises/' },
+};
+
+const visibleRoutes = enabledRoutes
+  .filter((name) => name in ROUTE_LABELS)
+  .map((name) => ROUTE_LABELS[name]!);
+---
+
+<Base title={title} description={description ?? undefined}>
+  <article class="prose landing">
+    <h1>{title}</h1>
+    {description && <p class="lead">{description}</p>}
+
+    {visibleRoutes.length > 0 && (
+      <>
+        <h2 class="read-heading">Read</h2>
+        <ul class="route-list">
+          {visibleRoutes.map((r) => (
+            <li><a href={r.href}>{r.label}</a></li>
+          ))}
+        </ul>
+      </>
+    )}
+
+    {portfolio && portfolio !== false && (
+      <p class="portfolio-footer">
+        <small>
+          Part of <a href={portfolio.url}>{portfolio.label}</a>
+        </small>
+      </p>
+    )}
+  </article>
+</Base>
+
+<style>
+  .landing {
+    max-width: 60ch;
+    margin: 2rem auto;
+  }
+  .lead {
+    font-size: 1.1rem;
+    line-height: 1.5;
+    margin: 1.25rem 0 2.5rem 0;
+  }
+  .read-heading {
+    font-size: 0.85rem;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--color-text-muted, #555);
+    margin-top: 2.5rem;
+    margin-bottom: 0.75rem;
+  }
+  .route-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+  }
+  .route-list li {
+    padding: 0.4rem 0;
+    font-family: var(--font-sans, sans-serif);
+    font-size: 1rem;
+  }
+  .portfolio-footer {
+    margin-top: 3rem;
+    color: var(--color-text-muted, #555);
+    font-family: var(--font-sans, sans-serif);
+  }
+</style>

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

@@ -41,6 +41,16 @@ export interface RouteToggles {
   print: boolean;
   chapters: boolean;
   convergence: boolean;
+  /**
+   * v4.5.0: auto-inject a minimal `/` landing page that reads the book's
+   * `title`, `description`, and `portfolio` from defineBookConfig and
+   * renders a route list (filtered to enabled routes). Defaults to `true`
+   * on every profile. Consumers with their own `src/pages/index.astro` keep
+   * their custom landing (file-system routes win over `injectRoute`). Set
+   * to `false` to suppress the auto-injection entirely without writing
+   * a custom landing.
+   */
+  landing: boolean;
   /**
    * v3.4.0 (closes #7): auto-inject `/frontmatter/[slug]/` rendering a
    * consumer-defined `frontmatter` content collection. Default `false` per
@@ -57,6 +67,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,8 @@ 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
+    landing: true,          // v4.5.0: auto-inject minimal root landing; consumers override via src/pages/index.astro
   },
   styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
   katex: true,

package/src/profiles/course-notes.ts

@@ -26,6 +26,8 @@ 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
+    landing: true,          // v4.5.0: auto-inject minimal root landing
   },
   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,8 @@ 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
+    landing: true,          // v4.5.0: auto-inject minimal root landing
   },
   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,8 @@ 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
+    landing: true,               // v4.5.0: auto-inject minimal root landing
   },
   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,8 @@ 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
+    landing: true,          // v4.5.0: auto-inject minimal root landing
   },
   styles: [
     'tokens.css', 'layout.css', 'callouts.css', 'chapter.css',