@brandon_m_behring/book-scaffold-astro 3.0.0-alpha.0

package/pages/search.astro

@@ -0,0 +1,87 @@
+---
+/**
+ * search.astro — full-page Pagefind search UI.
+ *
+ * The Pagefind index is generated at build time by `pagefind --site dist`
+ * (see package.json). This page is the interactive entry point: users
+ * land here via the header search icon and type queries; Pagefind's
+ * bundled UI renders results with excerpts from indexed chapters.
+ *
+ * CSS/JS paths (/pagefind/*) only exist after the build step, not in
+ * `astro dev`. See README for dev-search workflow.
+ */
+import Base from '../layouts/Base.astro';
+---
+
+<Base
+  title="Search · book-template-astro"
+  description="Full-text search across the book. Indexed via Pagefind at build time; all queries run in the browser."
+>
+  <link rel="stylesheet" href="/pagefind/pagefind-ui.css" slot="head" />
+
+  <main class="prose search-page">
+    <h1>Search</h1>
+    <p>
+      Full-text search runs in your browser. The index is generated at
+      build time and is less than 100 KB total — queries never leave
+      the page.
+    </p>
+    <div id="search"></div>
+  </main>
+
+  <script src="/pagefind/pagefind-ui.js" is:inline></script>
+  <script is:inline>
+    // Initialize after the Pagefind bundle has loaded.
+    window.addEventListener('DOMContentLoaded', () => {
+      if (typeof window.PagefindUI === 'function') {
+        new window.PagefindUI({
+          element: '#search',
+          showImages: false,
+          showSubResults: true,
+          resetStyles: false,
+        });
+      } else {
+        document.getElementById('search').innerHTML =
+          '<p><em>Search index not found. Run <code>npm run build</code> first; dev mode does not include the index.</em></p>';
+      }
+    });
+  </script>
+
+  <style is:global>
+    /* Tame PagefindUI defaults to match the book's typography + palette. */
+    .pagefind-ui__form {
+      margin-top: var(--space-4);
+    }
+    .pagefind-ui__search-input {
+      font-family: var(--font-body) !important;
+      font-size: var(--text-base) !important;
+      padding: var(--space-3) !important;
+      border: 1px solid var(--color-border) !important;
+      border-radius: var(--radius-md) !important;
+      background: var(--color-bg-subtle) !important;
+      color: var(--color-text) !important;
+    }
+    .pagefind-ui__search-input:focus {
+      border-color: var(--color-link) !important;
+      outline: 2px solid color-mix(in srgb, var(--color-link) 30%, transparent);
+    }
+    .pagefind-ui__result {
+      border-bottom: 1px solid var(--color-border) !important;
+      padding: var(--space-3) 0 !important;
+    }
+    .pagefind-ui__result-link {
+      color: var(--color-link) !important;
+      font-weight: 500 !important;
+    }
+    .pagefind-ui__result-excerpt {
+      color: var(--color-text) !important;
+      font-size: var(--text-sm) !important;
+    }
+    .pagefind-ui__result-excerpt mark {
+      background: var(--warm-gold-tint);
+      color: var(--color-text);
+      padding: 0 0.15em;
+      border-radius: var(--radius-sm);
+    }
+  </style>
+</Base>

package/pedagogy/kf-chapter-shape.md

