readme: trim the fluff, loosen the tone

1 files changed, 166 insertions, 192 deletions

diff --git a/README.md b/README.md
index 8ce3002..1bb1369 100644
--- a/README.md
+++ b/README.md
@@ -1,155 +1,141 @@
-# sl0pboy — a Game Boy Color emulator in C, rendered to the terminal
+# sl0pboy — a Game Boy Color emulator that lives in your terminal
 
-A from-scratch Game Boy / Game Boy Color emulator written in plain C11. It
-renders graphics directly to the terminal using 24-bit (truecolor) ANSI escape
-codes and the Unicode upper-half-block trick (`▀`): each character cell packs
-two vertical pixels (foreground = top pixel, background = bottom pixel),
-giving a 160×144 GB screen in 160×72 terminal cells.
+A from-scratch GB / GBC emulator in plain C11 that paints straight to the
+terminal — no window, no GPU, just truecolor ANSI and the upper-half-block
+trick (`▀`): every character cell = two stacked pixels (fg on top, bg on
+bottom). That squeezes the 160×144 screen into 160×72 cells.
 
-To keep terminal load low, output is minimized two ways: SGR color escapes
-are only emitted when the fg/bg changes, and **inter-frame diffing** redraws
-only the cells that changed since the previous frame (jumping over unchanged
-runs with `ESC[row;colH`). A fully static screen writes nothing after the
-first frame; on the acid2 screens this cut output from ~7.1 MB to ~65 KB
-over 2 s (~108×). Terminal resize (`SIGWINCH`) triggers a full repaint.
+To keep your terminal from crying, it only emits SGR escapes when a color
+changes, and it **diffs frames** — only redrawing cells that moved (skipping
+unchanged runs with `ESC[row;colH`). A static screen writes *nothing* after
+frame one; on acid2 that dropped output from ~7.1 MB to ~65 KB over 2 s (≈108×).
+Resize the terminal and `SIGWINCH` triggers a full repaint.
 
 ## Build & run
 
 ```sh
 make
-./build/sl0pboy path/to/rom.gb             # interactive (ROM is the final argument)
-./build/sl0pboy --test 30 rom.gb           # run 30s, log serial to stderr (test roms)
-./build/sl0pboy --shot 60 out.ppm rom.gb   # run 60 frames, dump a PPM screenshot
-./build/sl0pboy --sixel 3 rom.gb           # sixel graphics output at 3x zoom
-./build/sl0pboy --sixel 3 --chrome rom.gb  # ...wrapped in a Game Boy body/frame
-./build/sl0pboy --bios rom.gb              # boot through the BIOS before the game
-./build/sl0pboy --sock rom.gb              # open a control/debug socket (/tmp/sl0pboy.sock)
-./build/sl0pboy --headless rom.gb          # no video; serial <-> stdio (OS console)
-./build/sl0pboy --help                     # full option list
+./build/sl0pboy path/to/rom.gb             # just play it (ROM goes last)
+./build/sl0pboy --test 30 rom.gb           # run 30s, serial -> stderr (test roms)
+./build/sl0pboy --shot 60 out.ppm rom.gb   # 60 frames in, dump a PPM
+./build/sl0pboy --sixel 3 rom.gb           # real pixels via sixel, 3x zoom
+./build/sl0pboy --sixel 3 --chrome rom.gb  # ...in a lil' handheld body
+./build/sl0pboy --bios rom.gb              # boot through the real BIOS first
+./build/sl0pboy --sock rom.gb              # control/debug socket (/tmp/sl0pboy.sock)
+./build/sl0pboy --headless rom.gb          # no video, serial <-> stdio
+./build/sl0pboy --help                     # the whole menu
 ```
 
-### Boot ROM / BIOS (`--bios`)
+Needs a truecolor terminal (`COLORTERM=truecolor`) at least 160 columns wide.
 
