Rewrite the two game tutorials as instructions rather than commentary

Chapters 17 and 18 read as a code review of a finished listing: they explained
why each decision had been made, walked through the project's own history, and
led with what had once been broken. A reader who wanted to build the game got
the reasoning and had to reconstruct the program.

Both are now step-by-step. Each opens with a picture of the finished game and a
bullet list of the steps, each bullet is a section, and each section states its
goal, shows the code, and says how to check it. Chapter 17 is sixteen steps and
Chapter 18 is thirteen, and the last of each is the assembly: the order of the
file, the full declaration block, and the routines the earlier steps referred to.
Project history is gone -- it belongs in Chapter 14 and in git -- and where a
listing has to do something awkward, the tutorial shows how first and names the
`TODO.md` item that will make it unnecessary second.

**Three defects had no entry anywhere**, which the rewrite found by trying to
state each rule as a rule. §6 item 35: `a - b + c` computes `a - (b + c)`,
because `subtraction()` sits above `addition()` as its own precedence level and
the inner loop eats the `+`. Item 36: only one unparenthesised `AND` or `OR` is
matched, which is item 12's `if`-where-`while` on the one operator pair item 12
did not reach. Item 37: a `GOTO` out of a `FOR` or a `DO` leaks the loop's scope,
so a main loop written that way stops on the thirty-second lost life -- which is
why both games are built out of `LABEL` and `GOTO`, and it is a workaround rather
than a preference. Chapter 3 gains the identifier rule the third trial ran into:
there is no underscore in a name, and the error says `UNKNOWN TOKEN _`.

**`tools/screenshot.c` learned to draw the text layer**, behind a new `text=1`
fence attribute, because Chapter 17's game is characters in the grid and a figure
without that layer is two sprites on black. It opens the bundled font at the size
the standalone frontend uses, so a figure's cell size is the reader's cell size,
and it uses the akgl sink alone rather than a tee so the program's output lands in
the picture instead of on the stdout the caller reads to decide a figure failed.
Both new figures -- `breakout-game.png` and `breakout-game-artwork.png` -- are
generated from listings in the chapters like every other one.

Verified by handing each chapter, alone, to an agent on a much smaller model and
telling it to build the game from the tutorial text with the `examples/` tree off
limits. The first pass scored 3.5 and 3 out of 10 and named what was missing:
routines referred to but never shown, the third level layout, the sprite `DATA`,
the font table, edits to earlier routines that were never marked as edits. Those
are now in. The second pass built a 658-line Chapter 17 game that plays itself
for ninety seconds with the score at 1890 and no error line, and the third built
a 1053-line Chapter 18 game with 61 labels, no invented routines, no gaps found,
and forty seconds clean. 9/10 and 8/10.

One real bug in the new prose, caught in review: Chapter 18's `HITBAR` did not
set the `HIT#` that `BALLPADDLE` reads to decide whether the paddle already
caught the ball. Both suites green in both configurations, `docs_examples` and
`docs_screenshots --check` pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL

docs/03-the-language.md

@@ -21,6 +21,11 @@ a character that says what it holds:
 There is no such thing as a variable with no suffix. A bare name is a **label** — see
 Chapter 4 — so `GOTO DONE` and `LABEL DONE` are how the two meet.
 
+**A name is letters and digits and nothing else.** There is no underscore: `HIGH_SCORE#`
+does not scan, and what it reports is `UNKNOWN TOKEN _` rather than anything about naming,
+so it is worth knowing before you meet it. Run words together — `HIGHSCORE#` — or shorten
+them, which is what the listings in this guide do.
+
 `@` is the odd one out: it says "a structure" without saying *which*, so a structure
 variable has to be declared with `DIM E@ AS ENEMY` before it can be used. That is
 **[Chapter 16](16-structures.md)**, along with records, pointers and how a host shares its

docs/06-graphics.md

@@ -250,5 +250,5 @@ lines and then presents, and presenting throws the drawing buffer away — so a
 drawing verbs longer than one batch is torn rather than merely transient, and an
 `SSHAPE` at the end of it captures only the part issued since the present. Watching
 `TI#` change is how a program finds the boundary; Chapter 13 has the measured numbers and