@@ -0,0 +1,96 @@
+# Koller-Friedman chapter shape
+
+Every chapter in a book-scaffold-astro project uses a uniform three-part
+skeleton: **Representation**, **Operation**, **Evolution**. The idea
+comes from Daphne Koller and Nir Friedman's *Probabilistic Graphical
+Models: Principles and Techniques* (MIT Press, 2009), where every
+chapter on a graphical model type follows this sequence.
+
+## The three parts
+
+### Representation
+
+What is the thing, conceptually? Define the object the chapter is
+about. Give its structural properties, its type signature, the
+invariants that make it itself. Answer: **what are we looking at?**
+
+A chapter on agents might define: what an agent is as a computational
+object; what makes an agent distinct from a script; what invariants
+(context, tools, permissions) every agent carries.
+
+### Operation
+
+How does the thing behave? Show the dynamics — how it's used, how it
+fails, how it composes. Include the verification / testing perspective.
+Answer: **what does it do, and how do we know it's doing the right
+thing?**
+
+For the same agent chapter, Operation would cover: the session loop,
+how agents consume context, how multi-step tasks decompose, common
+failure modes, and how to detect them.
+
+### Evolution
+
+How does the thing change over time? Show comparative and historical
+evidence. This is where the book's "convergence / divergence" callouts
+live — which tools adopted this pattern, when, and where they still
+differ. Answer: **is this idea stable, or is it still being argued?**
+
+For the agent chapter, Evolution would cover: when each tool shipped
+agent primitives, which design decisions converged, what's still open.
+
+## Why this shape
+
+Three reasons:
+
+1. **Drift-resistance.** When every chapter looks the same structurally,
+   the skeleton is legible at a glance. Drift into feature documentation
+   becomes visible because it won't fit the shape. A chapter that
+   accidentally turns into a feature catalogue has no Evolution section
+   — the gap is the alarm.
+
+2. **Reader fluency.** A reader learns the skeleton once and reads every
+   subsequent chapter fluently. They know where to find the invariants
+   (Representation), where to find the failure modes (Operation), and
+   where to find the historical context (Evolution). No hunting.
+
+3. **Comparative pedagogy.** The Evolution section makes cross-tool
+   comparison first-class. When tools converge on a pattern, the
+   Convergence callout renders in gold. When tools diverge on a
+   design choice, the Divergence callout renders with a dashed
+   accent. Neither is hidden; both are expected.
+
+## How the scaffold enforces this
+
+The scaffold doesn't validate chapter structure at build time (too
+brittle), but it ships visual affordances that make the structure
+visible:
+
+- `/chapters/` index renders volatility + freshness + tools badges on
+  every card — the reader sees the Evolution metadata before they even
+  open the chapter.
+- `Convergence` and `Divergence` callouts signal stability state
+  within a chapter. Both live in the Evolution section by convention.
+- `last_verified` + `volatility` frontmatter fields power the freshness
+  badge. Since freshness is tied to volatility class, Evolution pressure
+  on a chapter directly surfaces as a stale badge.
+
+## Authoring tips
+
+- **Start every chapter with Representation.** Even if you know the
+  reader has seen the concept before, restate it in the chapter's own
+  terms. Assume no prior chapter.
+- **Operation goes second, not last.** Tempting to put examples last;
+  the KF structure asks you to argue the object first, then show how
+  it behaves.
+- **Evolution is the longest section in early-stage chapters.** When
+  the topic is young, the "how did we get here" story is the most
+  valuable part of the chapter. As the topic matures, Evolution shrinks
+  while Representation and Operation grow.
+
+## References
+
+- Koller, D., & Friedman, N. (2009). *Probabilistic Graphical Models:
+  Principles and Techniques*. MIT Press.
+- The agentic-coding book's `00-design.mdx` explains how the scaffold
+  implements these ideas — read it as a worked example.

package/pedagogy/source-tiers.md

