@brandon_m_behring/book-scaffold-astro 3.6.5 → 3.7.0

package/pages/chapters.astro

@@ -2,59 +2,91 @@
 /**
  * /chapters — book index page.
  *
- * Groups non-draft chapters by Part in ascending order. Each card exposes
- * `data-tools="<slug> <slug>..."` so the ToolFilter island can hide cards via
- * a single attribute selector without touching card rendering.
+ * Route-level concerns kept here:
+ *   - Data fetch (getAllChapters)
+ *   - byPart Map grouping (insertion-order preserved across number + string keys)
+ *   - ToolFilter island wiring (inline script, data-tools attribute on cards,
+ *     part-group hide-when-empty, filter hint)
+ *   - CSS, structural JSX, <Base> wrapping
  *
- * v3.5.2 (closes #24): schema-aware. Previously hardcoded the tools-profile
- * shape and crashed on academic profile (no `chapter` / `volatility` /
- * `tools_compared` / `last_verified`). Now renders either shape:
- *   - tools: `Chapter N` + volatility badge + freshness + tools-compared tags
- *   - academic: `Week N` + status badge (no freshness or tools-compared)
- * Field presence is the schema discriminator (cheaper than reading
- * BOOK_PROFILE at the route layer).
+ * Per-profile concerns dispatched via `PROFILES[BOOK_PROFILE].chaptersRenderer`:
+ *   - Meta-row composition (numbering, badges)
+ *   - Sort key strategy
+ *   - data-tools value computation
+ *
+ * v3.7.0 (closes #35): replaces the field-presence discriminator that
+ * lived inline in v3.5.2. Each profile now ships a ChaptersRenderer
+ * implementing the strategy interface; consumers opting profiles without
+ * a dedicated renderer (e.g., minimal + routes.chapters: true) get the
+ * fallbackChaptersRenderer which dispatches via field presence — exactly
+ * the v3.5.2 behavior, preserved as a safety net.
  */
 import Base from '../layouts/Base.astro';
 import { getAllChapters, type Chapter } from '../src/lib/chapters';
-import { getFreshness, freshnessLabel } from '../src/lib/freshness';
-
-const chapters = await getAllChapters();
+import { PROFILES } from '../src/profiles/index';
+import { fallbackChaptersRenderer } from '../src/profiles/renderers/fallback-chapters';
+import type { ChaptersRenderer, PartKey } from '../src/lib/chapters-renderer';
 
-// Stable insertion-order grouping by `part`. Map key may be number (tools) or
-// string (academic enum); Map preserves insertion order for both.
-type PartKey = string | number;
-const byPart = new Map<PartKey, Chapter[]>();
-for (const c of chapters) {
-  const key = (c.data as { part: PartKey }).part;
-  const list = byPart.get(key);
-  if (list) list.push(c);
-  else byPart.set(key, [c]);
-}
+const profileName = (import.meta.env.BOOK_PROFILE ?? 'minimal') as keyof typeof PROFILES;
+const profileDef = PROFILES[profileName];
+const renderer: ChaptersRenderer =
+  (profileDef as { chaptersRenderer?: ChaptersRenderer } | undefined)?.chaptersRenderer
+  ?? fallbackChaptersRenderer;
 
-function formatDate(d: Date): string {
-  return d.toISOString().slice(0, 10);
-}
+const chapters = await getAllChapters();
 
