@brandon_m_behring/book-scaffold-astro 4.6.0 → 4.7.0

package/CLAUDE.md

@@ -58,6 +58,35 @@ sources: []                        # array of source-manifest keys
 ---
 ```
 
+### Research-portfolio profile (`src/schemas.ts:researchPortfolioChapterSchema`)
+
+Hybrid of academic + tools provenance with research-paper-style inline sources. Only `title` + `last_verified` are required; all hierarchy and classification fields are optional.
+
+```yaml
+---
+title: "..."                       # required
+last_verified: 2026-05-19          # date, required
+# optional — hierarchy (use whichever fits; all may be omitted)
+slug: ch01-introduction            # defaults to filename
+chapter: 1
+part: 1                            # number OR academic-style string enum
+week: 1
+# optional — status (AUTHORING state) vs freshness (EPISTEMIC type) are ORTHOGONAL
+status: prose_only                 # 'scaffolded'|'prose_only'|'code_only'|'chapter_only'|'reading_only'|'implemented'|'planned'
+freshness: experimental-result     # 'experimental-result'|'literature-survey'|'theoretical'|'reference'
+# optional — provenance + inline sources (T1-T4 tiers)
+volatility: feature-surface        # 'stable-principle'|'architectural-pattern'|'feature-surface'
+tags: [prompt-injection, ...]      # freeform string array
+sources:
+  - tier: T1
+    url: https://...
+    label: Primary source
+# optional: description, draft, updated, author, published, image (SEO/og:*)
+---
+```
+
+**`status` vs `freshness` is the #1 author gotcha.** `status` = authoring state (have I written it?). `freshness` = epistemic type (what kind of evidence?). A chapter can be `status: scaffolded` (not written yet) AND `freshness: theoretical` (will be a math argument). See Recipe 13 for the full table.
+
 ## Component reference
 
 Two callout families coexist. Authors import what they need.

package/dist/index.mjs

@@ -398,8 +398,8 @@ var academicProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
-    // academic consumers ship their own week-based /chapters listing
+    chapters: true,
+    // v4.6.1 (#75 follow-up): auto-injected /chapters/[...slug]/ + /chapters/ index. Pre-v4.3.0 academic books shipped their own listing; v4.6.0 (#76 Layer 3c) removed the consumer template assuming auto-injection. Default flipped here to close the gap. Consumers wanting their own listing override via `routes: { chapters: false }` + their own src/pages/chapters/* — see recipe 18.
     convergence: false,
     // tools-profile-specific
     frontmatter: false,
@@ -607,7 +607,8 @@ var minimalProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
+    chapters: true,
+    // v4.6.1 (#75 follow-up): default-on across all profiles. Consumer override via routes: { chapters: false }.
     convergence: false,
     frontmatter: false,
     // opt-in per book; see #7
@@ -631,8 +632,8 @@ var courseNotesProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
-    // multi-book consumers route via [book]/[slug] themselves
+    chapters: true,
+    // v4.6.1 (#75 follow-up): default-on. Multi-book consumers (DLAI-style) override via routes: { chapters: false } + own [book]/[slug] routes — see #15 deferred.
     convergence: false,
     frontmatter: false,
     // opt-in per book; see #7
@@ -659,8 +660,8 @@ var researchPortfolioProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
-    // portfolio books ship their own landing/index
+    chapters: true,
+    // v4.6.1 (#75 follow-up): default-on. Portfolios still ship their own /frontmatter/* + landing; /chapters/* renders the underlying chapter list.
     convergence: false,
     // tools-profile-specific
     frontmatter: true,

package/dist/schemas.mjs

@@ -282,8 +282,8 @@ var academicProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
-    // academic consumers ship their own week-based /chapters listing
+    chapters: true,
+    // v4.6.1 (#75 follow-up): auto-injected /chapters/[...slug]/ + /chapters/ index. Pre-v4.3.0 academic books shipped their own listing; v4.6.0 (#76 Layer 3c) removed the consumer template assuming auto-injection. Default flipped here to close the gap. Consumers wanting their own listing override via `routes: { chapters: false }` + their own src/pages/chapters/* — see recipe 18.
     convergence: false,
     // tools-profile-specific
     frontmatter: false,
@@ -491,7 +491,8 @@ var minimalProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
+    chapters: true,
+    // v4.6.1 (#75 follow-up): default-on across all profiles. Consumer override via routes: { chapters: false }.
     convergence: false,
     frontmatter: false,
     // opt-in per book; see #7
@@ -515,8 +516,8 @@ var courseNotesProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
-    // multi-book consumers route via [book]/[slug] themselves
+    chapters: true,
+    // v4.6.1 (#75 follow-up): default-on. Multi-book consumers (DLAI-style) override via routes: { chapters: false } + own [book]/[slug] routes — see #15 deferred.
     convergence: false,
     frontmatter: false,
     // opt-in per book; see #7
@@ -543,8 +544,8 @@ var researchPortfolioProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
-    // portfolio books ship their own landing/index
+    chapters: true,
+    // v4.6.1 (#75 follow-up): default-on. Portfolios still ship their own /frontmatter/* + landing; /chapters/* renders the underlying chapter list.
     convergence: false,
     // tools-profile-specific
     frontmatter: true,

package/examples/chapter-template-research-portfolio.mdx

@@ -1,25 +1,33 @@
 ---
+# required fields — schema will reject the chapter if missing
 title: "Chapter N — Title goes here"
-slug: chN-short-slug
-chapter: 1
-part: 1
+last_verified: 2026-05-19              # required; YAML date (no quotes)
+
+# optional — hierarchy (use whichever fits; all may be omitted)
+slug: chN-short-slug                   # optional; defaults to filename
+chapter: 1                             # optional; tools-style numeric
+part: 1                                # optional; number OR academic-style string enum
 week: 1                                # optional; omit if not on a weekly cadence
-status: prose_only                     # 'prose_only' | 'code_only' | 'implemented' | ...
-freshness: experimental-result         # 'experimental-result' | 'literature-survey' | 'theoretical' | 'reference'
-volatility: feature-surface            # 'stable-principle' | 'architectural-pattern' | 'feature-surface'
-tags:
+
+# optional — status (AUTHORING state) vs freshness (EPISTEMIC type); see Recipe 13
+status: prose_only                     # 'scaffolded'|'prose_only'|'code_only'|'chapter_only'|'reading_only'|'implemented'|'planned'
+freshness: experimental-result         # 'experimental-result'|'literature-survey'|'theoretical'|'reference'
+
+# optional — provenance
+volatility: feature-surface            # 'stable-principle'|'architectural-pattern'|'feature-surface'
+tags:                                  # optional; freeform string array
   - replace-me
   - with
   - real-tags
-sources:
+sources:                               # optional; structured inline T1-T4
   - tier: T1
     url: https://example.invalid/primary-source
     label: Primary source (e.g., NVD CVE / arXiv paper / official spec)
   - tier: T2
     url: https://example.invalid/secondary
     label: Secondary corroboration
-last_verified: 2026-05-19
-draft: true
+
+draft: true                            # optional; defaults to false
 ---
 
 import PreReleaseBanner from '@brandon_m_behring/book-scaffold-astro/components/PreReleaseBanner.astro';

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

package/recipes/07-chapter-shapes.md

@@ -47,6 +47,8 @@ Source: Koller & Friedman, *Probabilistic Graphical Models*, 2009 — chapter st
 | Research synthesis (one paper or theorem per chapter) | Academic | `academic` |
 | A practitioner field-guide across multiple tools | Tools | `tools` |
 | A versioned tech survey with convergence tracking | Tools | `tools` |
+| A research-portfolio with mixed evidence types + AI disclosure | Hybrid | `research-portfolio` (see [Recipe 13](13-research-portfolio-getting-started.md)) |
+| A course-notes / study-derived corpus | Hybrid | `course-notes` |
 | A solo essay collection | either, lean Academic | `minimal` (uses tools schema) |
 
 ## Hybrid books

package/recipes/09-validation.md

@@ -49,8 +49,25 @@ For pre-commit: add to `.pre-commit-config.yaml`:
 
 ## Environment variables
 
-- `BOOK_PROFILE` — `academic` enables Cite-key checking; otherwise skipped.
+- `BOOK_PRESET` (canonical) / `BOOK_PROFILE` (alias) — which preset to validate against. `academic` enables Cite-key checking.
 - `BOOK_REPO_ROOT` — absolute path to the paired code repo for CodeRef checks. Unset → skipped (the scaffold default; minimal/tools books rarely have a paired code repo).
+- `BOOK_CHAPTERS_DIR` — override the chapters directory (default: read from `content.config.ts`, fallback `src/content/chapters`).
+
+## Preset / chaptersBase resolution (v4.7.0+, #75)
+
+The validator resolves both `preset` and `chaptersBase` by consulting multiple sources in a documented order. Notable v4.7.0 addition: the v4.5+ canonical form
+
+```ts
+// src/content.config.ts
+export const { collections } = defineBookSchemas({
+  preset: 'research-portfolio',
+  chaptersBase: './src/content/textbook',
+});
+```
+
+is now read by the CLI (previously it was silently ignored — the CLI defaulted to `profile=minimal` and walked `./src/content/chapters/` while `astro build` applied the correct settings, masking real schema drift).
+
+Full precedence chain documented in [`PACKAGE_DESIGN.md §8 — Preset + chaptersBase resolution`](../../PACKAGE_DESIGN.md#preset--chaptersbase-resolution-v470-closes-75).
 
 ## Output
 

package/recipes/13-research-portfolio-getting-started.md

@@ -3,7 +3,7 @@
 The `research-portfolio` preset (v3.5.0+) is for books that combine:
 
 - **Academic structure**: week/part/status, KaTeX math, BibTeX citations, Theorem family
-- **Tools-style provenance**: volatility class, T1–T4 tier-tagged sources, `last_verified` freshness
+- **Tools-style provenance**: volatility class, T1–T4 tier-tagged sources, required `last_verified` date
 - **Portfolio-specific affordances**: pre-release banner, AI collaboration disclosure, blocked-by-upstream callouts, structured ethics/policy references
 
 If your book is primarily a weekly curriculum, use [`academic`](07-chapter-shapes.md#academic). If primarily AI-CLI comparison content, use [`tools`](07-chapter-shapes.md#tools). If a course-derived study notebook, use [`course-notes`](07-chapter-shapes.md#course-notes). Research portfolios sit at the intersection of all three and get their own preset.
@@ -39,28 +39,66 @@ This scaffolds:
 
 ## Chapter frontmatter shape
 
+Two fields are **required** by the schema; everything else is optional.
+
+| Field | Required? | Notes |
+|---|---|---|
+| `title` | **required** | Non-empty string |
+| `last_verified` | **required** | YAML date (`2026-05-19`); used by freshness reports + the v4.6 prevalidate hook |
+| All other fields | optional | See annotations in the template below |
+
+### `status` vs `freshness` — two distinct axes
+
+These look similar but mean different things. Authors often confuse them — getting `freshness` wrong fails the schema with `InvalidContentEntryDataError`.
+
+| Field | Concept | Enum values | Mental check |
+|---|---|---|---|
+| `status` | **Authoring state** — where am I in writing this chapter? | `scaffolded`, `prose_only`, `code_only`, `chapter_only`, `reading_only`, `implemented`, `planned` | "Have I written it?" |
+| `freshness` | **Epistemic type** — what kind of evidence does this chapter rest on? | `experimental-result`, `literature-survey`, `theoretical`, `reference` | "What kind of knowledge is this?" |
+
+A chapter can be `status: scaffolded` (not yet written) AND `freshness: theoretical` (will be a mathematical argument). They're orthogonal.
+
+If you want to mark a chapter as "not written yet", use `status: scaffolded` or `status: planned`. `freshness` has no value for that — it describes the chapter's content type, not its progress.
+
+### Template
+
 ```yaml
 ---
