diff --git a/README.md b/README.md
index bf84acb093..8313ea3004 100644
--- a/README.md
+++ b/README.md
@@ -156,6 +156,115 @@ Paperclip handles the hard orchestration details correctly.
+## 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 │ │ Plugins │ │ Budget │ │
+│ │ & Agents │ │ & Runtime │ │ │ │ & Costs │ │
+│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
+│ │
+│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
+│ │ Routines │ │ Secrets & │ │ Activity │ │ Company │ │
+│ │& Schedules│ │ Storage │ │ & Events │ │Portability│ │
+│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
+└──────────────────────────────────────────────────────────────┘
+ ▲ ▲ ▲ ▲
+ ┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐
+ │ Claude │ │ Codex │ │ CLI │ │ HTTP/web │
+ │ Code │ │ │ │ agents │ │ bots │
+ └───────────┘ └───────────┘ └───────────┘ └───────────┘
+```
+
+### The Systems
+
+
| + +**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. + + | ++ +**Org Chart & Agents** — Agents have roles, titles, reporting lines, permissions, and budgets. Adapter examples match the diagram: Claude Code, Codex, CLI agents such as Cursor/Gemini/bash, HTTP/webhook bots such as OpenClaw, and external adapter plugins. If it can receive a heartbeat, it's hired. + + | +
| + +**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. + + | ++ +**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. + + | +
| + +**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. + + | ++ +**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. + + | +
| + +**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. + + | ++ +**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. + + | +
| + +**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. + + | ++ +**Secrets & Storage** — Instance and company secrets, encrypted local storage, provider-backed object storage, attachments, and work products. Sensitive values stay out of prompts unless a scoped run explicitly needs them. + + | +
| + +**Activity & Events** — Mutating actions, heartbeat state changes, cost events, approvals, comments, and work products are recorded as durable activity so operators can audit what happened and why. + + | ++ +**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. + + | +