AGENTS.md: the operating instructions, including which key, where blockers really are, and the first thing to test

AGENTS.md

@@ -0,0 +1,106 @@
+# Instructions for the agent working in this project
+
+You are picking up a project that is starting fresh, after two earlier attempts are
+closed. Read this file first, then `HANDOVER.md`, then `docs/PLAN.md`. Do not read the old
+project unless this file tells you to.
+
+## What we are building
+
+One small Go terminal program with four screens, sitting on top of Paperclip, inside
+TUIOS. Paperclip already keeps tasks, blockers, comments, approvals, run history, cost and
+the git worktree for each task. We do not build any of that again.
+
+The four screens:
+
+1. Task tree — todo, in progress, blocked, done, for one project.
+2. New task — a form: title, description, what must finish first, and the command that
+   proves it is finished.
+3. Live log and diff — what the selected task is doing, and what it changed.
+4. Unblock and reply — the task's conversation, with a box to reply.
+
+## The one rule that matters most
+
+Each fact has exactly one owner, and for tasks, blockers, comments, approvals, runs and
+cost that owner is Paperclip. Our code never stores its own copy. If a screen and
+Paperclip disagree, the screen is wrong and gets fixed.
+
+## Which key to use
+
+Two credentials exist and they are not interchangeable.
+
+- **Use the user key** — environment variable `PAPERCLIP_BOARD_KEY` — for everything this
+  program does on the person's behalf: creating tasks, adding blockers, posting comments.
+  It records the action as the person's.
+- **Do not use the agent key** (`PAPERCLIP_API_KEY`) for writes. Outside a heartbeat run
+  Paperclip refuses it with 403 "cross-issue writes need a run to attribute them to". That
+  refusal is correct. Use the agent key only for read-only checks.
+
+Example read, safe with either key:
+
+```
+curl -s -H "Authorization: Bearer $PAPERCLIP_BOARD_KEY" \
+  http://127.0.0.1:3100/api/health
+```
+
+Never print either key, never commit it, never paste it into a prompt.
+
+## Blockers are not in the task list
+
+This is the trap that would look fine and be wrong. The list endpoint returns tasks with
+`blockedByIssueIds` empty even when a blocker exists. To know what blocks a task, ask
+about that task:
+
+```
+GET /api/issues/{id}/diagnostics/blockers
+```
+
+It returns `readiness.unresolvedBlockerCount` and the blocking tasks. The task tree reads
+this per task. `docs/PAPERCLIP-API-NOTES.md` has the measured response.
+
+## What the first session must do
+
+Only the first item of `CHECKLIST.md`. One task, really run, with no interface.
+
+1. The sandbox project `spike-2026-11-09` already has two tasks: `AUD-157` and `AUD-158`,
+   the second blocked by the first. Safe to use or delete.
+2. Assign the first task to the Pi agent and see whether a heartbeat picks it up. **This
+   is unproven.** If assignment does not wake an agent, write down exactly what happened;
+   do not build a workaround yet.
+3. Watch the status change, read the comment the agent writes, read the cost, and find the
+   worktree Paperclip created.
+4. Report what you saw, with the commands and the responses.
+
+Do not start the Go program until that passes.
+
+## Things that are ours, because Paperclip does not do them
+
+- One project = one folder on one machine, and remembering which machine it is on.
+- The page layout in TUIOS, and repairing it.
+- Creating, adopting, resetting and deleting a project.
+- `ocr` code review over the diff, and merging one task at a time.
+- The command that decides a task is finished, kept with the project.
+- The notes that explain each screen.
+
+## Interface rules, from the person, not negotiable
+
+- Handle the terminal resize message. Never hardcode sizes. Show a short "too small"
+  screen instead of a broken one. Run in the alternate screen.
+- Inside TUIOS window mode, `h j k l`, `z` and `n` belong to TUIOS and never reach the
+  program. Use Tab, Shift-Tab, arrows, Space and Enter inside the app, and keep a bare Esc
+  free to close a box.
+- Create the mouse-click zone manager once and wrap the whole view; per-part wrapping
+  drifts when panes resize.
+- No network calls and no git work inside the update or view functions. Use commands that
+  return messages, or the pane freezes.
+- Go with Bubble Tea, Lipgloss, Bubbles, Huh and BubbleZone.
+
+## How to report
+
+Say what you ran and what came back. If something is unproven, say it is unproven. "It
+should work" is not a result. A dry run is not a test.
+
+## The old project
+
+`~/paseo/projects/tuios_coding_harness` (plans and history) and `~/paseo/harness` (the
+code). Read `docs/OPEN-ISSUES.md` first if you need to know what broke there. Do not copy
+code from it; copy nothing but understanding.

README.md

@@ -3,7 +3,9 @@
 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.
 
-Read these in order:
+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.