-By default the emulator skips the boot ROM and starts the cartridge directly
-with the documented post-boot register state. Pass `--bios [path]` to instead
-run a real boot ROM first, so you get the authentic power-on animation (the
-Nintendo logo drop, and on a CGB the color splash + chime) before control is
-handed to the game:
+## Boot ROM / BIOS (`--bios`)
+
+By default we skip the boot ROM and drop you into the cartridge with the
+documented post-boot register state. Want the real power-on show — the Nintendo
+logo drop, the CGB color splash + chime? Pass `--bios [path]`:
 
 ```sh
-./build/sl0pboy --bios roms/pky.gbc                 # defaults to bios/gbc_bios.bin
+./build/sl0pboy --bios roms/pky.gbc                    # defaults to bios/gbc_bios.bin
 ./build/sl0pboy --bios path/to/boot.bin roms/pky.gbc
-./build/sl0pboy --bios --sixel 3 --chrome roms/pky.gbc   # boot inside the shell
+./build/sl0pboy --bios --sixel 3 --chrome roms/pky.gbc # boot inside the shell
 ```
 
-The boot ROM is mapped over low memory (with the CGB header hole at
-`0x0100-0x01FF` where the cartridge shows through) and unmaps itself when the
-ROM writes `0xFF50`, exactly like hardware. A 256-byte image boots as DMG; a
-2304-byte image (like the bundled `bios/gbc_bios.bin`) boots as CGB — which
-also colorizes plain DMG games via the boot ROM's compatibility palette.
+It maps the boot ROM over low memory (with the CGB header hole at
+`0x0100-0x01FF` where the cart peeks through) and unmaps itself when the ROM
+pokes `0xFF50`, just like hardware. 256 bytes → boots as DMG; 2304 bytes (like
+the bundled `bios/gbc_bios.bin`) → boots as CGB, which also colorizes plain DMG
+games via the boot ROM's compatibility palette.
 
-### Headless serial console (`--headless`)
+## Headless serial console (`--headless`)
 
-For bring-up and debugging of an OS/monitor running on the emulated Game Boy,
-`--headless` disables all rendering and the terminal UI and instead wires the
-**serial port straight to stdio**:
+Bringing up an OS/monitor on the emulated Game Boy? `--headless` kills all
+rendering and wires the **serial port straight to stdio**:
 
