Showcase README; Outline collection for agents; repository created on Gitea

docs/outline/04-agent-runbook.md

@@ -0,0 +1,45 @@
+# Agent runbook
+
+Read this before you change anything.
+
+## First
+
+1. Read `AGENTS.md`.
+2. Read `HANDOVER.md`.
+3. Run `tuios ls` and find the session called `paperclip-harness`.
+4. In a pane, run `Repair>repair`. Every check must pass. If it does not, fix that first.
+
+## Build and restart
+
+```sh
+cd tui && go build -o ../bin/harness .
+```
+
+Then press `R` in `Repair>repair`. Do not start a second copy of a panel: `bin/board` adopts the
+pane that is already there.
+
+## Rules that are not preferences
+
+- Writes use `PAPERCLIP_BOARD_KEY`. The agent key is refused outside a run, and that refusal is
+  correct.
+- Read blockers from `/api/issues/{id}/diagnostics/blockers`. The task list does not carry them.
+- Read a worktree path from a single-task read. The task list does not carry it either.
+- Never store a fact Paperclip owns.
+- A comment on an assigned task wakes its agent. Tool verdicts hand the task back to the person
+  first.
+- TUIOS keeps `h j k l z n` and also `[ ] Tab , . = ;` and the digits. Use arrows, `jk`, `(` `)`,
+  `Space`, `Enter`. Keep `Esc` free.
+
+## Traps, measured
+
+- A pane started by TUIOS has a smaller `PATH`. `bin/lib/harness.py` and `toolpane.go` add the
+  usual directories for that reason.
+- TUIOS can re-tile a pane without the program hearing about it. Re-ask for the size.
+- Closing the last pane deletes a workspace and renumbers the rest. Resolve workspaces by name.
+- `switch-session` is refused when the call comes from a pane. A program cannot move the person's
+  client.
+
+## Reporting
+
+Say what you ran and what came back. If something is unproven, say it is unproven. A dry run is
+not a test.