@@ -0,0 +1,121 @@
+# Source tiers
+
+Every source cited in a book-scaffold-astro book carries a `tier` field
+in `sources/manifest.yaml`. The tier calibrates reader trust at the
+point of use — a citation renders with a tier badge, and the source
+archive page groups entries by tier descending.
+
+Four tiers in descending authority. This methodology migrated from the
+predecessor LaTeX book `claude-best-practices`'s `docs/source-hierarchy.md`
+(2025-2026), where it evolved across v2.0 → v2.9.
+
+## The four tiers
+
+### T1-official
+
+Vendor-official documentation or release notes. Highest trust for
+factual claims about the vendor's own tool.
+
+Examples:
+- `anthropic.com/docs/...` for claims about Claude Code behavior.
+- `cloud.google.com/gemini-code-assist/...` for Gemini CLI.
+- `platform.openai.com/docs/codex/...` for Codex CLI.
+
+Use when the claim is about the vendor's tool's specification — what
+a flag does, what a command name is, what an event payload looks like.
+
+### T2-release-notes
+
+Release blog posts, changelogs, conference talks from the vendor.
+Trustworthy for intent and availability claims. Slightly less formal
+than T1 docs because release notes describe what the vendor
+*announced*, not necessarily what the shipped artifact behaves like.
+
+Examples:
+- `anthropic.com/news/...` for a feature announcement.
+- A YouTube talk from a Google Next session about Gemini CLI.
+- An OpenAI DevDay blog post about Codex CLI release.
+
+Use when the claim is about vendor intent, a ship date, or a feature
+preview that may not yet have docs.
+
+### T3-practitioner
+
+Respected community writing with a durable argument the author has
+defended over time. The author is not the vendor; the writing's
+authority comes from the argument's staying power.
+
+Examples:
+- Gwern Branwen on sidenote UX (`gwern.net/sidenote`) — decade-defended
+  argument.
+- Edward Tufte's design books — foundational, long-defended typography
+  principles.
+- Specific practitioner posts where the author has repeatedly revisited
+  and defended the argument.
+
+Use when citing a pattern, principle, or methodology that the vendor
+hasn't formally documented but that a serious community author has
+argued over time.
+
+### T4-conjecture
+
+Blog posts, tweets, unverified claims. Use as pointers to investigate
+rather than as authority.
+
+Examples:
+- A tweet claiming a tool does X (without a linked authoritative source).
+- A blog post describing a workaround that worked once.
+- A Reddit thread with consensus but no authoritative confirmation.
+
+Use sparingly. If a T4 source is load-bearing for a claim, either
+elevate the claim (find a T1-T3 source) or drop the claim.
+
+## Tier is not a judgment of the author
+
+A brilliant tweet is T4 until someone does the work to elevate it;
+a bland vendor page is T1 because the vendor is the definitive source
+for their own tool's behavior.
+
+This is important. The tier reflects the relationship between the
+source and the claim it supports. A practitioner's blog post *about
+Claude Code's behavior* is T3 (or T4); the same practitioner's blog
+post *about their own methodology for using Claude Code* could be T3
+if the methodology is original and defended.
+
+## Re-verification cadence per tier
+
+Each tier implies an audit cadence. The scaffold's quarterly audit
+workflow (post-v1.0) operationalizes this:
+
+| Tier | Re-verify cadence | Rationale |
+|------|-------------------|-----------|
+| T1-official | On major vendor release | Triggered by release, not calendar |
+| T2-release-notes | Quarterly | Release notes drift as ship dates slip |
+| T3-practitioner | Annually | Authors rarely retract; arguments evolve slowly |
+| T4-conjecture | Before citing | If the claim still matters, verify it; otherwise drop |
+
+## How the scaffold uses this
+
+- `sources/manifest.yaml` is the source-of-truth. Each entry has a
+  `tier` field validated against the `sourceTiers` enum.
+- `<Citation src="slug" />` renders a tier badge at the point of
+  citation. Readers calibrate their trust mid-sentence.
+- Appendix D (source archive) groups entries by tier descending
+  (T1 → T4). Empty tiers render honest "no entries yet" placeholders.
+- The scaffold does not automate re-verification. That's intentional:
+  the human audit is load-bearing; automating it would create a false
+  sense of security.
+
+## Authoring tips
+
+- **Over-cite rather than under-cite.** If a claim rests on external
+  evidence, cite it even if you think the evidence is obvious.
+- **Favor T1-T2 for claims about specific tools.** If a T3 practitioner
+  post is the best you have for a tool-behavior claim, note the gap;
+  the T1 source will likely appear later.
+- **A T4 citation is a research todo.** If you're citing a tweet, ask
+  yourself whether the claim belongs in a future-draft note rather than
+  a published chapter.
+- **The archive's integrity is the book's integrity.** A source whose
+  content shifted beneath a citation silently demotes the chapter that
+  cited it to an unknown state.

package/pedagogy/volatility-classes.md

