docs(reference): five diagrams

[kfox]

Last of the eight. The Programmer's Reference Guide had no figures at all, while carrying a twelve-step pipeline, a six-mode attribute story and a 64 KB memory map that are all inherently spatial. Five diagrams, one per thing prose was doing badly.

Figure	Chapter	Shows
fig-1-1-ladder	1, The Precedence Ladder	The five layers, and the rung an ensemble run inserts between the per-system file and the command line
fig-3-1-pipeline	3, From Frame to Screen	The twelve steps and the setting that enters at each, bracketed where the frame stops being full colour
fig-3-2-cells	3, The Six Display Modes	One hardware cell in each of the four picture modes, with the attribute bytes and their addresses
fig-4-1-audio	4, Two Ways Out	The DAC path against the sampler path, and what each costs the 6510
fig-5-1-memory	5, What Lands in Memory	The 64 KB during a bitmap scene: four 16 KB windows on one memory, colour RAM outside all of them

The plan listed the cells figure first and the pipeline second; they are numbered here in reading order instead, because From Frame to Screen comes first in the chapter and a caption that disagrees with its filename is a trap for the next person.

How they are drawn

A new scripts/make_reference_diagrams.py, Pillow, the vendored faces in docs/shared/fonts/ and the template's own palette — so a diagram sits in the same type and the same blue as the page around it.

• Not Typst drawings. A Typst figure is invisible on github.com, and the Markdown is the book.
• Not the guide's cv2.putText path. A Hershey stroke font next to Jost reads as a screenshot of a different document. capture_guide_figure.py's PIL path was the better model but reads a user-installed font, which makes the output depend on the machine that drew it.
• Committed, like the generated appendices and for the same reason: the release renders the books with uv run --no-project and cannot regenerate anything that imports c64cast. make reference-figures redraws them.

Two things about the isometric map worth keeping:

• Each bank is a solid slab with the used regions coloured as sections of the bar. Drawn the other way round — extruded blocks standing on a flat plate — every region reads as an L hovering over nothing.
• The banks are spaced further apart than a slab's own projected height ((len + depth)·sin30 + h), because a rhombus overlaps a copy of itself shifted up by any less than that. At a smaller rise every bank crossed the one below it and the whole thing came out an Escher staircase.

Type is sized from where the figure lands rather than from how it looks on screen: the template places a figure at 78% of a 4.60in measure, so 1500px across is ~420dpi and a 7pt label is 40px. A must_fit() guard refuses to draw a line that would run off its box — a figure is looked at once, and a silently clipped label is exactly the kind of thing that ships.

Also

• pillow named in the dev group. It already resolved transitively through matplotlib, but this script imports it directly.
• make reference-figures, beside guide-figures, in .PHONY and in help.
• docs/reference/img/README.md shot list, generated by the script, as the guide's img/ has.
• The reference README gains a section on the diagrams.

Tests

tests/test_reference_diagrams.py holds the script's copy of the palette to template.typ (the same trick test_book_build.py uses for the duplicated book basenames), checks every figure is committed at the size the script draws it, that each is referenced by a chapter and that none is orphaned, and that the shot list is fresh. Pixels are deliberately not compared: Pillow's rasteriser is not stable across versions, so a byte-for-byte drift test would fail on an unrelated dependency bump.

test_book_build.py::test_every_referenced_figure_exists picks these up for free.

Verification

All offline, no hardware.

• make check — lint, mypy --strict + pyright, 3336 tests, green.
• make reference-appendices && git diff --exit-code docs/ — no drift.
• --check on all three books, then make books.
• Read the rendered pages: each figure sits with the text it illustrates (pp. 8, 33, 36, 45, 60), the type is within a step of the body size rather than the half-size it started at, and the Performance Card is still two pages.