@brandon_m_behring/book-scaffold-astro 4.6.1 → 4.8.0

package/CLAUDE.md

@@ -99,6 +99,8 @@ Two callout families coexist. Authors import what they need.
 
 **Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginNote`, `Sidenote`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`, `PocLayout` (v4.1.0+; wraps slot in a per-`kind` layout shell — 5 closed-union kinds; see `recipes/15-defining-styles.md`).
 
+**Provenance** (v4.8.0, any profile, **auto-injected by the chapter route — not author-imported**): per-chapter "How this was made" audit-trail block, rendered from the optional `provenance` frontmatter (`ai_tools`, `prompts_archive`, `decisions_log`, `audit_history`, `citation_backstop`). **Opt-out**: a chapter with no `provenance` shows a fallback ("Audit history not yet recorded"). Distinct from `AICollaborationDisclosure` (book-level, manual model+role disclosure). Repo-relative path fields render as `<code>`; only `http(s)` values link.
+
 Full reference in `recipes/04-component-library.md`.
 
 ## Citation patterns

package/components/Provenance.astro

@@ -0,0 +1,206 @@
+---
+/**
+ * Provenance — per-chapter "How this was made" audit-trail disclosure (v4.8.0).
+ *
+ * Renders the optional `provenance` chapter frontmatter (see provenanceObject in
+ * src/schemas.ts) as a collapsed <details> block, family-styled with the warm-plum
+ * disclosure language (cf. AICollaborationDisclosure.astro) and the ▸/▾ summary
+ * marker (cf. .chapter-toc in styles/chapter.css). No JavaScript.
+ *
+ * Auto-injected by the chapter route (pages/chapters/[...slug].astro) on EVERY
+ * chapter of EVERY profile — so it is OPT-OUT, not opt-in: a chapter with no
+ * `provenance` still renders, showing a fallback ("Audit history not yet
+ * recorded — initial draft"). This forces awareness and signals to readers that
+ * an audit trail is expected.
+ *
+ * Scope (deliberate): this block owns the PROCESS audit trail (ai_tools, prompts,
+ * decisions, audits, citation backstop). It does NOT render freshness/volatility —
+ * ChapterHeader.astro owns that "is this current?" badge. And it is distinct from
+ * AICollaborationDisclosure (book-level, manual model+role disclosure).
+ *
+ * Claim-safety: references are repo-relative paths (e.g. "audits/AUDIT_x.md",
+ * "DECISIONS.md#anchor") that do NOT resolve on the built static site, so they
+ * render as <code> text. Only genuine http(s) URLs become clickable links — the
+ * site's "no dead links" thesis applied to its own chrome.
+ */
+import type { Provenance } from '../src/schemas.js';
+
+interface Props {
+  data: Provenance | null;
+}
+const { data } = Astro.props;
+
+const isUrl = (s: string) => /^https?:\/\//i.test(s);
+const fmtDate = (d: Date | string) =>
+  (d instanceof Date ? d : new Date(d)).toISOString().slice(0, 10);
+
+const aiTools = data?.ai_tools ?? [];
+const audits = data?.audit_history ?? [];
+const backstop = data?.citation_backstop;
+const promptsArchive = data?.prompts_archive;
+const decisionsLog = data?.decisions_log;
+
+// Opt-out (D3): the block always renders; "empty" → fallback.
+const hasContent =
+  aiTools.length > 0 ||
+  audits.length > 0 ||
+  Boolean(backstop) ||
+  Boolean(promptsArchive) ||
+  Boolean(decisionsLog);
+
+// Teaser digest shown in the <summary> so the signal reads while collapsed.
+const teaserParts: string[] = [];
+if (audits.length) teaserParts.push(`${audits.length} audit${audits.length > 1 ? 's' : ''}`);
+if (backstop) teaserParts.push(`${backstop}-backed`);
+if (!teaserParts.length && aiTools.length) {
+  teaserParts.push(`${aiTools.length} tool${aiTools.length > 1 ? 's' : ''}`);
+}
+const teaser = teaserParts.length ? `How this was made · ${teaserParts.join(' · ')}` : 'How this was made';
+---
+<aside class="provenance" role="note" aria-labelledby="provenance-h">
+  <details class="provenance-details">
+    <summary id="provenance-h">{teaser}</summary>
+
+    {hasContent ? (
+      <div class="provenance-body">
+        {aiTools.length > 0 && (
+          <p class="provenance-row">
+            <span class="provenance-label">AI tools</span>
+            {aiTools.map((t) => <span class="provenance-chip">{t}</span>)}
+          </p>
+        )}
+
+        {(promptsArchive || decisionsLog) && (
+          <p class="provenance-row">
+            <span class="provenance-label">References</span>
+            {promptsArchive && (
+              <span class="provenance-ref">prompts: {isUrl(promptsArchive)
+                ? <a href={promptsArchive}>{promptsArchive}</a>
+                : <code>{promptsArchive}</code>}</span>
+            )}
+            {decisionsLog && (
+              <span class="provenance-ref">decisions: {isUrl(decisionsLog)
+                ? <a href={decisionsLog}>{decisionsLog}</a>
+                : <code>{decisionsLog}</code>}</span>
+            )}
+          </p>
+        )}
+
+        {audits.length > 0 && (
+          <div class="provenance-row">
+            <span class="provenance-label">Audit history</span>
+            <ul class="provenance-audits">
+              {audits.map((a) => (
+                <li>
+                  <time datetime={fmtDate(a.date)}>{fmtDate(a.date)}</time>
+                  <span class="provenance-audit-type">{a.type}</span>
+                  {isUrl(a.file) ? <a href={a.file}>{a.file}</a> : <code>{a.file}</code>}
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+
+        {backstop && (
+          <p class="provenance-row">
+            <span class="provenance-label">Citation backstop</span>
+            <span class={`provenance-badge backstop-${backstop}`}>{backstop}</span>
+          </p>
+        )}
+      </div>
+    ) : (
+      <p class="provenance-fallback">
+        Audit history not yet recorded — initial draft.
+      </p>
+    )}
+  </details>
+</aside>
+
+<style>
+  .provenance {
+    display: block;
+    margin: var(--space-6) 0;
+    padding: var(--space-3) var(--space-4);
+    border-left: var(--border-bar) solid var(--warm-plum);
+    background: var(--warm-plum-tint);
+    border-radius: 0 var(--radius-md) var(--radius-md) 0;
+    font-size: var(--text-sm);
+    line-height: var(--leading-normal);
+    max-width: var(--measure-main);
+  }
+  .provenance-details > summary {
+    cursor: pointer;
+    font-weight: 500;
+    color: var(--warm-plum);
+    letter-spacing: 0.02em;
+    list-style: none;
+  }
+  .provenance-details > summary::-webkit-details-marker {
+    display: none;
+  }
+  .provenance-details > summary::before {
+    content: '▸ ';
+    display: inline-block;
+  }
+  .provenance-details[open] > summary::before {
+    content: '▾ ';
+  }
+  .provenance-body {
+    margin-top: var(--space-3);
+  }
+  .provenance-row {
+    margin: var(--space-2) 0;
+    text-indent: 0;
+  }
+  .provenance-label {
+    display: inline-block;
+    min-width: 9rem;
+    font-size: var(--text-xs);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--warm-plum);
+    vertical-align: top;
+  }
+  .provenance-chip,
+  .provenance-badge {
+    display: inline-block;
+    margin: 0 var(--space-1) var(--space-1) 0;
+    padding: 0.1em 0.5em;
+    border-radius: var(--radius-sm);
+    background: color-mix(in srgb, var(--warm-plum) 12%, var(--paper));
+    font-size: var(--text-xs);
+  }
+  .provenance-ref {
+    display: inline-block;
+    margin-right: var(--space-3);
+  }
+  .provenance-ref code,
+  .provenance-audits code {
+    font-family: var(--font-code);
+    font-size: 0.95em;
+    background: var(--color-code-bg);
+    padding: 0.1em 0.4em;
+    border-radius: var(--radius-sm);
+  }
+  .provenance-audits {
+    list-style: none;
+    margin: var(--space-1) 0 0;
+    padding-left: 0;
+  }
+  .provenance-audits li {
+    margin: var(--space-1) 0;
+  }
+  .provenance-audits time {
+    font-family: var(--font-code);
+    margin-right: var(--space-2);
+  }
+  .provenance-audit-type {
+    margin-right: var(--space-2);
+    font-style: italic;
+  }
+  .provenance-fallback {
+    margin: var(--space-3) 0 0;
+    font-style: italic;
+    opacity: 0.8;
+  }
+</style>

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Q as volatilityLevels, h as ChaptersRenderer, n as Style } from './types-B2bO9Nga.js';
-export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, R as ResearchPortfolioChapter, m as RouteToggles, S as StatusBadge, o as StyleInput, T as ToolsChapter, V as VolatilityBadge, p as academicChapterSchema, q as academicParts, r as changeKinds, s as changelogSchema, t as chapterStatus, u as composeStyles, v as courseNotesChapterSchema, w as defineProfile, x as defineStyle, y as minimalChapterSchema, z as normalizeFrontmatterConfig, D as patternCategories, E as patternsSchema, G as researchPortfolioChapterSchema, H as resolvePreset, I as resolveProfile, J as sourceTiers, K as sourceTiersResearch, L as sourcesSchema, N as toolSlugs, O as toolsChapterSchema } from './types-B2bO9Nga.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Y as volatilityLevels, h as ChaptersRenderer, o as Style } from './types-DTQ2l6B6.js';
+export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, m as Provenance, R as ResearchPortfolioChapter, n as RouteToggles, S as StatusBadge, p as StyleInput, T as ToolsChapter, V as VolatilityBadge, q as academicChapterSchema, r as academicParts, s as changeKinds, t as changelogSchema, u as chapterStatus, v as citationBackstops, w as composeStyles, x as courseNotesChapterSchema, y as defineProfile, z as defineStyle, D as minimalChapterSchema, E as normalizeFrontmatterConfig, G as patternCategories, H as patternsSchema, I as provenanceObject, J as provenanceSchema, K as researchPortfolioChapterSchema, L as resolvePreset, N as resolveProfile, O as sourceTiers, Q as sourceTiersResearch, U as sourcesSchema, W as toolSlugs, X as toolsChapterSchema } from './types-DTQ2l6B6.js';
 import 'astro/zod';
 
 /**

package/dist/index.mjs

@@ -168,6 +168,18 @@ var chapterStatus = [
   "scaffolded",
   "planned"
 ];
+var citationBackstops = ["research-kb", "manual", "unverified"];
+var provenanceObject = z.object({
+  ai_tools: z.array(z.string()).default([]),
+  prompts_archive: z.string().optional(),
+  decisions_log: z.string().optional(),
+  audit_history: z.array(z.object({ date: z.date(), type: z.string(), file: z.string() })).default([]),
+  citation_backstop: z.enum(citationBackstops).optional()
+}).strict();
+var provenanceSchema = provenanceObject.refine(
+  (p) => p.ai_tools.length > 0 || p.audit_history.length > 0 || Boolean(p.citation_backstop) || Boolean(p.prompts_archive) || Boolean(p.decisions_log),
+  { message: "provenance is present but empty \u2014 omit the key, or set at least one field" }
+).optional();
 var academicChapterSchema = z.object({
   week: z.number().int().min(1).max(99),
   part: z.enum(academicParts),
@@ -185,7 +197,9 @@ var academicChapterSchema = z.object({
   published: z.date().optional(),
   updated: z.date().optional(),
   tags: z.array(z.string()).default([]),
-  image: z.string().optional()
+  image: z.string().optional(),
+  // v4.8.0: optional process-as-artifact audit trail (Provenance.astro).
+  provenance: provenanceSchema
 });
 var toolsChapterSchema = z.object({
   title: z.string().min(1),
@@ -203,7 +217,9 @@ var toolsChapterSchema = z.object({
   author: z.string().optional(),
   published: z.date().optional(),
   tags: z.array(z.string()).default([]),
-  image: z.string().optional()
+  image: z.string().optional(),
+  // v4.8.0: optional process-as-artifact audit trail (Provenance.astro).
+  provenance: provenanceSchema
 });
 var minimalChapterSchema = toolsChapterSchema;
 var sourceTiersResearch = ["T1", "T2", "T3", "T4"];
@@ -237,7 +253,9 @@ var courseNotesChapterSchema = z.object({
   author: z.string().optional(),
   published: z.date().optional(),
   updated: z.date().optional(),
-  image: z.string().optional()
+  image: z.string().optional(),
+  // v4.8.0: optional process-as-artifact audit trail (Provenance.astro).
+  provenance: provenanceSchema
 });
 var researchPortfolioChapterSchema = z.object({
   // Identity
@@ -295,7 +313,9 @@ var researchPortfolioChapterSchema = z.object({
   // `tags` + `updated` already existed; `author` + `published` + `image` are new.
   author: z.string().optional(),
   published: z.date().optional(),
-  image: z.string().optional()
+  image: z.string().optional(),
+  // v4.8.0: optional process-as-artifact audit trail (Provenance.astro).
+  provenance: provenanceSchema
 });
 var sourcesSchema = z.object({
   url: z.string().url(),
@@ -1262,6 +1282,7 @@ export {
   changelogSchema,
   chapterSortKey,
   chapterStatus,
+  citationBackstops,
   composeStyles,
   courseNotesChapterSchema,
   courseNotesStyle,
@@ -1278,6 +1299,8 @@ export {
   normalizeFrontmatterConfig,
   patternCategories,
   patternsSchema,
+  provenanceObject,
+  provenanceSchema,
   researchPortfolioChapterSchema,
   researchPortfolioStyle,
   resolvePreset,

package/dist/schemas.d.ts

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

package/dist/schemas.mjs

@@ -52,6 +52,18 @@ var chapterStatus = [
   "scaffolded",
   "planned"
 ];
+var citationBackstops = ["research-kb", "manual", "unverified"];
+var provenanceObject = z.object({
+  ai_tools: z.array(z.string()).default([]),
+  prompts_archive: z.string().optional(),
+  decisions_log: z.string().optional(),
+  audit_history: z.array(z.object({ date: z.date(), type: z.string(), file: z.string() })).default([]),
+  citation_backstop: z.enum(citationBackstops).optional()
+}).strict();
+var provenanceSchema = provenanceObject.refine(
+  (p) => p.ai_tools.length > 0 || p.audit_history.length > 0 || Boolean(p.citation_backstop) || Boolean(p.prompts_archive) || Boolean(p.decisions_log),
+  { message: "provenance is present but empty \u2014 omit the key, or set at least one field" }
+).optional();
 var academicChapterSchema = z.object({
   week: z.number().int().min(1).max(99),
   part: z.enum(academicParts),
@@ -69,7 +81,9 @@ var academicChapterSchema = z.object({
   published: z.date().optional(),
   updated: z.date().optional(),
   tags: z.array(z.string()).default([]),
-  image: z.string().optional()
+  image: z.string().optional(),
+  // v4.8.0: optional process-as-artifact audit trail (Provenance.astro).
+  provenance: provenanceSchema
 });
 var toolsChapterSchema = z.object({
   title: z.string().min(1),
@@ -87,7 +101,9 @@ var toolsChapterSchema = z.object({
   author: z.string().optional(),
   published: z.date().optional(),
   tags: z.array(z.string()).default([]),
-  image: z.string().optional()
+  image: z.string().optional(),
+  // v4.8.0: optional process-as-artifact audit trail (Provenance.astro).
+  provenance: provenanceSchema
 });
 var minimalChapterSchema = toolsChapterSchema;
 var sourceTiersResearch = ["T1", "T2", "T3", "T4"];
@@ -121,7 +137,9 @@ var courseNotesChapterSchema = z.object({
   author: z.string().optional(),
   published: z.date().optional(),
   updated: z.date().optional(),
-  image: z.string().optional()
+  image: z.string().optional(),
+  // v4.8.0: optional process-as-artifact audit trail (Provenance.astro).
+  provenance: provenanceSchema
 });
 var researchPortfolioChapterSchema = z.object({
   // Identity
@@ -179,7 +197,9 @@ var researchPortfolioChapterSchema = z.object({
   // `tags` + `updated` already existed; `author` + `published` + `image` are new.
   author: z.string().optional(),
   published: z.date().optional(),
-  image: z.string().optional()
+  image: z.string().optional(),
+  // v4.8.0: optional process-as-artifact audit trail (Provenance.astro).
+  provenance: provenanceSchema
 });
 var sourcesSchema = z.object({
   url: z.string().url(),

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.1",
+  "version": "4.8.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -72,6 +72,7 @@
     "./components/PolicyRef.astro": "./components/PolicyRef.astro",
     "./components/Practice.astro": "./components/Practice.astro",
     "./components/PreReleaseBanner.astro": "./components/PreReleaseBanner.astro",
+    "./components/Provenance.astro": "./components/Provenance.astro",
     "./components/Recovery.astro": "./components/Recovery.astro",
     "./components/ResultBox.astro": "./components/ResultBox.astro",
     "./components/Sidebar.astro": "./components/Sidebar.astro",

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

@@ -17,8 +17,10 @@
  * [...slug].astro for the canonical pattern).
  */
 import { getCollection, render } from 'astro:content';
+import type { Provenance } from '../../src/schemas.js';
 import Chapter from '../../layouts/Chapter.astro';
 import Base from '../../layouts/Base.astro';
+import ProvenanceBlock from '../../components/Provenance.astro';
 
 const BOOK_PRESET = import.meta.env.BOOK_PRESET ?? 'minimal';
 const USE_CHAPTER_LAYOUT = ['academic', 'research-portfolio'].includes(BOOK_PRESET);
@@ -34,7 +36,14 @@ export async function getStaticPaths() {
 const { entry } = Astro.props;
 const { Content, headings } = await render(entry);
 const Layout = USE_CHAPTER_LAYOUT ? Chapter : Base;
+
+// v4.8.0: per-chapter provenance audit trail. Rendered here (not in a single
+// layout) so it reaches BOTH layout paths — Chapter.astro (academic/
+// research-portfolio) AND Base.astro (tools/minimal/course-notes). Opt-out:
+// always rendered; absent `provenance` → the component's fallback.
+const provenance = (entry.data as { provenance?: Provenance }).provenance ?? null;
 ---
 <Layout entry={entry} headings={headings}>
   <Content />
+  <ProvenanceBlock data={provenance} />
 </Layout>

package/recipes/04-component-library.md

@@ -73,6 +73,24 @@ Supported `type` values: `theorem`, `proposition`, `lemma`, `corollary`, `defini
 | `Tag` | Inline volatility/topic tag | `<Tag>stable-principle</Tag>` |
 | `StatusBadge` | Render frontmatter `status` value with color | `<StatusBadge status={frontmatter.status} />` |
 | `ChapterHeader` | Auto-rendered metadata block (week, part, status, companion links) | placed at top of each chapter automatically by Chapter.astro |
+| `Provenance` | Auto-rendered per-chapter audit trail (v4.8.0) | placed at the end of each chapter by the chapter route — not imported |
+
+## Per-chapter provenance (v4.8.0, auto-injected)
+
+`Provenance` renders a collapsible "How this was made" block on **every** chapter — you don't import or place it. It reads the optional `provenance` frontmatter and is **opt-out**: a chapter with no `provenance` shows a fallback ("Audit history not yet recorded"). It surfaces *process* (the audit trail); `ChapterHeader` still owns *freshness*. Distinct from `AICollaborationDisclosure` (book-level, manual model+role disclosure).
+
+```yaml
+provenance:
+  ai_tools: ['Claude Code (Opus 4.8)', 'research-kb']
+  prompts_archive: docs/sessions/2026-05-22--ch07.md   # repo-relative path or URL
+  decisions_log: DECISIONS.md#ch07-derivation           # repo-relative path or URL
+  audit_history:
+    - { date: 2026-05-15, type: routine, file: audits/AUDIT_2026-05-15.md }
+    - { date: 2026-05-22, type: independent, file: audits/AUDIT_2026-05-22.md }
+  citation_backstop: research-kb                         # research-kb | manual | unverified
+```
+
+Repo-relative paths render as `<code>`; only `http(s)` values become links (no dead links). If present, the `provenance` object must be non-empty (omit the key to opt out — unknown keys are rejected). `citation_backstop` is a closed set; `audit_history[].type` is free text.
 
 ## Conditional imports
 

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/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/schemas.ts

@@ -70,6 +70,46 @@ export const chapterStatus = [
   'planned',
 ] as const;
 
+// ===== Provenance (v4.8.0) — process-as-artifact audit trail =====
+//
+// Optional per-chapter block attached to EVERY profile schema below.
+// components/Provenance.astro renders it as a collapsible "How this was made"
+// disclosure (opt-out: absent → fallback). Distinct from AICollaborationDisclosure
+// (book-level, manual). Paths are repo-relative, so prompts_archive / decisions_log
+// use plain z.string() — NOT .url() (which would reject "DECISIONS.md#anchor").
+// audit_history.type is a free string (real audit types vary: 'routine',
+// 'independent', 'first-deploy', ...); citation_backstop is a controlled vocabulary.
+export const citationBackstops = ['research-kb', 'manual', 'unverified'] as const;
+
+export const provenanceObject = z
+  .object({
+    ai_tools: z.array(z.string()).default([]),
+    prompts_archive: z.string().optional(),
+    decisions_log: z.string().optional(),
+    audit_history: z
+      .array(z.object({ date: z.date(), type: z.string(), file: z.string() }))
+      .default([]),
+    citation_backstop: z.enum(citationBackstops).optional(),
+  })
+  // .strict(): a misspelled key (e.g. `desisions_log`) must fail loud at build,
+  // not be silently stripped — silent data loss is the opposite of an audit trail.
+  .strict();
+
+// Attached to every chapter schema as an optional field. The `.refine` makes
+// "present ⇒ non-empty": a bare `provenance: {}` is author error (omit the key
+// to opt out instead), so it fails fast rather than rendering a meaningless block.
+export const provenanceSchema = provenanceObject
+  .refine(
+    (p) =>
+      p.ai_tools.length > 0 ||
+      p.audit_history.length > 0 ||
+      Boolean(p.citation_backstop) ||
+      Boolean(p.prompts_archive) ||
+      Boolean(p.decisions_log),
+    { message: 'provenance is present but empty — omit the key, or set at least one field' },
+  )
+  .optional();
+
 // ===== Chapter schemas — one per profile =====
 
 export const academicChapterSchema = z.object({
@@ -90,6 +130,8 @@ export const academicChapterSchema = z.object({
   updated: z.date().optional(),
   tags: z.array(z.string()).default([]),
   image: z.string().optional(),
+  // v4.8.0: optional process-as-artifact audit trail (Provenance.astro).
+  provenance: provenanceSchema,
 });
 
 export const toolsChapterSchema = z.object({
@@ -109,6 +151,8 @@ export const toolsChapterSchema = z.object({
   published: z.date().optional(),
   tags: z.array(z.string()).default([]),
   image: z.string().optional(),
+  // v4.8.0: optional process-as-artifact audit trail (Provenance.astro).
+  provenance: provenanceSchema,
 });
 
 /** Minimal profile currently aliases the tools schema. */
@@ -168,6 +212,8 @@ export const courseNotesChapterSchema = z.object({
   published: z.date().optional(),
   updated: z.date().optional(),
   image: z.string().optional(),
+  // v4.8.0: optional process-as-artifact audit trail (Provenance.astro).
+  provenance: provenanceSchema,
 });
 
 /**
@@ -255,6 +301,8 @@ export const researchPortfolioChapterSchema = z.object({
   author: z.string().optional(),
   published: z.date().optional(),
   image: z.string().optional(),
+  // v4.8.0: optional process-as-artifact audit trail (Provenance.astro).
+  provenance: provenanceSchema,
 });
 
 // ===== Inferred chapter types — one per schema =====
@@ -269,6 +317,7 @@ export type ToolsChapter = z.infer<typeof toolsChapterSchema>;
 export type MinimalChapter = z.infer<typeof minimalChapterSchema>;
 export type CourseNotesChapter = z.infer<typeof courseNotesChapterSchema>;
 export type ResearchPortfolioChapter = z.infer<typeof researchPortfolioChapterSchema>;
+export type Provenance = z.infer<typeof provenanceObject>;
 
 // ===== Collateral collection schemas (tools-profile; always-defined) =====