@brandon_m_behring/book-scaffold-astro 3.1.0 → 3.3.0

package/LATEX_TO_MDX_MAPPING.md

@@ -0,0 +1,130 @@
+# LaTeX → MDX component mapping
+
+A consumer-facing reference for converting LaTeX book sources into MDX that consumes `@brandon_m_behring/book-scaffold-astro` components.
+
+The scaffold ships **38 components**. Without this map, a `.tex → .mdx` conversion ends up rediscovering them by grep — and frequently rebuilding duplicates. This doc is the canonical "if your LaTeX source has `\begin{<env>}`, here's the component" reference.
+
+> Pair with [PACKAGE_DESIGN.md](./PACKAGE_DESIGN.md) §17 for the broader migration story and the `defineMdxComponents` helper for consumer-shipped extensions.
+
+## Components shipped by the scaffold
+
+| LaTeX construct | MDX component | Import path | Signature | Notes |
+|---|---|---|---|---|
+| `\begin{tcolorbox}[narrativebox]` | `SkillBox` | `…/components/SkillBox.astro` | `title: string` | Recipe / how-to box |
+| `\begin{tcolorbox}[conceptbox]` | `ConceptBox` | `…/components/ConceptBox.astro` | `term: string` | Single-term definition |
+| `\begin{tcolorbox}[insightbox]` | `InsightBox` | `…/components/InsightBox.astro` | `title?: string` | Non-obvious observation |
+| `\begin{keyconcept}` | `KeyIdea` | `…/components/KeyIdea.astro` | — | Crystallized takeaway |
+| `\begin{warnbox}` / `\warningmargin{}` | `WarnBox` | `…/components/WarnBox.astro` | `title?: string` | Caveats / failure modes |
+| `\begin{notebox}` | `NoteBox` | `…/components/NoteBox.astro` | `title?: string` | Chapter overviews |
+| `\begin{paperbox}` | `PaperBox` | `…/components/PaperBox.astro` | `title?: string` | Paper restatement |
+| `\begin{counterbox}` | `CounterBox` | `…/components/CounterBox.astro` | `title?: string` | Counter-evidence |
+| `\begin{examplebox}` | `ExampleBox` | `…/components/ExampleBox.astro` | `title?: string` | Extended walkthrough |
+| `\begin{openquestion}` | `OpenQuestion` | `…/components/OpenQuestion.astro` | `title?: string` | Research questions |
+| `\begin{trythis}` | `TryThis` | `…/components/TryThis.astro` | `title?: string` | Practice exercise |
+| `\begin{tipbox}` | `TipBox` | `…/components/TipBox.astro` | `title?: string` | Pro tips / shortcuts |
+| `\begin{dynconnect}` | `DynConnect` | `…/components/DynConnect.astro` | `title?: string` | Cross-domain connection |
+| `\begin{theorem}` / `\begin{proposition}` / `\begin{lemma}` / `\begin{corollary}` / `\begin{definition}` / `\begin{remark}` / `\begin{proof}` | `Theorem` | `…/components/Theorem.astro` | `kind, n?, name?, id?` | amsthm family — single component dispatches via `kind` prop |
+| `\marginnote{}` | `MarginNote` | `…/components/MarginNote.astro` | — | Side commentary |
+| `\sidenote{}` | `Sidenote` | `…/components/Sidenote.astro` | — | Auto-numbered marginalia (Tufte) |
+| `\includegraphics + \caption` | `Figure` | `…/components/Figure.astro` | `src, caption?, id?` | XRef-registered |
+| `\cite{}` / `\parencite{}` | `Citation` | `…/components/Citation.astro` | `src, as?` | Resolves `sources` collection |
+| `\cite{}` (inline) | `Cite` | `…/components/Cite.astro` | `key` | Inline citation key |
+| `\xref{}` / `\cref{}` | `XRef` | `…/components/XRef.astro` | `id` | Cross-reference resolver |
+| `\code{path:N}` / inline file refs | `CodeRef` | `…/components/CodeRef.astro` | `path, line?, lineEnd?` | GitHub-linked source ref |
+| (custom Shiki blocks) | `CodeBlock` | `…/components/CodeBlock.astro` | `lang, title?` | Wrapped fenced code |
+| `\recovery{}` | `Recovery` | `…/components/Recovery.astro` | `pattern, symptom?` | Anti-pattern escape |
+| `\casestudy{}` | `CaseStudy` | `…/components/CaseStudy.astro` | `date, title?` | Dated anecdote |
+| `\weekref{}` (academic) | `WeekRef` | `…/components/WeekRef.astro` | `week` | Cross-chapter week ref |
+
+Component subset table for tools-profile-specific UI (volatility dashboards, convergence timelines):
+
+| Construct | Component | Use case |
+|---|---|---|
+| Volatility badge | `Tag` | `volatility` enum chip in chapter meta |
+| Tool comparison | `ToolFilter` (island) | Interactive comparison gate |
+| Version selector | `VersionSelector` (island) | Switch between tool versions |
+| Convergence event | `Convergence` | "All tools converged here" timeline marker |
+| Divergence event | `Divergence` | "Tool X went its own way" annotation |
+| Pattern timeline | `PatternTimeline` | Multi-event convergence dashboard |
+| Status badge | `StatusBadge` | 7→3-state translation (academic) |
+| Source archive | `SourceArchive` | Tier-tagged source listing |
+
+## What is NOT shipped (extension candidates)
+
+The scaffold deliberately doesn't ship these. Add to your consumer via the [`defineMdxComponents`](#consumer-side-extensions-definemdxcomponents) helper described below; surface as a tracked issue if the gap recurs across pilots.
+
+- `\begin{problem}` / `\begin{solution}` — interview-prep problem cards
+- `\begin{vignette}` — multi-step scenario walkthroughs
+- `\begin{decisiontree}` — branching decision logic
+- `\begin{interviewcontext}` — interview-tied learning-outcome callouts
+- `<AnkiCard>` — flashcard widget
+- `<Term>` — glossary term reference with tooltip
+- `<RedFlag>` — escalated warning beyond `WarnBox`
+- `<NarrativeBox>` (with extended props) — if a consumer needs richer narrative annotations beyond `SkillBox`
+
+## Consumer-side extensions: `defineMdxComponents`
+
+When your book uses custom MDX components, create `src/mdx-components.ts` (or `.js` / `.mjs`) at your project root. The scaffold auto-detects it and threads the components through all auto-injected routes (`/print`, future `/pdf`, `/epub`).
+
+```ts
+// consumer's src/mdx-components.ts
+import { defineMdxComponents } from '@brandon_m_behring/book-scaffold-astro';
+import AnkiCard from './components/AnkiCard.astro';
+import NarrativeBox from './components/NarrativeBox.astro';
+import Term from './components/Term.astro';
+
+export default defineMdxComponents({
+  AnkiCard,
+  NarrativeBox,
+  Term,
+});
+```
+
+The `defineMdxComponents<T>()` helper is a TypeScript identity function — it returns the value unchanged, but preserves the exact key→component type mapping for IntelliSense. Same pattern as Vite/Astro `defineConfig`, Zod `z.object`, Drizzle `pgTable`.
+
+To use a non-default path, pass it explicitly:
+
+```ts
+// astro.config.mjs
+export default defineBookConfig({
+  site: '...',
+  mdxComponentsModule: './src/my-custom-components.ts',
+});
+```
+
+## Disabling auto-injected routes
+
+The scaffold auto-injects per-profile defaults (see [PACKAGE_DESIGN.md](./PACKAGE_DESIGN.md) §6). Multi-book consumers (one Astro app, many books under `[book]/[chapter]`) typically want the flat `/chapters` route off:
+
+```ts
+// astro.config.mjs
+import { defineBookConfig } from '@brandon_m_behring/book-scaffold-astro';
+
+export default defineBookConfig({
+  site: '...',
+  profile: 'course-notes',
+  routes: {
+    chapters: false,        // override the profile default
+    convergence: false,
+  },
+});
+```
+
+The shape is fixed (`references | search | print | chapters | convergence`) and TypeScript catches typos like `convergance: false`.
+
+## Common conversion mistakes
+
+Errors observed during the DLAI pilot (closed in v3.3.0 issue #5):
+
+1. **Built `NarrativeBox` from scratch** → should have used `SkillBox`. Same vertical box semantic; `SkillBox` already has the `title` prop.
+2. **Built `ConceptBox` (block container)** → conflicts with scaffold's `ConceptBox` (term-definition signature). Either rename the consumer one (`ConceptBlock`) or use scaffold's signature.
+3. **Built `KeyConcept`** → should have used `KeyIdea`. Same crystallized-takeaway role; the scaffold's name comes from the Tufte-style margin-emphasis convention.
+4. **Built `RedFlag`** → should have used `WarnBox`. Add a higher-severity variant via consumer-side `defineMdxComponents` if needed instead of duplicating WarnBox's semantic.
+5. **Built `Sidenote` with category prop** → conflicts with scaffold's auto-numbered `Sidenote`. The scaffold uses CSS counters; consumer-side category metadata can wrap (e.g., `<TypedSidenote category="recovery"><Sidenote>...</Sidenote></TypedSidenote>`).
+6. **Built duplicate `Citation` and `Figure`** → scaffold's versions are XRef-registered. Use them; extend behavior via wrapper components if richer attribution is needed.
+
+## See also
+
+- [PACKAGE_DESIGN.md](./PACKAGE_DESIGN.md) — full API contract + Phase A planning decisions
+- [README.md](./README.md) — toolkit overview + getting started
+- [CHANGELOG.md](../CHANGELOG.md) — release notes (issue #5 closed in v3.3.0)

package/components/ChapterHeader.astro

@@ -9,9 +9,15 @@
  * part, status, companion artifacts) appears in its place.
  *
  * v3.1.0 — academic flavor: Roman-numeral part labels, StatusBadge
- * component, and an optional companion-artifacts block matching v2.0's
- * hand-rolled academic ChapterHeader (verbatim restore for content density
- * parity at narrow viewports).
+ * component, and an optional companion-artifacts block.
+ *
+ * v3.2.0 — companions refactored from sibling <aside> to inline <span>
+ * elements inside the existing .chapter-meta flex row. v3.1.0 shipped
+ * <aside class="chapter-companions"> with no CSS; UA-default <ul> block
+ * layout added ~100px height at <=1280px, producing a uniform vertical
+ * pixel shift on all academic chapters. Inline rendering eliminates the
+ * extra block by construction. The data-companion attribute on each
+ * inline span preserves introspection.
  */
 import type { CollectionEntry } from 'astro:content';
 import { getFreshness, freshnessLabel } from '../src/lib/freshness';
@@ -92,13 +98,14 @@ const volatility = typeof d.volatility === 'string' ? d.volatility : null;
 // generic basename strip so any book whose render-notebooks output lands
 // under public/notebooks/ gets a correct deep link (v2.0 hardcoded a
 // post_transformers-specific prefix; v3.1.0 generalizes).
-const hasCompanions =
-  hasAcademicMeta &&
-  (typeof d.code_path === 'string' ||
-    typeof d.tests_path === 'string' ||
-    typeof d.notebook_path === 'string');
+//
+// v3.2.0: each companion renders as an inline <span class="chapter-companion">
+// inside .chapter-meta — no sibling <aside>, no <ul>, no "Companion artifacts:"
+// label. Zero added vertical height vs v2.0.
+const codePath = hasAcademicMeta && typeof d.code_path === 'string' ? d.code_path : null;
+const testsPath = hasAcademicMeta && typeof d.tests_path === 'string' ? d.tests_path : null;
 const notebookHtmlPath =
-  typeof d.notebook_path === 'string'
+  hasAcademicMeta && typeof d.notebook_path === 'string'
     ? `/notebooks/${(d.notebook_path as string)
         .replace(/^.*\//, '')
         .replace(/\.ipynb$/, '')}.html`
@@ -126,33 +133,25 @@ const notebookHtmlPath =
       </span>
     )}
     {updated && <span>Updated {formatDate(updated)}</span>}
