@brandon_m_behring/book-scaffold-astro 4.2.0 → 4.3.0

package/bin/book-scaffold.mjs

@@ -17,6 +17,7 @@ const handlers = {
   'build-labels': '../scripts/build-labels.mjs',
   'build-bib': '../scripts/build-bib.mjs',
   'build-figures': '../scripts/build-figures.mjs',
+  'build-tips': '../scripts/build-tips.mjs',
   'render-notebooks': '../scripts/render-notebooks.mjs',
 };
 
@@ -26,7 +27,8 @@ 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-figures      PDF -> SVG via pdftocairo / pdftoppm fallback.
+  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).
   render-notebooks   ipynb -> HTML via Jupyter nbconvert.
 
   --help, -h         This message.

package/components/Exercise.astro

@@ -0,0 +1,24 @@
+---
+/**
+ * Exercise — inline at concept introduction per CS:APP precedent
+ * (v4.3.0, closes #71).
+ *
+ * Reader is expected to attempt while reading. Solutions live at the
+ * chapter end via id reference (paired via <Solution for="{id}"> inside
+ * <ExerciseSolutions>; manual pairing — no auto-collection).
+ *
+ * Light treatment: border-left in neutral color + "Exercise" label +
+ * anchor id (`#exercise-{id}`) for cross-linking from <Solution>.
+ *
+ * Family: book-genre (cross-profile).
+ */
+interface Props {
+  id: string;
+}
+const { id } = Astro.props;
+const anchorId = `exercise-${id}`;
+---
+<aside class="exercise" id={anchorId} role="note">
+  <strong class="exercise-label">Exercise</strong>
+  <div class="exercise-body"><slot /></div>
+</aside>

package/components/ExerciseSolutions.astro

@@ -0,0 +1,22 @@
+---
+/**
+ * ExerciseSolutions — chapter-end wrapper that provides the section
+ * heading + container for <Solution> elements (v4.3.0, closes #71).
+ *
+ * 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
+ *
+ * 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.
+ *
+ * Family: book-genre (cross-profile).
+ */
+---
+<section class="exercise-solutions" id="exercise-solutions">
+  <h2 class="exercise-solutions-heading">Exercise solutions</h2>
+  <div class="exercise-solutions-body"><slot /></div>
+</section>

package/components/Practice.astro

@@ -0,0 +1,30 @@
+---
+/**
+ * Practice — end-of-chapter problem with difficulty marker per CS:APP
+ * (v4.3.0, closes #71).
+ *
+ * Difficulty 1-4 rendered as ◆ count (filled diamonds out of 4). No
+ * inline solutions; instructor-manual style — separate from Exercise
+ * which has solutions at chapter end.
+ *
+ * Anchor id (`#practice-{id}`) for cross-references.
+ *
+ * Family: book-genre (cross-profile).
+ */
+type Difficulty = '1' | '2' | '3' | '4';
+interface Props {
+  id: string;
+  difficulty: Difficulty;
+}
+const { id, difficulty } = Astro.props;
+const anchorId = `practice-${id}`;
+const filled = Number.parseInt(difficulty, 10);
+const markers = '◆'.repeat(filled) + '◇'.repeat(4 - filled);
+---
+<aside class="practice" id={anchorId} role="note">
+  <div class="practice-header">
+    <strong class="practice-label">Practice</strong>
+    <span class="practice-difficulty" aria-label={`Difficulty ${difficulty} of 4`}>{markers}</span>
+  </div>
+  <div class="practice-body"><slot /></div>
+</aside>

package/components/Solution.astro

@@ -0,0 +1,27 @@
+---
+/**
+ * Solution — paired by id with an <Exercise> at chapter end
+ * (v4.3.0, closes #71).
+ *
+ * Author writes `<Solution for="ch1-ex-2">solution text</Solution>` inside
+ * an <ExerciseSolutions> wrapper. The `for` attribute matches the
+ * corresponding <Exercise>'s `id`; the rendered solution links back to
+ * the inline exercise via `#exercise-{for}`.
+ *
+ * Manual pairing — no build-time auto-collection of Exercise content
+ * (deferred to v4.4.0+). Author maintains the id↔for mapping by hand.
+ *
+ * Family: book-genre (cross-profile).
+ */
+interface Props {
+  for: string;
+}
+const { for: forId } = Astro.props;
+---
+<div class="solution" id={`solution-${forId}`}>
+  <div class="solution-header">
+    <strong class="solution-label">Solution</strong>
+    <a href={`#exercise-${forId}`} class="solution-backlink">↑ Exercise</a>
+  </div>
+  <div class="solution-body"><slot /></div>
+</div>

package/components/Tip.astro