+# required
 title: "Chapter title"
-slug: ch01-introduction          # optional; defaults to filename
-chapter: 1                       # tools-style numeric
-part: 1                          # either number OR academic-style string enum
-week: 1                          # optional; only if you use weekly cadence
-status: prose_only               # academic 7-state (optional)
-freshness: experimental-result   # 'experimental-result' | 'literature-survey' | 'theoretical' | 'reference'
-volatility: feature-surface      # tools-style: 'stable-principle' | 'architectural-pattern' | 'feature-surface'
-tags:                            # freeform string array (NOT the tools_compared enum)
+last_verified: 2026-05-19         # YAML date (no quotes); becomes a JS Date
+
+# optional — hierarchy (use whichever fits; all three may be omitted)
+slug: ch01-introduction           # defaults to filename
+chapter: 1                        # tools-style numeric
+part: 1                           # either number OR academic-style string enum
+week: 1                           # only if you use weekly cadence
+
+# optional — authoring state + epistemic type
+status: prose_only                # 'scaffolded'|'prose_only'|'code_only'|'chapter_only'|'reading_only'|'implemented'|'planned'
+freshness: experimental-result    # 'experimental-result'|'literature-survey'|'theoretical'|'reference'
+
+# optional — provenance
+volatility: feature-surface       # 'stable-principle'|'architectural-pattern'|'feature-surface'
+tags:                             # freeform string array (NOT the tools_compared enum)
   - prompt-injection
   - red-team
   - CVE-2025-32711