-- transmitted bytes (the GB writing `SB`/`SC` with the internal clock) go to **stdout**
-- **stdin** is fed back as the received byte on each transfer (non-blocking;
-  `0xFF` open-bus when nothing is waiting)
+- bytes the GB transmits (`SB`/`SC` w/ internal clock) → **stdout**
+- **stdin** feeds back as the received byte each transfer (non-blocking; `0xFF`
+  open-bus when nothing's waiting)
 
-Emulation is paced to native speed by default; add `--uncapped` to run flat out.
-Because it's plain stdio it pipes and scripts cleanly:
+Paced to native speed by default; `--uncapped` runs flat out. It's just stdio,
+so it pipes clean:
 
 ```sh
 ./build/sl0pboy --headless os.gb                  # interactive byte console
-./build/sl0pboy --headless --uncapped os.gb       # as fast as possible
-printf 'ls\n' | ./build/sl0pboy --headless os.gb  # feed input, capture output
+./build/sl0pboy --headless --uncapped os.gb       # gotta go fast
+printf 'ls\n' | ./build/sl0pboy --headless os.gb  # feed input, grab output
 ./build/sl0pboy --headless os.gb | tee session.log
 ```
 
-The serial console model matches what a GB program expects: write the byte to
-`SB` (`$FF01`), then kick a transfer with `SC = $81` (`$FF02`, start + internal
-clock). Output appears immediately; the transfer-complete serial interrupt still
-fires. (`--test` keeps its old behavior, logging serial to **stderr**.)
-
-Requires a truecolor-capable terminal (`COLORTERM=truecolor`) at least
-160 columns wide.
+The model is what a GB program expects: write byte → `SB` (`$FF01`), kick with
+`SC = $81` (`$FF02`, start + internal clock). Output shows up instantly and the
+transfer-complete interrupt still fires. (`--test` still logs serial to
+**stderr** like before.)
 
-### Sixel output
+## Sixel output
 
-On terminals that support **sixel** graphics (xterm `-ti vt340`, foot, WezTerm,
-mlterm, Contour, recent iTerm2, etc.) pass `--sixel [scale]` to render true
-pixels instead of half-blocks:
+On sixel-capable terminals (xterm `-ti vt340`, foot, WezTerm, mlterm, Contour,
+recent iTerm2…) `--sixel [scale]` draws real pixels instead of half-blocks:
 
 ```sh
-./build/sl0pboy --sixel rom.gb        # default 2x zoom (320×288 pixels)
-./build/sl0pboy --sixel 4 rom.gb      # 4x zoom
+./build/sl0pboy --sixel rom.gb     # 2x zoom (320×288)
+./build/sl0pboy --sixel 4 rom.gb   # 4x zoom
 ```
 
-Each frame builds a per-frame palette from the framebuffer (≤256 entries — 4
-shades on DMG, a small set on CGB; colors are quantized more coarsely only if a
-frame ever overflows), then emits standard sixel bands with per-column
-run-length encoding. `scale` is an integer pixel zoom (1–6). Sixel frames are
-sent in full (no inter-frame diffing), so combine with `--frameskip` on slower
-terminals.
+Each frame builds its own ≤256-color palette from the framebuffer (4 shades on
+DMG, a small set on CGB; quantized coarser only if a frame overflows) and emits
+standard sixel bands with per-column RLE. `scale` is 1–6. Sixel frames go out in
+full (no diffing) — pair with `--frameskip` on slow terminals.
 
-#### Game Boy chrome
+### Game Boy chrome
 
-Add `--chrome` (sixel only) to draw a DMG-style **sl0pboy** handheld around the
-LCD — screen bezel with accent stripe, power LED, silk-screened branding
-(`sl0pboy` logo, `DOT MATRIX WITH STEREO SOUND`, button labels), a D-pad, A/B
-buttons, Start/Select and a speaker grille. The controls light up while the
-matching button is held, so it doubles as an on-screen input display:
+`--chrome` (sixel only) wraps the LCD in a DMG-style **sl0pboy** handheld:
+bezel + accent stripe, power LED, silk-screened branding (`sl0pboy` logo,
+`DOT MATRIX WITH STEREO SOUND`, button labels), D-pad, A/B, Start/Select,
+speaker grille. Buttons light up while held, so it doubles as an input display:
 
 ```sh
 ./build/sl0pboy --sixel 3 --chrome rom.gb
 ```
 
-The shell is drawn with flat colors so it adds only a handful of palette
-entries. It composites into a larger canvas (240×342 px before scaling), so a
-given `scale` produces a proportionally bigger image than the bare LCD.
+Flat colors → only a handful of extra palette entries. It composites onto a
+bigger canvas (240×342 px pre-scale), so a given `scale` is proportionally
+larger than the bare LCD.
 
-#### LCD palette (`--palette`)
+### LCD palette (`--palette`)
 
-By default the LCD shows the game's true colors (the greenish DMG shades, or
-full CGB color). Pass `--palette NAME` to remap every LCD pixel to a 4-shade
-palette by luminance for the classic monochrome-LCD look — this even greens
-out full-color CGB games for that retro vibe:
+By default the LCD shows true colors (greenish DMG shades or full CGB). Want the
+retro monochrome-LCD look? `--palette NAME` remaps every LCD pixel to a 4-shade
+ramp by luminance — this even greens out full-color CGB games:
 
 ```sh
-./build/sl0pboy --sixel 3 --chrome --palette dmg rom.gb   # classic DMG-01 pea green
+./build/sl0pboy --sixel 3 --chrome --palette dmg rom.gb   # classic pea green
 ./build/sl0pboy --sixel 3 --green rom.gb                  # alias for --palette dmg
 ./build/sl0pboy --palette gray rom.gb                     # GB-Pocket grayscale
 ```
 
-Names: `dmg`/`green` (the iconic `#9bbc0f` pea-green ramp) and `pocket`/`gray`
-(grayscale). The recolor applies to every render path — half-block, sixel and
-chrome — and only touches the LCD, not the drawn shell.
+Names: `dmg`/`green` (the iconic `#9bbc0f` pea-green ramp) and `pocket`/`gray`.
+Applies to every render path — half-block, sixel, chrome — and only touches the
+LCD, never the shell.
 
-### Speed & frame skipping
+## Speed & frame skipping
 
-The emulator always advances every Game Boy frame at the correct rate, so
-games run at their intended speed. Because writing a frame to the terminal is
-by far the most expensive step, drawing can be *decoupled* from emulation via
-frame skipping — the machine keeps running in real time while the terminal is
-refreshed less often:
+Games always run at the correct rate. But writing a frame to the terminal is the
+expensive part, so drawing is *decoupled* from emulation — the machine keeps
+ticking in real time while the terminal refreshes less often:
 
 ```sh
-./build/sl0pboy --frameskip 2 rom.gb   # emulate 60 fps, draw every 3rd frame (20 fps)
-./build/sl0pboy --fps 120 rom.gb        # run the game at 2x speed
-./build/sl0pboy --uncapped rom.gb       # run as fast as possible (turbo)
+./build/sl0pboy --frameskip 2 rom.gb   # emulate 60fps, draw every 3rd (20fps)
+./build/sl0pboy --fps 120 rom.gb       # 2x game speed
+./build/sl0pboy --uncapped rom.gb      # turbo — as fast as it'll go
 ```
 
