# System overview

## What it is

Paperclip Harness is a terminal interface over Paperclip. Paperclip is a control plane. It keeps
tasks, blockers, comments, approvals, runs, cost and a git worktree for each task. This project
shows that work in a terminal, inside TUIOS, and adds the few actions a person needs.

## The parts

- **Paperclip** on `http://127.0.0.1:3100`. It owns every fact. It runs Pi agents.
- **TUIOS**. It owns sessions, workspaces, panes and part of the keyboard.
- **The Go program** in `tui/`. One binary. Each pane runs one screen.
- **Commands** in `bin/`. They do the work that should not be a keystroke: adopt a folder, build
  panes, merge one task, review one task, ask Mouse-1 one question.

## The eight workspaces

| Workspace | Purpose |
|---|---|
| Shell | a prompt in the project folder, with the paths printed above it |
| Board | the state of the work, and what needs a person |
| Work | runs, diff, facts, review, run log, merge |
| Agents | who is working, on what, for how much; and their settings, skills, extensions |
| Reply | the task thread and a reply box |
| New task | the form that creates a task |
| Project | dashboard, costs, settings, adopted projects |
| Repair | health checks, live layout, rebuild log, session cleanup |

## The data flow

1. A person creates a task in `New task`, or one already exists in Paperclip.
2. The person assigns it on `Board`. Paperclip wakes the agent.
3. The agent works in its own git worktree, on its own branch.
4. The agent comments and sets the status.
5. The person reads the run log, the diff and the review.
6. The person merges. `bin/merge` rebases, checks, reviews, merges, and checks again.

## What the project stores

One file per project: `<folder>/.harness/harness.toml`. It holds the session name, the machine,
the Paperclip project id, and the task being watched. It holds no task data.

A registry at `~/.config/paperclip-harness/projects.toml` lists adopted projects, so a person can
see which folder lives where.