diff --git a/docs/mx-re/toolchain-and-plan.md b/docs/mx-re/toolchain-and-plan.md
new file mode 100644
index 0000000..73fbbe8
--- /dev/null
+++ b/docs/mx-re/toolchain-and-plan.md
@@ -0,0 +1,66 @@
+# Workabout MX — reverse-engineering toolchain & documentation plan
+
+Goal: reverse-engineer the Workabout MX ROM (`w2mx_v7.20f_eng.bin`, v7.20f) and
+produce complete programming documentation for the device, since none exists for
+the MX specifically.
+
+## Toolchain (reproducible, headless)
+
+ROM identifies as MAME machine **`psionwamx`** ("Workabout mx"), CPU NEC V30MX
+(`psion_asic9mx`), with `psion_asic5` (barcode/UART) and the SIBO expansion slots.
+
+Setup:
+```
+mkdir -p roms/psionwamx && cp w2mx_v7.20f_eng.bin roms/psionwamx/w2mx_v7.20f.bin
+mame psionwamx -rompath roms -verifyroms          # -> "romset psionwamx is good"
+```
+
+**Dynamic RE (MAME debugger, headless via xvfb):**
+```
+xvfb-run -a mame psionwamx -rompath roms -debug \
+         -debugscript CMDS.txt -sound none -seconds_to_run N
+```
+Useful `CMDS.txt` debugger commands:
+- `trace FILE` then `go` — log every executed instruction (correct bank mapping).
+- `dasm FILE,ADDR,LEN` — disassemble a region as currently mapped.
+- `dump FILE,ADDR,LEN` — hex dump memory.
+- `bpset ADDR,1,{commands}` — breakpoint with actions (e.g. dump then continue).
+- `wpset ADDR,LEN,rw` — watchpoint (catch who reads/writes a driver global).
+
+This resolves the segment/relocation mapping that flat static disassembly of the
+ROM could not (e.g. `SCANNER.DYL` / `SCANAPP` code).
+
+**Static RE:** `radare2 -e asm.arch=x86 -e asm.bits=16 w2mx_v7.20f_eng.bin`
+(good for strings, byte-pattern search, and clean fixed-mapped regions).
+
+## What "complete documentation" covers
+
+1. **Hardware** (largely in the HDK, to be confirmed/extended for the MX):
+   memory map & banking, ASIC1/2/4/5/9MX register maps, I/O ports, interrupts.
+2. **Boot & OS**: reset path, hardware init sequence, the `int 0xCF` OS/executive
+   call and its function table, the `int 0xD9`/etc. service vectors.
+3. **I/O & drivers**: the device model, `p_open`/`p_iow` function codes per driver,
+   and each driver: `TTY`, `WL2` (scanner), `MCR`, `PAR`, `SND`, IR, etc.
+4. **Scanner** (immediate priority, partly done — see SCANNER-API.md): `WL2:D`,
+   Symbol2 decoder, the 11-byte param block, trigger (ops 6/7), and the
+   still-open **data-retrieval** path — to be nailed by tracing `SCANAPP` live.
+5. **System services / libraries**: file system (DBF), window server, HWIM/FORM.
+
+## RE order
+
+1. Nail the scanner data-retrieval by running `SCANAPP`/`DEMMAN` under MAME,
+   breakpointing the `WL2` code, and tracing how the decoded bytes are delivered.
+2. Map the `int 0xCF` OS call table (breakpoint the vector, log CL/BX/DX per call).
+3. Document the boot + ASIC init (already partly traced).
+4. Work outward to the drivers and system services.
+
+Findings land in `docs/` as they are confirmed (e.g. `SCANNER-API.md`), each
+marked confirmed-on-emulator / confirmed-on-device / inferred.
+
+## Notes
+
+- `int 0xCF` convention (from traced code): `CL` = I/O function code, `BX` =
+  channel handle, `DX` = argument; result in `AX`. This is the `p_iow` layer.
+- MAME cannot inject a real barcode into the laser, so scanner *decode* may not
+  reproduce in emulation; but the *code path* (open/config/enable/read structure)
+  traces fully, which is what we need to write correct client code.