paperclip-harness/README.md

# Paperclip harness — start here

This is a new project. Nothing here runs yet. It exists so the third attempt starts from
a clean place, with the history of the first two attempts attached.

If you are an agent: read `AGENTS.md` first, then `HANDOVER.md`, then `docs/PLAN.md`.

If you are the person: read these in order:

1. `HANDOVER.md` — what we tried before, what worked, what failed, and why this is different.
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/TUIOS-RUNBOOK.md` — TUIOS, not tmux: the three machines, starting a session, driving panes.
6. `docs/OPERATING-RULES.md` — the nine rules, including how a task is judged finished.
7. `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.

## The one-line version

Paperclip already owns tasks, blockers, comments, approvals, runs, cost and git
worktrees. We are building one small Go terminal program with four screens on top of it.
Nothing else.

## What you need installed (all present on .13 today)

- Paperclip server running locally on `http://127.0.0.1:3100` (it is; 685 endpoints).
- `PAPERCLIP_BOARD_KEY` in the environment — the **user** key. The terminal program uses
  this one. An agent key cannot write outside a heartbeat run.
- Go toolchain — **now installed** (`go1.26.5`, from `nix profile`). The NixOS config change
  that makes it permanent is staged in `/etc/nixos/configuration.nix` and needs one
  `sudo nixos-rebuild switch`. See `docs/ENVIRONMENT-FACTS.md`.
- Pi, which is already the worker adapter on your Paperclip agent.

## Running the terminal program

```bash
bin/layout                                # open every screen as a TUIOS pane
bin/screen reply AUD-162                  # or one screen

cd tui
go run . -screen tree -project spike-2026-11-10    # one screen in this terminal
go run . -screen tree -project spike-2026-11-10 -dump   # the same data as plain text
```

The screens live in the session named `paperclip-harness`, one per workspace. How that is
built and repaired is in `docs/TUIOS-RUNBOOK.md`.

The project can be an id or its url key. Keys inside the program: arrows or Tab and
Shift-Tab move, `r` re-reads from Paperclip, `q` quits. A bare Esc is left free, because in
TUIOS it has to close a box.

## The six workspaces

Written the way we talk about them: **Workspace>pane**. `Board>board` means the board
program running in the Board workspace.

| Workspace>pane | shows | keys |
|---|---|---|
| Shell>shell | a prompt in the project folder: the pane that never exits, and the escape hatch for anything no panel covers | — |
| Board>board | tasks by group · the chosen task · needs you | ↑↓ j k · enter · a · u · / · t (tools) · tab |
| Work>work | runs · change · facts · review | [ ] tab · ↑↓ j k · g G · t (tools) |
| Reply>reply | the task · the thread · the reply box | enter · s · esc |
| New task>new | the form · what a task needs · what will be sent | tab · enter · ctrl+n |
| Project>project | overview · facts · costs · settings | [ ] tab · ↑↓ j k |
| Repair>repair | health · layout · rebuild log | [ ] tab · ↑↓ j k · R · B |
| Agents>agents | roster · runs · log · settings | [ ] tab · ↑↓ j k · enter · p P w · A |

Choosing a task on the board and pressing Enter writes it into the project's
`.harness/harness.toml`, and every other workspace follows within a second.

### Tool panes

`t` in `Board>board` or `Work>work` opens a chooser: shell, Lazygit, Hunk, Yazi, Neovim,
fzf, ocr. Note that TUIOS also binds `t` in **window management mode** (toggle tiling, new
window); inside the program the pane must be in terminal mode for `t` to arrive, which is
the normal state while you are typing in it. The tool opens as a pane beside the one you are in, in the same workspace, and
`esc` closes the chooser. Quitting the tool (its own key) closes its pane. Nothing is added
to the layout, so the eight workspaces stay as they are.

### Refresh and rebuild

- **`r`** — read the data again in this panel. Nothing closes, nothing moves, the
  layout is untouched. Use it when the numbers look stale.
- **`B`** — on the Repair screen only: add whatever panes are missing without
  closing any, so it is safe to press from inside a pane.
- **`?`** — the keys for the panel you are in, as an overlay.
- **`/`** — filter the task list by identifier, title or assignee name.
- **`u`** — unblock a task whose blocker has finished but which still says blocked.
- **`R`** — rebuild everything: `bin/board --replace` closes each pane the layout
  owns and builds all seven again, in order. It runs detached in its own session,
  because the panel you pressed it in is one of the panes being replaced; the
  output is written to `/tmp/paperclip-harness-rebuild.log`, and the Repair
  workspace shows that log on its third tab.

`R` is on every screen except the new-task form, where letters are text.

## How an interface change is tested

Not in a plain terminal, and not in tmux. TUIOS owns part of the keyboard and forwards
clicks relative to the pane, so the check is a real TUIOS pane read back with
`capture-pane`. The commands are in `docs/TUIOS-RUNBOOK.md`, which is the one place they
live.

## The commands

| command | what it does |
|---|---|
| `bin/office <folder> [--project X] [--session Y]` | adopt a folder: write `.harness/harness.toml`, build its pages |
| `bin/board [--folder DIR] [--replace]` | build or repair the pages; run twice and nothing is duplicated |
| `bin/project-reset <folder> [--dry-run] [--yes]` | close the pages, remove the worktrees and branches; keep the folder and every Paperclip record |
| `bin/merge <task> [--check]` | rebase, verify, review with `ocr`, merge; a refusal is a decision for the person |
| `bin/review <task> [--post]` | the same review on its own |
| `bin/screen <screen> [task or project]` | open one page by name |

## Rules for this project

- No interface work before a real task has run end to end.
- Paperclip owns the facts. We never keep a second copy of a task, a blocker or a cost.
- Every claim in a document names the command that showed it.
- Nothing is copied from the old project except documents.