@brandon_m_behring/book-scaffold-astro 3.3.0 → 3.4.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { b as BookConfigOptions, d as BookScaffoldIntegrationOptions, v as volatilityLevels } from './types-s8NxCLU2.js';
-export { A as AcademicChapter, B as BOOK_PROFILES, a as BookConfigError, c as BookProfile, e as BookSchemasOptions, C as ChapterFor, f as CourseNotesChapter, M as MinimalChapter, P as ProfileDefinition, R as RouteToggles, T as ToolsChapter, g as academicChapterSchema, h as academicParts, i as changeKinds, j as changelogSchema, k as chapterStatus, l as courseNotesChapterSchema, m as defineProfile, n as minimalChapterSchema, p as patternCategories, o as patternsSchema, r as resolveProfile, s as sourceTiers, q as sourcesSchema, t as toolSlugs, u as toolsChapterSchema } from './types-s8NxCLU2.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, y as volatilityLevels } from './types-Bb97Na9S.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, h as CourseNotesChapter, M as MinimalChapter, P as ProfileDefinition, R as RouteToggles, T as ToolsChapter, i as academicChapterSchema, j as academicParts, k as changeKinds, l as changelogSchema, m as chapterStatus, n as courseNotesChapterSchema, o as defineProfile, p as minimalChapterSchema, q as patternCategories, r as patternsSchema, s as resolvePreset, t as resolveProfile, u as sourceTiers, v as sourcesSchema, w as toolSlugs, x as toolsChapterSchema } from './types-Bb97Na9S.js';
 import 'astro/zod';
 
 declare function defineBookConfig(opts: BookConfigOptions): Promise<AstroUserConfig>;

package/dist/index.mjs

@@ -263,8 +263,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
@@ -280,8 +282,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",
@@ -304,7 +308,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"]
 });
@@ -319,7 +325,9 @@ 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"]
 });
@@ -335,6 +343,7 @@ 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);
@@ -359,29 +368,33 @@ 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;
 }
+function resolveProfile(explicit) {
+  return resolvePreset(void 0, explicit);
+}
 
 // src/integration.ts
 import { fileURLToPath } from "url";
@@ -435,7 +448,11 @@ var ROUTE_REGISTRY = {
   search: { pattern: "/search", file: "search.astro" },
   print: { pattern: "/print", file: "print.astro" },
   chapters: { pattern: "/chapters", file: "chapters.astro" },
-  convergence: { pattern: "/convergence", file: "convergence.astro" }
+  convergence: { pattern: "/convergence", file: "convergence.astro" },
+  // v3.4.0 (#7): consumer-collection-backed frontmatter route. Opt-in via
+  // routes: { frontmatter: true } AND content.config.ts defining the
+  // collection (use frontmatterCollection() helper from /schemas subpath).
+  frontmatter: { pattern: "/frontmatter/[slug]", file: "frontmatter/[...slug].astro" }
 };
 function resolvePage(file) {
   return fileURLToPath(new URL(`../pages/${file}`, import.meta.url));
@@ -466,9 +483,14 @@ function bookScaffoldIntegration(opts) {
         }
         const consumerRoot = fileURLToPath(config.root);
         const resolvedMdxPath = resolveMdxComponentsPath(consumerRoot, mdxComponentsModule);
+        const presetLiteral = JSON.stringify(profile);
         updateConfig({
           vite: {
-            plugins: [makeMdxComponentsVitePlugin(resolvedMdxPath)]
+            plugins: [makeMdxComponentsVitePlugin(resolvedMdxPath)],
+            define: {
+              "import.meta.env.BOOK_PRESET": presetLiteral,
+              "import.meta.env.BOOK_PROFILE": presetLiteral
+            }
           }
         });
       }
