How this book is designed

This chapter is the reader’s guide to the book’s structure — and a working example of every component you’ll meet, exercised through the routing pipeline. If something on this page looks wrong on your device, it’s a bug in the scaffold, not in the chapter.

The book uses a uniform three-section decomposition for every chapter, a bounded vocabulary of typed callouts, always-visible sidenotes with a mobile reflow, and visible freshness stamps. The rest of this chapter explains each of those.

Representation

Every chapter has the same skeleton: Representation, Operation, Evolution. The idea is borrowed from Koller and Friedman’s Probabilistic Graphical Models — uniform chapter shape defends against drift. When every chapter looks the same structurally, a reader learns the skeleton once and reads fluently. Drift into feature documentation becomes visible because it won’t fit the shape.

The Evolution cornerstone is load-bearing: it embeds the book’s meta-goal (tracking how practices change) into every chapter, not just a methodology appendix. A convergence across tools signals a stable principle; a divergence signals open design space.

Operation

Each chapter uses a small vocabulary of typed callouts. Six are visual pedagogy blocks:

Two are comparative blocks, used in the Evolution section to surface cross-tool patterns:

Sidenotes and citations

Sidenotes live in the right margin on desktop and reflow as inline asides on mobile. Gwern’s principle applies: sidenotes should display by default, and any reader effort defeats the point. So no tap-to-reveal on mobile — just a visually distinct inline block. Citations use the same mechanism but resolve a slug from the source manifest, rendering a tier badge and links to the original and its Perma.cc archive: Tufte CSS · Dave Liepmann (2014)T3-practitioner original

Code blocks use Shiki in CSS-variables mode. The colors map to the same Warm Tol palette as the callouts, so code and prose share one visual language:

// Estimate the warm-cache cost of a CLAUDE.md pass.
export function budgetFor(path: string, maxTokens = 40_000): number {
  const text = Deno.readTextFileSync(path);
  const tokens = estimateTokens(text);
  if (tokens > maxTokens) {
    throw new Error(`${path} exceeds budget: ${tokens}/${maxTokens}`);
  }
  return tokens;
}

Tables are used for tool comparisons in the Operation section, as shorthand for “here’s how each tool does this”:

Evolution

The book itself evolves over time. Three mechanisms make that visible:

Freshness stamps. The chapter header shows Last verified 2026-04-17. When a reader sees an older date on a volatile claim, they know to double-check against current tool docs before relying on it.

Version branches (planned). When multi-version deploys land, each published version will stay live at its own URL (/v1.0/, /v1.1/) and a version selector in the header will let readers switch — so practices documented in one version don’t disappear when the next ships; they become historical reference. (Not yet live — the header’s version selector currently shows placeholder entries.)

The convergence dashboard. A dedicated page reads from changelog/tools/*.yaml + changelog/patterns.yaml and renders a timeline: when did each tool adopt each pattern? Patterns that all three have landed become Convergence boxes in chapters. See the Divergence box above for an open example: context window size has diverged sharply. When or if it converges is itself evolving data.

How to read stale chapters

The volatility badge in the header signals how likely a chapter is to date:

• stable-principle — rarely changes. Read anytime.
• architectural-pattern — revises on major tool versions. Glance at the last-verified date.
• feature-surface — changes with minor versions. Check the date, and cross-reference against current tool release notes.

A note on the scaffold

This book renders on @brandon_m_behring/book-scaffold-astro — the chapter layout, typed callouts, sidenotes, code theme, and freshness stamps all come from there, separable from any one book’s content. If a component looks wrong on your device, that’s a scaffold bug, not a chapter error.