Showcase README; Outline collection for agents; repository created on Gitea

docs/outline/01-system-overview.md

@@ -0,0 +1,45 @@
+# 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.