diff --git a/README.md b/README.md
index f9db804..9052bdb 100644
--- a/README.md
+++ b/README.md
@@ -8,20 +8,43 @@ coordinates the swarm and gates lifecycle changes on user approval via git
 commits, surfaced through a vibec0re-styled HTTP dashboard.
 
 ```
-                     ┌────────────────────────┐
-                     │  hive-c0re (Rust)      │
-        operator ──▶ │  • lifecycle           │ ─▶ nixos-containers
-                     │  • broker (sqlite)     │     ├── hm1nd       (manager)
-                     │  • approvals (sqlite)  │     ├── h-alice     (sub-agent)
-                     │  • dashboard :7000     │     └── h-bob       ...
-                     │  • per-agent sockets   │
-                     └────────────────────────┘
+host (NixOS, runs hive-c0re.service)
+│
+├── operator
+│   ├── browser → :7000               hive-c0re dashboard (containers, approvals)
+│   ├── browser → :8000 / :8100-8999  per-agent web UIs (live SSE, send, login)
+│   └── CLI     → /run/hyperhive/host.sock         JSON-line admin protocol
+│
+├── hive-c0re  (Rust daemon)
+│   ├── lifecycle    nixos-container CRUD + per-agent flake generation
+│   ├── broker       sqlite messages + tokio broadcast (powers SSE + wake-ups)
+│   ├── approvals    sqlite queue, two kinds: ApplyCommit (config) + Spawn
+│   ├── auto_update  rebuilds any container whose recorded flake rev is stale
+│   ├── dashboard    axum HTTP + async-form actions + SSE message flow
+│   └── sockets      /run/hyperhive/{host,manager,agents/<n>}/mcp.sock
+│
+└── nixos-containers  (each bind-mounts its socket dir → /run/hive,
+   │                   its credentials dir → /root/.claude;
+   │                   manager additionally gets /agents RW)
+   │
+   ├── hm1nd      hive-m1nd serve : claude turn loop +
+   │              MCP (send / recv / request_spawn / kill /
+   │                   request_apply_commit) + web UI on :8000
+   │
+   └── h-<name>   hive-ag3nt serve : claude turn loop +
+                  MCP (send / recv) + web UI on a hashed :8100-8999
 ```
 
-Each container runs a harness binary that drives `claude --print --continue`
-in a turn loop, exposes a per-agent web UI with a live event stream, and
-talks to the broker over a bind-mounted unix socket via an embedded MCP
-server claude calls into.
+Each turn: harness pops one inbox message (Recv long-polls server-side and
+wakes on a broker Sent event) → builds a wake prompt → spawns
+`claude --print --continue --output-format stream-json --mcp-config …` →
+streams JSON events into the per-agent SSE bus → claude drives any further
+`recv`/`send` itself via the embedded MCP server.
+
+Config changes flow the other way: manager edits `/agents/<name>/config/agent.nix`
+(bind-mounted from the host's proposed repo) → commits → submits the sha as
+an approval → operator clicks ◆ APPR0VE on the dashboard → hive-c0re copies
+the file into the applied repo and `nixos-container update`s the agent.
 
 ## Host config