Screens 1 and 4 running as TUIOS panes: reply screen, adopt-or-create launcher, layout script

docs/PAPERCLIP-API-NOTES.md

@@ -274,3 +274,28 @@ Read from `GET /api/companies/{companyId}/agents`:
 
 The company's `budgetMonthlyCents` is 0. There is no currency field anywhere in the payload:
 Paperclip counts cents and does not name a currency, so "5000" is a number, not "$50 AUD".
+
+---
+
+# Milestone 2 passed from the terminal, 2026-11-10
+
+The reply screen sent one call that both comments and changes status:
+
+```
+PATCH /api/issues/AUD-162   {"status":"todo","comment":"Unblocked: AUD-161 is done, …"}
+→ 200, status todo
+```
+
+Read back afterwards:
+
+```
+GET /api/issues/AUD-162/comments → 1 comment, authorType: user, authorUserId: 2204TMD0…
+GET /api/issues/AUD-162/activity → actorType: user, issue.comment_added, then
+                                   issue.updated status {from blocked, to todo}
+```
+
+Before the move, `AUD-161` was set to `done` and `diagnostics/blockers` for `AUD-162`
+returned `allBlockersDone: true, unresolvedBlockerCount: 0` while the task itself stayed
+`blocked`. So Paperclip does not walk a task forward on its own when its blocker clears; it
+makes the task ready and leaves the decision to a person or a program. That is the job the
+reply screen does, and the reason this milestone exists.

docs/TUIOS-RUNBOOK.md

@@ -98,3 +98,24 @@ 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.
+
+## Opening the screens
+
+The session for this project is named **`paperclip-harness`**. The scripts take that name
+themselves; they never read `TUIOS_SESSION`, because that is the session of the pane you
+happen to be typing in, and using it once put a screen in the wrong session.
+
+```
+bin/layout                       # every screen, in order, adopting what is already there
+bin/screen tree                  # one screen
+bin/screen reply AUD-162
+```
+
+Both are idempotent: a second run focuses the pane that is already running that screen. The
+pane is a shell that starts the program and returns to the shell when it exits, so a pane
+never closes itself and the workspace keeps the pane that stops it being deleted.
+
+Measured: closing the last pane on a workspace leaves the number but **erases the
+workspace's name**. Reopening therefore falls back to the first empty workspace and renames
+it, which is why `bin/screen` prints either `created` or `adopted` and the workspace it
+used. Nothing stores a workspace number.