@@ -0,0 +1,110 @@
+# Volatility classes
+
+Every chapter declares a `volatility` class in its frontmatter. The
+class encodes how fast the chapter's claims are expected to date. The
+freshness badge on the chapter header reads this class and computes
+"fresh" / "verify soon" / "stale" against three thresholds.
+
+## The three classes
+
+### `stable-principle` — 365-day threshold
+
+Claims that trace back to a durable principle or an argument the author
+has defended over many years. These age slowly; re-verify annually.
+
+Examples:
+- Chapters on the *shape* of agentic interaction (the session loop,
+  context as a finite resource, briefing documents as a stable pattern).
+- Chapters on pedagogy and reading methodology (how to calibrate trust
+  against source tier, how to audit your own practice).
+- Chapters whose claims would still be defensible after a major tool
+  release because they're not about any specific tool's surface.
+
+Freshness bands: fresh < 274d, verify-soon 274-365d, stale > 365d.
+
+### `architectural-pattern` — 180-day threshold
+
+Claims about cross-tool design patterns that change on major version
+releases but not minor ones. Re-verify every 6 months.
+
+Examples:
+- Chapter on subagent delegation (the *pattern* is stable; specific
+  interface names and tool signatures can shift on major releases).
+- Chapter on hooks / MCP / plugins (the pattern of "tool extends its
+  own behavior via a lifecycle event" is architectural; the specific
+  event names and payload shapes are feature-surface).
+- Chapter on automation modes (the *categorization* into interactive /
+  headless / scheduled is architectural).
+
+Freshness bands: fresh < 135d, verify-soon 135-180d, stale > 180d.
+
+### `feature-surface` — 90-day threshold
+
+Claims about specific tool features, flags, file paths, command names,
+or configuration schemas. These age fastest; re-verify quarterly.
+
+Examples:
+- Tool-specific companion appendices (Claude Code's specific flags,
+  Gemini CLI's specific file layout, Codex CLI's specific commands).
+- Chapters on pricing, hook event lists, specific env var names.
+- Any chapter where the example code contains current-release-specific
+  API calls.
+
+Freshness bands: fresh < 68d, verify-soon 68-90d, stale > 90d.
+
+## Choosing the class
+
+The dominant rule: **classify by the claim type, not by the topic.**
+
+A chapter titled "Subagents" sounds like it should be feature-surface
+(subagent interfaces change), but if the chapter argues the *pattern*
+and uses specific tool syntax only as illustration, it's an
+architectural-pattern chapter. The same chapter could be
+feature-surface if it's a concrete reference document for a specific
+tool's subagent flags.
+
+A test: *if this tool ships a major version tomorrow, what changes?*
+- Nothing conceptual → stable-principle.
+- Interfaces but not the pattern → architectural-pattern.
+- Named flags / paths / commands change → feature-surface.
+
+## Why three (not two, not five)
+
+Three classes encode distinct re-verification cadences:
+- Annual (stable-principle) — corresponds to the book's major-edition
+  cycle.
+- Semi-annual (architectural-pattern) — corresponds to tool major
+  version release cadence.
+- Quarterly (feature-surface) — corresponds to tool minor release
+  cadence.
+
+Two classes would collapse annual + semi-annual, hiding cases where a
+chapter is almost-principle-but-not-quite. Four classes would
+over-resolve and create arguments about edge cases. Three is the
+minimum that captures the essential granularity without encouraging
+bikeshedding.
+
+## How the scaffold uses this
+
+- `src/lib/freshness.ts` maps volatility to threshold. Three status
+  bands derived from % of threshold: fresh (<75%), verify-soon (75-100%),
+  stale (>100%).
+- `src/components/ChapterHeader.astro` renders a colored badge next to
+  the chapter's last-verified date (green / gold / rose).
+- `src/pages/chapters.astro` renders the same badge on every card in
+  the chapter index, so readers can assess drift across the whole book
+  at a glance.
+
+## Authoring tips
+
+- **Default to feature-surface on first publication.** You'll almost
+  always be wrong about how durable a specific claim is. Letting the
+  freshness badge age the claim down to stale is honest; pretending
+  it was stable-principle when it wasn't is a drift trap.
+- **Promote to architectural-pattern when the claim survives a major
+  release unchanged.** The promotion is evidence, not guess.
+- **Promote to stable-principle only after multiple tools have
+  adopted.** Principle-shaped claims should be defended by convergence
+  evidence, not by aspiration.
+- **Freshness is not a quality signal.** A stale feature-surface chapter
+  isn't wrong; it's old. Re-verify before demoting the chapter.

package/recipes/00-getting-started.md

