How this book is designed

This chapter is a reader’s guide to the book’s structure — and, during Stage 0 of the scaffold build, a working example that exercises every component 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. Every published version stays live at its own URL (/v1.0/, /v1.1/). Readers can browse history; a version selector in the header lets them switch. Practices documented in v1.0 don’t disappear when v1.1 ships — they become historical reference.

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.

Meta-status

This chapter exists as the Stage 0 demo — a working instance of every component through the full routing pipeline. It will be replaced (or retitled and demoted to an appendix) when Stage 1 ports the first real chapter, Context as Currency.

If you’re reading this in a deployed version of the scaffold, the scaffold is working. The scaffold is separable from any one book — see the plan file at ~/.claude/plans/i-believe-this-project-generic-sphinx.md for the staged roadmap.