@brandon_m_behring/book-scaffold-astro 3.2.0 → 3.4.0

package/dist/schemas.mjs

@@ -3,55 +3,9 @@ import { existsSync as existsSync2 } from "fs";
 import { defineCollection } from "astro:content";
 import { glob, file } from "astro/loaders";
 
-// src/types.ts
-import { existsSync, readFileSync } from "fs";
-var BOOK_PROFILES = ["academic", "tools", "minimal"];
-var BookConfigError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "BookConfigError";
-  }
-};
-function readEnvFile(path = ".env") {
-  try {
-    if (!existsSync(path)) return {};
-    const out = {};
-    for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
-      const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*?)\s*$/);
-      if (!m) continue;
-      let val = m[2] ?? "";
-      if (val.startsWith('"') && val.endsWith('"') || val.startsWith("'") && val.endsWith("'")) {
-        val = val.slice(1, -1);
-      }
-      out[m[1]] = val;
-    }
-    return out;
-  } catch {
-    return {};
-  }
-}
-function resolveProfile(explicit) {
-  let candidate = explicit ?? process.env.BOOK_PROFILE;
-  let source = "default";
-  if (explicit) source = "param";
-  else if (process.env.BOOK_PROFILE) source = "env";
-  if (!candidate) {
-    const fromFile = readEnvFile().BOOK_PROFILE;
-    if (fromFile) {
-      candidate = fromFile;
-      source = "dotenv";
-    }
-  }
-  candidate = candidate ?? "minimal";
-  if (!BOOK_PROFILES.includes(candidate)) {
-    throw new BookConfigError(
-      `profile must be one of ${BOOK_PROFILES.join(" | ")} (got ${JSON.stringify(candidate)})`
-    );
-  }
-  if (source === "default") {
-    console.warn("book-scaffold-astro: BOOK_PROFILE not set; falling back to 'minimal'.");
-  }
-  return candidate;
+// src/profile-kit.ts
+function defineProfile(p) {
+  return p;
 }
 
 // src/schemas.ts
@@ -122,6 +76,32 @@ var toolsChapterSchema = z.object({
   draft: z.boolean().default(false),
   updated: z.date().optional()
 });
+var minimalChapterSchema = toolsChapterSchema;
+var courseNotesChapterSchema = z.object({
+  // Identity
+  title: z.string().min(1),
+  chapter: z.number().int().min(0).max(99),
+  part: z.number().int().min(0).max(20).default(1),
+  description: z.string().optional(),
+  // Source attribution
+  course: z.string().optional(),
+  instructor: z.string().optional(),
+  source_url: z.string().url().optional(),
+  // Pedagogy
+  learning_outcomes: z.array(
+    z.object({
+      id: z.string(),
+      verb: z.string(),
+      text: z.string()
+    })
+  ).default([]),
+  tags: z.array(z.string()).default([]),
+  // Provenance + status (shared shape with tools profile)
+  last_verified: z.date(),
+  volatility: z.enum(volatilityLevels).default("architectural-pattern"),
+  sources: z.array(z.string()).default([]),
+  draft: z.boolean().default(false)
+});
 var sourcesSchema = z.object({
   url: z.string().url(),
   title: z.string().min(1),
@@ -158,17 +138,167 @@ var patternsSchema = z.object({
   convergence_date: z.date().nullable().optional()
 });
 
+// src/profiles/academic.ts
+var academicProfile = defineProfile({
+  name: "academic",
+  schema: academicChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,
+    // academic consumers ship their own week-based /chapters listing
+    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
+});
+
+// src/profiles/tools.ts
+var toolsProfile = defineProfile({
+  name: "tools",
+  schema: toolsChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: true,
+    // tools profile ships a flat chapter index
+    convergence: true,
+    // tools profile ships convergence dashboard
+    frontmatter: false
+    // opt-in per book; see #7
+  },
+  styles: [
+    "tokens.css",
+    "layout.css",
+    "callouts.css",
+    "chapter.css",
+    "typography.css",
+    "print.css",
+    "convergence.css",
+    "tool-filter.css"
+  ]
+});
+
+// src/profiles/minimal.ts
+var minimalProfile = defineProfile({
+  name: "minimal",
+  schema: minimalChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: 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/course-notes.ts
+var courseNotesProfile = defineProfile({
+  name: "course-notes",
+  schema: courseNotesChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,
+    // multi-book consumers route via [book]/[slug] themselves
+    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/index.ts
+var PROFILES = {
+  academic: academicProfile,
+  tools: toolsProfile,
+  minimal: minimalProfile,
+  "course-notes": courseNotesProfile
+};
+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);
+    this.name = "BookConfigError";
+  }
+};
+function readEnvFile(path = ".env") {
+  try {
+    if (!existsSync(path)) return {};
+    const out = {};
+    for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+      const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*?)\s*$/);
+      if (!m) continue;
+      let val = m[2] ?? "";
+      if (val.startsWith('"') && val.endsWith('"') || val.startsWith("'") && val.endsWith("'")) {
+        val = val.slice(1, -1);
+      }
+      out[m[1]] = val;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+function resolvePreset(explicitPreset, explicitProfile) {
+  let candidate = explicitPreset ?? explicitProfile ?? process.env.BOOK_PRESET ?? process.env.BOOK_PROFILE;
+  let source = "default";
+  if (explicitPreset || explicitProfile) source = "param";
+  else if (process.env.BOOK_PRESET || process.env.BOOK_PROFILE) source = "env";
+  if (!candidate) {
+    const env = readEnvFile();
+    const fromFile = env.BOOK_PRESET ?? env.BOOK_PROFILE;
+    if (fromFile) {
+      candidate = fromFile;
+      source = "dotenv";
+    }
+  }
+  candidate = candidate ?? "minimal";
+  if (!BOOK_PRESETS.includes(candidate)) {
+    throw new BookConfigError(
+      `preset must be one of ${BOOK_PRESETS.join(" | ")} (got ${JSON.stringify(candidate)})`
+    );
+  }
+  if (source === "default") {
+    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({
     loader: glob({
       // Exclude underscore-prefixed files (standard "hidden" convention).
       pattern: ["**/*.{md,mdx}", "!**/_*"],
       base: chaptersBase
     }),
-    schema: profile === "academic" ? academicChapterSchema : toolsChapterSchema
+    schema: schemaForProfile
   });
   const collections = {
     chapters
@@ -194,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.2.0",
+  "version": "3.4.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -113,7 +113,8 @@
     "pedagogy",
     "examples",
     "CLAUDE.md",
-    "README.md"
+    "README.md",
+    "LATEX_TO_MDX_MAPPING.md"
   ],
   "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/pages/print.astro

@@ -7,6 +7,13 @@
  * body, and wraps in a <section.chapter-print> so print.css can force
  * page breaks between chapters.
  *
+ * v3.3.0 (closes #2): renders chapters with the consumer's MDX-components
+ * map. Consumer creates src/mdx-components.{ts,js,mjs} that default-exports
+ * a defineMdxComponents({...}) call; this route imports the map via the
+ * virtual:book-scaffold/mdx-components module exposed by the toolkit's
+ * Vite plugin. If the consumer has no mdx-components file, the virtual
+ * module exports {} so the import is harmless.
+ *
  * Build pipeline:
  *   npm run build            → Astro emits dist/print/index.html
  *   npm run pdf              → pagedjs-cli fetches dist/print/ via preview
@@ -17,6 +24,7 @@ import Base from '../layouts/Base.astro';
 import { render } from 'astro:content';
 import { getAllChapters } from '../src/lib/chapters';
 import ChapterHeader from '../components/ChapterHeader.astro';
+import mdxComponents from 'virtual:book-scaffold/mdx-components';
 
 const chapters = await getAllChapters();
 const rendered = await Promise.all(
@@ -32,7 +40,7 @@ const rendered = await Promise.all(
     {rendered.map(({ entry, Content }) => (
       <section class="chapter-print">
         <ChapterHeader data={entry.data} />
-        <Content />
+        <Content components={mdxComponents} />
       </section>
     ))}
   </main>

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 = [];