-| Flag              | Meaning                                             |
-|-------------------|-----------------------------------------------------|
-| `--frameskip N`   | draw 1 of every `N+1` emulated frames (default 0)   |
-| `--fps N`         | emulation speed cap in fps (default 59.73 native)   |
-| `--uncapped`/`--turbo` | run emulation as fast as possible              |
+| Flag                   | Meaning                                            |
+|------------------------|----------------------------------------------------|
+| `--frameskip N`        | draw 1 of every `N+1` emulated frames (default 0)  |
+| `--fps N`              | emulation speed cap (default 59.73 native)         |
+| `--uncapped`/`--turbo` | run emulation as fast as possible                  |
 
-Frame skip and turbo are also adjustable live with `[` / `]` and `f`; in turbo
-mode terminal redraws are additionally clamped to ~60 Hz. On exit the emulator
-prints how many frames it emulated vs. actually drew.
+Frame skip and turbo are live-adjustable with `[` / `]` and `f` (turbo also
+clamps redraws to ~60 Hz). On exit it prints frames emulated vs. actually drawn.
 
 ## Controls
 
@@ -161,31 +147,30 @@ prints how many frames it emulated vs. actually drew.
 | enter          | Start   |
 | space          | Select  |
 | `f`            | toggle fast-forward (turbo) |
-| `[` / `]`      | decrease / increase frame skip |
+| `[` / `]`      | frame skip down / up |
 | `q` / Ctrl-C   | Quit    |
 
-Since terminals don't report key-release, buttons are held for a few frames
-after each keypress (relying on the terminal's key-repeat for sustained holds).
+Terminals don't report key-release, so buttons stay held for a few frames after
+each press (leaning on key-repeat for sustained holds).
 
-### External control channel (FIFO)
+## External control channel (FIFO)
 
-Start with `--fifo [path]` (default `/tmp/sl0pboy.fifo`) to open a named pipe that
-accepts button commands from any process. Unlike the terminal keyboard, this
-can send true key-**release** events, so it gives deterministic input for
-scripting and automated testing.
+`--fifo [path]` (default `/tmp/sl0pboy.fifo`) opens a named pipe any process can
+poke. Unlike the keyboard it can send true key-**release** events → deterministic
+input for scripting and tests.
 
 ```sh
 ./build/sl0pboy --fifo /tmp/sl0pboy.fifo rom.gb &
-echo 'a' > /tmp/sl0pboy.fifo          # momentary tap of A
+echo 'a' > /tmp/sl0pboy.fifo          # tap A
 echo 'start' > /tmp/sl0pboy.fifo      # tap Start
 echo '+left' > /tmp/sl0pboy.fifo      # press and HOLD Left
-echo 'a b' > /tmp/sl0pboy.fifo        # tap A and B together (Left still held)
+echo 'a b' > /tmp/sl0pboy.fifo        # tap A+B (Left still held)
 echo '-left' > /tmp/sl0pboy.fifo      # release Left
-echo 'release' > /tmp/sl0pboy.fifo    # release everything held
-echo 'a:30' > /tmp/sl0pboy.fifo       # tap A, held for 30 frames
+echo 'release' > /tmp/sl0pboy.fifo    # release everything
+echo 'a:30' > /tmp/sl0pboy.fifo       # tap A, held 30 frames
 ```
 
-Commands (one line, space/comma separated tokens, case-insensitive):
+One line, space/comma-separated, case-insensitive:
 
 | Token          | Effect                                  |
 |----------------|-----------------------------------------|
@@ -193,20 +178,16 @@ Commands (one line, space/comma separated tokens, case-insensitive):
 | `name:N`       | tap held for N frames                   |
 | `+name`        | press and hold until released           |
 | `-name`        | release a held button                   |
-| `release`      | release all held buttons                |
+| `release`      | release everything held                 |
 
-Set `GBC_INPUT_DEBUG=1` to trace resulting joypad state to stderr.
+`GBC_INPUT_DEBUG=1` traces joypad state to stderr. The FIFO is input-only and
+can't reply — for introspection use the socket below (it's a strict superset).
 