@@ -0,0 +1,28 @@
+---
+/**
+ * Tip — numbered cross-volume tip per Pragmatic Programmer precedent
+ * (v4.3.0, closes #70).
+ *
+ * Author writes `<Tip n="14" title="Care About Your Craft">rule statement</Tip>`.
+ * Number is explicit (registry doesn't auto-number). Body slot is the
+ * pull-quotable single-sentence rule.
+ *
+ * Gold border (reuses --callout-insight); distinctive single-line layout
+ * + anchor id (`#tip-{n}`) for cross-referencing from later chapters.
+ *
+ * Family: book-genre (cross-profile; usable from any preset).
+ */
+interface Props {
+  n: string | number;
+  title: string;
+}
+const { n, title } = Astro.props;
+const anchorId = `tip-${n}`;
+---
+<aside class="callout callout-tip-numbered" id={anchorId} role="note">
+  <div class="callout-tip-header">
+    <span class="callout-tip-number">Tip {n}</span>
+    <strong class="callout-tip-title">{title}</strong>
+  </div>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/TipsCard.astro

@@ -0,0 +1,44 @@
+---
+/**
+ * TipsCard — print-friendly pull-out card listing all numbered tips
+ * (v4.3.0, closes #70).
+ *
+ * Reads `src/data/tips.json` (emitted by `book-scaffold build-tips`).
+ * Author places it on a back-matter print route (e.g., `/print-tips`).
+ *
+ * Renders a single-column ordered list with page-break-inside: avoid
+ * so the card prints cleanly on one or more dedicated pages.
+ *
+ * Graceful skip: if tips.json doesn't exist or is empty, renders an
+ * 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.
+}
+---
+<aside class="tips-card" role="contentinfo">
+  <h2 class="tips-card-title">Tips</h2>
+  {tips.length === 0 && (
+    <p class="tips-card-empty">
+      No tips found. Run <code>book-scaffold build-tips</code> to generate
+      <code>src/data/tips.json</code> from <code>&lt;Tip&gt;</code> instances in chapters.
+    </p>
+  )}
+  {tips.length > 0 && (
+    <ol class="tips-card-list">
+      {tips.map((tip) => (
+        <li class="tips-card-item">
+          <a href={`/tips#tip-${tip.n}`} class="tips-card-link">
+            <span class="tips-card-number">{tip.n}.</span>
+            <strong class="tips-card-rule">{tip.title}</strong>
+          </a>
+        </li>
+      ))}
+    </ol>
+  )}
+</aside>

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-DR0-GwxO.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-DR0-GwxO.js';
+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 'astro/zod';
 
 declare function defineBookConfig(opts: BookConfigOptions): Promise<AstroUserConfig>;
@@ -195,4 +195,53 @@ declare const BUILTIN_STYLES: {
     readonly 'research-portfolio': Style;
 };
 
-export { BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, type Freshness, type FreshnessStatus, Style, type VolatilityLevel, academicChaptersRenderer, academicStyle, bookScaffoldIntegration, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, researchPortfolioStyle, toolsChaptersRenderer, toolsStyle, volatilityLevels };
+/**
+ * src/lib/define-tips.ts — `defineTips()` API for cross-volume tip registry
+ * (v4.3.0, closes #70).
+ *
+ * Pragmatic Programmer-style numbered tips can be distributed across multiple
+ * volumes (e.g., Handbook tips 1-25, Architect's Reference 26-40, Field-Guide
+ * 41-50). Authors write `<Tip n="14" ...>` with explicit numbers; defineTips()
+ * lets per-volume books offset their displayed numbers + label without
+ * renumbering source tags.
+ *
+ * Branded type follows the same convention as `defineStyle` (v4.0.0 D6):
+ * type-only `unique symbol` brand, closed shape, readonly fields, no public
+ * index signature. Consumer-side metadata goes in scoped `extra` if needed.
+ */
+declare const TipsConfigBrand: unique symbol;
+interface TipsConfig {
+    /** Type-only brand for nominal typing. Set automatically by defineTips. */
+    readonly [TipsConfigBrand]: true;
+    /** Internal version marker; auto-set to 1 by defineTips. */
+    readonly __tipsConfigVersion: 1;
+    /** Display offset added to each `<Tip n="N">` for cross-volume coordination.
+     *  Example: Vol B with volumeOffset=25 renders `<Tip n="1">` as "Tip 26". */
+    readonly volumeOffset?: number;
+    /** Optional label shown alongside tip numbers in the /tips index + TipsCard.
+     *  Example: "Vol B" → "Vol B Tip 26". */
+    readonly volumeLabel?: string;
+    /** Scoped consumer-side metadata (matches defineStyle pattern). */
+    readonly extra?: Readonly<Record<string, unknown>>;
+}
+/** Input type for defineTips — omits the auto-set internal fields. */
+type TipsConfigInput = Omit<TipsConfig, typeof TipsConfigBrand | '__tipsConfigVersion'>;
+/**
+ * Identity helper that creates a typed, branded TipsConfig.
+ * Zero runtime overhead beyond an object spread + version marker.
+ *
+ * Usage:
+ *
+ *   import { defineTips } from '@brandon_m_behring/book-scaffold-astro';
+ *
+ *   export const tipsConfig = defineTips({
+ *     volumeOffset: 25,
+ *     volumeLabel: 'Vol B',
+ *   });
+ *
+ * Consumed by `<Tip>` and `<TipsCard>` components + the auto-injected
+ * `/tips` route to compute display numbers from `<Tip n="N">` source tags.
+ */
+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 };

package/dist/index.mjs