-sources:
+sources:                          # structured inline; tier ∈ {T1, T2, T3, T4}
   - tier: T1
     url: https://nvd.nist.gov/vuln/detail/CVE-2025-32711
     label: NVD CVE-2025-32711 (primary advisory)
   - tier: T2
     url: https://arxiv.org/abs/2406.00799
     label: TaskTracker (Wallace et al. 2024)
-last_verified: 2026-05-19
+
+# optional — SEO / OpenGraph (v4.6+)
+description: "..."                # used by Base.astro meta tags
+author: "Brandon Behring"
+published: 2026-05-01
+updated: 2026-05-19
+image: "/og/ch01.png"
+
 draft: false
 ---
 ```

package/recipes/20-anki-export.md

@@ -0,0 +1,175 @@
+# Recipe 20 — Anki deck export (consumer-side pattern)
+
+**Profile**: any (most useful for `course-notes` and `research-portfolio`).
+
+**TL;DR**: The scaffold does **not** ship an `<AnkiCard>` component or an `extract-cards` CLI (see [PACKAGE_DESIGN.md §15a](../../PACKAGE_DESIGN.md#15a-deferred-scope-post-v4x) for why). This recipe shows how a consumer can roll their own — a small `<AnkiCard>` component plus a `scripts/extract-anki.mjs` extractor that walks the chapters collection and emits an Anki deck. ~120 lines of consumer-side code; no scaffold changes required.
+
+If your book is the **third** independent consumer to want this, please open an issue at [book-scaffold-astro](https://github.com/brandon-behring/book-scaffold-astro/issues) — that's the signal we need to consider promoting this to scaffold-level surface.
+
+## When to use this pattern
+
+Use it if your book:
+
+- Has discrete reviewable facts that benefit from spaced repetition (course notes, foundational reference material).
+- Already authors chapter content in MDX and wants flashcards as a *byproduct*, not a parallel deck file.
+- Wants `<AnkiCard>` to render inline as a "study widget" on the chapter page AND export to `.apkg` for offline review.
+
+Do **not** use it if your book is essay-style prose, narrative arguments, or working through proofs — the per-card "front/back" shape fights that content.
+
+## Step 1 — Add the component
+
+Create `src/components/AnkiCard.astro`:
+
+```astro
+---
+export interface Props {
+  id?: string;        // Stable Anki note GUID (recommended)
+  front: string;      // Card front (HTML / Markdown allowed in slot)
+  back?: string;      // Optional one-line back; otherwise use slot
+  tags?: string[];    // Anki tags (in addition to chapter slug)
+}
+const { id, front, back, tags = [] } = Astro.props;
+---
+
+<aside class="anki-card" data-id={id} data-front={front} data-tags={tags.join(',')}>
+  <header><strong>Q.</strong> {front}</header>
+  {back ? <p><strong>A.</strong> {back}</p> : <slot />}
+</aside>
+
+<style>
+  .anki-card {
+    border-left: 4px solid var(--color-accent, #6366f1);
+    padding: 0.75rem 1rem;
+    margin: 1rem 0;
+    background: var(--color-surface-2, #fafafa);
+    border-radius: 4px;
+  }
+  .anki-card header { margin-bottom: 0.5rem; }
+</style>
+```
+
+Import in chapters:
+
+```mdx
+import AnkiCard from '../components/AnkiCard.astro';
+
+<AnkiCard id="ch01-q01" front="What does the central limit theorem state?">
+The distribution of sample means approaches a normal distribution as $n \to \infty$,
+regardless of the underlying population distribution (provided finite variance).
+</AnkiCard>
+```
+
+## Step 2 — Add the extractor
+
+Create `scripts/extract-anki.mjs` at the project root:
+
+```js
+#!/usr/bin/env node
+/**
+ * scripts/extract-anki.mjs — walk chapters, find <AnkiCard> instances, emit JSON.
+ *
+ * Pairs with src/components/AnkiCard.astro. For .apkg generation, pipe the
+ * JSON through a separate tool (e.g., genanki Python lib) — keeping that
+ * outside this script avoids a runtime dependency on an Anki package builder.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { glob } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+
+const CHAPTERS_GLOB = 'src/content/chapters/**/*.{md,mdx}';
+const OUT_PATH = 'dist-anki/cards.json';
+
+// Match <AnkiCard ...> ... </AnkiCard> OR self-closing <AnkiCard ... />.
+// Captures attribute block + optional slot body.
+const ANKI_RE = /<AnkiCard\s+([^>]*?)(?:\/>|>([\s\S]*?)<\/AnkiCard>)/g;
+const ATTR_RE = /(\w+)\s*=\s*(?:"([^"]*)"|\{([^}]*)\}|'([^']*)')/g;
+
+function parseAttrs(attrStr) {
+  const out = {};
+  let m;
+  while ((m = ATTR_RE.exec(attrStr)) !== null) {
+    out[m[1]] = m[2] ?? m[3] ?? m[4];
+  }
+  return out;
+}
+
+async function main() {
+  const cards = [];
+  for await (const file of glob(CHAPTERS_GLOB)) {
+    const src = await readFile(file, 'utf8');
+    const slug = file.replace(/^.*\/chapters\//, '').replace(/\.mdx?$/, '');
+    let m;
+    while ((m = ANKI_RE.exec(src)) !== null) {
+      const attrs = parseAttrs(m[1]);
+      cards.push({
+        guid: attrs.id ?? `${slug}-${cards.length}`,
+        chapter: slug,
+        front: attrs.front,
+        back: attrs.back ?? (m[2] ?? '').trim(),
+        tags: (attrs.tags ?? '').split(',').filter(Boolean).concat([slug]),
+      });
+    }
+  }
+
+  await mkdir(dirname(OUT_PATH), { recursive: true });
+  await writeFile(OUT_PATH, JSON.stringify(cards, null, 2) + '\n');
+  console.log(`extract-anki: ${cards.length} cards → ${OUT_PATH}`);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });
+```
+
+Wire it into `package.json`:
+
+```json
+{
+  "scripts": {
+    "build:anki": "node scripts/extract-anki.mjs"
+  }
+}
+```
+
+## Step 3 — Generate the `.apkg`
+
+The JSON output is intentionally tool-neutral. Pick whichever Anki builder fits your stack:
+
+- **Python `genanki`** (most common): wrap the JSON read in a 20-line Python script that emits `.apkg` via `genanki.Deck` + `genanki.Note`. Stable note GUIDs from the `guid` field keep your review history when the source updates.
+- **Node `anki-apkg-export`** (npm): direct from Node if you want to stay in one runtime.
+- **Plain CSV import**: Anki's CSV importer reads the JSON directly enough that you can convert with `jq -r '.[] | [.guid, .front, .back, (.tags | join(" "))] | @tsv'`.
+
+The scaffold deliberately does **not** opine on the choice — the JSON is the contract.
+
+## Step 4 — Per-book grouping (if needed)
+
+The example above emits one deck per book. If you have a multi-book corpus (per the DLAI Study Notes pattern), gate emission on a `book` discriminator in chapter frontmatter:
+
+```js
+const byBook = new Map();
+// ... inside the loop:
+const fm = parseFrontmatter(src);  // bring your own YAML parser
+const book = fm.book ?? 'main';
+if (!byBook.has(book)) byBook.set(book, []);
+byBook.get(book).push({ ... });
+```
+
+Then write one file per book key. Multi-book corpus routing is itself out of scope at v4.x ([deferred, see #15](../../PACKAGE_DESIGN.md#15a-deferred-scope-post-v4x)) — if you need it, the same consumer-side pattern applies.
+
+## Common gotchas
+
+- **Stable GUIDs**: if you omit `id`, the script falls back to `${slug}-${index}`. Adding/removing cards above an existing card will shift indices and break review history. **Always set explicit `id` props** for cards you want to survive content edits.
+- **Markdown in slots**: Anki accepts HTML; MDX renders the slot content to HTML before this extractor sees it, so most formatting carries through. KaTeX math is a special case — the extractor sees raw `$...$` LaTeX; either pre-render with KaTeX server-side before extraction, or use Anki's MathJax integration.
+- **Pagefind**: `<AnkiCard>` instances are indexed by Pagefront like any prose. If you don't want flashcard fronts in search results, wrap in `<aside data-pagefind-ignore>`.
+- **Visual regression**: the component adds a styled block to every chapter that has cards. If you maintain visual baselines, regenerate them after first adoption.
+
+## Why this isn't in the scaffold
+
+Per [PACKAGE_DESIGN.md §15a](../../PACKAGE_DESIGN.md#15a-deferred-scope-post-v4x): single consumer signal so far (DLAI), runtime dep concerns (`.apkg` is a SQLite-backed zip — needs an external builder), and the design space for per-book grouping is entangled with multi-book corpus routing (also deferred). When 2-3 consumers independently want this, it gets promoted.
+
+## Canonical files
+
+- This recipe (consumer pattern)
+- [PACKAGE_DESIGN.md §15a](../../PACKAGE_DESIGN.md#15a-deferred-scope-post-v4x) — deferral rationale
+
+## Reference implementation
+
+- [`dlai-study-notes`](https://github.com/brandon-behring/dlai-study-notes) — the DLAI Study Notes pilot that prototyped this pattern (originator of issue #16).

package/recipes/README.md

@@ -20,6 +20,12 @@ Terse pointers into canonical code for the most common book-authoring workflows.
 | 12 | [Where to file issues](12-where-to-file-issues.md) | any | Consumer-pilot issue template, label conventions |
 | 13 | [Research-portfolio getting started](13-research-portfolio-getting-started.md) | research-portfolio | When to use the preset, frontmatter shape, the 4 new components |
 | 14 | [Port a LaTeX book](14-port-latex-book.md) | typically academic | Operational playbook for porting an existing LaTeX manuscript — bib sharing, inline-upstream-PR loop, common pitfalls |
+| 15 | [Defining styles](15-defining-styles.md) | any | The `defineStyle` API (v4.0+): compose styles per-key, override CSS, share between books |
+| 16 | [TikZ figures](16-tikz-figures.md) | typically academic | `build-figures` TikZ standalone → SVG pipeline |
+| 17 | [Draft chapter workflow](17-draft-chapter-workflow.md) | any | `draft: true` filtering, in-flight chapters, prerequisite gating |
+| 18 | [Chapter route ownership](18-chapter-route-ownership.md) | any | When to override the auto-injected `/chapters/[...slug]/` route |
+| 19 | [Prevalidate hook](19-prevalidate-hook.md) | any | Wire `prevalidate` to run `build:bib` + `build:labels` before `validate` |
+| 20 | [Anki deck export (consumer-side)](20-anki-export.md) | any (esp. course-notes, research-portfolio) | Roll-your-own `<AnkiCard>` + extractor; scaffold deliberately doesn't ship this |
 
 ## How to read recipes
 

package/scripts/validate.mjs

@@ -28,7 +28,7 @@
 import { readFile, access } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
-import { walkMdx, readChaptersBase } from './walk-mdx.mjs';
+import { walkMdx, readChaptersBase, readBookSchemaConfig } from './walk-mdx.mjs';
 
 /**
  * Best-effort .env reader. Mirrors `readEnvFile` in src/types.ts; kept inline
@@ -105,17 +105,26 @@ const DATA_DIR = resolve(ROOT, 'src/data');
 
 // Preset resolution (matches resolvePreset in src/types.ts):
 //   --preset flag > BOOK_PRESET env > BOOK_PROFILE env >
-//   .env BOOK_PRESET > .env BOOK_PROFILE > 'minimal'.
+//   .env BOOK_PRESET > .env BOOK_PROFILE >
+//   defineBookSchemas({ preset }) in content.config.ts >
+//   defineBookSchemas({ profile }) in content.config.ts (alias) >
+//   'minimal'.
 // .env fallback closes #20 — without it, consumers who set BOOK_PROFILE in
 // .env (the documented convenience in SKILL.md + create-book defaults) saw
 // the CLI silently default to minimal, hiding academic-profile errors.
+// content.config.ts fallback closes #75 — without it, consumers using the
+// canonical v4.5+ defineBookSchemas({ preset, chaptersBase }) form had the
+// CLI silently default to minimal, hiding research-portfolio (and any
+// non-env-set) profile errors while astro build applied the correct settings.
 const dotenv = readEnvFile(resolve(ROOT, '.env'));
+const schemaConfig = await readBookSchemaConfig(ROOT);
 const PRESET =
   presetFromFlag ??
   process.env.BOOK_PRESET ??
   process.env.BOOK_PROFILE ??
   dotenv.BOOK_PRESET ??
   dotenv.BOOK_PROFILE ??
+  schemaConfig.preset ??
   'minimal';
 // Alias kept for downstream message text only; the resolution above is canonical.
 const PROFILE = PRESET;

package/scripts/walk-mdx.mjs

@@ -34,6 +34,79 @@ export async function* walkMdx(dir, baseDir = dir) {
   }
 }
 
+/**
+ * Read the consumer's `content.config.ts` (or `.mjs` / `.js`) and extract
+ * `defineBookSchemas({ preset?, profile?, chaptersBase? })` options.
+ *
+ * v4.7.0 (closes #75): consumers using the v4.5+ canonical form
+ *
+ *   export const { collections } = defineBookSchemas({
+ *     preset: 'research-portfolio',
+ *     chaptersBase: './src/content/textbook',
+ *   });
+ *
+ * previously had BOTH options ignored by the CLI scripts. `validate` and
+ * `build-labels` resolved preset only from env vars and walked the default
+ * chapters dir, silently checking the wrong directory under the wrong
+ * profile while astro build applied the correct settings — a divergence
+ * masking real schema drift.
+ *
+ * Strategy: regex-parse the source file (avoid runtime import; the file
+ * imports from `astro:content` / `astro/loaders` which don't resolve in
+ * plain Node). Captures the entire `defineBookSchemas({ ... })` options
+ * object, then field-by-field regex within that scope for `preset:`,
+ * `profile:` (alias), and `chaptersBase:`.
+ *
+ * Returns `{ preset, chaptersBase }` — both nullable. Returns `null` for
+ * either field when:
+ *   - content.config.{ts,mjs,js} doesn't exist
+ *   - no `defineBookSchemas(...)` call found
+ *   - the field is absent or uses a dynamic form (variable, template literal)
+ *
+ * `preset` and `profile` are aliases (canonical name flipped in v3.7+);
+ * `preset` wins when both are present.
+ */
+export async function readBookSchemaConfig(projectRoot) {
+  const result = { preset: null, chaptersBase: null };
+  for (const ext of ['ts', 'mjs', 'js']) {
+    const configPath = join(projectRoot, `src/content.config.${ext}`);
+    if (!existsSync(configPath)) continue;
+    let source;
+    try {
+      source = await readFile(configPath, 'utf8');
+    } catch {
+      return result;
+    }
+    // Match `defineBookSchemas({ ... })` — capture the options object body.
+    // Non-greedy `[\s\S]*?` matches the smallest balanced-enough scope; for
+    // typical configs the options object is small (≤200 chars) and any
+    // nested braces (uncommon in this API) would terminate the match early.
+    // Acceptable trade-off: simple regex over a real parser.
+    const callMatch = source.match(
+      /\bdefineBookSchemas\s*\(\s*\{([\s\S]*?)\}\s*\)/,
+    );
+    if (callMatch) {
+      const optsBody = callMatch[1];
+      // preset is canonical (v3.7+); profile is backward-compat alias.
+      const presetMatch =
+        optsBody.match(/\bpreset\s*:\s*'([^']+)'/) ||
+        optsBody.match(/\bpreset\s*:\s*"([^"]+)"/);
+      const profileMatch =
+        optsBody.match(/\bprofile\s*:\s*'([^']+)'/) ||
+        optsBody.match(/\bprofile\s*:\s*"([^"]+)"/);
+      result.preset = presetMatch?.[1] ?? profileMatch?.[1] ?? null;
+      const chaptersBaseMatch =
+        optsBody.match(/\bchaptersBase\s*:\s*'([^']+)'/) ||
+        optsBody.match(/\bchaptersBase\s*:\s*"([^"]+)"/);
+      result.chaptersBase = chaptersBaseMatch?.[1] ?? null;
+    }
+    // First existing file wins (priority: .ts > .mjs > .js).
+    return result;
+  }
+  // No content.config.{ts,mjs,js} at all.
+  return result;
+}
+
 /**
  * Read the consumer's `content.config.ts` (or `.mjs` / `.js`) and extract
  * the `loader.base` path for the `chapters` content collection.
@@ -46,6 +119,9 @@ export async function* walkMdx(dir, baseDir = dir) {
  * consumer's config file and returns the actual base path so both scripts
  * discover the consumer's chapter files.
  *
+ * v4.7.0 (closes #75): when the raw Astro form isn't present, also consult
+ * `readBookSchemaConfig()` for `defineBookSchemas({ chaptersBase })`.
+ *
  * Strategy: regex-parse the source file (avoid runtime import; the file
  * imports from `astro:content` / `astro/loaders` which don't resolve in
  * plain Node). Matches both single- and double-quoted string literals;
@@ -55,6 +131,7 @@ export async function* walkMdx(dir, baseDir = dir) {
  * `${projectRoot}/src/content/chapters` when:
  *   - content.config.{ts,mjs,js} doesn't exist
  *   - the file exists but no `chapters` collection or `loader.base` found
+ *     AND no `defineBookSchemas({ chaptersBase: ... })` form found
  *   - the matched base path uses dynamic forms (variables, template literals)
  *     instead of a string literal
  *
@@ -91,6 +168,12 @@ export async function readChaptersBase(projectRoot) {
     if (captured) {
       return resolve(projectRoot, captured);
     }
+    // v4.7.0 (closes #75): no raw Astro form match — try the v4.5+ form
+    // `defineBookSchemas({ chaptersBase: '...' })`.
+    const schemaConfig = await readBookSchemaConfig(projectRoot);
+    if (schemaConfig.chaptersBase) {
+      return resolve(projectRoot, schemaConfig.chaptersBase);
+    }
     // File exists but no override found — assume the consumer uses the
     // scaffold's defineBookSchemas() default.
     return DEFAULT_BASE;

package/src/profiles/academic.ts

@@ -20,7 +20,7 @@ export const academicProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,        // academic consumers ship their own week-based /chapters listing
+    chapters: true,         // v4.6.1 (#75 follow-up): auto-injected /chapters/[...slug]/ + /chapters/ index. Pre-v4.3.0 academic books shipped their own listing; v4.6.0 (#76 Layer 3c) removed the consumer template assuming auto-injection. Default flipped here to close the gap. Consumers wanting their own listing override via `routes: { chapters: false }` + their own src/pages/chapters/* — see recipe 18.
     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

package/src/profiles/course-notes.ts

@@ -22,7 +22,7 @@ export const courseNotesProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,        // multi-book consumers route via [book]/[slug] themselves
+    chapters: true,         // v4.6.1 (#75 follow-up): default-on. Multi-book consumers (DLAI-style) override via routes: { chapters: false } + own [book]/[slug] routes — see #15 deferred.
     convergence: false,
     frontmatter: false,     // opt-in per book; see #7
     tips: false,            // v4.3.0 #70: opt-in per book

package/src/profiles/minimal.ts

@@ -17,7 +17,7 @@ export const minimalProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
+    chapters: true,         // v4.6.1 (#75 follow-up): default-on across all profiles. Consumer override via routes: { chapters: false }.
     convergence: false,
     frontmatter: false,     // opt-in per book; see #7
     tips: false,            // v4.3.0 #70: opt-in per book

package/src/profiles/research-portfolio.ts

@@ -33,7 +33,7 @@ export const researchPortfolioProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,             // portfolio books ship their own landing/index
+    chapters: true,              // v4.6.1 (#75 follow-up): default-on. Portfolios still ship their own /frontmatter/* + landing; /chapters/* renders the underlying chapter list.
     convergence: false,          // tools-profile-specific
     frontmatter: true,           // portfolios universally need title/disclosure/banner pages
     tips: false,                 // v4.3.0 #70: opt-in per book