-/** Render-ready label for a Part heading. Tools: "Part N" or "Appendices"
- *  (parts >= 6 are appendices). Academic: titlecase the enum string. */
-function partLabel(part: PartKey): string {
-  if (typeof part === 'number') {
-    return part >= 6 ? 'Appendices' : `Part ${part}`;
-  }
-  return part
-    .split('-')
-    .map((w) => (w.length ? w[0].toUpperCase() + w.slice(1) : ''))
-    .join(' ');
+// Precompute each card's render-ready fields in the frontmatter block.
+// This keeps TypeScript generics (Record<string, unknown> casts, the
+// renderer return-type unions) out of the JSX template, where the
+// Astro compiler treats `<` as a tag-start token and trips on type
+// assertions inside expressions.
+interface CardData {
+  c: Chapter;
+  toolsAttr: string;
+  number: string;
+  volatility: ReturnType<typeof renderer.getVolatilityData>;
+  status: ReturnType<typeof renderer.getStatusData>;
+  freshness: ReturnType<typeof renderer.getFreshnessData>;
+  freshnessText: string | null;
+  verifiedLabel: string | null;
+  toolsCompared: string[];
+  data: { title: unknown; description?: unknown };
 }
 
-function isAppendix(part: PartKey): boolean {
-  return typeof part === 'number' && part >= 6;
+function buildCard(c: Chapter, appendix: boolean): CardData {
+  const data = c.data as Record<string, unknown>;
+  const freshness = renderer.getFreshnessData(data);
+  const freshnessText = freshness
+    ? freshness.status === 'fresh'
+      ? 'Fresh'
+      : freshness.status === 'verify-soon'
+        ? 'Verify soon'
+        : 'Stale'
+    : null;
+  return {
+    c,
+    toolsAttr: renderer.getToolsAttr(data),
+    number: renderer.formatChapterNumber(data, appendix),
+    volatility: renderer.getVolatilityData(data),
+    status: renderer.getStatusData(data),
+    freshness,
+    freshnessText,
+    verifiedLabel: renderer.getVerifiedDateLabel(data),
+    toolsCompared: renderer.getToolsCompared(data),
+    data: { title: data.title, description: data.description as string | undefined },
+  };
 }
 
-/** Per-card schema detection. Cheaper than reading BOOK_PROFILE — the shape
- *  of the chapter's data already tells us which profile produced it. */
-function isToolsShape(data: Record<string, unknown>): boolean {
-  return 'volatility' in data && 'chapter' in data;
+// Stable insertion-order grouping. Map preserves order for both number and
+// string keys (academic uses string-enum parts; tools uses numeric parts).
+const byPart = new Map<PartKey, CardData[]>();
+for (const c of chapters) {
+  const key = renderer.partKey(c.data as Record<string, unknown>);
+  const appendix = renderer.isAppendix(key);
+  const card = buildCard(c, appendix);
+  const list = byPart.get(key);
+  if (list) list.push(card);
+  else byPart.set(key, [card]);
 }
 ---
 <Base
@@ -72,89 +104,58 @@ function isToolsShape(data: Record<string, unknown>): boolean {
 
     <p class="chapters-filter-hint" id="filter-hint" aria-live="polite"></p>
 
-    {Array.from(byPart.entries()).map(([part, list]) => {
-      const appendix = isAppendix(part);
-      return (
-        <section class="part-group">
-          <h2 class="part-heading">
-            <span class="part-label">{partLabel(part)}</span>
-          </h2>
-          <ol class="chapter-list">
-            {list.map((c) => {
-              const data = c.data as Record<string, unknown>;
-              const tools = isToolsShape(data);
-              // data-tools attribute drives the ToolFilter island. Academic
-              // cards opt out by claiming "cross-tool" — always visible
-              // regardless of filter state.
-              const toolsAttr = tools
-                ? (data.tools_compared as string[]).join(' ')
-                : 'cross-tool';
-              const freshness = tools
-                ? getFreshness(data.last_verified as Date, data.volatility as Parameters<typeof getFreshness>[1])
-                : null;
-              const freshnessText = freshness
-                ? freshness.status === 'fresh'
-                  ? 'Fresh'
-                  : freshness.status === 'verify-soon'
-                    ? 'Verify soon'
-                    : 'Stale'
-                : null;
-              return (
-                <li class="chapter-card" data-tools={toolsAttr}>
-                  <a href={`/${c.id}/`} class="chapter-card-link">
-                    <div class="chapter-card-meta">
-                      <span class="chapter-card-number">
-                        {tools
-                          ? appendix
-                            ? `Appendix ${String.fromCharCode(64 + (data.chapter as number)).toLowerCase()}`
-                            : `Chapter ${data.chapter}`
-                          : `Week ${data.week}`}
-                      </span>
-                      {tools && (
-                        <span
-                          class={`volatility-badge volatility-${data.volatility}`}
-                          title={`Volatility: ${data.volatility}`}
-                        >{data.volatility}</span>
-                      )}
-                      {!tools && data.status && (
-                        <span
-                          class={`status-badge status-${data.status}`}
-                          title={`Status: ${data.status}`}
-                        >{data.status}</span>
-                      )}
-                      {freshness && freshnessText && (
-                        <span
-                          class="freshness-badge"
-                          data-status={freshness.status}
-                          aria-label={freshnessLabel(freshness)}
-                          title={freshnessLabel(freshness)}
-                        >{freshnessText}</span>
-                      )}
-                      {tools && data.last_verified && (
-                        <span class="chapter-card-verified">
-                          verified {formatDate(data.last_verified as Date)}
-                        </span>
-                      )}
-                    </div>
-                    <h3 class="chapter-card-title">{data.title}</h3>
-                    {data.description && (
-                      <p class="chapter-card-description">{data.description as string}</p>
-                    )}
-                    {tools && (
-                      <div class="chapter-card-tools">
-                        {(data.tools_compared as string[]).map((t) => (
-                          <span class="tool-badge">{t}</span>
-                        ))}
-                      </div>
-                    )}
-                  </a>
-                </li>
-              );
-            })}
-          </ol>
-        </section>
-      );
-    })}
+    {Array.from(byPart.entries()).map(([part, cards]) => (
+      <section class="part-group">
+        <h2 class="part-heading">
+          <span class="part-label">{renderer.formatPartLabel(part)}</span>
+        </h2>
+        <ol class="chapter-list">
+          {cards.map((card) => (
+            <li class="chapter-card" data-tools={card.toolsAttr}>
+              <a href={`/${card.c.id}/`} class="chapter-card-link">
+                <div class="chapter-card-meta">
+                  <span class="chapter-card-number">{card.number}</span>
+                  {card.volatility && (
+                    <span
+                      class={`volatility-badge volatility-${card.volatility.level}`}
+                      title={`Volatility: ${card.volatility.label}`}
+                    >{card.volatility.label}</span>
+                  )}
+                  {card.status && (
+                    <span
+                      class={`status-badge status-${card.status.status}`}
+                      title={`Status: ${card.status.label}`}
+                    >{card.status.label}</span>
+                  )}
+                  {card.freshness && card.freshnessText && (
+                    <span
+                      class="freshness-badge"
+                      data-status={card.freshness.status}
+                      aria-label={card.freshness.label}
+                      title={card.freshness.label}
+                    >{card.freshnessText}</span>
+                  )}
+                  {card.verifiedLabel && (
+                    <span class="chapter-card-verified">{card.verifiedLabel}</span>
+                  )}
+                </div>
+                <h3 class="chapter-card-title">{card.data.title}</h3>
+                {card.data.description && (
+                  <p class="chapter-card-description">{card.data.description as string}</p>
+                )}
+                {card.toolsCompared.length > 0 && (
+                  <div class="chapter-card-tools">
+                    {card.toolsCompared.map((t) => (
+                      <span class="tool-badge">{t}</span>
+                    ))}
+                  </div>
+                )}
+              </a>
+            </li>
+          ))}
+        </ol>
+      </section>
+    ))}
   </article>
 </Base>
 

package/src/lib/chapters-renderer.ts

@@ -0,0 +1,99 @@
+/**
+ * src/lib/chapters-renderer.ts — per-profile strategy interface for the
+ * /chapters route. Pure-function strategy; no Astro imports here or in
+ * implementations (kept that way so profile modules can re-export renderers
+ * without dragging Astro virtual modules into tsup's DTS bundle — same
+ * constraint that motivated the chapter-sort.ts split in v3.5.2).
+ *
+ * v3.7.0 (closes #35): replaces the field-presence discriminator that
+ * v3.5.2 put inside pages/chapters.astro. Each profile module now owns
+ * its chapters-page rendering semantics via this interface, and the
+ * route file dispatches via PROFILES[BOOK_PROFILE].chaptersRenderer.
+ *
+ * Why pure data, not Astro components: profile modules are bundled by
+ * tsup into dist/, but Astro components (.astro files) cannot be processed
+ * by tsup's DTS bundler. Keeping the renderer surface as plain data
+ * (strings, numbers, plain objects, null) lets the route file own all
+ * JSX rendering while each profile owns the per-shape semantics.
+ */
+
+export type PartKey = string | number;
+
+export type FreshnessStatus = 'fresh' | 'verify-soon' | 'stale';
+
+/** Volatility badge metadata for tools-profile rendering. */
+export interface VolatilityBadge {
+  /** CSS modifier (`stable-principle | architectural-pattern | feature-surface`). */
+  level: string;
+  /** Visible chip text + tooltip body. */
+  label: string;
+}
+
+/** Academic status badge metadata. */
+export interface StatusBadge {
+  /** CSS modifier (`implemented | scaffolded | planned | ...`). */
+  status: string;
+  /** Visible chip text + tooltip body. */
+  label: string;
+}
+
+/** Freshness affordance with status band + ARIA-friendly label. */
+export interface FreshnessAffordance {
+  status: FreshnessStatus;
+  label: string;
+}
+
+/**
+ * A renderer owns the per-shape semantics for the /chapters route. The
+ * route file orchestrates: data fetching, byPart grouping, ToolFilter
+ * island wiring, CSS, structural JSX. The renderer answers:
+ *
+ *  - How is this chapter labelled?
+ *  - Which badges apply?
+ *  - What's the ToolFilter attribute?
+ *  - How do these chapters sort?
+ *
+ * All methods are pure: same input → same output, no side effects.
+ */
+export interface ChaptersRenderer {
+  /** Group key for the byPart Map. Tools = number, academic = string-enum. */
+  partKey(data: Record<string, unknown>): PartKey;
+
+  /** Human-facing heading label for a Part group ("Part 1", "Foundations"). */
+  formatPartLabel(part: PartKey): string;
+
+  /** Whether the group renders as an appendix (tools profile only). */
+  isAppendix(part: PartKey): boolean;
+
+  /** Chapter card heading text. Examples:
+   *   tools         → "Chapter 1" or "Appendix a"
+   *   academic      → "Week 3"
+   *   fallback      → best-effort from available fields
+   */
+  formatChapterNumber(data: Record<string, unknown>, appendix: boolean): string;
+
+  /** Value for the `data-tools` attribute (ToolFilter island wiring).
+   *  Tools = space-joined slugs from `tools_compared`.
+   *  Non-tools = "cross-tool" (always-visible regardless of filter). */
+  getToolsAttr(data: Record<string, unknown>): string;
+
+  /** Volatility badge metadata, or null if the profile doesn't use it. */
+  getVolatilityData(data: Record<string, unknown>): VolatilityBadge | null;
+
+  /** Academic status badge metadata, or null. */
+  getStatusData(data: Record<string, unknown>): StatusBadge | null;
+
+  /** Freshness affordance, or null if the profile doesn't track `last_verified`.
+   *  `now` is injectable for deterministic tests. */
+  getFreshnessData(data: Record<string, unknown>, now?: Date): FreshnessAffordance | null;
+
+  /** "verified YYYY-MM-DD" meta-row text, or null. */
+  getVerifiedDateLabel(data: Record<string, unknown>): string | null;
+
+  /** Tools-compared tag list for the bottom card row, or empty array. */
+  getToolsCompared(data: Record<string, unknown>): string[];
+
+  /** Sort key — profile-aware. Tools = `part * 1000 + chapter`;
+   *  academic = `partOrdinal * 1000 + week`. */
+  sortKey(data: Record<string, unknown>): number;
+}

package/src/profile-kit.ts

@@ -0,0 +1,100 @@
+/**
+ * profile-kit — internal helper for declaring book profiles.
+ *
+ * Each profile (academic, tools, minimal, course-notes, future paper-review,
+ * etc.) lives in its own self-contained module under src/profiles/ and uses
+ * defineProfile() to declare its schema + auto-injected routes + auto-loaded
+ * styles. The PROFILES registry in src/profiles/index.ts wires them together;
+ * bookScaffoldIntegration consumes the registry.
+ *
+ * defineProfile() is an identity function — same pattern as Vite's
+ * defineConfig, Astro's defineConfig, Zod's z.object. Currently no generic
+ * constraint on the schema parameter: per-profile inferred chapter types
+ * are exported separately (AcademicChapter, ToolsChapter, etc.) via
+ * `z.infer<typeof schema>`, so the registry doesn't need to track each
+ * schema's exact shape. Keeping the schema typed as `unknown` here also
+ * avoids tsup's DTS bundler dragging deep Zod internals into the .d.ts
+ * (rollup-plugin-dts can't always resolve Zod's `default` export shape).
+ *
+ * Adding a new profile is a single-file change:
+ *   1. Create src/profiles/<name>.ts (define schema + type + profile config).
+ *   2. Register it in src/profiles/index.ts (one line in PROFILES + one line
+ *      in ChapterFor<P>).
+ *   3. (Optional) ship a default chapter route page under package/pages/.
+ */
+
+import type { ChaptersRenderer } from './lib/chapters-renderer.js';
+
+/**
+ * The set of routes the toolkit can auto-inject. Per-profile defaults are
+ * declared in each profile module; consumers override via
+ * defineBookConfig({ routes: { … } }).
+ *
+ * The shape is fixed — adding a new auto-injected route requires updating
+ * this type AND adding a default to every profile module. The trade-off is
+ * worth it: consumers get TS autocomplete on the route names and TS errors
+ * on typos like `convergance: false`.
+ */
+export interface RouteToggles {
+  references: boolean;
+  search: boolean;
+  print: boolean;
+  chapters: boolean;
+  convergence: boolean;
+  /**
+   * v3.4.0 (closes #7): auto-inject `/frontmatter/[slug]/` rendering a
+   * consumer-defined `frontmatter` content collection. Default `false` per
+   * profile — opt in via defineBookConfig({ routes: { frontmatter: true } })
+   * AND define the collection via `frontmatterCollection()` in content.config.ts.
+   * If enabled without defining the collection, Astro errors clearly at build.
+   */
+  frontmatter: boolean;
+}
+
+/** Profile definition — declarative shape for one book profile. */
+export interface ProfileDefinition {
+  /** Stable name; must match the key in PROFILES + the BOOK_PROFILE env value. */
+  name: string;
+  /**
+   * The Zod schema used as the chapter collection schema. Typed as
+   * `unknown` here on purpose — per-profile inferred chapter types
+   * (AcademicChapter, ToolsChapter, …) are exported separately and give
+   * consumers the narrow typing where it matters. defineCollection
+   * (in src/schemas-entry.ts) accepts the schema runtime-style.
+   */
+  schema: unknown;
+  /** Auto-injected routes; consumers override via defineBookConfig({ routes }). */
+  routes: RouteToggles;
+  /** CSS basenames loaded for this profile (resolved from package/styles/). */
+  styles: string[];
+  /** Whether KaTeX should be wired in (academic profile only currently). */
+  katex?: boolean;
+  /**
+   * v3.7.0 (closes #35): per-profile renderer for the /chapters route.
+   * Owns the chapter-card meta-row composition, numbering format, sort key,
+   * and ToolFilter wiring for this profile's data shape. Pure-function
+   * strategy (no Astro imports — see src/lib/chapters-renderer.ts header).
+   *
+   * Optional: profiles that don't ship a dedicated renderer get the
+   * fallbackChaptersRenderer (field-presence dispatch) at route render time.
+   */
+  chaptersRenderer?: ChaptersRenderer;
+}
+
+/**
+ * Identity helper for declaring a profile module.
+ *
+ *   export const courseNotesProfile = defineProfile({
+ *     name: 'course-notes',
+ *     schema: courseNotesChapterSchema,
+ *     routes: { references: true, search: true, print: true, chapters: false, convergence: false },
+ *     styles: ['tokens.css', ...],
+ *   });
+ *
+ * No runtime work; the value goes through unchanged. Useful as a typed
+ * "this is a profile" marker that catches missing required fields at
+ * authoring time.
+ */
+export function defineProfile(p: ProfileDefinition): ProfileDefinition {
+  return p;
+}

package/src/profiles/academic.ts

@@ -0,0 +1,30 @@
+/**
+ * Academic profile — weekly curriculum with 7-state status taxonomy.
+ *
+ * Reference consumer: post_transformers. Schema definition + inferred
+ * chapter type live in src/schemas.ts (consolidated to keep all Zod-using
+ * code in one file — see schemas.ts header for the DTS-bundler rationale).
+ * This module composes the schema with routes + styles via defineProfile.
+ */
+import { defineProfile } from '../profile-kit.js';
+import { academicChapterSchema } from '../schemas.js';
+import { academicChaptersRenderer } from './renderers/academic-chapters.js';
+
+// Re-export for consumer ergonomics (`import { AcademicChapter } from '@brandon_m_behring/book-scaffold-astro'`).
+export type { AcademicChapter } from '../schemas.js';
+
+export const 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
+    frontmatter: false,     // opt-in per book; see #7
+  },
+  styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
+  katex: true,
+  chaptersRenderer: academicChaptersRenderer,   // v3.7.0 (#35) — owns /chapters semantics if consumer opts in via routes.chapters
+});

package/src/profiles/course-notes.ts

@@ -0,0 +1,32 @@
+/**
+ * Course-notes profile — chapters derived from a video course / MOOC / book.
+ *
+ * Reference consumer (forthcoming): DLAI knowledge-graphs-rag pilot. Schema
+ * + inferred type live in src/schemas.ts; this module composes with routes
+ * + styles. Multi-book corpus pattern is supported by consumer-side schema
+ * extension via Zod .extend() with a `book` discriminator.
+ *
+ * Distinct from the tools profile (which has tools_compared as an enum of
+ * AI CLIs) and academic profile (which is week-based). Don't reuse either.
+ */
+import { defineProfile } from '../profile-kit.js';
+import { courseNotesChapterSchema } from '../schemas.js';
+import { fallbackChaptersRenderer } from './renderers/fallback-chapters.js';
+
+export type { CourseNotesChapter } from '../schemas.js';
+
+export const 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,
+    frontmatter: false,     // opt-in per book; see #7
+  },
+  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
+  chaptersRenderer: fallbackChaptersRenderer,
+});

