Write the usage guide as thirteen chapters in docs/

Organised the way the C128 Programmer's Reference Guide is: the language
first, then each hardware area, then the reference sections. One markdown
file per chapter.

The verb and function references are generated from the interpreter's own
dispatch table, with an assertion that every row is described, so they cannot
drift out of step with what the program accepts. 98 verbs and 30 functions.

Every example was run before it was written down, which caught three claims
that were wrong: a whole FOR loop on one line prints nothing rather than
looping once, MID and INSTR count from zero where a C128 counts from one, and
a multi-line DEF returns a value the caller has to assign away.

Chapter 13 is the list a BASIC 7.0 programmer needs -- roughly sixty
documented differences, including the two known FOR defects and the fact that
drawing does not survive a frame.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/12-function-reference.md

@@ -0,0 +1,56 @@
+# 12. Function reference
+
+Every function, alphabetically, generated from the interpreter's own dispatch table.
+
+A function is called with parentheses and yields a value; it cannot stand alone as a
+statement. The arity column is how many arguments it takes — the interpreter checks it,
+so a call with the wrong number is a syntax error rather than a surprise.
+
+| Function | Args | Form | What it gives |
+|---|---|---|---|
+| `ABS` | 1 | `ABS(n)` | The absolute value of an integer or float. |
+| `ATN` | 1 | `ATN(n)` | Arctangent, in radians. |
+| `BUMP` | 1 | `BUMP(1)` | Which sprites have collided, as a bitmask. **Reading clears it.** |
+| `CHR` | 1 | `CHR(n)` | The character for a Unicode code point, as a string. |
+| `COS` | 1 | `COS(n)` | Cosine, in radians. |
+| `ERR` | 1 | `ERR(n)` | The message text for an error code. `ERR(ER#)` names the last one. |
+| `HEX` | 1 | `HEX(n)` | An integer as hexadecimal text. |
+| `INSTR` | 2 | `INSTR(A$, B$)` | Where `B$` appears in `A$`, counting from zero, or -1. |
+| `LEFT` | 2 | `LEFT(A$, n)` | The leftmost `n` characters. Clamped to the string's length. |
+| `LEN` | 1 | `LEN(x)` | The length of a string, or the element count of an array. |
+| `LOG` | 1 | `LOG(n)` | Natural logarithm. |
+| `MID` | 3 | `MID(A$, start, len)` | A substring, counting from zero. |
+| `MOD` | 2 | `MOD(a, b)` | The remainder of `a / b`. Integers only. |
+| `PEEK` | 1 | `PEEK(addr)` | The byte at a real address. |
+| `POINTER` | 1 | `POINTER(V)` | The address of a variable's value. |
+| `POINTERVAR` | 1 | `POINTERVAR(V)` | The address of the variable structure itself, metadata included. |
+| `RAD` | 1 | `RAD(n)` | Degrees converted to radians. |
+| `RIGHT` | 2 | `RIGHT(A$, n)` | The rightmost `n` characters. Clamped. |
+| `RSPCOLOR` | 1 | `RSPCOLOR(n)` | One of `SPRCOLOR`'s two shared registers, 1 or 2. |
+| `RSPPOS` | 2 | `RSPPOS(n, f)` | A sprite's x (0), y (1) or speed (2). |
+| `RSPRITE` | 2 | `RSPRITE(n, f)` | One of a sprite's `SPRITE` settings, in `SPRITE`'s argument order. |
+| `SGN` | 1 | `SGN(n)` | -1, 0 or 1 according to the sign. |
+| `SHL` | 2 | `SHL(n, bits)` | Shift left. |
+| `SHR` | 2 | `SHR(n, bits)` | Shift right. |
+| `SIN` | 1 | `SIN(n)` | Sine, in radians. |
+| `SPC` | 1 | `SPC(n)` | A string of `n` spaces. |
+| `STR` | 1 | `STR(n)` | A number as a string. |
+| `TAN` | 1 | `TAN(n)` | Tangent, in radians. |
+| `VAL` | 1 | `VAL(A$)` | A string as a number. Refuses text that is not one. |
+| `XOR` | 2 | `XOR(a, b)` | Bitwise exclusive or. |
+
+## Reserved variables
+
+Two things a C128 exposes as bare names are ordinary global variables here, because
+this dialect has no variable name without a type suffix:
+
+| Here | On a C128 | Holds |
+|---|---|---|
+| `ER#` | `ER` | the code of the last trapped error |
+| `EL#` | `EL` | the line it happened on |
+| `TI#` | `TI` | jiffies — sixtieths of a second — since the host's clock started |
+| `TI$` | `TI$` | the same time as `HHMMSS` |
+
+`ER#` carries this interpreter's error code, not a Commodore error number. There is no
+correspondence to reproduce — the errors raised here are not the errors a 1985 ROM
+raised — so print `ERR(ER#)` rather than the number.