@brandon_m_behring/book-scaffold-astro 3.3.0 → 3.5.0

package/dist/schemas.mjs

@@ -77,6 +77,7 @@ var toolsChapterSchema = z.object({
   updated: z.date().optional()
 });
 var minimalChapterSchema = toolsChapterSchema;
+var sourceTiersResearch = ["T1", "T2", "T3", "T4"];
 var courseNotesChapterSchema = z.object({
   // Identity
   title: z.string().min(1),
@@ -102,6 +103,59 @@ var courseNotesChapterSchema = z.object({
   sources: z.array(z.string()).default([]),
   draft: z.boolean().default(false)
 });
+var researchPortfolioChapterSchema = z.object({
+  // Identity
+  title: z.string().min(1),
+  slug: z.string().optional(),
+  // explicit slug override (otherwise filename)
+  description: z.string().optional(),
+  // Hierarchy — accept either academic-style or tools-style; all optional.
+  // The academic 'part' field is a string enum; tools 'part' is a number.
+  // Use z.union to permit either type.
+  part: z.union([z.number().int().min(0).max(20), z.string()]).optional(),
+  week: z.number().int().min(0).max(99).optional(),
+  chapter: z.number().int().min(0).max(99).optional(),
+  // Academic-style status (optional for research-portfolio — books may track
+  // chapters as 'prose_only' / 'experimental-result' / etc.).
+  status: z.enum([
+    "implemented",
+    "chapter_only",
+    "reading_only",
+    "prose_only",
+    "code_only",
+    "scaffolded",
+    "planned"
+  ]).optional(),
+  // Research-portfolio specific: nature of the chapter's content.
+  // Distinct from academic's 'status' (which tracks authoring state) — this
+  // describes the EVIDENCE TYPE the chapter rests on.
+  freshness: z.enum([
+    "experimental-result",
+    // primary data the author produced
+    "literature-survey",
+    // synthesis of others' work
+    "theoretical",
+    // analytical / mathematical argument
+    "reference"
+    // canonical material (definitions, taxonomy)
+  ]).optional(),
+  // Provenance (tools-style — overlap with tools/course-notes profiles).
+  volatility: z.enum(volatilityLevels).optional(),
+  tags: z.array(z.string()).default([]),
+  // freeform; replaces tools_compared
+  // Structured inline sources with T1-T4 tiers.
+  sources: z.array(
+    z.object({
+      tier: z.enum(sourceTiersResearch),
+      url: z.string().url(),
+      label: z.string().min(1)
+    })
+  ).default([]),
+  // Status + dates.
+  last_verified: z.date(),
+  updated: z.date().optional(),
+  draft: z.boolean().default(false)
+});
 var sourcesSchema = z.object({
   url: z.string().url(),
   title: z.string().min(1),
@@ -148,8 +202,10 @@ var academicProfile = defineProfile({
     print: true,
     chapters: false,
     // academic consumers ship their own week-based /chapters listing
-    convergence: false
+    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
@@ -165,8 +221,10 @@ var toolsProfile = defineProfile({
     print: true,
     chapters: true,
     // tools profile ships a flat chapter index
-    convergence: true
+    convergence: true,
     // tools profile ships convergence dashboard
+    frontmatter: false
+    // opt-in per book; see #7
   },
   styles: [
     "tokens.css",
@@ -189,7 +247,9 @@ var minimalProfile = defineProfile({
     search: true,
     print: true,
     chapters: false,
-    convergence: false
+    convergence: false,
+    frontmatter: false
+    // opt-in per book; see #7
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"]
 });
@@ -204,22 +264,46 @@ var courseNotesProfile = defineProfile({
     print: true,
     chapters: false,
     // multi-book consumers route via [book]/[slug] themselves
-    convergence: false
+    convergence: false,
+    frontmatter: false
+    // opt-in per book; see #7
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"]
 });
 
+// src/profiles/research-portfolio.ts
+var researchPortfolioProfile = defineProfile({
+  name: "research-portfolio",
+  schema: researchPortfolioChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,
+    // portfolio books ship their own landing/index
+    convergence: false,
+    // tools-profile-specific
+    frontmatter: true
+    // portfolios universally need title/disclosure/banner pages
+  },
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
+  katex: true
+  // math is common in research content
+});
+
 // src/profiles/index.ts
 var PROFILES = {
   academic: academicProfile,
   tools: toolsProfile,
   minimal: minimalProfile,
-  "course-notes": courseNotesProfile
+  "course-notes": courseNotesProfile,
+  "research-portfolio": researchPortfolioProfile
 };
 var BOOK_PROFILES = Object.keys(PROFILES);
 
 // src/types.ts
 import { existsSync, readFileSync } from "fs";
+var BOOK_PRESETS = BOOK_PROFILES;
 var BookConfigError = class extends Error {
   constructor(message) {
     super(message);
@@ -244,35 +328,45 @@ function readEnvFile(path = ".env") {
     return {};
   }
 }
-function resolveProfile(explicit) {
-  let candidate = explicit ?? process.env.BOOK_PROFILE;
+function resolvePreset(explicitPreset, explicitProfile) {
+  let candidate = explicitPreset ?? explicitProfile ?? process.env.BOOK_PRESET ?? process.env.BOOK_PROFILE;
   let source = "default";
-  if (explicit) source = "param";
-  else if (process.env.BOOK_PROFILE) source = "env";
+  if (explicitPreset || explicitProfile) source = "param";
+  else if (process.env.BOOK_PRESET || process.env.BOOK_PROFILE) source = "env";
   if (!candidate) {
-    const fromFile = readEnvFile().BOOK_PROFILE;
+    const env = readEnvFile();
+    const fromFile = env.BOOK_PRESET ?? env.BOOK_PROFILE;
     if (fromFile) {
       candidate = fromFile;
       source = "dotenv";
     }
   }
   candidate = candidate ?? "minimal";
-  if (!BOOK_PROFILES.includes(candidate)) {
+  if (!BOOK_PRESETS.includes(candidate)) {
     throw new BookConfigError(
-      `profile must be one of ${BOOK_PROFILES.join(" | ")} (got ${JSON.stringify(candidate)})`
+      `preset must be one of ${BOOK_PRESETS.join(" | ")} (got ${JSON.stringify(candidate)})`
     );
   }
   if (source === "default") {
-    console.warn("book-scaffold-astro: BOOK_PROFILE not set; falling back to 'minimal'.");
+    console.warn("book-scaffold-astro: BOOK_PRESET not set; falling back to 'minimal'.");
   }
   return candidate;
 }
 
 // src/schemas-entry.ts
+function frontmatterCollection(schema, base = "./src/content/frontmatter") {
+  return defineCollection({
+    loader: glob({
+      pattern: ["**/*.{md,mdx}", "!**/_*"],
+      base
+    }),
+    schema
+  });
+}
 function defineBookSchemas(opts = {}) {
-  const profile = resolveProfile(opts.profile);
+  const profile = resolvePreset(opts.preset, opts.profile);
   const chaptersBase = opts.chaptersBase ?? "./src/content/chapters";
-  const schemaForProfile = profile === "academic" ? academicChapterSchema : profile === "course-notes" ? courseNotesChapterSchema : profile === "minimal" ? minimalChapterSchema : toolsChapterSchema;
+  const schemaForProfile = profile === "academic" ? academicChapterSchema : profile === "course-notes" ? courseNotesChapterSchema : profile === "research-portfolio" ? researchPortfolioChapterSchema : profile === "minimal" ? minimalChapterSchema : toolsChapterSchema;
   const chapters = defineCollection({
     loader: glob({
       // Exclude underscore-prefixed files (standard "hidden" convention).
@@ -305,5 +399,6 @@ function defineBookSchemas(opts = {}) {
   return { collections };
 }
 export {
-  defineBookSchemas
+  defineBookSchemas,
+  frontmatterCollection
 };

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

@@ -0,0 +1,79 @@
+---
+title: "Chapter N — Title goes here"
+slug: chN-short-slug
+chapter: 1
+part: 1
+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:
+  - replace-me
+  - with
+  - real-tags
+sources:
+  - 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
+---
+
+import PreReleaseBanner from '@brandon_m_behring/book-scaffold-astro/components/PreReleaseBanner.astro';
+import PolicyRef from '@brandon_m_behring/book-scaffold-astro/components/PolicyRef.astro';
+import AICollaborationDisclosure from '@brandon_m_behring/book-scaffold-astro/components/AICollaborationDisclosure.astro';
+import BlockedByCallout from '@brandon_m_behring/book-scaffold-astro/components/BlockedByCallout.astro';
+import Theorem from '@brandon_m_behring/book-scaffold-astro/components/Theorem.astro';
+import Sidenote from '@brandon_m_behring/book-scaffold-astro/components/Sidenote.astro';
+import Cite from '@brandon_m_behring/book-scaffold-astro/components/Cite.astro';
+
+<PreReleaseBanner state="alpha" />
+
+## Introduction
+
+This chapter template exercises the four research-portfolio-specific components.
+Delete sections that don't apply to your chapter.
+
+## Section: a result with provenance
+
+Per <Cite key="example2024" />, the result holds under conditions $\Phi \subset \mathbb{R}^n$.
+<Sidenote>Sidenotes float to the right margin on desktop and inline below 768px.</Sidenote>
+
+<Theorem kind="theorem" n="1" name="Existence">
+Let $f: X \to Y$ be a map satisfying ... Then there exists ...
+</Theorem>
+
+## Section: policy + AI disclosure references
+
+See <PolicyRef file="ETHICS.md" section="§1 Dual-use disclosure" label="our ethics policy" />
+for the dual-use review process applied to this chapter.
+
+<AICollaborationDisclosure
+  model="Claude Opus 4.7 (Anthropic)"
+  role="research collaborator + writing collaborator"
+  commit_attribution="Co-Authored-By: Claude <noreply@anthropic.com>"
+>
+  All factual claims and numeric results in this chapter independently verified
+  by the human author; AI contributions reviewed line-by-line before merge.
+</AICollaborationDisclosure>
+
+## Section: an upstream blocker
+
+<BlockedByCallout
+  upstream="dataset X v2.0"
+  url="https://example.invalid/dataset-x/issues/42"
+  reason="full evaluation suite (current: smoke subset only)"
+  unblockedAt="2026-Q3"
+>
+  This section's numerical claims will be re-verified once dataset X v2.0 ships
+  with the missing splits. Current numbers are from the smoke subset and should
+  be treated as upper bounds.
+</BlockedByCallout>
+
+## Section: conclusion
+
+Wrap up here. Common pattern: 1-2 sentences summarizing the result, 1 sentence
+on limitations, 1 sentence pointing at the next chapter.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -41,6 +41,8 @@
       "import": "./dist/schemas.mjs"
     },
     "./package.json": "./package.json",
+    "./components/AICollaborationDisclosure.astro": "./components/AICollaborationDisclosure.astro",
+    "./components/BlockedByCallout.astro": "./components/BlockedByCallout.astro",
     "./components/CaseStudy.astro": "./components/CaseStudy.astro",
     "./components/ChapterHeader.astro": "./components/ChapterHeader.astro",
     "./components/ChapterNav.astro": "./components/ChapterNav.astro",
@@ -63,6 +65,8 @@
     "./components/OpenQuestion.astro": "./components/OpenQuestion.astro",
     "./components/PaperBox.astro": "./components/PaperBox.astro",
     "./components/PatternTimeline.astro": "./components/PatternTimeline.astro",
+    "./components/PolicyRef.astro": "./components/PolicyRef.astro",
+    "./components/PreReleaseBanner.astro": "./components/PreReleaseBanner.astro",
     "./components/Recovery.astro": "./components/Recovery.astro",
     "./components/ResultBox.astro": "./components/ResultBox.astro",
     "./components/Sidebar.astro": "./components/Sidebar.astro",
@@ -114,7 +118,8 @@
     "examples",
     "CLAUDE.md",
     "README.md",
-    "LATEX_TO_MDX_MAPPING.md"
+    "LATEX_TO_MDX_MAPPING.md",
+    "examples"
   ],
   "scripts": {
     "build": "tsup && rm -f dist/types-*.d.ts",

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

@@ -0,0 +1,48 @@
+---
+/**
+ * pages/frontmatter/[...slug].astro — auto-injected route for the
+ * consumer-defined `frontmatter` content collection. v3.4.0 closes #7.
+ *
+ * Opt-in: consumer enables via defineBookConfig({ routes: { frontmatter: true } })
+ * AND defines the collection in src/content.config.ts via the
+ * `frontmatterCollection(schema)` helper. Drops MDX files under
+ * src/content/frontmatter/; each renders at /frontmatter/<slug>/.
+ *
+ * Why a single template route (not consumer-owned): the rendering shape
+ * is uniform (Base layout + prose + Content) — every consumer would write
+ * the same file. Centralizing it keeps the consumer-side surface to just
+ * the schema definition + the routes-toggle flip.
+ *
+ * mdx-components plumbing (issue #2): the consumer's src/mdx-components.ts
+ * components are imported via the virtual module and threaded through
+ * <Content components={mdxComponents} />, so custom MDX components render
+ * here exactly as they do on /print and chapter routes.
+ */
+import { getCollection, render } from 'astro:content';
+import Base from '../../layouts/Base.astro';
+import mdxComponents from 'virtual:book-scaffold/mdx-components';
+
+export async function getStaticPaths() {
+  const entries = await getCollection('frontmatter');
+  return entries.map((entry) => ({
+    params: { slug: entry.id },
+    props: { entry },
+  }));
+}
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+
+// The schema is consumer-defined; we read defensively to avoid crashes
+// if the consumer skipped title/description fields. The frontmatterCollection
+// helper documents the recommended shape.
+const data = entry.data as Record<string, unknown>;
+const title = typeof data.title === 'string' ? data.title : entry.id;
+const description = typeof data.description === 'string' ? data.description : undefined;
+---
+
+<Base title={title} description={description ?? ''}>
+  <article class="prose frontmatter-page">
+    <Content components={mdxComponents} />
+  </article>
+</Base>

package/recipes/12-where-to-file-issues.md

@@ -0,0 +1,58 @@
+# Recipe 12 — Where to file issues (consumer-driven evolution)
+
+This toolkit grows through cross-consumer dogfooding. Each new book project you stand up — academic curriculum, AI-CLI comparison, course notes, research portfolio, or something new — is both content work *and* a structured test of the scaffold's abstraction.
+
+## When to file an issue
+
+File against [`brandon-behring/book-scaffold-astro/issues`](https://github.com/brandon-behring/book-scaffold-astro/issues) when:
+
+- The scaffold's current schemas don't fit your book's content shape (e.g. course notes needing freeform `tags` instead of the `tools_compared` enum).
+- An auto-injected route conflicts with your book's URL structure (e.g. multi-book corpus that routes via `[book]/[slug]/`).
+- A scaffold-injected route can't render your custom MDX components (e.g. you have `<AnkiCard>` that needs to appear on `/print`).
+- A CLI subcommand crashes or behaves unexpectedly (e.g. `validate` reports zero chapters).
+- A scaffold component you rebuilt has an exact equivalent already shipped (waste signal — file as `docs: missing in LATEX_TO_MDX_MAPPING.md`).
+- An API decision blocks one of your downstream projects.
+
+## Issue shape
+
+Mirror the pattern used by issues [#1–#14](https://github.com/brandon-behring/book-scaffold-astro/issues?q=is%3Aissue+sort%3Acreated-desc):
+
+```markdown
+## Problem
+<observed behavior + repro steps + which consumer surfaced it>
+
+## Evidence
+<command output, file paths, version pin (`npm view @brandon_m_behring/book-scaffold-astro version`)>
+
+## Suggested fix
+<one or more concrete options; trade-offs noted>
+
+## Acceptance criteria
+<bulleted checklist a reviewer can verify>
+```
+
+Label with `bug` / `enhancement` / `documentation`. Reference the consumer repo + line where the friction was hit.
+
+## Why this matters (the loop)
+
+Each batch of cross-consumer issues drives a minor toolkit release:
+
+- **v3.0–v3.2** absorbed Phase B/C/D feedback from `post_transformers` + `book-template-astro`.
+- **v3.3.0** closed 5 issues surfaced from the DLAI knowledge-graphs-rag pilot (course-notes profile + defineMdxComponents + per-route override + LaTeX migration doc).
+- **v3.4.0** closed 8 more (preset vocabulary + propagation + frontmatter helper + validate root fix + CI hygiene + docs).
+- **v3.5.0** (future) is expected to add the `research-portfolio` preset per issue #6 once cross-repo coordination with `prompt-injection-portfolio` is ready.
+
+Profile-by-profile growth is the explicit strategy: the toolkit gets a new profile when a real consumer needs one, not before.
+
+## What NOT to file
+
+- Bug reports from external users of a single book — file those against the book's repo, not the scaffold's.
+- Style preferences that already have an escape hatch (e.g. `extraStyles` array, consumer-side `<style>` blocks).
+- Speculative features ("we might one day want X"). Wait for the second consumer to actually need it.
+
+## Where to find prior decisions
+
+- [`CHANGELOG.md`](../../CHANGELOG.md) — release-by-release breakdown.
+- [`PACKAGE_DESIGN.md`](../PACKAGE_DESIGN.md) §1 Q1–Q6 — original Phase A locked decisions.
+- [`LATEX_TO_MDX_MAPPING.md`](../LATEX_TO_MDX_MAPPING.md) — 38-component reference.
+- [Closed issues](https://github.com/brandon-behring/book-scaffold-astro/issues?q=is%3Aissue+is%3Aclosed) — many problems already have rejected-alternative discussion attached.

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

@@ -0,0 +1,179 @@
+# Recipe 13 — Research-portfolio getting started
+
+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
+- **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.
+
+## When to use this preset
+
+Choose `research-portfolio` if your book:
+
+- Reports on research the author conducted directly (experimental results, theoretical analysis, literature surveys with original synthesis)
+- Has an evolving release state — chapters land at different times, the book passes through alpha → beta → rc states
+- Cites primary sources directly inline per-chapter (vs the tools-profile pattern of a central sources collection)
+- Discloses AI collaboration / dual-use considerations / governance per repo policy
+- Tracks upstream blockers (waiting on a tool release, a paper publication, a dataset)
+
+Reference (forthcoming) consumer: [`prompt-injection-portfolio`](https://github.com/brandon-behring/prompt-injection-portfolio).
+
+## Quickstart
+
+```bash
+npx @brandon_m_behring/create-book my-portfolio --preset=research-portfolio
+cd my-portfolio
+npm install
+npm run dev
+```
+
+This scaffolds:
+
+- `astro.config.mjs` with `defineBookConfig({ preset: 'research-portfolio' })`
+- `src/content.config.ts` with the `researchPortfolioChapterSchema`
+- A sample chapter at `src/content/chapters/01-introduction.mdx`
+- Frontmatter pages at `src/content/frontmatter/` (title-page, ai-disclosure, banner)
+- A `bibliography.bib` stub for citations
+
+## Chapter frontmatter shape
+
+```yaml
+---
+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)
+  - prompt-injection
+  - red-team
+  - CVE-2025-32711
+sources:
+  - 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
+draft: false
+---
+```
+
+All hierarchy fields (`part`, `week`, `chapter`) are optional — chapters can use whichever shape fits. The route templates dispatch on which is set.
+
+## The 4 portfolio-specific components
+
+Shipped in v3.5.0 alongside the preset:
+
+### `<PreReleaseBanner>` — declare release state
+
+```astro
+---
+import PreReleaseBanner from '@brandon_m_behring/book-scaffold-astro/components/PreReleaseBanner.astro';
+---
+<PreReleaseBanner state="alpha" />
+<PreReleaseBanner state="beta" dismissAt="v0.7.0" />
+<PreReleaseBanner state="rc" message="Final review pass; please file issues." />
+<PreReleaseBanner state="locked" />
+```
+
+Place at the top of a layout to surface site-wide, or inline at the top of a specific chapter. Four states: `'alpha' | 'beta' | 'rc' | 'locked'`. Each has a default message + color treatment; override with `message`.
+
+### `<PolicyRef>` — inline link to a repo-root policy doc
+
+```astro
+---
+import PolicyRef from '@brandon_m_behring/book-scaffold-astro/components/PolicyRef.astro';
+---
+See <PolicyRef file="ETHICS.md" section="§1 Dual-use disclosure" label="our ethics policy" />
+for the dual-use review process.
+
+Per <PolicyRef file="SECURITY.md" /> the disclosure timeline is 90 days.
+```
+
+Resolves to `/<file>#<slug-of-section>` by default (assumes consumer ships the markdown at site root via `public/` or an Astro page). Override the href with `href="..."`.
+
+### `<AICollaborationDisclosure>` — render an AI-collab paragraph
+
+```astro
+---
+import AICollaborationDisclosure from '@brandon_m_behring/book-scaffold-astro/components/AICollaborationDisclosure.astro';
+---
+<AICollaborationDisclosure
+  model="Claude Opus 4.7 + Sonnet 4.6 (Anthropic)"
+  role="research collaborator + writing collaborator"
+  commit_attribution="Co-Authored-By: Claude <noreply@anthropic.com>"
+>
+  All factual claims independently verified by the human author; AI contributions
+  reviewed line-by-line before merge.
+</AICollaborationDisclosure>
+```
+
+Three required props (`model`, `role`, `commit_attribution`); optional slot for prose. For YAML-driven config, load the YAML consumer-side and spread props:
+
+```astro
+---
+import disclosure from '../data/ai-collaboration.yaml';
+---
+<AICollaborationDisclosure {...disclosure} />
+```
+
+(The scaffold doesn't bundle a YAML parser; use `astro:content` file loader with `yaml()` or similar consumer-side.)
+
+### `<BlockedByCallout>` — declare upstream blockers
+
+```astro
+---
+import BlockedByCallout from '@brandon_m_behring/book-scaffold-astro/components/BlockedByCallout.astro';
+---
+<BlockedByCallout
+  upstream="book-scaffold-astro v3.5.0"
+  url="https://github.com/brandon-behring/book-scaffold-astro/issues/6"
+  reason="research-portfolio preset + 3 new components"
+  unblockedAt="2026-05-19"
+>
+  Once the preset ships, this chapter's frontmatter migrates from the
+  hand-rolled schema to the upstream `research-portfolio` shape.
+</BlockedByCallout>
+```
+
+Use for chapters/sections waiting on external work — a tool release, a paper publication, a dataset acquisition. The structured fields produce a scannable card; slot content holds migration notes / workaround prose.
+
+## Frontmatter pages
+
+The `research-portfolio` preset enables `/frontmatter/[slug]/` by default. Drop MDX files under `src/content/frontmatter/` (each needs `slug`, `title`, `order` per `frontmatterCollection()` — see [recipe 04](04-component-library.md) or PACKAGE_DESIGN.md §17).
+
+Common frontmatter pages for a portfolio:
+
+- `title-page.mdx` — book title + author + version + license
+- `ai-collaboration-disclosure.mdx` — wraps `<AICollaborationDisclosure>`
+- `pre-alpha-banner.mdx` (or similar) — author's note on release state
+- `executive-summary.mdx` — 1-page overview for skim readers
+- `acknowledgments.mdx` — collaborators + funding + dataset providers
+- `ethics-policy.mdx` — wraps `<PolicyRef>` to other ETHICS docs
+
+## Migrating from a hand-rolled schema
+
+If you previously rolled your own schema (e.g., for `prompt-injection-portfolio` pre-v3.5.0), migration is mostly mechanical:
+
+1. **Replace your `defineCollection` for chapters** with `defineBookSchemas({ preset: 'research-portfolio' }).collections.chapters`.
+2. **Rename `tools_compared` → `tags`** in frontmatter across chapters (the new schema uses freeform `tags`; the rename is a global find-and-replace).
+3. **Restructure `sources`** to the new inline shape `{ tier: 'T1', url, label }` — if you were using the tools-profile `sources` collection (referenced by string keys), inline them per chapter.
+4. **Replace ad-hoc PreReleaseBanner / EthicsRef / AIAssistanceDisclosure** components with the scaffold-shipped versions (delete your local copies; update imports).
+5. **Bump pin to `^3.5.0`** in your `package.json`.
+
+See `package/CHANGELOG.md` §3.5.0 for the full additive list.
+
+## See also
+
+- [Recipe 04 — Component library](04-component-library.md) — full component reference (38+ now with v3.5.0 additions)
+- [Recipe 07 — Chapter shapes](07-chapter-shapes.md) — choosing between presets
+- [Recipe 12 — Where to file issues](12-where-to-file-issues.md) — feedback loop for new portfolios
+- [`LATEX_TO_MDX_MAPPING.md`](../LATEX_TO_MDX_MAPPING.md) — converting a LaTeX research book
+- [`PACKAGE_DESIGN.md`](../PACKAGE_DESIGN.md) — full API contract

package/scripts/build-bib.mjs

@@ -33,6 +33,24 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+
+// --help / -h: non-mutating (closes #14).
+const USAGE = `Usage: book-scaffold build-bib
+
+Bibliography pipeline (academic profile). Reads bibliography.bib (or
+BOOK_BIB_PATH if set), parses via @citation-js, emits src/data/references.json.
+
+Env:
+  BOOK_BIB_PATH      Override path to .bib file (default: ./bibliography.bib).
+
+Options:
+  --help, -h         Print this message and exit (non-mutating).
+`;
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
 import { Cite } from '@citation-js/core';
 import '@citation-js/plugin-bibtex';
 

package/scripts/build-figures.mjs

@@ -30,6 +30,25 @@ import { dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 
+// --help / -h: non-mutating (closes #14).
+const USAGE = `Usage: book-scaffold build-figures
+
+Figure pipeline. PDF -> SVG via pdftocairo (PNG fallback via pdftoppm at
+200dpi). Walks figures/ (or BOOK_FIGURES_PATH), emits to public/figures/.
+Graceful-skip if pdftocairo / pdftoppm not on PATH.
+
+Env:
+  BOOK_FIGURES_PATH   Override figures source (default: figures/).
+
+Options:
+  --help, -h          Print this message and exit (non-mutating).
+`;
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = process.cwd();