@@ -478,7 +500,7 @@ function bookScaffoldIntegration(opts) {
 
 // src/config.ts
 async function defineBookConfig(opts) {
-  const profile = resolveProfile(opts.profile);
+  const profile = resolvePreset(opts.preset, opts.profile);
   const remarkPlugins = [];
   const rehypePlugins = [];
   if (profile === "academic") {
@@ -531,6 +553,8 @@ async function defineBookConfig(opts) {
     ...userMarkdown
   };
   const {
+    preset: _preset,
+    // v3.4.0
     profile: _profile,
     routes: _routes,
     // v3.3.0
@@ -541,6 +565,7 @@ async function defineBookConfig(opts) {
     markdown: _markdown,
     ...rest
   } = opts;
+  void _preset;
   void _profile;
   void _routes;
   void _mdxComponentsModule;
@@ -598,6 +623,7 @@ function freshnessLabel(f) {
   }
 }
 export {
+  BOOK_PRESETS,
   BOOK_PROFILES,
   BookConfigError,
   academicChapterSchema,
@@ -615,6 +641,7 @@ export {
   minimalChapterSchema,
   patternCategories,
   patternsSchema,
+  resolvePreset,
   resolveProfile,
   sourceTiers,
   sourcesSchema,

package/dist/schemas.d.ts

@@ -1,7 +1,40 @@
-import { e as BookSchemasOptions } from './types-s8NxCLU2.js';
+import { defineCollection } from 'astro:content';
+import { g as BookSchemasOptions } from './types-Bb97Na9S.js';
 import 'astro';
 import 'astro/zod';
 
+/**
+ * v3.4.0 (closes #7): consumer-facing helper to define a `frontmatter`
+ * content collection that the scaffold's auto-injected
+ * `/frontmatter/[slug]` route can render.
+ *
+ * Usage in consumer's content.config.ts:
+ *
+ *   import { defineBookSchemas, frontmatterCollection } from
+ *     '@brandon_m_behring/book-scaffold-astro/schemas';
+ *   import { z } from 'astro:content';
+ *
+ *   export const { collections } = {
+ *     collections: {
+ *       ...defineBookSchemas().collections,
+ *       frontmatter: frontmatterCollection(z.object({
+ *         slug: z.string(),
+ *         title: z.string(),
+ *         order: z.number(),
+ *         description: z.string().optional(),
+ *       })),
+ *     },
+ *   };
+ *
+ * Then enable the route via `defineBookConfig({ routes: { frontmatter: true } })`
+ * and drop MDX files under `src/content/frontmatter/`. The scaffold-injected
+ * route renders each entry with the consumer's mdx-components in scope (issue #2
+ * plumbing applies).
+ *
+ * Default loader: `**\/*.{md,mdx}` under `./src/content/frontmatter` (excluding
+ * underscore-prefixed files). Override `base` via the second arg.
+ */
+declare function frontmatterCollection(schema: Parameters<typeof defineCollection>[0]['schema'], base?: string): unknown;
 /**
  * Returns the package's default content collections. Closed shape per Q5;
  * consumer extends via object spread and Zod `.extend()` (see PACKAGE_DESIGN.md §5).
@@ -10,4 +43,4 @@ declare function defineBookSchemas(opts?: BookSchemasOptions): {
     collections: Record<string, unknown>;
 };
 
-export { defineBookSchemas };
+export { defineBookSchemas, frontmatterCollection };

package/dist/schemas.mjs

@@ -148,8 +148,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 +167,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 +193,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,7 +210,9 @@ 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"]
 });
@@ -220,6 +228,7 @@ 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,33 +253,43 @@ 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 chapters = defineCollection({
@@ -305,5 +324,6 @@ function defineBookSchemas(opts = {}) {
   return { collections };
 }
 export {
-  defineBookSchemas
+  defineBookSchemas,
+  frontmatterCollection
 };

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.4.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

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/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();
 

package/scripts/build-labels.mjs

@@ -36,6 +36,26 @@
 import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
 import { resolve, join, basename, dirname } from 'node:path';
 
+// --help / -h: non-mutating (closes #14).
+const USAGE = `Usage: book-scaffold build-labels
+
+Emit src/data/labels.json for <XRef> resolution. Walks chapter MDX files,
+extracts labelable components (Theorem, Figure, ...), assigns display strings
+like "Theorem 4.2" matching LaTeX \\cref.
+
+Env:
+  BOOK_CHAPTERS_DIR   Override chapters dir (default: src/content/chapters).
+  BOOK_LABELS_OUT     Override output path (default: src/data/labels.json).
+
+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 CHAPTERS_DIR = process.env.BOOK_CHAPTERS_DIR ?? 'src/content/chapters';
 const OUTPUT_PATH = process.env.BOOK_LABELS_OUT ?? 'src/data/labels.json';
 

package/scripts/render-notebooks.mjs

@@ -35,6 +35,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 render-notebooks
+
+Notebook pipeline. .ipynb -> standalone HTML via Jupyter nbconvert (--basic).
+Walks notebooks/ (or BOOK_NOTEBOOKS_PATH), emits to public/notebooks/.
+Graceful-skip if uv not on PATH.
+
+Env:
+  BOOK_NOTEBOOKS_PATH   Override notebooks source (default: notebooks/).
+
+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();
 

package/scripts/validate.mjs

@@ -7,56 +7,70 @@
  * book so it's pre-commit-hook friendly.
  *
  * Checks performed (per Q14 in the v2.0 plan):
- *
  *   1. <Cite key="..." /> — key exists in src/data/references.json.
- *      (Cite.astro already throws on unknown keys at build time; we
- *      surface ALL bad keys at once instead of failing on the first.)
- *
- *   2. <XRef id="..." /> — id exists in src/data/labels.json. XRef
- *      doesn't fail the build for unknown ids; without this check,
- *      typos ship to readers as "[?label]" placeholders.
- *
- *   3. <Figure src="/path/..." /> — referenced file exists under
- *      public/. Figure.astro renders a broken-image icon otherwise.
- *
- *   4. Internal markdown links [text](/foo) — target resolves to a
- *      known chapter slug or a known top-level route. External (http*)
- *      links are not checked (would need network IO).
+ *   2. <XRef id="..." /> — id exists in src/data/labels.json.
+ *   3. <Figure src="/path/..." /> — file exists under public/.
+ *   4. Internal markdown links [text](/foo) — target resolves.
+ *   5. <CodeRef path="..." line={N} /> — when BOOK_REPO_ROOT set,
+ *      path exists + line in bounds.
  *
- *   5. <CodeRef path="..." line={N} /> — when run inside a repo
- *      whose root is BOOK_REPO_ROOT, the path exists and the line
- *      number is within file bounds. Skipped when BOOK_REPO_ROOT
- *      isn't set (the scaffold default; only meaningful for academic
- *      books that paired with an experiments/ subtree).
- *
- * What this DOESN'T do (and why):
- *   - frontmatter Zod validation — already done by astro build's
- *     content-collection sync.
- *   - MDX renders — same; astro build will fail.
- *   - KaTeX strict-mode — covered by rehype-katex when academic
- *     profile is active; undefined macros become build errors.
+ * Run from the consumer's project root. Closes #8 (was resolving paths
+ * from the package's own directory inside node_modules — false negatives
+ * across all reference consumers).
  *
  * Usage:
- *   node scripts/validate.mjs
- *   BOOK_REPO_ROOT=/abs/path/to/code/repo node scripts/validate.mjs
- *
- * Exit code = total failure count (0 = pass, ≥1 = errors).
+ *   book-scaffold validate
+ *   book-scaffold validate --preset academic
+ *   BOOK_REPO_ROOT=/abs/path npx book-scaffold validate
  *
- * Wire into:
- *   - package.json scripts: "validate": "node scripts/validate.mjs"
- *   - pre-commit hook: .pre-commit-config.yaml
- *   - CI build pipeline: run before `astro build`
+ * Exit code = total failure count (0 = pass, >=1 = errors).
  */
 import { readFile, access } from 'node:fs/promises';
 import { glob } from 'node:fs/promises';
 import { resolve, dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 
-const ROOT = resolve(fileURLToPath(import.meta.url), '../..');
+// --help / -h: non-mutating (closes #14).
+const USAGE = `Usage: book-scaffold validate [--preset <name>]
+
+Pre-flight content validator. Checks Cite keys, XRef ids, Figure srcs,
+internal markdown links, and (when BOOK_REPO_ROOT is set) CodeRef paths.
+
+Options:
+  --preset <name>    academic | tools | minimal | course-notes
+                     (overrides BOOK_PRESET / BOOK_PROFILE env)
+  --help, -h         Print this message and exit (non-mutating).
+
+Env:
+  BOOK_PRESET        Preset name (preferred over BOOK_PROFILE).
+  BOOK_PROFILE       Backward-compat alias for BOOK_PRESET.
+  BOOK_REPO_ROOT     Absolute path to a sibling code repo for CodeRef checks.
+
+Exit code = total failure count.
+`;
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+
+// --preset <name> CLI flag (closes #9 — single source of truth across
+// defineBookConfig + validate).
+const argv = process.argv.slice(2);
+const presetFlagIdx = argv.findIndex((a) => a === '--preset');
+const presetFromFlag = presetFlagIdx >= 0 ? argv[presetFlagIdx + 1] : undefined;
+
+// v3.4.0: ROOT is the consumer's CWD, not the package's own dir.
+// Resolves issue #8 — three reference consumers reported "0 chapter(s) checked"
+// because ROOT was the package directory inside node_modules.
+const ROOT = process.cwd();
 const CHAPTERS_DIR = resolve(ROOT, 'src/content/chapters');
 const PUBLIC_DIR = resolve(ROOT, 'public');
 const DATA_DIR = resolve(ROOT, 'src/data');
-const PROFILE = process.env.BOOK_PROFILE ?? 'minimal';
+
+// Preset resolution: --preset flag > BOOK_PRESET env > BOOK_PROFILE env > 'minimal'.
+const PRESET = presetFromFlag ?? process.env.BOOK_PRESET ?? process.env.BOOK_PROFILE ?? 'minimal';
+// Alias kept for downstream message text only; the resolution above is canonical.
+const PROFILE = PRESET;
 const REPO_ROOT = process.env.BOOK_REPO_ROOT ?? null;
 
 const errors = [];