-The FIFO is one-way (input only) and can't reply. For introspection/debugging
-use the socket control channel below, which is a strict superset.
+## Socket control & debug channel
 
-### Socket control & debug channel
-
-Start with `--sock [path]` (default `/tmp/sl0pboy.sock`) to open a Unix-domain
-stream socket. It accepts everything the FIFO does **plus** emulator
-introspection commands, and — being a socket — it *replies* to each command and
-pushes asynchronous events when execution stops. Connect any line-oriented
-client:
+`--sock [path]` (default `/tmp/sl0pboy.sock`) opens a Unix stream socket. It does
+everything the FIFO does **plus** CPU/memory introspection, and — being a socket
+— it *replies* and pushes async events when execution stops:
 
 ```sh
 ./build/sl0pboy --sock /tmp/sl0pboy.sock rom.gb &
@@ -214,10 +195,9 @@ socat - UNIX-CONNECT:/tmp/sl0pboy.sock       # interactive
 # or: nc -U /tmp/sl0pboy.sock
 ```
 
-The protocol is line based (one command per line). Replies start with `ok` or
-`err`; asynchronous notifications start with `event`. Numbers accept `0x` hex
-or decimal; **memory bytes are hex** (so `read` output feeds straight back into
-`write`).
+Line-based: one command per line. Replies start `ok`/`err`; async notifications
+start `event`. Numbers take `0x` hex or decimal; **memory bytes are hex** so
+`read` output feeds straight back into `write`.
 
 | Command                     | Effect                                             |
 |-----------------------------|----------------------------------------------------|
