README.md

@@ -71,6 +71,39 @@ See [`docs/wiring.md`](docs/wiring.md) for the level-shifter circuit and the
 pre-C64 bring-up checklist, and [`docs/kernel-notes.md`](docs/kernel-notes.md)
 for the resolved kernel real-time decisions.
 
+## Running the frontend on the Pi
+
+A tagged build publishes a release zip that bundles everything needed to run on
+a Pi without building anything:
+
+```
+comodore-iec-emu/
+  selftest.sh      one-shot wiring self-test (no C64 connected)
+  launch.sh        load module → run iecpoc → unload
+  pyproject.toml   iecpoc packaging metadata
+  README.md
+  iecpoc/          the Python frontend
+  modules/         iec_listener_<kernel_version>.ko, one per supported kernel
+```
+
+Unzip it on the Pi and run **`launch.sh`**. It installs the frontend into a local
+`.venv`, detects the running kernel and picks the matching `.ko` (by *vermagic*,
+not filename), `insmod`s it, runs `iecpoc`, and **always `rmmod`s on exit** — so
+the Pi is left exactly as before:
+
+```bash
+unzip comodore-iec-emu-*.zip && cd comodore-iec-emu
+sudo ./selftest.sh                 # first: check the wiring (want 0x1F)
+sudo ./launch.sh                   # then: load + run the frontend (address 4)
+sudo ./launch.sh --address 8       # listen as device 8
+sudo ./launch.sh -- --raw          # forward extra args (after --) to iecpoc
+```
+
+The module is picked automatically; pass `--ko PATH` only to force a specific
+file. `launch.sh` needs `python3` plus `python3-venv` (and network on first run
+for the build backend). See [`kernel/README.md`](kernel/README.md) for the
+self-test details and the per-kernel module selection.
+
 ## Status
 
 - **Phase 0 (userspace + tests):** complete, runs on any host.

kernel/README.md

@@ -23,16 +23,26 @@ before connecting the real bus (see PLAN.md §10).
 autoload): it detects the running kernel, picks the matching module, loads it,
 runs the self-test, and always unloads it again.
 
-A released package ships several kernel builds side by side:
+A released package ships several kernel builds side by side, plus the launcher
+and the Python frontend:
 
 ```
 comodore-iec-emu/
-├── selftest.sh
+├── selftest.sh      # one-shot wiring self-test (this document)
+├── launch.sh        # load module → run the iecpoc frontend → unload
+├── pyproject.toml   # iecpoc packaging metadata (launch.sh pip-installs it)
+├── README.md
+├── iecpoc/          # the Python userspace decoder/trace
 └── modules/
     ├── iec_listener_1-6.12.93-1+rpt1.ko   # built for 6.12.x (bookworm)
     └── iec_listener_1-6.18.34-1+rpt1.ko   # built for 6.18.x (trixie)
 ```
 
+`selftest.sh` only verifies the wiring (it loads and immediately unloads). To
+actually capture and decode C64 traffic, use **`launch.sh`**, which installs the
+frontend, loads the matching module, runs `iecpoc`, and unloads on exit — see the
+[top-level README](../README.md#running-the-frontend-on-the-pi).
+
 You don't pick the file yourself: the script reads `uname -r`, then scans
 `modules/` (and a few fallback locations) and selects the `.ko` whose **vermagic**
 matches the running kernel. Matching is by vermagic rather than filename because