@brandon_m_behring/book-scaffold-astro 4.7.0 → 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.7.0",
+  "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/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) =====