@@ -226,51 +206,50 @@ or decimal; **memory bytes are hex** (so `read` output feeds straight back into
 | `state`                     | `ok state running\|paused`                         |
 | `cpu` (`regs`)              | dump CPU context (af/bc/de/hl/sp/pc/ime/halted/cycles) |
 | `reg <name> <val>`          | set a register/flag (a..l, af..hl, sp, pc, ime)    |
-| `read <addr> [len]`         | read `len` bytes (bus read), returned as hex       |
-| `write <addr> <bytes…>`     | write bytes: `de ad be ef` or a `deadbeef` string  |
-| `step [n]`                  | single-step n instructions, replies with new context |
-| `continue` (`c`)           | resume free-running emulation                      |
-| `pause`                     | halt CPU advancement at the next instruction       |
+| `read <addr> [len]`         | read `len` bytes (bus read), as hex                |
+| `write <addr> <bytes…>`     | write bytes: `de ad be ef` or `deadbeef`           |
+| `step [n]`                  | single-step n instructions, replies w/ new context |
+| `continue` (`c`)            | resume free-running emulation                      |
+| `pause`                     | halt at the next instruction                       |
 | `break <addr>`              | add a PC breakpoint (no arg lists them)            |
 | `delete <0xaddr\|#idx\|all>` | remove a breakpoint                               |
 | `watch <addr>`              | value-change watchpoint on a byte (no arg lists)   |
 | `unwatch <0xaddr\|#idx\|all>`| remove a watchpoint                               |
-| `record start <path> [everyN]` | capture frames to `<path>` (1 of every N); build a GIF with `tools/gbgif.py` |
-| `record stop`               | finish the capture (replies with the frame count)  |
-| `record` (`status`)         | report whether a capture is active                 |
-| `input play <path> [reset]` | replay a synthesized input movie (frame-locked); `reset` = replay from a clean power-on |
-| `input stop`                | stop movie playback (releases all buttons)         |
-| `input` (`status`)          | report movie playback state                        |
-| `quit`                      | shut the emulator down                             |
-| *(any button tokens)*       | same vocabulary as the FIFO (tap/hold/release)     |
+| `record start <path> [everyN]` | capture frames (1 of every N); GIF w/ `tools/gbgif.py` |
+| `record stop`               | finish the capture (replies w/ frame count)        |
+| `record` (`status`)         | is a capture active?                               |
+| `input play <path> [reset]` | replay an input movie (frame-locked); `reset` = from clean power-on |
+| `input stop`                | stop playback (releases all buttons)               |
+| `input` (`status`)          | movie playback state                               |
+| `quit`                      | shut it down                                        |
+| *(any button tokens)*       | same vocabulary as the FIFO                        |
 
-### Video capture & input replay (demo GIFs)
+## Video capture & input replay (demo GIFs)
 
-Capture the displayed frame to a flat file and turn it into a GIF:
+Dump the on-screen frame to a flat file, then bake a GIF:
 
-```
-./gbctl record start /abs/out.gbv 2   # capture 1 of every 2 frames (~30fps)
+```sh
+./gbctl record start /abs/out.gbv 2   # 1 of every 2 frames (~30fps)
 ...
 ./gbctl record stop
 python3 tools/gbgif.py out.gbv out.gif --scale 3
 ```
 
-Recording captures exactly what's on screen: if the emulator was started with
-`--palette` and/or `--chrome`, those are baked into the capture (the `.gbv`
-header records the resulting dimensions, so e.g. chrome frames are 240×362 and
-`gbgif.py` picks that up automatically). `--shot` screenshots honor the same
-options. Start without them for the bare 160×144 true-color LCD.
+Capture grabs exactly what's on screen — start with `--palette`/`--chrome` and
+they're baked in (the `.gbv` header stores the real dimensions, so chrome frames
+come out 240×362 and `gbgif.py` figures it out automatically). `--shot`
+screenshots honor the same options. Skip them for the bare 160×144 LCD.
 
-Drive the ROM from a **synthesized input movie** instead of live input, for
-reproducible demos. A movie is a text file of `<frames> [buttons...]` lines
+Want reproducible demos? Drive the ROM from a **synthesized input movie** instead
+of live input. A movie is a text file of `<frames> [buttons...]` lines
 (`a b start select up down left right`; none/`-` = released); the emulator
-applies one line's worth of joypad state per emulated frame, so replay is
-deterministic. Build one by hand or with `tools/gbmovie.py`:
+applies one line's joypad state per frame, so replay is deterministic. Build by
+hand or with `tools/gbmovie.py`:
 
 ```python
 from gbmovie import Movie
 m = Movie()
-m.wait(340)                 # boot splash + fastboot -> overworld
+m.wait(340)                 # boot + fastboot -> overworld
 m.hold("select", 8)         # open the SL0P menu
 m.tap("down", repeat=13)    # cursor to the last item
 m.hold("a", 6); m.wait(600)
@@ -278,35 +257,31 @@ m.save("demo.gbmv")
 ```
 
 `input play <path> reset` gives a clean, repeatable power-on (keeps cart
-ROM+SRAM, zeroes all other state), so a movie replays byte-identically every
-time. For a frame-exact demo GIF, arm both while paused so they start on the
-same frame:
+ROM+SRAM, zeroes everything else), so a movie replays byte-identically. For a
+frame-exact GIF, arm both while paused so they start on the same frame:
 
-```
+```sh
 ./gbctl pause
 ./gbctl input play /abs/demo.gbmv reset
 ./gbctl record start /abs/demo.gbv 2
 ./gbctl continue
-...                                   # let the movie play
+...                                   # let it play
 ./gbctl record stop
 python3 tools/gbgif.py demo.gbv demo.gif --scale 3 --start 172
 ```
 
-When free-running (`continue`) hits a breakpoint or watchpoint, every connected
-client receives an async line and the machine pauses:
+When free-running hits a breakpoint/watchpoint, every connected client gets an
+async line and the machine pauses:
 
 ```
 event stop breakpoint af=0x0840 bc=0x0800 … pc=0x0048 … cycles=72654560
 event stop watch 0xFF44 af=0x90C0 … pc=0x4812 …
 ```
 
-There is also a `stopinfo` command (alias `why`/`laststop`) that reports the
-last reason execution halted, so a client that wasn't connected when an async
-`event` fired can still recover it (`ok stop breakpoint 0x0150 …`).
-
-`step` runs synchronously and replies immediately with the stop reason and the
-resulting context (`ok stop step …` / `ok stop breakpoint …` / `ok stop watch …`).
-Example session:
+Missed the event because you weren't connected yet? `stopinfo` (aka
+`why`/`laststop`) reports the last stop reason (`ok stop breakpoint 0x0150 …`).
+`step` runs synchronously and replies immediately with the stop reason + new
+context. A quick session:
 
 ```
 > pause
@@ -324,56 +299,55 @@ ok running
 event stop breakpoint … pc=0x0150 …
 ```
 
