diff --git a/README.md b/README.md
index ae8027f..6ddc5f7 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,8 @@ If you are the person: read these in order:
 6. `docs/ENVIRONMENT-FACTS.md` — the ids, the installed tools, and the one step that is
    still unproven.
 
+![architecture](docs/diagrams/architecture.png)
+
 ## The one-line version
 
 Paperclip already owns tasks, blockers, comments, approvals, runs, cost and git
diff --git a/docs/DOCMAP.md b/docs/DOCMAP.md
index 4930665..5664f1e 100644
--- a/docs/DOCMAP.md
+++ b/docs/DOCMAP.md
@@ -26,6 +26,8 @@ it is a pointer and should be deleted or replaced.
 | `docs/TEST-PLAN.md` | this project | the test plan: every step, every key, every expected result |
 | `docs/RUNS-AND-MERGE.md` | this project | what a task, a run and a merge are, with the measured run counts |
 | `docs/NEXT.md` | this project | what is left to build, in order, and what is still unproven |
+| `docs/architecture.mmd` | this project | the system diagram in Mermaid: TUIOS panes, the commands, Paperclip, where work happens |
+| `docs/diagrams/architecture.png` | this project | the same diagram rendered, for a README or a handover |
 
 ## What is not a document of this project
 
diff --git a/docs/architecture.mmd b/docs/architecture.mmd
new file mode 100644
index 0000000..be57a68
--- /dev/null
+++ b/docs/architecture.mmd
@@ -0,0 +1,54 @@
+flowchart TB
+    subgraph People
+        P["The person<br/>on .27 or .51"]
+    end
+
+    subgraph TUIOS["TUIOS daemon on .13"]
+        direction TB
+        W1["Board>board"]
+        W2["Work>work"]
+        W3["Agents>agents"]
+        W4["Reply>reply"]
+        W5["New task>new"]
+        W6["Project>project"]
+        W7["Repair>repair"]
+        W8["Shell>shell"]
+    end
+
+    subgraph Harness["bin/ commands"]
+        O["office<br/>adopt, create session, build panes"]
+        B["board<br/>build or repair panes"]
+        M["merge<br/>rebase, check, review, merge"]
+        R["review<br/>ocr alone"]
+        T["triage<br/>Mouse-1 one question"]
+    end
+
+    subgraph Paperclip["Paperclip on .13 :3100"]
+        API["Control plane API"]
+        DB[("Tasks, blockers, comments,<br/>runs, cost, approvals")]
+        AG["Agents<br/>Pi adapter (pi_local)"]
+    end
+
+    subgraph Work["Work happens here"]
+        WT["Worktree per task<br/>.paperclip/worktrees"]
+        PI["Pi session per run<br/>~/.pi/paperclips"]
+        SK["Skills<br/>~/.pi/agent/skills"]
+    end
+
+    GH["Gitea / git repository"]
+
+    P --> TUIOS
+    W1 & W2 & W3 & W4 & W5 & W6 & W7 --> API
+    W8 --> O & B & M & R & T
+    O & B --> TUIOS
+    M & R --> GH
+    M --> OCR["ocr review"]
+    T --> MOUSE["Mouse-1 API"]
+    API --> DB
+    API --> AG
+    AG --> WT
+    AG --> PI
+    AG --> SK
+    WT --> GH
+
+    click API "https://maps.lab.audasmedia.com.au/paperclip-harness/docs/" "View Archify Map"
diff --git a/docs/diagrams/architecture.png b/docs/diagrams/architecture.png
new file mode 100644
index 0000000..831da52
Binary files /dev/null and b/docs/diagrams/architecture.png differ