diff --git a/README.md b/README.md
index d3b5d0df..04b472c0 100644
--- a/README.md
+++ b/README.md
@@ -33,9 +33,19 @@ host (NixOS, runs hive-c0re.service)
 │   ├── hive-forge     Forgejo — per-agent accounts, config mirror (agent-configs/)
 │   └── hive-matrix    tuwunel — Matrix homeserver + per-agent accounts
 │
-└── agent containers
-    ├── h-ruth     manager (privileged MCP surface, approval gating)
-    └── h-<name>   sub-agent (claude + MCP tools + per-agent web UI + unix socket)
+├── agent containers
+│   ├── h-ruth     manager (privileged MCP surface, approval gating)
+│   └── h-<name>   sub-agent (claude + MCP tools + per-agent web UI + unix socket)
+│
+└── swarm (optional — connects hives; one host per swarm runs these)
+    ├── swarm-controller       cross-hive state: hive directory, agent roster, jobs
+    ├── swarm-ui               swarm-wide SPA, served straight off the gateway (no own container)
+    ├── swarm-authelia         SSO — one login gates swarm-ui + Grafana + more
+    ├── swarm-nats             message queue (JetStream KV: hive-status, …)
+    ├── swarm-otel             telemetry collector, sole holder of the upstream credential
+    ├── swarm-victoriametrics  metrics store
+    ├── swarm-victorialogs     log store
+    └── swarm-grafana          dashboards over the metrics/log stores, own OIDC login
 ```
 
 **[→ website](https://hyperhive.darkest.space)** ·