+    {codePath && (
+      <span class="chapter-companion" data-companion="code">
+        <CodeRef path={codePath} />
+      </span>
+    )}
+    {testsPath && (
+      <span class="chapter-companion" data-companion="tests">
+        <CodeRef path={testsPath} />
+      </span>
+    )}
+    {notebookHtmlPath && (
+      <span class="chapter-companion" data-companion="notebook">
+        <a href={notebookHtmlPath}>Notebook</a>
+      </span>
+    )}
   </div>
   <h1>{title}</h1>
   {description && <p class="chapter-description">{description}</p>}
 
-  {hasCompanions && (
-    <aside class="chapter-companions">
-      <strong>Companion artifacts:</strong>
-      <ul>
-        {typeof d.code_path === 'string' && (
-          <li>
-            Implementation: <CodeRef path={d.code_path as string} />
-          </li>
-        )}
-        {typeof d.tests_path === 'string' && (
-          <li>
-            Tests: <CodeRef path={d.tests_path as string} />
-          </li>
-        )}
-        {notebookHtmlPath && (
-          <li>
-            Notebook: <a href={notebookHtmlPath}>{notebookHtmlPath}</a>
-          </li>
-        )}
-      </ul>
-    </aside>
-  )}
-
   {hasToolsMeta && volatility && (
     <div class="chapter-badge-row">
       <span class="chapter-badge-row-label">Volatility:</span>

package/dist/index.d.ts

@@ -1,135 +1,82 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { b as BookConfigOptions, d as BookScaffoldIntegrationOptions } from './types-BoCXCvBy.js';
-export { B as BOOK_PROFILES, a as BookConfigError, c as BookProfile, e as BookSchemasOptions, r as resolveProfile } from './types-BoCXCvBy.js';
-import { z } from 'astro/zod';
+import { b as BookConfigOptions, d as BookScaffoldIntegrationOptions, v as volatilityLevels } from './types-s8NxCLU2.js';
+export { A as AcademicChapter, B as BOOK_PROFILES, a as BookConfigError, c as BookProfile, e as BookSchemasOptions, C as ChapterFor, f as CourseNotesChapter, M as MinimalChapter, P as ProfileDefinition, R as RouteToggles, T as ToolsChapter, g as academicChapterSchema, h as academicParts, i as changeKinds, j as changelogSchema, k as chapterStatus, l as courseNotesChapterSchema, m as defineProfile, n as minimalChapterSchema, p as patternCategories, o as patternsSchema, r as resolveProfile, s as sourceTiers, q as sourcesSchema, t as toolSlugs, u as toolsChapterSchema } from './types-s8NxCLU2.js';
+import 'astro/zod';
 
 declare function defineBookConfig(opts: BookConfigOptions): Promise<AstroUserConfig>;
 
 declare function bookScaffoldIntegration(opts: BookScaffoldIntegrationOptions): AstroIntegration;
 
 /**
- * Zod schemas + enum constants for book content collections.
+ * Identity helper — consumers wrap their mdx-components map for TS inference.
+ * Same pattern as Vite/Astro defineConfig: a generic identity function that
+ * preserves the exact shape (vs widening to Record<string, …>).
  *
- * Imports `z` from `astro/zod` (a real module re-export) so schemas can
- * be constructed at package-load time outside an Astro runtime context.
- * `defineBookSchemas` in index.ts wraps these into Astro `defineCollection`
- * calls at the consumer's content-config load time.
+ *   export default defineMdxComponents({ AnkiCard, NarrativeBox });
  *
- * Schemas ported verbatim from v2.0 src/content.config.ts. See
- * PACKAGE_DESIGN.md §5 for the public reproduction.
+ * The generic constraint Record<string, unknown> is intentionally loose:
+ * consumer components are `.astro` files whose runtime type
+ * (AstroComponentFactory) lives in `astro/runtime/server/index.js` — not a
+ * public Astro export, and importing from internals creates fragility. The
+ * looser constraint lets the helper compile cleanly across Astro versions;
+ * IntelliSense still surfaces exact keys.
  */
+declare function defineMdxComponents<T extends Record<string, unknown>>(components: T): T;
 
-declare const toolSlugs: readonly ["claude-code", "gemini-cli", "codex-cli", "cross-tool"];
-declare const volatilityLevels: readonly ["stable-principle", "architectural-pattern", "feature-surface"];
-declare const sourceTiers: readonly ["T1-official", "T2-release-notes", "T3-practitioner", "T4-conjecture"];
-declare const changeKinds: readonly ["added", "removed", "changed", "deprecated"];
-declare const patternCategories: readonly ["safety", "scale", "context", "interaction", "extension", "other"];
-declare const academicParts: readonly ["foundations", "ssm-core", "beyond-ssm", "integration", "synthesis"];
-declare const chapterStatus: readonly ["implemented", "chapter_only", "reading_only", "prose_only", "code_only", "scaffolded", "planned"];
-declare const academicChapterSchema: z.ZodObject<{
-    week: z.ZodNumber;
-    part: z.ZodEnum<{
-        foundations: "foundations";
-        "ssm-core": "ssm-core";
-        "beyond-ssm": "beyond-ssm";
-        integration: "integration";
-        synthesis: "synthesis";
-    }>;
-    title: z.ZodString;
-    status: z.ZodEnum<{
-        implemented: "implemented";
-        chapter_only: "chapter_only";
-        reading_only: "reading_only";
-        prose_only: "prose_only";
-        code_only: "code_only";
-        scaffolded: "scaffolded";
-        planned: "planned";
-    }>;
-    roadmap_lines: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
-    code_path: z.ZodOptional<z.ZodString>;
-    tests_path: z.ZodOptional<z.ZodString>;
-    notebook_path: z.ZodOptional<z.ZodString>;
-    description: z.ZodOptional<z.ZodString>;
-    draft: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip>;
-declare const toolsChapterSchema: z.ZodObject<{
-    title: z.ZodString;
-    part: z.ZodNumber;
-    chapter: z.ZodNumber;
-    volatility: z.ZodEnum<{
-        "stable-principle": "stable-principle";
-        "architectural-pattern": "architectural-pattern";
-        "feature-surface": "feature-surface";
-    }>;
-    tools_compared: z.ZodArray<z.ZodEnum<{
-        "claude-code": "claude-code";
-        "gemini-cli": "gemini-cli";
-        "codex-cli": "codex-cli";
-        "cross-tool": "cross-tool";
-    }>>;
-    last_verified: z.ZodDate;
-    sources: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    description: z.ZodOptional<z.ZodString>;
-    draft: z.ZodDefault<z.ZodBoolean>;
-    updated: z.ZodOptional<z.ZodDate>;
-}, z.core.$strip>;
-declare const sourcesSchema: z.ZodObject<{
-    url: z.ZodString;
-    title: z.ZodString;
-    author: z.ZodOptional<z.ZodString>;
-    publish_date: z.ZodOptional<z.ZodDate>;
-    captured_at: z.ZodDate;
-    content_hash: z.ZodOptional<z.ZodString>;
-    tier: z.ZodEnum<{
-        "T1-official": "T1-official";
-        "T2-release-notes": "T2-release-notes";
-        "T3-practitioner": "T3-practitioner";
-        "T4-conjecture": "T4-conjecture";
-    }>;
-    tool: z.ZodEnum<{
-        "claude-code": "claude-code";
-        "gemini-cli": "gemini-cli";
-        "codex-cli": "codex-cli";
-        "cross-tool": "cross-tool";
-    }>;
-    perma_cc: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    local_cache: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-}, z.core.$strip>;
-declare const changelogSchema: z.ZodObject<{
-    tool: z.ZodEnum<{
-        "claude-code": "claude-code";
-        "gemini-cli": "gemini-cli";
-        "codex-cli": "codex-cli";
-        "cross-tool": "cross-tool";
-    }>;
-    versions: z.ZodDefault<z.ZodArray<z.ZodObject<{
-        version: z.ZodString;
-        date: z.ZodDate;
-        changes: z.ZodDefault<z.ZodArray<z.ZodObject<{
-            pattern: z.ZodString;
-            kind: z.ZodEnum<{
-                added: "added";
-                removed: "removed";
-                changed: "changed";
-                deprecated: "deprecated";
-            }>;
-            note: z.ZodString;
-            source_key: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-    }, z.core.$strip>>>;
-}, z.core.$strip>;
-declare const patternsSchema: z.ZodObject<{
-    name: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-    category: z.ZodOptional<z.ZodEnum<{
-        safety: "safety";
-        scale: "scale";
-        context: "context";
-        interaction: "interaction";
-        extension: "extension";
-        other: "other";
-    }>>;
-    convergence_date: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
-}, z.core.$strip>;
+/**
+ * src/lib/freshness.ts — volatility-aware staleness computation.
+ *
+ * Each chapter carries a `last_verified` date and a `volatility` class.
+ * This module maps those to a freshness status the reader can trust.
+ *
+ * Thresholds chosen to align with Ch 15's source-tier audit cadences:
+ *   stable-principle      → 365 days (principles drift annually at most)
+ *   architectural-pattern → 180 days (between annual and quarterly; "on
+ *                                     major release" isn't derivable from
+ *                                     frontmatter)
+ *   feature-surface       → 90 days  (quarterly)
+ *
+ * Status bands (fraction of threshold):
+ *   fresh       (<75%)   — green dot, unobtrusive
+ *   verify-soon (75-100%) — yellow, mild warning
+ *   stale       (>100%)  — amber/red, "verify before trusting"
+ *
+ * Example assertions (verified by visual inspection during Stage 3.1):
+ *   getFreshness(today, 'feature-surface').status     === 'fresh'
+ *   getFreshness(today-70d, 'feature-surface').status === 'verify-soon'
+ *   getFreshness(today-100d, 'feature-surface').status === 'stale'
+ *   getFreshness(today-200d, 'stable-principle').status === 'fresh'
+ *   getFreshness(today-300d, 'stable-principle').status === 'verify-soon'
+ */
+
+type VolatilityLevel = (typeof volatilityLevels)[number];
+type FreshnessStatus = 'fresh' | 'verify-soon' | 'stale';
+interface Freshness {
+    status: FreshnessStatus;
+    daysOld: number;
+    thresholdDays: number;
+    /** Days until stale; negative when already stale. */
+    daysUntil: number;
+}
+/**
+ * Compute freshness for a chapter given its last_verified date + volatility.
+ *
+ * Pure function; caller supplies `now` only in tests. Production callers omit.
+ *
+ * v3.3.0 (closes issue #1): tolerant of `lastVerified === undefined`. Returns
+ * `null` instead of crashing when the chapter schema omits the field (e.g.,
+ * academic profile chapters that don't track verification dates, or consumer
+ * schemas that don't declare last_verified).
+ *
+ * Callers compose with optional chaining:
+ *   const status = getFreshness(d.last_verified, d.volatility)?.status;
+ */
+declare function getFreshness(lastVerified: Date | undefined, volatility: VolatilityLevel, now?: Date): Freshness | null;
+/** Human-readable label for each status; used for ARIA + tooltips.
+ *
+ * v3.3.0: accepts `null` (the new return shape of getFreshness for undefined
+ * inputs). Returns a sentinel "unknown" label so callers can render a neutral
+ * affordance without a separate branch. */
+declare function freshnessLabel(f: Freshness | null): string;
 
-export { BookConfigOptions, BookScaffoldIntegrationOptions, academicChapterSchema, academicParts, bookScaffoldIntegration, changeKinds, changelogSchema, chapterStatus, defineBookConfig, patternCategories, patternsSchema, sourceTiers, sourcesSchema, toolSlugs, toolsChapterSchema, volatilityLevels };
+export { BookConfigOptions, BookScaffoldIntegrationOptions, type Freshness, type FreshnessStatus, type VolatilityLevel, bookScaffoldIntegration, defineBookConfig, defineMdxComponents, freshnessLabel, getFreshness, volatilityLevels };

package/dist/index.mjs

@@ -118,9 +118,223 @@ var init_katex_macros = __esm({
 import mdx from "@astrojs/mdx";
 import preact from "@astrojs/preact";
 
+// src/profile-kit.ts
+function defineProfile(p) {
+  return p;
+}
+
+// src/schemas.ts
+import { z } from "astro/zod";
+var toolSlugs = [
+  "claude-code",
+  "gemini-cli",
+  "codex-cli",
+  "cross-tool"
+];
+var volatilityLevels = [
+  "stable-principle",
+  "architectural-pattern",
+  "feature-surface"
+];
+var sourceTiers = [
+  "T1-official",
+  "T2-release-notes",
+  "T3-practitioner",
+  "T4-conjecture"
+];
+var changeKinds = ["added", "removed", "changed", "deprecated"];
+var patternCategories = [
+  "safety",
+  "scale",
+  "context",
+  "interaction",
+  "extension",
+  "other"
+];
+var academicParts = [
+  "foundations",
+  "ssm-core",
+  "beyond-ssm",
+  "integration",
+  "synthesis"
+];
+var chapterStatus = [
+  "implemented",
+  "chapter_only",
+  "reading_only",
+  "prose_only",
+  "code_only",
+  "scaffolded",
+  "planned"
+];
+var academicChapterSchema = z.object({
+  week: z.number().int().min(1).max(99),
+  part: z.enum(academicParts),
+  title: z.string().min(1),
+  status: z.enum(chapterStatus),
+  roadmap_lines: z.tuple([z.number().int(), z.number().int()]).optional(),
+  code_path: z.string().optional(),
+  tests_path: z.string().optional(),
+  notebook_path: z.string().optional(),
+  description: z.string().optional(),
+  draft: z.boolean().default(false)
+});
+var toolsChapterSchema = z.object({
+  title: z.string().min(1),
+  part: z.number().int().min(0).max(10),
+  chapter: z.number().int().min(0).max(99),
+  volatility: z.enum(volatilityLevels),
+  tools_compared: z.array(z.enum(toolSlugs)).min(1),
+  last_verified: z.date(),
+  sources: z.array(z.string()).default([]),
+  description: z.string().optional(),
+  draft: z.boolean().default(false),
+  updated: z.date().optional()
+});
+var minimalChapterSchema = toolsChapterSchema;
+var courseNotesChapterSchema = z.object({
+  // Identity
+  title: z.string().min(1),
+  chapter: z.number().int().min(0).max(99),
+  part: z.number().int().min(0).max(20).default(1),
+  description: z.string().optional(),
+  // Source attribution
+  course: z.string().optional(),
+  instructor: z.string().optional(),
+  source_url: z.string().url().optional(),
+  // Pedagogy
+  learning_outcomes: z.array(
+    z.object({
+      id: z.string(),
+      verb: z.string(),
+      text: z.string()
+    })
+  ).default([]),
+  tags: z.array(z.string()).default([]),
+  // Provenance + status (shared shape with tools profile)
+  last_verified: z.date(),
+  volatility: z.enum(volatilityLevels).default("architectural-pattern"),
+  sources: z.array(z.string()).default([]),
+  draft: z.boolean().default(false)
+});
+var sourcesSchema = z.object({
+  url: z.string().url(),
+  title: z.string().min(1),
+  author: z.string().optional(),
+  publish_date: z.date().optional(),
+  captured_at: z.date(),
+  content_hash: z.string().regex(/^sha256:[a-f0-9]+$/).optional(),
+  tier: z.enum(sourceTiers),
+  tool: z.enum(toolSlugs),
+  perma_cc: z.string().url().nullable().optional(),
+  local_cache: z.string().nullable().optional()
+});
+var changelogSchema = z.object({
+  tool: z.enum(toolSlugs),
+  versions: z.array(
+    z.object({
+      version: z.string().min(1),
+      date: z.date(),
+      changes: z.array(
+        z.object({
+          pattern: z.string(),
+          kind: z.enum(changeKinds),
+          note: z.string().min(1),
+          source_key: z.string().optional()
+        })
+      ).default([])
+    })
+  ).default([])
+});
+var patternsSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  category: z.enum(patternCategories).optional(),
+  convergence_date: z.date().nullable().optional()
+});
+
+// src/profiles/academic.ts
+var academicProfile = defineProfile({
+  name: "academic",
+  schema: academicChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,
+    // academic consumers ship their own week-based /chapters listing
+    convergence: false
+    // tools-profile-specific
+  },
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
+  katex: true
+});
+
+// src/profiles/tools.ts
+var toolsProfile = defineProfile({
+  name: "tools",
+  schema: toolsChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: true,
+    // tools profile ships a flat chapter index
+    convergence: true
+    // tools profile ships convergence dashboard
+  },
+  styles: [
+    "tokens.css",
+    "layout.css",
+    "callouts.css",
+    "chapter.css",
+    "typography.css",
+    "print.css",
+    "convergence.css",
+    "tool-filter.css"
+  ]
+});
+
+// src/profiles/minimal.ts
+var minimalProfile = defineProfile({
+  name: "minimal",
+  schema: minimalChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,
+    convergence: false
+  },
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"]
+});
+
+// src/profiles/course-notes.ts
+var courseNotesProfile = defineProfile({
+  name: "course-notes",
+  schema: courseNotesChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,
+    // multi-book consumers route via [book]/[slug] themselves
+    convergence: false
+  },
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"]
+});
+
+// src/profiles/index.ts
+var PROFILES = {
+  academic: academicProfile,
+  tools: toolsProfile,
+  minimal: minimalProfile,
+  "course-notes": courseNotesProfile
+};
+var BOOK_PROFILES = Object.keys(PROFILES);
+
 // src/types.ts
 import { existsSync, readFileSync } from "fs";
