docs: add architecture systems section to README

Adds a "What's Under the Hood" section with an ASCII architecture
diagram and feature-level descriptions of Paperclip's 10 core systems:
identity, org chart, tasks, heartbeats, workspaces, governance,
budgets, routines, plugins, and company portability.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

README.md

@@ -156,6 +156,107 @@ Paperclip handles the hard orchestration details correctly.
 
 <br/>
 
+## What's Under the Hood
+
+Paperclip is a full control plane, not a wrapper. Before you build any of this yourself, know that it already exists:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        PAPERCLIP SERVER                        │
+│                                                                 │
+│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌─────────────┐ │
+│  │ Identity & │  │   Work &  │  │ Heartbeat │  │ Governance  │ │
+│  │   Access   │  │   Tasks   │  │ Execution │  │ & Approvals │ │
+│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘  └──────┬──────┘ │
+│        │              │              │               │         │
+│  ┌─────┴─────┐  ┌─────┴─────┐  ┌─────┴─────┐  ┌─────┴──────┐ │
+│  │  Org Chart │  │ Workspaces│  │  Adapter   │  │   Budget   │ │
+│  │  & Agents  │  │ & Runtime │  │  Registry  │  │  & Costs   │ │
+│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘  └──────┬──────┘ │
+│        │              │              │               │         │
+│  ┌─────┴──────────────┴──────────────┴───────────────┴──────┐  │
+│  │                     Postgres + Plugins                    │  │
+│  └───────────────────────────────────────────────────────────┘  │
+│        │              │              │               │         │
+│  ┌─────┴─────┐  ┌─────┴─────┐  ┌─────┴─────┐  ┌─────┴──────┐ │
+│  │ Routines  │  │ Secrets & │  │  Activity  │  │  Company   │ │
+│  │& Schedules│  │  Storage  │  │  & Events  │  │ Portability│ │
+│  └───────────┘  └───────────┘  └───────────┘  └────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+          ▲               ▲               ▲               ▲
+    ┌─────┴────┐   ┌──────┴─────┐  ┌──────┴─────┐  ┌─────┴────┐
+    │ Claude   │   │   Codex    │  │  OpenClaw   │  │  Any bot │
+    │  Code    │   │            │  │             │  │ (HTTP/WS)│
+    └──────────┘   └────────────┘  └────────────┘  └──────────┘
+```
+
+### The Systems
+
+<table>
+<tr>
+<td width="50%">
+
+**Identity & Access** — Two deployment modes (trusted local or authenticated), board users, agent API keys, short-lived run JWTs, company memberships, invite flows, and OpenClaw onboarding. Every mutating request is traced to an actor.
+
+</td>
+<td width="50%">
+
+**Org Chart & Agents** — Agents have roles, titles, reporting lines, permissions, and budgets. The adapter registry supports Claude, Codex, Cursor, OpenClaw, Gemini, HTTP, bash, and external adapter plugins. If it can receive a heartbeat, it's hired.
+
+</td>
+</tr>
+<tr>
+<td>
+
+**Work & Task System** — Issues carry company/project/goal/parent links, atomic checkout with execution locks, first-class blocker dependencies, comments, documents, attachments, work products, labels, and inbox state. No double-work, no lost context.
+
+</td>
+<td>
+
+**Heartbeat Execution** — DB-backed wakeup queue with coalescing, budget checks, workspace resolution, secret injection, skill loading, and adapter invocation. Runs produce structured logs, cost events, session state, and audit trails. Recovery handles orphaned runs automatically.
+
+</td>
+</tr>
+<tr>
+<td>
+
+**Workspaces & Runtime** — Project workspaces, isolated execution workspaces (git worktrees, operator branches), and runtime services (dev servers, preview URLs). Agents work in the right directory with the right context every time.
+
+</td>
+<td>
+
+**Governance & Approvals** — Board approval workflows, execution policies with review/approval stages, decision tracking, budget hard-stops, agent pause/resume/terminate, and full audit logging. You're the board — nothing ships without your sign-off.
+
+</td>
+</tr>
+<tr>
+<td>
+
+**Budget & Cost Control** — Token and cost tracking by company, agent, project, goal, issue, provider, and model. Scoped budget policies with warning thresholds and hard stops. Overspend pauses agents and cancels queued work automatically.
+
+</td>
+<td>
+
+**Routines & Schedules** — Recurring tasks with cron, webhook, and API triggers. Concurrency and catch-up policies. Each routine execution creates a tracked issue and wakes the assigned agent — no manual kick-offs needed.
+
+</td>
+</tr>
+<tr>
+<td>
+
+**Plugins** — Instance-wide plugin system with out-of-process workers, capability-gated host services, job scheduling, tool exposure, and UI contributions. Extend Paperclip without forking it.
+
+</td>
+<td>
+
+**Company Portability** — Export and import entire organizations — agents, skills, projects, routines, and issues — with secret scrubbing and collision handling. One deployment, many companies, complete data isolation.
+
+</td>
+</tr>
+</table>
+
+<br/>
+
 ## What Paperclip is not
 
 |                              |                                                                                                                      |