# 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.