-var BOOK_PROFILES = ["academic", "tools", "minimal"];
 var BookConfigError = class extends Error {
   constructor(message) {
     super(message);
@@ -171,48 +385,92 @@ function resolveProfile(explicit) {
 
 // src/integration.ts
 import { fileURLToPath } from "url";
-var PACKAGE_NAME = "@brandon_m_behring/book-scaffold-astro";
-var ALWAYS_ON_STYLES = [
-  "tokens.css",
-  "layout.css",
-  "callouts.css",
-  "chapter.css",
-  "typography.css",
-  "print.css"
-];
-var TOOLS_ONLY_STYLES = ["convergence.css", "tool-filter.css"];
-var DEFAULT_ROUTES_ALL = [
-  { pattern: "/references", file: "references.astro" },
-  { pattern: "/search", file: "search.astro" },
-  { pattern: "/print", file: "print.astro" }
-];
-var DEFAULT_ROUTES_TOOLS = [
-  { pattern: "/chapters", file: "chapters.astro" },
-  { pattern: "/convergence", file: "convergence.astro" }
+
+// src/mdx-components-resolver.ts
+import { existsSync as existsSync2 } from "fs";
+import { resolve } from "path";
+var CANDIDATE_FILES = [
+  "src/mdx-components.ts",
+  "src/mdx-components.js",
+  "src/mdx-components.mjs"
 ];
+var VIRTUAL_ID = "virtual:book-scaffold/mdx-components";
+var RESOLVED_ID = "\0" + VIRTUAL_ID;
+function resolveMdxComponentsPath(consumerRoot, explicit) {
+  if (explicit) {
+    const p = resolve(consumerRoot, explicit);
+    return existsSync2(p) ? p : null;
+  }
+  for (const candidate of CANDIDATE_FILES) {
+    const p = resolve(consumerRoot, candidate);
+    if (existsSync2(p)) return p;
+  }
+  return null;
+}
+function makeMdxComponentsVitePlugin(consumerPath) {
+  return {
+    name: "book-scaffold:mdx-components",
+    enforce: "pre",
+    resolveId(id) {
+      if (id === VIRTUAL_ID) return RESOLVED_ID;
+      return null;
+    },
+    load(id) {
+      if (id !== RESOLVED_ID) return null;
+      if (consumerPath === null) {
+        return "export default {};";
+      }
+      return `export { default } from ${JSON.stringify(consumerPath)};`;
+    }
+  };
+}
+function defineMdxComponents(components) {
+  return components;
+}
+
+// src/integration.ts
+var PACKAGE_NAME = "@brandon_m_behring/book-scaffold-astro";
+var ROUTE_REGISTRY = {
+  references: { pattern: "/references", file: "references.astro" },
+  search: { pattern: "/search", file: "search.astro" },
+  print: { pattern: "/print", file: "print.astro" },
+  chapters: { pattern: "/chapters", file: "chapters.astro" },
+  convergence: { pattern: "/convergence", file: "convergence.astro" }
+};
 function resolvePage(file) {
   return fileURLToPath(new URL(`../pages/${file}`, import.meta.url));
 }
 function bookScaffoldIntegration(opts) {
-  const { profile, extraStyles = [] } = opts;
+  const { profile, routes: userOverrides = {}, extraStyles = [], mdxComponentsModule } = opts;
+  const def = PROFILES[profile];
+  const enabledRoutes = { ...def.routes, ...userOverrides };
   return {
     name: "book-scaffold-astro",
     hooks: {
-      "astro:config:setup": ({ injectScript, injectRoute }) => {
-        const styles = profile === "tools" ? [...ALWAYS_ON_STYLES, ...TOOLS_ONLY_STYLES, ...extraStyles] : [...ALWAYS_ON_STYLES, ...extraStyles];
+      "astro:config:setup": ({ injectScript, injectRoute, updateConfig, config }) => {
+        const styles = [...def.styles, ...extraStyles];
         for (const sheet of styles) {
           injectScript("page-ssr", `import '${PACKAGE_NAME}/styles/${sheet}';`);
         }
-        if (profile === "academic") {
+        if (def.katex) {
           injectScript("page-ssr", "import 'katex/dist/katex.min.css';");
         }
-        const routes = profile === "tools" ? [...DEFAULT_ROUTES_ALL, ...DEFAULT_ROUTES_TOOLS] : [...DEFAULT_ROUTES_ALL];
-        for (const route of routes) {
+        for (const [name, on] of Object.entries(enabledRoutes)) {
+          if (!on) continue;
+          const route = ROUTE_REGISTRY[name];
+          if (!route) continue;
           injectRoute({
             pattern: route.pattern,
             entrypoint: resolvePage(route.file)
           });
         }
+        const consumerRoot = fileURLToPath(config.root);
+        const resolvedMdxPath = resolveMdxComponentsPath(consumerRoot, mdxComponentsModule);
+        updateConfig({
+          vite: {
+            plugins: [makeMdxComponentsVitePlugin(resolvedMdxPath)]
+          }
+        });
       }
     }
   };
@@ -249,7 +507,14 @@ async function defineBookConfig(opts) {
   const integrations = [
     mdx(),
     preact(),
-    bookScaffoldIntegration({ profile, extraStyles: opts.extraStyles }),
+    bookScaffoldIntegration({
+      profile,
+      routes: opts.routes,
+      // v3.3.0 — per-route override (issue #3)
+      mdxComponentsModule: opts.mdxComponentsModule,
+      // v3.3.0 — explicit mdx-components path (issue #2)
+      extraStyles: opts.extraStyles
+    }),
     ...opts.extraIntegrations ?? []
   ];
   const userMarkdown = opts.markdown ?? {};
@@ -267,12 +532,18 @@ async function defineBookConfig(opts) {
   };
   const {
     profile: _profile,
+    routes: _routes,
+    // v3.3.0
+    mdxComponentsModule: _mdxComponentsModule,
+    // v3.3.0
     extraIntegrations: _extraIntegrations,
     extraStyles: _extraStyles,
     markdown: _markdown,
     ...rest
   } = opts;
   void _profile;
+  void _routes;
+  void _mdxComponentsModule;
   void _extraIntegrations;
   void _extraStyles;
   void _markdown;
@@ -293,109 +564,39 @@ async function defineBookConfig(opts) {
   return config;
 }
 
-// src/schemas.ts
-import { z } from "astro/zod";
-var toolSlugs = [
-  "claude-code",
-  "gemini-cli",
-  "codex-cli",
-  "cross-tool"
-];
-var volatilityLevels = [
-  "stable-principle",
-  "architectural-pattern",
-  "feature-surface"
-];
-var sourceTiers = [
-  "T1-official",
-  "T2-release-notes",
-  "T3-practitioner",
-  "T4-conjecture"
-];
-var changeKinds = ["added", "removed", "changed", "deprecated"];
-var patternCategories = [
-  "safety",
-  "scale",
-  "context",
-  "interaction",
-  "extension",
-  "other"
-];
-var academicParts = [
-  "foundations",
-  "ssm-core",
-  "beyond-ssm",
-  "integration",
-  "synthesis"
-];
-var chapterStatus = [
-  "implemented",
-  "chapter_only",
-  "reading_only",
-  "prose_only",
-  "code_only",
-  "scaffolded",
-  "planned"
-];
-var academicChapterSchema = z.object({
-  week: z.number().int().min(1).max(99),
-  part: z.enum(academicParts),
-  title: z.string().min(1),
-  status: z.enum(chapterStatus),
-  roadmap_lines: z.tuple([z.number().int(), z.number().int()]).optional(),
-  code_path: z.string().optional(),
-  tests_path: z.string().optional(),
-  notebook_path: z.string().optional(),
-  description: z.string().optional(),
-  draft: z.boolean().default(false)
-});
-var toolsChapterSchema = z.object({
-  title: z.string().min(1),
-  part: z.number().int().min(0).max(10),
-  chapter: z.number().int().min(0).max(99),
-  volatility: z.enum(volatilityLevels),
-  tools_compared: z.array(z.enum(toolSlugs)).min(1),
-  last_verified: z.date(),
-  sources: z.array(z.string()).default([]),
-  description: z.string().optional(),
-  draft: z.boolean().default(false),
-  updated: z.date().optional()
-});
-var sourcesSchema = z.object({
-  url: z.string().url(),
-  title: z.string().min(1),
-  author: z.string().optional(),
-  publish_date: z.date().optional(),
-  captured_at: z.date(),
-  content_hash: z.string().regex(/^sha256:[a-f0-9]+$/).optional(),
-  tier: z.enum(sourceTiers),
-  tool: z.enum(toolSlugs),
-  perma_cc: z.string().url().nullable().optional(),
-  local_cache: z.string().nullable().optional()
-});
-var changelogSchema = z.object({
-  tool: z.enum(toolSlugs),
-  versions: z.array(
-    z.object({
-      version: z.string().min(1),
-      date: z.date(),
-      changes: z.array(
-        z.object({
-          pattern: z.string(),
-          kind: z.enum(changeKinds),
-          note: z.string().min(1),
-          source_key: z.string().optional()
-        })
-      ).default([])
-    })
-  ).default([])
-});
-var patternsSchema = z.object({
-  name: z.string().min(1),
-  description: z.string().optional(),
-  category: z.enum(patternCategories).optional(),
-  convergence_date: z.date().nullable().optional()
-});
+// src/lib/freshness.ts
+var THRESHOLDS = {
+  "stable-principle": 365,
+  "architectural-pattern": 180,
+  "feature-surface": 90
+};
+var MS_PER_DAY = 1e3 * 60 * 60 * 24;
+function getFreshness(lastVerified, volatility, now = /* @__PURE__ */ new Date()) {
+  if (!(lastVerified instanceof Date)) return null;
+  const thresholdDays = THRESHOLDS[volatility];
+  const daysOld = Math.floor((now.getTime() - lastVerified.getTime()) / MS_PER_DAY);
+  const daysUntil = thresholdDays - daysOld;
+  let status;
+  if (daysOld < thresholdDays * 0.75) {
+    status = "fresh";
+  } else if (daysOld < thresholdDays) {
+    status = "verify-soon";
+  } else {
+    status = "stale";
+  }
+  return { status, daysOld, thresholdDays, daysUntil };
+}
+function freshnessLabel(f) {
+  if (f === null) return "Verification status unknown";
+  switch (f.status) {
+    case "fresh":
+      return `Fresh (${f.daysOld}d old; verify within ${f.daysUntil}d)`;
+    case "verify-soon":
+      return `Verify soon (${f.daysOld}d old; ${f.daysUntil}d until stale)`;
+    case "stale":
+      return `Stale (${f.daysOld}d old; ${Math.abs(f.daysUntil)}d past threshold)`;
+  }
+}
 export {
   BOOK_PROFILES,
   BookConfigError,
@@ -405,7 +606,13 @@ export {
   changeKinds,
   changelogSchema,
   chapterStatus,
+  courseNotesChapterSchema,
   defineBookConfig,
+  defineMdxComponents,
+  defineProfile,
+  freshnessLabel,
+  getFreshness,
+  minimalChapterSchema,
   patternCategories,
   patternsSchema,
   resolveProfile,

package/dist/schemas.d.ts

@@ -1,5 +1,6 @@
-import { e as BookSchemasOptions } from './types-BoCXCvBy.js';
+import { e as BookSchemasOptions } from './types-s8NxCLU2.js';
 import 'astro';
+import 'astro/zod';
 
 /**
  * Returns the package's default content collections. Closed shape per Q5;

package/dist/schemas.mjs

@@ -3,55 +3,9 @@ import { existsSync as existsSync2 } from "fs";
 import { defineCollection } from "astro:content";
 import { glob, file } from "astro/loaders";
 
-// src/types.ts
-import { existsSync, readFileSync } from "fs";
-var BOOK_PROFILES = ["academic", "tools", "minimal"];
-var BookConfigError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "BookConfigError";
-  }
-};
-function readEnvFile(path = ".env") {
-  try {
-    if (!existsSync(path)) return {};
-    const out = {};
-    for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
-      const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*?)\s*$/);
-      if (!m) continue;
-      let val = m[2] ?? "";
-      if (val.startsWith('"') && val.endsWith('"') || val.startsWith("'") && val.endsWith("'")) {
-        val = val.slice(1, -1);
-      }
-      out[m[1]] = val;
-    }
-    return out;
-  } catch {
-    return {};
-  }
-}
-function resolveProfile(explicit) {
-  let candidate = explicit ?? process.env.BOOK_PROFILE;
-  let source = "default";
-  if (explicit) source = "param";
-  else if (process.env.BOOK_PROFILE) source = "env";
-  if (!candidate) {
-    const fromFile = readEnvFile().BOOK_PROFILE;
-    if (fromFile) {
-      candidate = fromFile;
-      source = "dotenv";
-    }
-  }
-  candidate = candidate ?? "minimal";
-  if (!BOOK_PROFILES.includes(candidate)) {
-    throw new BookConfigError(
-      `profile must be one of ${BOOK_PROFILES.join(" | ")} (got ${JSON.stringify(candidate)})`
-    );
-  }
-  if (source === "default") {
-    console.warn("book-scaffold-astro: BOOK_PROFILE not set; falling back to 'minimal'.");
-  }
-  return candidate;
+// src/profile-kit.ts
+function defineProfile(p) {
+  return p;
 }
 
 // src/schemas.ts
@@ -122,6 +76,32 @@ var toolsChapterSchema = z.object({
   draft: z.boolean().default(false),
   updated: z.date().optional()
 });
+var minimalChapterSchema = toolsChapterSchema;
+var courseNotesChapterSchema = z.object({
+  // Identity
+  title: z.string().min(1),
+  chapter: z.number().int().min(0).max(99),
+  part: z.number().int().min(0).max(20).default(1),
+  description: z.string().optional(),
+  // Source attribution
+  course: z.string().optional(),
+  instructor: z.string().optional(),
+  source_url: z.string().url().optional(),
+  // Pedagogy
+  learning_outcomes: z.array(
+    z.object({
+      id: z.string(),
+      verb: z.string(),
+      text: z.string()
+    })
+  ).default([]),
+  tags: z.array(z.string()).default([]),
+  // Provenance + status (shared shape with tools profile)
+  last_verified: z.date(),
+  volatility: z.enum(volatilityLevels).default("architectural-pattern"),
+  sources: z.array(z.string()).default([]),
+  draft: z.boolean().default(false)
+});
 var sourcesSchema = z.object({
   url: z.string().url(),
   title: z.string().min(1),
@@ -158,17 +138,148 @@ var patternsSchema = z.object({
   convergence_date: z.date().nullable().optional()
 });
 
+// src/profiles/academic.ts
+var academicProfile = defineProfile({
+  name: "academic",
+  schema: academicChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,
+    // academic consumers ship their own week-based /chapters listing
+    convergence: false
+    // tools-profile-specific
+  },
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
+  katex: true
+});
+
+// src/profiles/tools.ts
+var toolsProfile = defineProfile({
+  name: "tools",
+  schema: toolsChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: true,
+    // tools profile ships a flat chapter index
+    convergence: true
+    // tools profile ships convergence dashboard
+  },
+  styles: [
+    "tokens.css",
+    "layout.css",
+    "callouts.css",
+    "chapter.css",
+    "typography.css",
+    "print.css",
+    "convergence.css",
+    "tool-filter.css"
+  ]
+});
+
+// src/profiles/minimal.ts
+var minimalProfile = defineProfile({
+  name: "minimal",
+  schema: minimalChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,
+    convergence: false
+  },
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"]
+});
+
+// src/profiles/course-notes.ts
+var courseNotesProfile = defineProfile({
+  name: "course-notes",
+  schema: courseNotesChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,
+    // multi-book consumers route via [book]/[slug] themselves
+    convergence: false
+  },
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"]
+});
+
+// src/profiles/index.ts
+var PROFILES = {
+  academic: academicProfile,
+  tools: toolsProfile,
+  minimal: minimalProfile,
+  "course-notes": courseNotesProfile
+};
+var BOOK_PROFILES = Object.keys(PROFILES);
+
+// src/types.ts
+import { existsSync, readFileSync } from "fs";
+var BookConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BookConfigError";
+  }
+};
+function readEnvFile(path = ".env") {
+  try {
+    if (!existsSync(path)) return {};
+    const out = {};
+    for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+      const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*?)\s*$/);
+      if (!m) continue;
+      let val = m[2] ?? "";
+      if (val.startsWith('"') && val.endsWith('"') || val.startsWith("'") && val.endsWith("'")) {
+        val = val.slice(1, -1);
+      }
+      out[m[1]] = val;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+function resolveProfile(explicit) {
+  let candidate = explicit ?? process.env.BOOK_PROFILE;
+  let source = "default";
+  if (explicit) source = "param";
+  else if (process.env.BOOK_PROFILE) source = "env";
+  if (!candidate) {
+    const fromFile = readEnvFile().BOOK_PROFILE;
+    if (fromFile) {
+      candidate = fromFile;
+      source = "dotenv";
+    }
+  }
+  candidate = candidate ?? "minimal";
+  if (!BOOK_PROFILES.includes(candidate)) {
+    throw new BookConfigError(
+      `profile must be one of ${BOOK_PROFILES.join(" | ")} (got ${JSON.stringify(candidate)})`
+    );
+  }
+  if (source === "default") {
+    console.warn("book-scaffold-astro: BOOK_PROFILE not set; falling back to 'minimal'.");
+  }
+  return candidate;
+}
+
 // src/schemas-entry.ts
 function defineBookSchemas(opts = {}) {
   const profile = resolveProfile(opts.profile);
   const chaptersBase = opts.chaptersBase ?? "./src/content/chapters";
+  const schemaForProfile = profile === "academic" ? academicChapterSchema : profile === "course-notes" ? courseNotesChapterSchema : profile === "minimal" ? minimalChapterSchema : toolsChapterSchema;
   const chapters = defineCollection({
     loader: glob({
       // Exclude underscore-prefixed files (standard "hidden" convention).
       pattern: ["**/*.{md,mdx}", "!**/_*"],
       base: chaptersBase
     }),
-    schema: profile === "academic" ? academicChapterSchema : toolsChapterSchema
+    schema: schemaForProfile
   });
   const collections = {
     chapters

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": "3.1.0",
+  "version": "3.3.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -113,7 +113,8 @@
     "pedagogy",
     "examples",
     "CLAUDE.md",
-    "README.md"
+    "README.md",
+    "LATEX_TO_MDX_MAPPING.md"
   ],
   "scripts": {
     "build": "tsup && rm -f dist/types-*.d.ts",

package/pages/print.astro

@@ -7,6 +7,13 @@
  * body, and wraps in a <section.chapter-print> so print.css can force
  * page breaks between chapters.
  *
+ * v3.3.0 (closes #2): renders chapters with the consumer's MDX-components
+ * map. Consumer creates src/mdx-components.{ts,js,mjs} that default-exports
+ * a defineMdxComponents({...}) call; this route imports the map via the
+ * virtual:book-scaffold/mdx-components module exposed by the toolkit's
+ * Vite plugin. If the consumer has no mdx-components file, the virtual
+ * module exports {} so the import is harmless.
+ *
  * Build pipeline:
  *   npm run build            → Astro emits dist/print/index.html
  *   npm run pdf              → pagedjs-cli fetches dist/print/ via preview
@@ -17,6 +24,7 @@ import Base from '../layouts/Base.astro';
 import { render } from 'astro:content';
 import { getAllChapters } from '../src/lib/chapters';
 import ChapterHeader from '../components/ChapterHeader.astro';
+import mdxComponents from 'virtual:book-scaffold/mdx-components';
 
 const chapters = await getAllChapters();
 const rendered = await Promise.all(
@@ -32,7 +40,7 @@ const rendered = await Promise.all(
     {rendered.map(({ entry, Content }) => (
       <section class="chapter-print">
         <ChapterHeader data={entry.data} />
-        <Content />
+        <Content components={mdxComponents} />
       </section>
     ))}
   </main>

package/src/lib/freshness.ts

@@ -49,12 +49,22 @@ const MS_PER_DAY = 1000 * 60 * 60 * 24;
  * Compute freshness for a chapter given its last_verified date + volatility.
  *
  * Pure function; caller supplies `now` only in tests. Production callers omit.
+ *
+ * v3.3.0 (closes issue #1): tolerant of `lastVerified === undefined`. Returns
+ * `null` instead of crashing when the chapter schema omits the field (e.g.,
+ * academic profile chapters that don't track verification dates, or consumer
+ * schemas that don't declare last_verified).
+ *
+ * Callers compose with optional chaining:
+ *   const status = getFreshness(d.last_verified, d.volatility)?.status;
  */
 export function getFreshness(
-  lastVerified: Date,
+  lastVerified: Date | undefined,
   volatility: VolatilityLevel,
   now: Date = new Date(),
-): Freshness {
+): Freshness | null {
+  if (!(lastVerified instanceof Date)) return null;
+
   const thresholdDays = THRESHOLDS[volatility];
   const daysOld = Math.floor((now.getTime() - lastVerified.getTime()) / MS_PER_DAY);
   const daysUntil = thresholdDays - daysOld;
@@ -71,8 +81,13 @@ export function getFreshness(
   return { status, daysOld, thresholdDays, daysUntil };
 }
 
-/** Human-readable label for each status; used for ARIA + tooltips. */
-export function freshnessLabel(f: Freshness): string {
+/** Human-readable label for each status; used for ARIA + tooltips.
+ *
+ * v3.3.0: accepts `null` (the new return shape of getFreshness for undefined
+ * inputs). Returns a sentinel "unknown" label so callers can render a neutral
+ * affordance without a separate branch. */
+export function freshnessLabel(f: Freshness | null): string {
+  if (f === null) return 'Verification status unknown';
   switch (f.status) {
     case 'fresh':
       return `Fresh (${f.daysOld}d old; verify within ${f.daysUntil}d)`;

package/styles/chapter.css

@@ -38,6 +38,29 @@
   font-size: 0.75em;
 }
 
+/* Inline companion-artifact chips inside .chapter-meta.
+ * v3.2.0: structural inline rendering. Previous v3.1.0 emitted a sibling
+ * <aside class="chapter-companions"><ul>...</ul></aside> with no CSS
+ * coverage; UA-default block layout added ~100px height at <=1280px,
+ * producing a uniform vertical pixel shift on academic chapter pages
+ * vs the v2.0 baseline. The inline span here adds zero block height by
+ * construction; styling matches the surrounding .chapter-meta spans. */
+.chapter-companion {
+  font-family: var(--font-code);
+  font-size: var(--text-sm);
+  color: var(--color-text-muted);
+}
+.chapter-companion a,
+.chapter-companion code {
+  color: inherit;
+  text-decoration: none;
+  border-bottom: 1px dotted var(--color-border);
+}
+.chapter-companion a:hover {
+  color: var(--color-link);
+  border-bottom-style: solid;
+}
+
 /* Volatility + tool badges: reuse .tool-badge from callouts.css */
 .volatility-badge {
   display: inline-block;