67 lines
3.2 KiB
Markdown
67 lines
3.2 KiB
Markdown
# 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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|