@@ -0,0 +1,77 @@
+# Recipe 00 — Getting started
+
+**Profile**: any (the recipe picks one based on your answer below).
+
+**TL;DR**: Pick a profile (`academic` / `tools` / `minimal`). Set `BOOK_PROFILE` in your shell or `.env`. Edit content under `src/content/chapters/`. `npm run dev` to preview.
+
+## 1. Choose a profile
+
+The scaffold ships three profiles. `BOOK_PROFILE` is read at startup by `astro.config.mjs` and `src/content.config.ts`.
+
+| Profile | Use when | Frontmatter schema | Default callouts | Math | Bibliography |
+|---|---|---|---|---|---|
+| `academic` | Textbook, research report, lecture notes | `week`, `part`(enum), `status`(7-state) | NoteBox, Theorem family, ExampleBox … | KaTeX with 36 macros | BibTeX → `src/data/references.json` |
+| `tools` | Comparative practitioner book (multiple tools tracked) | `chapter`, `part`(numeric), `volatility`, `tools_compared`, `sources` | SkillBox, KeyIdea, Convergence, Divergence … | off | YAML manifest at `sources/manifest.yaml` |
+| `minimal` | Single-author manifesto, essays, mixed-form work | falls back to `tools` schema (pick `tools` and ignore the fields you don't use) | tools-family | off | manual references page |
+
+Most academic books pick `academic`; most "Agentic Coding" style books pick `tools`. If unsure: pick `minimal` and switch later — schemas are forgiving as long as required fields are set.
+
+## 2. Set the profile
+
+Either:
+
+```bash
+# Shell-level (one session):
+export BOOK_PROFILE=academic
+npm run dev
+
+# Or in package.json scripts:
+"dev": "BOOK_PROFILE=academic astro dev"
+
+# Or in .env (recommended for committed defaults):
+echo "BOOK_PROFILE=academic" >> .env
+```
+
+The profile is read by `import.meta.env.BOOK_PROFILE` at build time. Re-run `npm install` if you change the profile and see stale type errors.
+
+## 3. Bootstrap a new book (recommended path)
+
+```bash
+~/.claude/skills/book-scaffold-astro/create-book.sh my-book-name --profile=academic
+cd ~/Claude/my-book-name
+npm install
+npm run dev
+```
+
+That creates a GitHub repo from this template, clones to `~/Claude/`, sets `BOOK_PROFILE` in `.env`, and copies the matching `week01-hello-world.mdx` demo chapter. Visit `localhost:4321`.
+
+## 4. Customize for your book
+
+- **package.json**: set `name`, `description`, `author`, `repository`
+- **wrangler.toml**: replace `name = "your-book-name"` with your project name (hyphens only)
+- **src/components/Sidebar.astro** (top of file): edit `siteTitle` / `siteSubtitle`
+- **bibliography.bib** (academic profile): replace placeholder with your refs
+- **src/content/chapters/week01-hello-world.mdx**: replace with your first chapter (or delete and start over)
+
+## 5. Pick a chapter shape
+
+The scaffold ships two skeleton templates:
+
+- `examples/chapter-template-academic.mdx` — week-based (Overview / Theory / Examples / Reflections / Forward-map)
+- `examples/chapter-template-tools.mdx` — Koller-Friedman (Representation / Operation / Evolution)
+
+See recipe 07 for the full rationale. Copy whichever matches your profile to `src/content/chapters/` and start writing.
+
+## 6. Deploy
+
+When ready, follow `recipes/05-deploy-cloudflare.md` to push to Cloudflare Workers + Static Assets. URL: `https://<book-name>.<account>.workers.dev` after first deploy.
+
+## What next
+
+- **Adding math**: `recipes/01-add-math.md` (academic profile only)
+- **Adding citations**: `recipes/02-bibliography-pipeline.md`
+- **Adding figures / notebooks**: `recipes/03-asset-pipelines.md`
+- **Using components**: `recipes/04-component-library.md`
+- **Layout tweaks**: `recipes/06-mobile-first-layout.md`
+- **Custom domain**: `recipes/10-custom-domain.md`
+- **All decisions explained**: `recipes/08-decisions-ledger.md`

package/recipes/01-add-math.md

@@ -0,0 +1,71 @@
+# Recipe 01 — Add math to your book (KaTeX)
+
+**Profile**: academic (gated by `BOOK_PROFILE=academic`)
+
+**TL;DR**: Math is wired but disabled by default. Set `BOOK_PROFILE=academic` and the build adds `remark-math` + `rehype-katex` (strict mode) with the SSM macro library at `src/lib/katex-macros.ts`.
+
+## How it works
+
+The conditional integration lives at the top of `astro.config.mjs`:
+- Reads `process.env.BOOK_PROFILE ?? 'minimal'`
+- For `academic`: dynamically imports `remark-math`, `rehype-katex`, and `ssmMacros`; adds them to the markdown pipeline
+- KaTeX CSS (`katex/dist/katex.min.css`) is always loaded by `Base.astro` — academic books need it; minimal/tools books carry the cost (~60 KB) without rendering math (the CSS is inert without matching DOM)
+
+## Enable math in your book
+
+1. Set `BOOK_PROFILE=academic` at run time:
+   ```bash
+   BOOK_PROFILE=academic npm run dev      # local hot-reload
+   BOOK_PROFILE=academic npm run build    # production build
+   ```
+   Or persist it in `.env`:
+   ```
+   BOOK_PROFILE=academic
+   ```
+
+2. Author math in MDX with `$...$` (inline) and `$$...$$` (display):
+   ```mdx
+   The continuous SSM $\dot{\statevec} = \statemat \statevec$
+   has eigenvalues...
+
+   $$
+   y_t = \outputmat \statevec_t + \feedmat u_t
+   $$
+   ```
+
+3. Strict mode is on by default (`strict: 'error'` in `rehypeKatex` options). Unknown macros, malformed expressions, and unsupported AMS environments fail the build with a precise error. This is intentional — catch typos at write-time, not in production.
+
+## Macro library
+
+`src/lib/katex-macros.ts` defines 36 macros:
+- 20 SSM-specific from the post-transformers academic reference: `\statevec`, `\statemat`, `\inputmat`, `\outputmat`, `\feedmat`, `\stepsize`, `\discA`, `\discB`, `\seqlen`, `\statedim`, `\inputdim`, `\scanop`, `\elemwise`, `\monodromy`, `\floquet`, `\lyapexp`, `\jacobian`, `\ddt`, `\pderiv`, `\spectralradius`
+- 16 general math: `\R`, `\C`, `\N`, `\Z`, `\E`, `\Prob`, `\norm`, `\ip`, `\abs`, `\argmax`, `\argmin`, `\diag`, `\tr`, `\spec`, `\rank`, `\bigO`
+- 1 compatibility alias: `\bm` → `\boldsymbol` (KaTeX doesn't ship `\bm`)
+
+To extend for your book, edit `src/lib/katex-macros.ts` and add new entries to the `ssmMacros` object:
+```ts
+export const ssmMacros = {
+  // existing macros...
+  '\\mybook': '\\mathbb{B}',           // 0-arg macro
+  '\\myfunc': '\\mathrm{my}(#1)',      // 1-arg macro
+};
+```
+
+## Common gotchas
+
+- **`\bm{x}` doesn't ship with KaTeX.** The macro library aliases it to `\boldsymbol{x}` (visually identical in stix-two / Computer Modern fonts).
+- **`\psmallmatrix` not supported by KaTeX.** Convert to `\begin{pmatrix} ... \end{pmatrix}` in your MDX source.
+- **Equation auto-numbering across a document is not supported by KaTeX.** Each `$$...$$` block is independent. Use `\tag{N}` for explicit numbering, or a per-chapter remark plugin (deferred; see PROFILES_DESIGN.md §6).
+- **`{,}` (LaTeX thousands separator) breaks MDX** — MDX parses `{...}` as a JSX expression. Use `1,000` not `1{,}000`.
+- **Math inside JSX components needs care.** `<Theorem>$x^2$</Theorem>` works because remark-math runs after MDX parses JSX, but escape any `{` or `}` in arguments.
+
+## Canonical files
+
+- `astro.config.mjs:14-32` — profile branch + plugin wiring
+- `src/lib/katex-macros.ts` — full macro library (36 entries)
+- `src/layouts/Base.astro:24-30` — KaTeX CSS import
+- `package.json` — `katex ^0.16`, `remark-math ^6`, `rehype-katex ^7` deps
+
+## Reference implementation
+
+[`~/Claude/post_transformers/guides/web/`](../) at commit `111ba26` (math first wired) through `2eaef5d` (current). The reference book has 6 academic chapters using these macros and exercises every edge case the scaffold supports.

package/recipes/02-bibliography-pipeline.md

@@ -0,0 +1,82 @@
+# Recipe 02 — Bibliography pipeline (BibTeX → JSON)
+
+**Profile**: academic (primarily), but build-bib runs in all profiles and gracefully skips when no `bibliography.bib` is present.
+
+**TL;DR**: Author citations in `bibliography.bib` (BibTeX). `npm run dev` or `npm run build` runs `scripts/build-bib.mjs` which emits `src/data/references.json`. Use `<Cite key="bibkey" />` in MDX to render `Author (Year)` links to `/references#bibkey`.
+
+## How it works
+
+1. **Source**: `bibliography.bib` at scaffold root (overridable via `BOOK_BIB_PATH` env var for books that share a `.bib` with another tree — e.g. a LaTeX sibling).
+2. **Build step**: `scripts/build-bib.mjs` invokes `@citation-js/core` + `@citation-js/plugin-bibtex` to parse the `.bib` and serialize to CSL JSON. Output: `src/data/references.json`, one key per bibkey. Idempotent.
+3. **Pre-hook**: `prebuild` and `predev` both call `npm run build:bib`, so any `npm run dev` / `npm run build` invocation refreshes the JSON.
+4. **Graceful skip**: If `bibliography.bib` is absent (minimal/tools profile, or a fresh scaffold), the script emits `{}` and exits 0. No error.
+5. **Component**: `src/components/Cite.astro` imports `references.json` and renders inline `Author (Year)` styled link. Unknown bibkeys throw a build-time error (same guarantee biber gives the LaTeX build).
+6. **Bibliography page**: `src/pages/references.astro` auto-renders all entries from `references.json`, sorted by surname+year, each with an anchor `id="<bibkey>"` so `<Cite>` links resolve.
+
+## Author a citation
+
+1. Add a BibTeX entry to `bibliography.bib`:
+   ```bibtex
+   @inproceedings{gu2024mamba,
+     author    = {Gu, Albert and Dao, Tri},
+     title     = {Mamba: Linear-Time Sequence Modeling with Selective State Spaces},
+     booktitle = {COLM},
+     year      = {2024},
+     note      = {arXiv:2312.00752}
+   }
+   ```
+
+2. Reference in MDX:
+   ```mdx
+   The selective scan <Cite key="gu2024mamba" /> replaces
+   the input-independent A matrix with...
+   ```
+
+3. Run the build:
+   ```bash
+   npm run dev        # prebuild runs build:bib first, then astro dev
+   ```
+   The Cite component renders `Gu & Dao (2024)` linked to `/references#gu2024mamba`. Optional page-locator: `<Cite key="..." page="42" />`.
+
+## Override the `.bib` location
+
+If your book stores its `.bib` outside the Astro project root (e.g. shared with a LaTeX sibling at `../shared/references.bib`):
+
+```bash
+BOOK_BIB_PATH=../shared/references.bib npm run build
+```
+
+Or persist in `.env`:
+```
+BOOK_BIB_PATH=../shared/references.bib
+```
+
+The script resolves relative paths against `process.cwd()`.
+
+## .gitleaks.toml allowlist
+
+Gitleaks' generic-api-key entropy heuristic flags bibkeys like `gu2024mamba` as false-positive secrets. The scaffold's `.gitleaks.toml` allowlists:
+- `src/content/chapters/.+\.mdx` (chapter prose using `<Cite key="...">`)
+- `bibliography\.bib` (BibTeX source)
+
+For books using `BOOK_BIB_PATH` to point elsewhere, extend the allowlist with the appropriate path pattern in your fork.
+
+`src/data/references.json` (the derived artifact) is `.gitignore`d entirely — it's regenerated on every build, and gitignoring it sidesteps gitleaks scanning of high-entropy bibkey arrays.
+
+## Common gotchas
+
+- **Duplicate bibkeys** cause the script to exit 1 — `@citation-js` silently overwrites earlier entries, which biber would flag. The wrapper script surfaces duplicates so they don't silently lose entries.
+- **Unknown bibkey in `<Cite>` throws at build time** — typos surface as an Astro build error pointing at the offending key.
+- **The `note = {arXiv:...}` convention** in BibTeX entries is detected by `src/pages/references.astro` and surfaced as a direct arXiv link in the bibliography page.
+
+## Canonical files
+
+- `scripts/build-bib.mjs:35-50` — path resolution + BOOK_BIB_PATH override
+- `src/components/Cite.astro` — author formatting, bibkey lookup
+- `src/pages/references.astro` — sorted bibliography page with anchors
+- `.gitleaks.toml` — bibkey allowlist
+- `package.json` `prebuild` / `predev` — auto-runs build:bib
+
+## Reference implementation
+
+[`~/Claude/post_transformers/guides/web/`](../) uses this pipeline with a `.bib` shared between biber (LaTeX legacy) and citation-js (active MDX site). 66 entries; see commit `acdc847` for the initial wiring.