TUIOS runbook: the environment is not tmux, and how sessions start on .13/.27/.51

The handover named TUIOS but never said plainly that it is not tmux, how a session is
created on each machine, that workspaces vanish when empty and renumber, that TUIOS keeps
h/j/k/l in window mode, or how to drive a pane from a script. All of it is now in
docs/TUIOS-RUNBOOK.md, referenced first in AGENTS.md and README.

AGENTS.md

@@ -4,6 +4,16 @@ You are picking up a project that is starting fresh, after two earlier attempts
 closed. Read this file first, then `HANDOVER.md`, then `docs/PLAN.md`. Do not read the old
 project unless this file tells you to.
 
+## Read this before anything else: the environment is TUIOS, not tmux
+
+This system runs inside **TUIOS**, a terminal multiplexer with workspaces and panes. There
+is no tmux here. `docs/TUIOS-RUNBOOK.md` explains it, including how to start a session from
+`.27`, `.13` or `.51`, and the four rules that have already cost us two days: workspaces
+disappear when empty and renumber, TUIOS keeps `h j k l` in window mode, a resize arrives
+as a normal terminal resize, and a page must keep one pane that never exits.
+
+Do not write a design that assumes tmux, a single fullscreen app, or a fixed window size.
+
 ## What we are building
 
 One small Go terminal program with four screens, sitting on top of Paperclip, inside

README.md

@@ -11,7 +11,8 @@ If you are the person: read these in order:
 2. `docs/PLAN.md` — the plan: the four screens, the milestones, what is Paperclip's job and what is ours.
 3. `docs/PAPERCLIP-API-NOTES.md` — what we measured against your running Paperclip, with the endpoint and the response.
 4. `CHECKLIST.md` — the exact steps for the next session, in order, with boxes to tick.
-5. `docs/DOCMAP.md` — which document is authoritative for what. One home per document.
+5. `docs/TUIOS-RUNBOOK.md` — TUIOS, not tmux: the three machines, starting a session, driving panes.
+6. `docs/DOCMAP.md` — which document is authoritative for what. One home per document.
 6. `docs/ENVIRONMENT-FACTS.md` — the ids, the installed tools, and the one step that is
    still unproven.
 

docs/DOCMAP.md

@@ -9,6 +9,7 @@ it is a pointer and should be deleted or replaced.
 | `AGENTS.md` | project root | instructions for the agent: what to build, which key, the first test |
 | `HANDOVER.md` | project root | what we tried before, what worked, what failed, the pitfalls |
 | `CHECKLIST.md` | project root | the next session, step by step, with tick boxes |
+| `docs/TUIOS-RUNBOOK.md` | this project | how TUIOS works, the three machines, how to start a session, how to drive panes |
 | `docs/PLAN.md` | this project | the plan: four screens, five milestones, who owns what |
 | `docs/ENVIRONMENT-FACTS.md` | this project | ids, installed tools, the unproven heartbeat step |
 | `docs/PAPERCLIP-API-NOTES.md` | this project | what we measured against the running Paperclip, with endpoints |

docs/TUIOS-RUNBOOK.md

@@ -0,0 +1,100 @@
+# How this runs: TUIOS, not tmux
+
+Read this before writing any code or starting any session. Everything here was measured on
+this setup; the commands are real.
+
+## The environment is TUIOS
+
+The terminal multiplexer on these machines is **TUIOS**, not tmux. There is no tmux session
+to attach to, and a design that assumes tmux will not work. TUIOS calls its groupings
+**workspaces**, and each split inside a workspace is a **pane**. A pane is a real terminal
+(its own PTY) running a program.
+
+Consequences that have already cost us two days:
+
+1. **A workspace with no panes is deleted, and the rest are renumbered.** Never hold a
+   workspace number. Always resolve a workspace by name at the moment you use it.
+2. **A page must keep one pane that never exits**, or the page vanishes. This is why every
+   screen in this project has a permanent pane.
+3. **TUIOS owns part of the keyboard.** In window-management mode it keeps `h j k l`, `z`
+   and `n`. A program only receives keys in terminal mode, entered with `i` or `Enter`, and
+   you leave window mode with the prefix key then `Esc` (default prefix `Ctrl+B`).
+4. **A resize reaches the program as a normal terminal resize** (SIGWINCH). Handle it. Do
+   not hardcode sizes.
+
+## The machines
+
+| Name | Address | Reachable how |
+|---|---|---|
+| `.13` `nixos-desktop` | `192.168.20.13` | headless, hosts the work and the Paperclip server; also reachable over the web |
+| `.27` `sam-4screen-desktop` | `192.168.20.27` | local only |
+| `.51` `sam-thinkpad` | `192.168.20.51` | local only |
+
+`.13` is the machine that hosts work. `.27` and `.51` are where a person sits. Any machine
+can drive any other over ssh, but ssh needs a key already installed
+(`ssh-copy-id 192.168.20.13` once if it ever asks for a password).
+
+## Starting a session
+
+Session creation needs a real terminal. Measured: `tuios new` and `tuios attach` both fail
+with "Standard output is not a terminal" when run from a script. So the person creates the
+session, once, in a terminal:
+
+```
+# on .27, to create a session that lives on .13
+tuios new --host nixos-desktop cookie
+
+# on the machine that owns the folder, plainly
+tuios new cookie
+```
+
+Then inside a pane of that session, on the host where the folder lives:
+
+```
+cd ~/src/cookie
+```
+
+Rules that follow from this:
+
+- The session lives on one machine. The folder lives on one machine. Use the same one.
+- Inside the session, on the host that owns the folder, nothing else is needed. No `--host`.
+- `--host` is only for acting on a *different* machine from where you typed the command.
+
+## Reading and driving a session from a script
+
+```
+tuios list-sessions
+tuios list-workspaces -s cookie --json      # number and name of each workspace
+tuios list-windows    -s cookie --json      # panes, their workspace and their name
+tuios new-window NAME -s cookie --workspace "<number>" --cwd <dir> --no-focus --keep-open -- <command...>
+tuios capture-pane  -s cookie -w <window-id>          # what the pane shows now
+tuios send-keys     -s cookie -w <window-id> <Key>    # drive a program in a pane
+tuios close-window  <window-id> -s cookie
+```
+
+The colour codes in `list-windows` output wrap the name, so match on the stripped text.
+Anything matching a bare name must strip escape sequences first — a plain ` name ` match
+fails and made a live session look absent.
+
+## What this means for our four screens
+
+Each screen is a pane in its own workspace, named for what it shows. The Go program draws
+inside the pane it is given; it never owns the whole terminal. A screen that needs the
+whole width is a pane that has been zoomed, not a separate mode.
+
+When a screen is started, it is started with the project and the session in its
+environment, so it knows what to read. When it is started twice, the second start must
+adopt the existing pane rather than create a duplicate.
+
+## Testing an interface change
+
+A test in a plain terminal, or in tmux, proves only that the program draws. TUIOS owns part
+of the keyboard and forwards mouse clicks relative to the pane, so the real check is:
+
+```
+tuios new-window harness-check -s "$TUIOS_SESSION" --no-focus --keep-open -- /tmp/harness-bin
+tuios capture-pane -s "$TUIOS_SESSION" -w harness-check
+tuios send-keys    -s "$TUIOS_SESSION" -w harness-check Down --repeat 2
+```
+
+If the pane shows what you expect after the keys, it works where it will be used.