kernel/README.md

@@ -20,14 +20,35 @@ before connecting the real bus (see PLAN.md §10).
 ### Running it
 
 `selftest.sh` is non-persistent (nothing is installed into `/lib/modules`, no
-autoload): it checks vermagic, loads the module, runs the self-test, and always
-unloads it again.
+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:
+
+```
+comodore-iec-emu/
+├── selftest.sh
+└── 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)
+```
+
+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
+the packaged name carries a Debian epoch/revision (`1:6.12.93-1+rpt1`) that
+`uname -r` (`6.12.93+rpt-rpi-v8`) does not.
 
 ```bash
-sudo ./selftest.sh                                # auto-finds ./ or ~/iec_listener.ko, address 4
-sudo ./selftest.sh ~/iec_listener.ko --address 5  # runs with ~/iec_listener.ko, address 5
+sudo ./selftest.sh                                # auto-selects the matching module, address 4
+sudo ./selftest.sh --address 5                    # same, address 5
+sudo ./selftest.sh ~/iec_listener.ko --address 5  # force a specific module file
 ```
 
+If no module matches the running kernel, the script lists the modules it found
+(with the kernel each was built for) and exits — rebuild for the current kernel,
+or pass a path explicitly.
+
 It exits non-zero unless the result is a full pass (`0x1F`), so it is usable in
 scripts/CI.