diff --git a/AGENTS.md b/AGENTS.md index 298f9c4..bea6ede 100644 --- a/AGENTS.md +++ b/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 diff --git a/README.md b/README.md index 31a3c19..90c592e 100644 --- a/README.md +++ b/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. diff --git a/docs/DOCMAP.md b/docs/DOCMAP.md index 275b5d3..a5ab024 100644 --- a/docs/DOCMAP.md +++ b/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 | diff --git a/docs/TUIOS-RUNBOOK.md b/docs/TUIOS-RUNBOOK.md new file mode 100644 index 0000000..8313ee3 --- /dev/null +++ b/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 "" --cwd --no-focus --keep-open -- +tuios capture-pane -s cookie -w # what the pane shows now +tuios send-keys -s cookie -w # drive a program in a pane +tuios close-window -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.