kfox · kfox · Aug 4, 2026 · Aug 4, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -116,6 +116,16 @@ the version and stamps it with the date.
   mean. A key is listed bare, and again qualified with its section where two
   sections share the name, which is the rule the book's own Notation section
   states. Every locator is a link that works on github.com and in the PDF alike.
+- **The Programmer's Reference Guide is illustrated.** Five diagrams, for the
+  five things in it that are spatial and were being carried entirely by prose:
+  the precedence ladder with the extra rung an ensemble inserts, the twelve-step
+  display pipeline with the setting that enters at each step, one hardware cell
+  in each of the four picture modes with the bytes that colour it, the DAC path
+  against the sampler path with what each costs the 6510, and the 64 KB during a
+  bitmap scene — the VIC's banks drawn as what they are, four 16 KB windows on
+  one memory, with colour RAM outside all of them. They are drawn by
+  `scripts/make_reference_diagrams.py` in the books' own faces and palette, and
+  committed; `make reference-figures` redraws them.
 - **The books' symbols no longer depend on the machine that built them.** Jost
   has no ✓ and no →, and Typst was filling them from whatever was installed — so
   the compatibility matrix was set in a heavy upright check locally and a thin

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -87,7 +87,9 @@ User's Guide, read in order), [docs/reference/](docs/reference/README.md) (the
 Programmer's Reference Guide — seven chapters over ten appendices and an index,
 of which appendices A–I and the whole index are generated by
 [scripts/gen_reference_appendices.py](scripts/gen_reference_appendices.py)
-and regenerated with `make reference-appendices`), and
+and regenerated with `make reference-appendices`; its five diagrams are drawn by
+[scripts/make_reference_diagrams.py](scripts/make_reference_diagrams.py) with
+`make reference-figures`), and
 [docs/card/](docs/card/README.md) (the two-page Performance Card, whose live-target
 table comes from that same pass). `make books` renders all three; each book's
 README says what belongs in it. The old single-file usage document is gone — its

diff --git a/Makefile b/Makefile
@@ -30,7 +30,8 @@ SYNC := $(if $(CI),,sync)
 .DEFAULT_GOAL := help
 
 .PHONY: help sync lint fmt test coverage typecheck doctor bench check clean schema \
-        guide reference card books guide-figures reference-appendices
+        guide reference card books guide-figures reference-figures \
+        reference-appendices
 
 # Books (docs/<book>/*.md + book.toml) are rendered by Typst, which is an
 # external binary rather than a Python package. The two faces (Jost*,
@@ -88,6 +89,7 @@ help:
 	@echo "  card       render docs/card/*.md to the Performance Card PDF (needs typst)"
 	@echo "  books      render every book"
 	@echo "  guide-figures  redraw the guide's placeholder figures"
+	@echo "  reference-figures  redraw the reference guide's diagrams"
 	@echo "  reference-appendices  regenerate the reference guide's appendices A-I + index"
 	@echo "  check      lint + typecheck + test"
 	@echo "  clean      remove build artifacts"
@@ -138,6 +140,12 @@ schema:
 guide-figures: $(SYNC)
 	$(PY) scripts/make_guide_figures.py
 
+# Redraw the reference guide's five diagrams. Unlike the guide's figures these
+# are drawings rather than captures, so there is nothing to preserve: the
+# script is the source and the PNGs are its committed output.
+reference-figures: $(SYNC)
+	$(PY) scripts/make_reference_diagrams.py
+
 guide: $(SYNC)
 	$(call render-book,$(GUIDE_DIR),$(GUIDE_BOOK))
 

diff --git a/docs/reference/02-config-rules.md b/docs/reference/02-config-rules.md
@@ -297,6 +297,8 @@ below it:
 | 4 | Command-line flags |
 | 5 | The environment (`C64CAST_DMA_PASSWORD`) |
 
+![Figure 1-1. The five layers, and the extra rung an ensemble run inserts between the per-system file and the command line.](img/fig-1-1-ladder.png)
+
 **The default** is what Appendix A prints. It is chosen to be what most runs
 want rather than what does least: audio is on, the display pipeline's quality
 stages are on, and a scene with no `display` gets the mode that suits its kind

diff --git a/docs/reference/04-display-pipeline.md b/docs/reference/04-display-pipeline.md
@@ -73,6 +73,8 @@ The on-screen display for live tuning and the `--frame-numbers` debug overlay
 are drawn at step 3, before quantisation, which is why they appear on every
 display mode without either of them knowing what a display mode is.
 
+![Figure 3-1. The twelve steps, and where each setting enters. Everything above step 8 still has the frame in full colour.](img/fig-3-1-pipeline.png)
+
 ## The Six Display Modes
 
 A display mode is a *choice about the VIC-II*, and each one trades resolution
@@ -154,6 +156,8 @@ slots are filled:
 background colour stops wasting a slot on it, and a corner of the frame stops
 being forced into a palette chosen for the subject in the middle.
 
+![Figure 3-2. One hardware cell in each of the four modes that draw a picture, with the bytes that colour it and where they live.](img/fig-3-2-cells.png)
+
 ## Quantising a Cell
 
 Three settings decide what a cell ends up looking like, and they are