package/src/profiles/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Profile registry — single source of truth for the BOOK_PROFILE enum.
+ *
+ * Each profile is a self-contained module that declares its schema + routes
+ * + styles via defineProfile(). The PROFILES object below is the only place
+ * the toolkit looks up profile config; bookScaffoldIntegration consumes
+ * PROFILES[profile] to drive injectRoute / injectScript calls.
+ *
+ * To add a new profile: create src/profiles/<name>.ts, then add two lines
+ * here (one to PROFILES, one to ChapterFor). The discriminated union of
+ * BookProfile = keyof typeof PROFILES updates automatically.
+ */
+import { academicProfile, type AcademicChapter } from './academic.js';
+import { toolsProfile, type ToolsChapter } from './tools.js';
+import { minimalProfile, type MinimalChapter } from './minimal.js';
+import { courseNotesProfile, type CourseNotesChapter } from './course-notes.js';
+import { researchPortfolioProfile, type ResearchPortfolioChapter } from './research-portfolio.js';
+
+export const PROFILES = {
+  academic: academicProfile,
+  tools: toolsProfile,
+  minimal: minimalProfile,
+  'course-notes': courseNotesProfile,
+  'research-portfolio': researchPortfolioProfile,
+} as const;
+
+export type BookProfile = keyof typeof PROFILES;
+
+export const BOOK_PROFILES = Object.keys(PROFILES) as readonly BookProfile[];
+
+/**
+ * Generic chapter-shape lookup. Consumers writing helpers parametrized over
+ * a profile can use this for narrowed typing:
+ *
+ *   function summarize<P extends BookProfile>(profile: P, chapter: ChapterFor<P>) {
+ *     // chapter is narrowed to AcademicChapter / ToolsChapter / etc.
+ *   }
+ */
+export type ChapterFor<P extends BookProfile> =
+  P extends 'academic' ? AcademicChapter :
+  P extends 'tools' ? ToolsChapter :
+  P extends 'minimal' ? MinimalChapter :
+  P extends 'course-notes' ? CourseNotesChapter :
+  P extends 'research-portfolio' ? ResearchPortfolioChapter :
+  never;
+
+// Re-export the inferred chapter types for consumer ergonomics.
+export type {
+  AcademicChapter,
+  ToolsChapter,
+  MinimalChapter,
+  CourseNotesChapter,
+  ResearchPortfolioChapter,
+};

package/src/profiles/minimal.ts

@@ -0,0 +1,27 @@
+/**
+ * Minimal profile — single-author essays / manifestos. Currently aliases
+ * the tools chapter schema (defined in src/schemas.ts as
+ * minimalChapterSchema). If minimal-specific fields emerge from a real
+ * consumer, this is where they land.
+ */
+import { defineProfile } from '../profile-kit.js';
+import { minimalChapterSchema } from '../schemas.js';
+import { fallbackChaptersRenderer } from './renderers/fallback-chapters.js';
+
+export type { MinimalChapter } from '../schemas.js';
+
+export const minimalProfile = defineProfile({
+  name: 'minimal',
+  schema: minimalChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,
+    convergence: false,
+    frontmatter: false,     // opt-in per book; see #7
+  },
+  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
+  chaptersRenderer: fallbackChaptersRenderer,
+});