-[Chapter 18](18-tutorial-breakout-artwork.md#step-4-find-the-frame-boundary) has a
+[Chapter 18](18-tutorial-breakout-artwork.md#step-5-find-the-frame-boundary) has a
 routine that uses them.

docs/13-differences.md

@@ -153,7 +153,7 @@ interpreter's error code, which bears no relation to a Commodore error number. P
   256 lines a batch: after synchronising to a jiffy edge, 220 lines of drawing survive a
   capture and 250 do not. The only way a program can see the boundary is to watch `TI#`,
   which is refreshed once per batch — so the step on which it changes is the first step
-  of one. [Chapter 18](18-tutorial-breakout-artwork.md#step-4-find-the-frame-boundary)
+  of one. [Chapter 18](18-tutorial-breakout-artwork.md#step-5-find-the-frame-boundary)
   builds a pacing routine out of exactly that.
 - **`CHAR` ignores its colour argument** and needs a text device with a cursor.
 

docs/14-architecture.md

@@ -181,7 +181,7 @@ A script cannot read the budget, but it can *see* it: `akbasic_runtime_settime()
 called once per frame by the host, so `TI#` changes on the first step of a batch and
 nowhere else. Spinning until it changes is the only frame synchronisation this dialect
 has, and it is what
-[Chapter 18](18-tutorial-breakout-artwork.md#step-4-find-the-frame-boundary) is built on.
+[Chapter 18](18-tutorial-breakout-artwork.md#step-5-find-the-frame-boundary) is built on.
 A host that gives the interpreter a larger budget makes more drawing fit; one that never
 calls `settime()` takes the synchronisation away entirely.
 

docs/README.md

@@ -15,7 +15,8 @@ embedding it, debugging it or changing it.
 
 **[Chapters 17](17-tutorial-breakout.md)** and **[18](18-tutorial-breakout-artwork.md)**
 are tutorials rather than reference: they build one complete game twice, two different
-ways, and are where the rules that a real program runs into are collected.
+ways, in numbered steps you can type in one at a time. Start with 17 — it needs nothing
+but the earlier chapters, and 18 assumes it.
 
 ## Chapters
 
@@ -37,8 +38,8 @@ ways, and are where the rules that a real program runs into are collected.
 | **[14. Architecture](14-architecture.md)** | How the interpreter is put together, how to debug it, how to change it |
 | **[15. Error codes](15-error-codes.md)** | Appendix: every value `ER#` can hold and every error line the interpreter prints |
 | **[16. Structures](16-structures.md)** | `TYPE`, records, strict pointers, and sharing a C struct with an embedding host |
-| **[17. Tutorial: Breakout](17-tutorial-breakout.md)** | Build a whole game out of the text grid and two `DATA` sprites, a step at a time |
-| **[18. Tutorial: Breakout with artwork](18-tutorial-breakout-artwork.md)** | Build it again out of loaded artwork, powerups and a drawn HUD |
+| **[17. Tutorial: Breakout](17-tutorial-breakout.md)** | Build a whole game out of the text grid and two `DATA` sprites, in sixteen steps |
+| **[18. Tutorial: Breakout with artwork](18-tutorial-breakout-artwork.md)** | Build it again out of loaded artwork, powerups and a drawn colour HUD, in thirteen |
 
 ## The shortest possible start
 

docs/images/README.md

@@ -17,5 +17,6 @@ test will fail on it, because it re-renders every figure and compares byte for b
 
 The tag that ties a figure to its listing is `screenshot=NAME` in the fence info string,
 and `MAINTENANCE.md` documents it along with `size=WxH` for a figure that needs a surface
-other than 320 by 200. A tagged block with no image here fails `docs_examples` in both
-build configurations, so a figure cannot be added to a chapter and then forgotten.
+other than 320 by 200, and `text=1` for one whose subject is the text grid rather than a
+drawing. A tagged block with no image here fails `docs_examples` in both build
+configurations, so a figure cannot be added to a chapter and then forgotten.