diff --git a/docs/reference/05-sound-and-music.md b/docs/reference/05-sound-and-music.md
@@ -31,6 +31,8 @@ get is the single most audible choice in the program.
 one and the DAC everywhere else, and `"dac"` forces the lo-fi path. Microphone
 and webcam audio always take the DAC, on every machine.
 
+![Figure 4-1. The two paths out of the host, and what each one costs the 6510.](img/fig-4-1-audio.png)
+
 ### The 4-Bit DAC
 
 The SID's master volume register is four bits wide. Write a sample value into

diff --git a/docs/reference/06-under-the-hood.md b/docs/reference/06-under-the-hood.md
@@ -87,6 +87,8 @@ every chip's scope, but only the first is audible.
 c64cast writes into a real Commodore's 64 KB, alongside a running BASIC program
 and the kernal. What follows is what it claims, and why.
 
+![Figure 5-1. The 64 KB during a bitmap scene. Each bank is one 16 KB window on the same memory; small regions are drawn at a minimum width, so the widths are not to scale.](img/fig-5-1-memory.png)
+
 ### The Picture
 
 | Address | Contents |

diff --git a/docs/reference/README.md b/docs/reference/README.md
@@ -82,6 +82,28 @@ and the description in all the measure that is left. `identity()` and
 [`template.typ`](../shared/template.typ), which is where every other
 measurement in the books lives.
 
+## The diagrams
+
+Five figures, in [`img/`](img/README.md), drawn by
+[`scripts/make_reference_diagrams.py`](../../scripts/make_reference_diagrams.py):
+
+```bash
+make reference-figures
+```
+
+They are drawings rather than screen captures — the User's Guide's `img/` is
+the other kind — and they are deliberately not Typst figures, because a Typst
+drawing is invisible on github.com and the Markdown is the book. Pillow draws
+them in the two vendored faces and the template's palette, so a diagram sits in
+the same type and the same blue as the page around it, and the output is
+committed for the same reason the appendices are: the release renders the PDFs
+without the project environment.
+
+`tests/test_reference_diagrams.py` fails if the script's copy of the palette
+drifts from [`template.typ`](../shared/template.typ), if a committed PNG is no
+longer the size the script draws, or if a figure is never referenced by a
+chapter.
+
 ## How the build works
 
 Same pipeline as every book: see [`docs/shared/`](../shared/README.md) for the

diff --git a/docs/reference/img/README.md b/docs/reference/img/README.md
@@ -0,0 +1,26 @@
+# Reference guide diagrams
+
+Every image here is drawn by
+[`scripts/make_reference_diagrams.py`](../../../scripts/make_reference_diagrams.py)
+and committed, because the release renders the books with
+`uv run --no-project` and cannot regenerate anything that imports
+`c64cast`. Redraw them with `make reference-figures` after changing a
+diagram, and commit the result.
+
+These are drawings rather than captures — the guide's `img/` is the
+other kind. They are set in the books' own two faces from
+`docs/shared/fonts/` and use the template's palette, except inside the
+cell diagram, whose subject is which C64 colour each attribute byte
+holds.
+
+| Figure | Chapter and section | Shows |
+|---|---|---|
+| `fig-1-1-ladder.png` | 1 · The Precedence Ladder | The five layers, and the rung an ensemble inserts |
+| `fig-3-1-pipeline.png` | 3 · From Frame to Screen | The twelve steps, and where each setting enters |
+| `fig-3-2-cells.png` | 3 · The Six Display Modes | One hardware cell per mode, with the bytes that colour it |
+| `fig-4-1-audio.png` | 4 · Two Ways Out | The DAC path against the sampler path, and what each costs |
+| `fig-5-1-memory.png` | 5 · What Lands in Memory | The 64 KB during a bitmap scene, banks stacked |
+
+The memory map is schematic in one respect: a region the size of an
+interrupt handler is a fraction of a pixel wide at 16 KB to the plate,
+so every region is drawn at a minimum width.
diff --git a/docs/reference/img/fig-1-1-ladder.png b/docs/reference/img/fig-1-1-ladder.png
diff --git a/docs/reference/img/fig-3-1-pipeline.png b/docs/reference/img/fig-3-1-pipeline.png
diff --git a/docs/reference/img/fig-3-2-cells.png b/docs/reference/img/fig-3-2-cells.png
diff --git a/docs/reference/img/fig-4-1-audio.png b/docs/reference/img/fig-4-1-audio.png
diff --git a/docs/reference/img/fig-5-1-memory.png b/docs/reference/img/fig-5-1-memory.png
diff --git a/pyproject.toml b/pyproject.toml
@@ -189,6 +189,10 @@ dev = [
     # declares it optional, so the `control` extra doesn't pull it; without it
     # those 13 tests skip. Dev-only; the runtime never imports it.
     "httpx==0.28.1",
+    # Draws the reference guide's diagrams in scripts/make_reference_diagrams.py.
+    # Already resolved transitively through matplotlib, but named here because
+    # that script imports it directly. Dev-only; the runtime never imports it.
+    "pillow==12.3.0",
     # JUnit XML reporter for the unittest suite (a unittest.TestRunner
     # subclass, NOT a different test framework). CI runs the suite through
     # `python -m xmlrunner discover` so Codecov Test Analytics can ingest the