@@ -376,8 +376,10 @@ var academicProfile = defineProfile({
     // academic consumers ship their own week-based /chapters listing
     convergence: false,
     // tools-profile-specific
-    frontmatter: false
+    frontmatter: false,
     // opt-in per book; see #7
+    tips: false
+    // v4.3.0 #70: opt-in per book; requires build-tips
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
@@ -490,8 +492,10 @@ var toolsProfile = defineProfile({
     // tools profile ships a flat chapter index
     convergence: true,
     // tools profile ships convergence dashboard
-    frontmatter: false
+    frontmatter: false,
     // opt-in per book; see #7
+    tips: false
+    // v4.3.0 #70: opt-in per book
   },
   styles: [
     "tokens.css",
@@ -568,8 +572,10 @@ var minimalProfile = defineProfile({
     print: true,
     chapters: false,
     convergence: false,
-    frontmatter: false
+    frontmatter: false,
     // opt-in per book; see #7
+    tips: false
+    // v4.3.0 #70: 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
@@ -587,8 +593,10 @@ var courseNotesProfile = defineProfile({
     chapters: false,
     // multi-book consumers route via [book]/[slug] themselves
     convergence: false,
-    frontmatter: false
+    frontmatter: false,
     // opt-in per book; see #7
+    tips: false
+    // v4.3.0 #70: 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
@@ -607,8 +615,10 @@ var researchPortfolioProfile = defineProfile({
     // portfolio books ship their own landing/index
     convergence: false,
     // tools-profile-specific
-    frontmatter: true
+    frontmatter: true,
     // portfolios universally need title/disclosure/banner pages
+    tips: false
+    // v4.3.0 #70: opt-in per book
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
@@ -800,7 +810,16 @@ var ROUTE_REGISTRY = {
   search: { pattern: "/search", file: "search.astro" },
   print: { pattern: "/print", file: "print.astro" },
   chapters: { pattern: "/chapters", file: "chapters.astro" },
+  // v4.3.0 (#69): per-chapter dynamic route auto-injected when
+  // routes.chapters: true. Mirrors the frontmatter pattern — toolkit ships
+  // BOTH the /chapters/ index AND the /chapters/<slug>/ dynamic route.
+  // Pre-v4.3.0 each consumer wrote this file by hand; all instances were
+  // mechanical copies of the same boilerplate.
+  chaptersSlug: { pattern: "/chapters/[...slug]", file: "chapters/[...slug].astro" },
   convergence: { pattern: "/convergence", file: "convergence.astro" },
+  // 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" },
   // 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).
@@ -841,8 +860,13 @@ function bookScaffoldIntegration(opts) {
         if (def.katex) {
           injectScript("page-ssr", "import 'katex/dist/katex.min.css';");
         }
+        const routesToInject = [];
         for (const [name, on] of Object.entries(enabledRoutes)) {
           if (!on) continue;
+          routesToInject.push(name);
+          if (name === "chapters") routesToInject.push("chaptersSlug");
+        }
+        for (const name of routesToInject) {
           const route = ROUTE_REGISTRY[name];
           if (!route) continue;
           const pattern = name === "frontmatter" ? frontmatterPatternFromPrefix(fmPrefix) : route.pattern;
@@ -1070,6 +1094,11 @@ var BUILTIN_STYLES = {
   "course-notes": courseNotesStyle,
   "research-portfolio": researchPortfolioStyle
 };
+
+// src/lib/define-tips.ts
+function defineTips(opts) {
+  return { __tipsConfigVersion: 1, ...opts };
+}
 export {
   BOOK_PRESETS,
   BOOK_PROFILES,
@@ -1091,6 +1120,7 @@ export {
   defineMdxComponents,
   defineProfile,
   defineStyle,
+  defineTips,
   fallbackChaptersRenderer,
   freshnessLabel,
   getFreshness,

package/dist/schemas.d.ts

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

package/dist/schemas.mjs

@@ -261,8 +261,10 @@ var academicProfile = defineProfile({
     // academic consumers ship their own week-based /chapters listing
     convergence: false,
     // tools-profile-specific
-    frontmatter: false
+    frontmatter: false,
     // opt-in per book; see #7
+    tips: false
+    // v4.3.0 #70: opt-in per book; requires build-tips
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
@@ -375,8 +377,10 @@ var toolsProfile = defineProfile({
     // tools profile ships a flat chapter index
     convergence: true,
     // tools profile ships convergence dashboard
-    frontmatter: false
+    frontmatter: false,
     // opt-in per book; see #7
+    tips: false
+    // v4.3.0 #70: opt-in per book
   },
   styles: [
     "tokens.css",
@@ -453,8 +457,10 @@ var minimalProfile = defineProfile({
     print: true,
     chapters: false,
     convergence: false,
-    frontmatter: false
+    frontmatter: false,
     // opt-in per book; see #7
+    tips: false
+    // v4.3.0 #70: 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
@@ -472,8 +478,10 @@ var courseNotesProfile = defineProfile({
     chapters: false,
     // multi-book consumers route via [book]/[slug] themselves
     convergence: false,
-    frontmatter: false
+    frontmatter: false,
     // opt-in per book; see #7
+    tips: false
+    // v4.3.0 #70: 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
@@ -492,8 +500,10 @@ var researchPortfolioProfile = defineProfile({
     // portfolio books ship their own landing/index
     convergence: false,
     // tools-profile-specific
-    frontmatter: true
+    frontmatter: true,
     // portfolios universally need title/disclosure/banner pages
+    tips: false
+    // v4.3.0 #70: 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.2.0",
+  "version": "4.3.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -57,6 +57,8 @@
     "./components/Divergence.astro": "./components/Divergence.astro",
     "./components/DynConnect.astro": "./components/DynConnect.astro",
     "./components/ExampleBox.astro": "./components/ExampleBox.astro",
+    "./components/Exercise.astro": "./components/Exercise.astro",
+    "./components/ExerciseSolutions.astro": "./components/ExerciseSolutions.astro",
     "./components/Figure.astro": "./components/Figure.astro",
     "./components/InsightBox.astro": "./components/InsightBox.astro",
     "./components/KeyIdea.astro": "./components/KeyIdea.astro",
@@ -68,17 +70,21 @@
     "./components/Pitfall.astro": "./components/Pitfall.astro",
     "./components/PocLayout.astro": "./components/PocLayout.astro",
     "./components/PolicyRef.astro": "./components/PolicyRef.astro",
+    "./components/Practice.astro": "./components/Practice.astro",
     "./components/PreReleaseBanner.astro": "./components/PreReleaseBanner.astro",
     "./components/Recovery.astro": "./components/Recovery.astro",
     "./components/ResultBox.astro": "./components/ResultBox.astro",
     "./components/Sidebar.astro": "./components/Sidebar.astro",
     "./components/Sidenote.astro": "./components/Sidenote.astro",
     "./components/SkillBox.astro": "./components/SkillBox.astro",
+    "./components/Solution.astro": "./components/Solution.astro",
     "./components/SourceArchive.astro": "./components/SourceArchive.astro",
     "./components/StatusBadge.astro": "./components/StatusBadge.astro",
     "./components/Tag.astro": "./components/Tag.astro",
     "./components/Theorem.astro": "./components/Theorem.astro",
+    "./components/Tip.astro": "./components/Tip.astro",
     "./components/TipBox.astro": "./components/TipBox.astro",
+    "./components/TipsCard.astro": "./components/TipsCard.astro",
     "./components/ToolFilter": {
       "types": "./dist/components/ToolFilter.d.ts",
       "import": "./dist/components/ToolFilter.mjs"

package/pages/chapters/[...slug].astro

@@ -0,0 +1,40 @@
+---
+/**
+ * Auto-injected per-chapter dynamic route (v4.3.0, closes #69).
+ *
+ * Gated on `routes.chapters: true` via bookScaffoldIntegration's
+ * injectRoute call. Mirrors the frontmatter route pattern (v3.4.0 #7):
+ * the toolkit ships BOTH the /chapters/ index AND the /chapters/<slug>/
+ * dynamic route, so consumers don't have to write the boilerplate.
+ *
+ * Layout switching by preset:
+ *   - academic + research-portfolio → Chapter.astro (KaTeX + theorem chrome)
+ *   - all others → Base.astro (lighter; for tools/minimal/course-notes)
+ *
+ * Pre-v4.3.0 each consumer wrote this file by hand; all instances were
+ * mechanical copies (see post_transformers/guides/web/src/pages/chapters/
+ * [...slug].astro and double_ml_time_series/web/src/pages/chapters/
+ * [...slug].astro for the canonical pattern).
+ */
+import { getCollection, render } from 'astro:content';
+import Chapter from '../../layouts/Chapter.astro';
+import Base from '../../layouts/Base.astro';
+
+const BOOK_PRESET = import.meta.env.BOOK_PRESET ?? 'minimal';
+const USE_CHAPTER_LAYOUT = ['academic', 'research-portfolio'].includes(BOOK_PRESET);
+
+export async function getStaticPaths() {
+  const chapters = await getCollection('chapters', (entry) => !entry.data.draft);
+  return chapters.map((entry) => ({
+    params: { slug: entry.id },
+    props: { entry },
+  }));
+}
+
+const { entry } = Astro.props;
+const { Content, headings } = await render(entry);
+const Layout = USE_CHAPTER_LAYOUT ? Chapter : Base;
+---
+<Layout entry={entry} headings={headings}>
+  <Content />
+</Layout>

package/pages/chapters.astro

@@ -112,7 +112,7 @@ for (const c of chapters) {
         <ol class="chapter-list">
           {cards.map((card) => (
             <li class="chapter-card" data-tools={card.toolsAttr}>
-              <a href={`/${card.c.id}/`} class="chapter-card-link">
+              <a href={`/chapters/${card.c.id}/`} class="chapter-card-link">
                 <div class="chapter-card-meta">
                   <span class="chapter-card-number">{card.number}</span>
                   {card.volatility && (

package/pages/tips.astro

@@ -0,0 +1,51 @@
+---
+/**
+ * Auto-injected /tips route (v4.3.0, closes #70).
+ *
+ * Gated on `routes.tips: true`. Reads `src/data/tips.json` (emitted by
+ * `book-scaffold build-tips`); renders an ordered list with anchor
+ * permalinks (`/tips#tip-N`).
+ *
+ * Graceful skip: if tips.json doesn't exist, renders an instructions
+ * page (doesn't fail the build).
+ */
+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.';
+}
+---
+<Base title="Tips" description="Numbered tips from this book, drawn from <Tip> instances in chapters.">
+  <article class="prose">
+    <h1>Tips</h1>
+    {loadError && (
+      <p class="tips-empty">{loadError}</p>
+    )}
+    {!loadError && tips.length === 0 && (
+      <p class="tips-empty">No tips defined yet. Add <code>&lt;Tip n="1" title="..."&gt;...&lt;/Tip&gt;</code> to a chapter and rebuild.</p>
+    )}
+    {tips.length > 0 && (
+      <ol class="tips-index">
+        {tips.map((tip) => (
+          <li id={`tip-${tip.n}`} class="tips-index-item">
+            <h2 class="tips-index-title">
+              <span class="tips-index-number">Tip {tip.n}.</span>
+              {tip.title}
+            </h2>
+            {tip.preview && (
+              <p class="tips-index-preview">{tip.preview}</p>
+            )}
+            <p class="tips-index-meta">
+              From <a href={`/chapters/${tip.chapter}/`}>{tip.chapter}</a>
+            </p>
+          </li>
+        ))}
+      </ol>
+    )}
+  </article>
+</Base>

package/recipes/17-draft-chapter-workflow.md

@@ -0,0 +1,88 @@
+# Recipe 17 — Draft chapter workflow (v4.3.0+)
+
+The scaffold ships a `draft: boolean` field on every chapter schema (default `false`). Chapters with `draft: true` are filtered out by the canonical chapter-list and per-chapter routes — they exist in `src/content/chapters/` but don't render. Closes [#68](https://github.com/brandon-behring/2-scaffold-astro/issues/68).
+
+## TL;DR
+
+```yaml
+---
+title: "My in-progress chapter"
+week: 4
+part: foundations
+status: scaffolded
+draft: true   # ← Chapter is invisible while draft: true. Flip to false to publish.
+---
+```
+
+## The filter
+
+Both the scaffold-injected `/chapters/` index AND the auto-injected per-chapter route `/chapters/[...slug]/` (new in v4.3.0; see [#69](https://github.com/brandon-behring/2-scaffold-astro/issues/69)) filter via:
+
+```ts
+await getCollection('chapters', (entry) => !entry.data.draft);
+```
+
+So a `draft: true` chapter:
+- Does **not** appear in `/chapters/`
+- Does **not** get a `/chapters/<slug>/` route
+- Does **not** appear in nav / TOC
+- DOES exist in the source tree (still validated by `book-scaffold validate`; still scanned by `book-scaffold build-labels`)
+
+This is by design: keeps in-progress work under version control without polluting the production build.
+
+## Schema definition
+
+All 5 built-in chapter schemas define `draft`:
+
+```ts
+// package/src/schemas.ts (academic + tools + minimal + course-notes + research-portfolio)
+draft: z.boolean().default(false),
+```
+
+The default is `false` — chapters publish by default. Authors flip to `true` to hide a work-in-progress.
+
+## When to use draft
+
+- **Active drafting** — writing a chapter over multiple sessions; don't want intermediate states deployed.
+- **Outline-stage chapters** — frontmatter exists but body is just a TODO list.
+- **Migration in progress** — porting from another source format (LaTeX, Docs, etc.); keep the partial port in-tree but invisible.
+
+When you're ready to publish, edit the frontmatter to `draft: false` (or delete the line — default is false).
+
+## When NOT to use draft
+
+- **Deleting a chapter** — if you no longer want it at all, delete the file. `draft: true` is for chapters that ARE coming back to live.
+- **Reordering** — `draft` doesn't affect chapter ordering. To rearrange chapters, edit the `week:` / `part:` / `chapter:` frontmatter fields (the field varies by preset).
+- **Section-level hiding** — `draft` is whole-chapter only. To hide a section within a published chapter, comment it out in MDX or use a build-time conditional.
+
+## Previewing draft chapters during development
+
+The default canonical filter excludes drafts in BOTH `npm run dev` and `npm run build`. To preview a draft locally without publishing it:
+
+**Option A** (transient): temporarily flip the chapter to `draft: false`, run `npm run dev`, then flip back before committing.
+
+**Option B** (recommended): scope the filter to honor an env var in your `src/pages/chapters/[...slug].astro` (only relevant if you've ejected from the scaffold's auto-injected route):
+
+```ts
+const includeDrafts = import.meta.env.BOOK_INCLUDE_DRAFTS === '1';
+const chapters = await getCollection('chapters', (entry) =>
+  includeDrafts || !entry.data.draft
+);
+```
+
+Then run `BOOK_INCLUDE_DRAFTS=1 npm run dev` for the draft-inclusive preview. This is NOT shipped in the scaffold's auto-route (would muddy the production behavior); add it to a consumer-owned override file if you need it.
+
+## Common gotchas
+
+- **Silent zero-chapters build** — if EVERY chapter has `draft: true` (or no chapters are published yet), `/chapters/` renders an empty list and no `/chapters/<slug>/` routes generate. Build succeeds with no warnings. Diagnosis: check `npx book-scaffold validate` output — it reports the total `chapter(s) checked` regardless of draft status, so you'll see "5 chapter(s) checked" even when no chapters render.
+- **Author's intent vs filter behavior** — early Phase-1 chapter authoring sessions sometimes catch this: chapter is fully written, frontmatter looks right, but it doesn't render. First check: `grep '^draft:' src/content/chapters/*.mdx` to find drafts. Time-to-diagnosis tax averages ~20 min per consumer per session until they remember the filter exists. This recipe is the discoverability fix.
+
+## See also
+
+- `recipes/01-create-book.md` — full scaffold getting-started flow
+- `recipes/09-validation.md` — `book-scaffold validate` semantics (which DON'T honor the draft filter)
+- `PACKAGE_DESIGN.md §5` — `defineBookSchemas` API (where the draft field lives)
+
+## Feedback
+
+If the filter behavior surprises you in a new way or you want a different draft-preview UX (e.g., a `BOOK_INCLUDE_DRAFTS` env in the scaffold's auto-route by default), file an issue at https://github.com/brandon-behring/book-scaffold-astro/issues with the `consumer:<workspace>` label.

package/scripts/build-tips.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * scripts/build-tips.mjs — emit src/data/tips.json from <Tip> instances
+ * in chapter MDX (v4.3.0, closes #70).
+ *
+ * Scans `src/content/chapters/**\/*.mdx` (honoring loader.base via
+ * readChaptersBase from walk-mdx.mjs — same path-resolution as build-labels +
+ * validate). Extracts `<Tip n="N" title="T">body</Tip>` occurrences via regex
+ * (same approach as build-labels.mjs LABELABLE_TYPES extraction). Emits an
+ * array sorted by n.
+ *
+ * Output shape:
+ *   [
+ *     { "n": 1, "title": "...", "chapter": "ch-slug", "preview": "first 80 chars" },
+ *     ...
+ *   ]
+ *
+ * Graceful no-op: if no <Tip> instances exist, writes [] (doesn't fail
+ * builds for consumers who don't use the feature).
+ *
+ * Run on `prebuild` via the consumer's package.json. Doesn't depend on
+ * Astro virtual modules — pure regex + Node fs.
+ */
+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-tips
+
+Scan chapter MDX for <Tip n="N" title="T">body</Tip> occurrences; emit
+src/data/tips.json sorted by n. Used by the /tips auto-route + <TipsCard>
+component when routes.tips: true.
+
+Env:
+  BOOK_CHAPTERS_DIR   Override chapters dir (default: src/content/chapters).
+  BOOK_TIPS_OUT       Override output path (default: src/data/tips.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_TIPS_OUT ?? 'src/data/tips.json';
+
+/**
+ * Extract <Tip n="..." title="..."> tags and their body content from MDX.
+ *
+ * Regex captures:
+ *   - n: the tip number (string; coerced to int when writing JSON)
+ *   - title: the tip title (string)
+ *   - body: text between opening + closing tags
+ *
+ * Limitations (deliberate, documented):
+ *   - Doesn't handle nested <Tip> tags (no real use case)
+ *   - String attributes must use single OR double quotes (not template literals)
+ *   - title may not contain a literal quote of the same type used as delimiter
+ *     (escaping isn't supported)
+ *   - body is captured raw; first 80 chars (ignoring leading whitespace) used as preview
+ */
+function extractTips(source, chapterSlug) {
+  const tips = [];
+  // Two-branch alternation (single OR double quotes), no backreference —
+  // same portability pattern as readChaptersBase regex (v4.1.2 lesson).
+  const re = new RegExp(
+    [
+      // double-quoted attrs
+      `<Tip\\s+n="([^"]+)"\\s+title="([^"]+)"\\s*>([\\s\\S]*?)</Tip>`,
+      // single-quoted attrs
+      `<Tip\\s+n='([^']+)'\\s+title='([^']+)'\\s*>([\\s\\S]*?)</Tip>`,
+      // mixed (n double, title single) — rare but support it
+      `<Tip\\s+n="([^"]+)"\\s+title='([^']+)'\\s*>([\\s\\S]*?)</Tip>`,
+      // mixed (n single, title double)
+      `<Tip\\s+n='([^']+)'\\s+title="([^"]+)"\\s*>([\\s\\S]*?)</Tip>`,
+    ].join('|'),
+    'g',
+  );
+  for (const match of source.matchAll(re)) {
+    // One of the 4 alternation branches matched; locate captures.
+    const [, n1, t1, b1, n2, t2, b2, n3, t3, b3, n4, t4, b4] = match;
+    const n = n1 || n2 || n3 || n4;
+    const title = t1 || t2 || t3 || t4;
+    const body = b1 || b2 || b3 || b4 || '';
+    if (!n || !title) continue;
+    const nNum = Number.parseInt(n, 10);
+    if (!Number.isFinite(nNum)) continue;
+    const preview = body
+      .trim()
+      .replace(/\s+/g, ' ')
+      .slice(0, 80);
+    tips.push({
+      n: nNum,
+      title,
+      chapter: chapterSlug,
+      preview,
+    });
+  }
+  return tips;
+}
+
+async function main() {
+  const allTips = [];
+  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;
+    }
+    allTips.push(...extractTips(source, chapterSlug));
+  }
+
+  // Sort by n; warn on duplicates (don't fail — the index page just shows duplicates).
+  allTips.sort((a, b) => a.n - b.n);
+  const seenN = new Set();
+  for (const tip of allTips) {
+    if (seenN.has(tip.n)) {
+      process.stderr.write(`build-tips: WARN duplicate Tip n="${tip.n}" (last wins on /tips index)\n`);
+    }
+    seenN.add(tip.n);
+  }
+
+  const outPath = resolve(CWD, OUTPUT_PATH);
+  await mkdir(dirname(outPath), { recursive: true });
+  await writeFile(outPath, JSON.stringify(allTips, null, 2) + '\n');
+  process.stdout.write(`build-tips: ${allTips.length} tip${allTips.length === 1 ? '' : 's'} → ${OUTPUT_PATH}\n`);
+}
+
+main().catch((err) => {
+  console.error('build-tips: failed');
+  console.error(err.message ?? err);
+  process.exit(1);
+});
+
+// Export for tests.
+export { extractTips };

package/src/lib/define-tips.ts

@@ -0,0 +1,56 @@
+/**
+ * src/lib/define-tips.ts — `defineTips()` API for cross-volume tip registry
+ * (v4.3.0, closes #70).
+ *
+ * Pragmatic Programmer-style numbered tips can be distributed across multiple
+ * volumes (e.g., Handbook tips 1-25, Architect's Reference 26-40, Field-Guide
+ * 41-50). Authors write `<Tip n="14" ...>` with explicit numbers; defineTips()
+ * lets per-volume books offset their displayed numbers + label without
+ * renumbering source tags.
+ *
+ * Branded type follows the same convention as `defineStyle` (v4.0.0 D6):
+ * type-only `unique symbol` brand, closed shape, readonly fields, no public
+ * index signature. Consumer-side metadata goes in scoped `extra` if needed.
+ */
+
+// ===== Branded nominal type =====
+
+declare const TipsConfigBrand: unique symbol;
+
+export interface TipsConfig {
+  /** Type-only brand for nominal typing. Set automatically by defineTips. */
+  readonly [TipsConfigBrand]: true;
+  /** Internal version marker; auto-set to 1 by defineTips. */
+  readonly __tipsConfigVersion: 1;
+  /** Display offset added to each `<Tip n="N">` for cross-volume coordination.
+   *  Example: Vol B with volumeOffset=25 renders `<Tip n="1">` as "Tip 26". */
+  readonly volumeOffset?: number;
+  /** Optional label shown alongside tip numbers in the /tips index + TipsCard.
+   *  Example: "Vol B" → "Vol B Tip 26". */
+  readonly volumeLabel?: string;
+  /** Scoped consumer-side metadata (matches defineStyle pattern). */
+  readonly extra?: Readonly<Record<string, unknown>>;
+}
+
+/** Input type for defineTips — omits the auto-set internal fields. */
+export type TipsConfigInput = Omit<TipsConfig, typeof TipsConfigBrand | '__tipsConfigVersion'>;
+
+/**
+ * Identity helper that creates a typed, branded TipsConfig.
+ * Zero runtime overhead beyond an object spread + version marker.
+ *
+ * Usage:
+ *
+ *   import { defineTips } from '@brandon_m_behring/book-scaffold-astro';
+ *
+ *   export const tipsConfig = defineTips({
+ *     volumeOffset: 25,
+ *     volumeLabel: 'Vol B',
+ *   });
+ *
+ * Consumed by `<Tip>` and `<TipsCard>` components + the auto-injected
+ * `/tips` route to compute display numbers from `<Tip n="N">` source tags.
+ */
+export function defineTips(opts: TipsConfigInput): TipsConfig {
+  return { __tipsConfigVersion: 1, ...opts } as TipsConfig;
+}

package/src/profile-kit.ts

@@ -49,6 +49,14 @@ export interface RouteToggles {
    * If enabled without defining the collection, Astro errors clearly at build.
    */
   frontmatter: boolean;
+  /**
+   * v4.3.0 (closes #70): auto-inject `/tips` route listing all numbered
+   * `<Tip>` instances from chapter MDX. Requires running
+   * `book-scaffold build-tips` (via prebuild) which emits src/data/tips.json.
+   * Default `false` per profile — opt in via
+   * defineBookConfig({ routes: { tips: true } }).
+   */
+  tips: boolean;
 }
 
 /** Profile definition — declarative shape for one book profile. */

package/src/profiles/academic.ts

@@ -23,6 +23,7 @@ export const academicProfile = defineProfile({
     chapters: false,        // academic consumers ship their own week-based /chapters listing
     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
   },
   styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
   katex: true,

package/src/profiles/course-notes.ts

@@ -25,6 +25,7 @@ export const courseNotesProfile = defineProfile({
     chapters: false,        // multi-book consumers route via [book]/[slug] themselves
     convergence: false,
     frontmatter: false,     // opt-in per book; see #7
+    tips: false,            // v4.3.0 #70: 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

@@ -20,6 +20,7 @@ export const minimalProfile = defineProfile({
     chapters: false,
     convergence: false,
     frontmatter: false,     // opt-in per book; see #7
+    tips: false,            // v4.3.0 #70: 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

@@ -36,6 +36,7 @@ export const researchPortfolioProfile = defineProfile({
     chapters: false,             // portfolio books ship their own landing/index
     convergence: false,          // tools-profile-specific
     frontmatter: true,           // portfolios universally need title/disclosure/banner pages
+    tips: false,                 // v4.3.0 #70: 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

@@ -20,6 +20,7 @@ export const toolsProfile = defineProfile({
     chapters: true,         // tools profile ships a flat chapter index
     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
   },
   styles: [
     'tokens.css', 'layout.css', 'callouts.css', 'chapter.css',

package/styles/callouts.css

@@ -210,6 +210,151 @@
   color: var(--color-text);
 }
 
+/* ===== v4.3.0 book-genre family =====================================
+ * Tip / TipsCard (Pragmatic Programmer precedent, #70)
+ * Exercise / Practice / Solution / ExerciseSolutions (CS:APP, #71)
+ */
+
+/* Tip (numbered, #70). Gold border + tip-number badge + title row. */
+.callout-tip-numbered {
+  border-left-color: var(--callout-learn);
+  background: var(--warm-gold-tint);
+}
+.callout-tip-numbered .callout-tip-header {
+  display: flex;
+  align-items: baseline;
+  gap: var(--space-3);
+  margin-bottom: var(--space-2);
+}
+.callout-tip-numbered .callout-tip-number {
+  font-size: var(--text-xs);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  font-weight: 700;
+  color: var(--callout-learn);
+  padding: 0 var(--space-2);
+  border: 1px solid var(--callout-learn);
+  border-radius: var(--radius-sm);
+  white-space: nowrap;
+}
+.callout-tip-numbered .callout-tip-title {
+  font-weight: 600;
+}
+
+/* TipsCard (print-friendly tips card, #70). */
+.tips-card {
+  margin: var(--space-8) 0;
+  padding: var(--space-6);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+  background: var(--color-bg-subtle);
+  page-break-inside: avoid;
+}
+.tips-card-title {
+  margin: 0 0 var(--space-4) 0;
+  font-size: var(--text-2xl);
+}
+.tips-card-list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+.tips-card-item {
+  padding: var(--space-2) 0;
+  border-bottom: 1px dashed var(--color-border);
+}
+.tips-card-link {
+  display: flex;
+  gap: var(--space-3);
+  text-decoration: none;
+  color: var(--color-text);
+}
+.tips-card-number {
+  font-weight: 700;
+  color: var(--callout-learn);
+  min-width: 2.5em;
+}
+.tips-card-empty {
+  color: var(--color-text-muted);
+  font-style: italic;
+}
+
+/* Exercise (#71). Light treatment for inline placement. */
+.exercise {
+  margin: var(--space-4) 0;
+  padding: var(--space-3) var(--space-4);
+  border-left: var(--border-bar) solid var(--color-border);
+  background: var(--color-bg-subtle);
+}
+.exercise-label {
+  display: block;
+  font-weight: 600;
+  font-size: var(--text-sm);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--color-text-muted);
+  margin-bottom: var(--space-2);
+}
+
+/* Practice (#71). Diamond-marker difficulty + label. */
+.practice {
+  margin: var(--space-6) 0;
+  padding: var(--space-4);
+  border-left: var(--border-bar) solid var(--callout-official);
+  background: var(--warm-plum-tint);
+}
+.practice-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  margin-bottom: var(--space-3);
+}
+.practice-label {
+  font-weight: 600;
+  font-size: var(--text-sm);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+.practice-difficulty {
+  font-family: var(--font-code);
+  color: var(--callout-official);
+}
+
+/* Solution (#71). Inside ExerciseSolutions wrapper. */
+.solution {
+  margin: var(--space-5) 0;
+  padding-left: var(--space-4);
+  border-left: 2px solid var(--callout-insight);
+}
+.solution-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  margin-bottom: var(--space-2);
+}
+.solution-label {
+  font-weight: 600;
+  font-size: var(--text-sm);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--callout-insight);
+}
+.solution-backlink {
+  font-size: var(--text-xs);
+  text-decoration: none;
+  color: var(--color-text-muted);
+}
+
+/* ExerciseSolutions (#71). Section wrapper at chapter end. */
+.exercise-solutions {
+  margin: var(--space-12) 0 var(--space-6) 0;
+  padding-top: var(--space-6);
+  border-top: 2px solid var(--color-border);
+}
+.exercise-solutions-heading {
+  margin: 0 0 var(--space-5) 0;
+}
+
 /* ===== Theorem family (Theorem.astro) =====
  * Plain (theorem/proposition/lemma/corollary): italic body
  * Definition family (definition/example/exercise/remark/proof): upright body