73 lines
3.3 KiB
Markdown
73 lines
3.3 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/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
|
|
cd tui
|
|
go run . -project spike-2026-11-10 # full-screen task tree
|
|
go run . -project spike-2026-11-10 -dump # same data as plain text, no interface
|
|
```
|
|
|
|
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
|
|
|
|
This machine runs TUIOS, and the program is used inside a TUIOS pane. A test in a plain
|
|
terminal, or in tmux, only proves that a program draws and survives a resize message. It
|
|
does not prove the program works where it will actually run, because TUIOS owns part of
|
|
the keyboard and sends its own resize messages.
|
|
|
|
So an interface change is checked by putting it in a real TUIOS pane and reading the pane
|
|
back:
|
|
|
|
```bash
|
|
tuios new-window -s "$TUIOS_SESSION" harness-check --no-focus --keep-open -- /tmp/harness-bin -project spike-2026-11-10
|
|
tuios capture-pane -s "$TUIOS_SESSION" -w harness-check
|
|
tuios send-keys -s "$TUIOS_SESSION" -w harness-check Down --repeat 2
|
|
tuios screenshot -w harness-check -o /tmp/harness-tuios.png
|
|
tuios close-window harness-check
|
|
```
|
|
|
|
`--no-focus` keeps the person's focus where it was, and the pane is closed afterwards, so
|
|
the layout is left as it was found.
|
|
|
|
## 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.
|