Record how the interface is tested: in a real TUIOS pane, not a plain terminal

README.md

@@ -43,6 +43,27 @@ The project can be an id or its url key. Keys inside the program: arrows or Tab
 Shift-Tab move, `r` re-reads from Paperclip, `q` quits. A bare Esc is left free, because in
 TUIOS it has to close a box.
 
+## How an interface change is tested
+
+This machine runs TUIOS, and the program is used inside a TUIOS pane. A test in a plain
+terminal, or in tmux, only proves that a program draws and survives a resize message. It
+does not prove the program works where it will actually run, because TUIOS owns part of
+the keyboard and sends its own resize messages.
+
+So an interface change is checked by putting it in a real TUIOS pane and reading the pane
+back:
+
+```bash
+tuios new-window -s "$TUIOS_SESSION" harness-check --no-focus --keep-open -- /tmp/harness-bin -project spike-2026-11-10
+tuios capture-pane -s "$TUIOS_SESSION" -w harness-check
+tuios send-keys -s "$TUIOS_SESSION" -w harness-check Down --repeat 2
+tuios screenshot -w harness-check -o /tmp/harness-tuios.png
+tuios close-window harness-check
+```
+
+`--no-focus` keeps the person's focus where it was, and the pane is closed afterwards, so
+the layout is left as it was found.
+
 ## Rules for this project
 
 - No interface work before a real task has run end to end.