-#### `gbctl` — CLI driver (agent/tmux friendly)
+### `gbctl` — the CLI driver (agent/tmux friendly)
 
-`./gbctl` wraps the socket in a terse CLI that also spawns/stops a tmux pane
-running the emulator, so an LLM agent (or you) can drive it by tool-calling one
-command at a time. Socket auto-resolves to the single live instance.
+`./gbctl` wraps the socket in a terse CLI that spawns/stops a tmux pane running
+the emulator — so an LLM agent (or you) can drive it one tool-call at a time.
+Socket auto-resolves to the single live instance.
 
 ```sh
-./gbctl spawn roms/game.gb --uncapped   # tmux pane + emulator --sock; waits ready
+./gbctl spawn roms/game.gb --uncapped   # tmux pane + --sock; waits ready
 ./gbctl cpu ; ./gbctl read 0xC000 16 ; ./gbctl write 0xC000 deadbeef
-./gbctl break 0x0150 ; ./gbctl continue 5   # blocks up to 5s for the stop event
+./gbctl break 0x0150 ; ./gbctl continue 5   # blocks up to 5s for the stop
 ./gbctl press a b ; ./gbctl hold left ; ./gbctl release
-./gbctl screen ; ./gbctl stop               # view the pane / tear down
+./gbctl screen ; ./gbctl stop               # peek at the pane / tear down
 ```
 
-Run `./gbctl` with no args for the full command list. This is driven end-to-end
-by the `gbc-driver` skill.
+Run `./gbctl` bare for the full command list. Driven end-to-end by the
+`gbc-driver` skill.
 
 ## Architecture
 
-| File        | Responsibility                                            |
+| File        | Does what                                                 |
 |-------------|-----------------------------------------------------------|
 | `types.h`   | fixed-width integer typedefs                              |
 | `cart.c`    | ROM loading, header parsing, MBC1/2/3/5, battery saves    |
 | `gb.c`      | system bus / memory map, joypad, OAM-DMA, HDMA/GDMA, reset|
-| `cpu.c`     | Sharp SM83 core (full opcode set, cycle-accurate accesses)|
+| `cpu.c`     | Sharp SM83 core (full opcodes, cycle-accurate accesses)   |
 | `timer.c`   | DIV/TIMA/TMA/TAC with falling-edge accuracy               |
 | `ppu.c`     | LCD controller, scanline renderer (BG/window/sprites), CGB|
 | `render.c`  | terminal truecolor output + raw-mode keyboard/FIFO input  |
-| `control.c` | socket control/debug channel: memory, CPU, step, breakpoints|
-| `main.c`    | argument parsing, frame loop, timing, screenshot/test modes|
+| `control.c` | socket control/debug: memory, CPU, step, breakpoints      |
+| `main.c`    | arg parsing, frame loop, timing, screenshot/test modes    |
 
 ## Emulation status
 
-Passing:
-- **blargg `cpu_instrs`** — all 11 sub-tests
-- **blargg `instr_timing`**
-- **blargg `mem_timing`** / **`mem_timing-2`** — all 3
-- **dmg-acid2** — PPU test renders correctly
-- **cgb-acid2** — CGB PPU test renders correctly
+**Passing:**
+- blargg `cpu_instrs` — all 11 sub-tests
+- blargg `instr_timing`
+- blargg `mem_timing` / `mem_timing-2` — all 3
+- dmg-acid2 + cgb-acid2 — both render correctly
 
-Implemented:
+**Implemented:**
 - Full SM83 CPU incl. HALT bug, EI delay, interrupt dispatch
 - Accurate timer edge behavior
 - PPU modes 0–3, STAT/LYC/VBlank interrupts, window line counter
-- CGB: double VRAM banks, BG/OBJ color palettes, tile attributes,
-  master priority, WRAM banking, double-speed (KEY1), HDMA/GDMA
+- CGB: double VRAM banks, BG/OBJ color palettes, tile attributes, master
+  priority, WRAM banking, double-speed (KEY1), HDMA/GDMA
 - MBC1/2/3/5 with RAM banking and battery `.sav` files
 
-Not yet implemented:
-- APU (audio) — registers are stubbed
+**Not yet:**
+- APU (audio) — registers stubbed
 - MBC3 RTC advancement
 - Sub-instruction PPU FIFO timing edge cases