diff --git a/CLAUDE.md b/CLAUDE.md
index d0d029c..1742ea0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,6 +10,20 @@ MCP has two components:
 - **CLI** (`mcp`) — thin client on the operator's workstation. Reads local service definition files, pushes intent to agents, queries status. No database.
 - **Agent** (`mcp-agent`) — smart per-node daemon. Manages containers via podman, stores the registry (SQLite), monitors for drift, alerts the operator.
 
+### Runtimes (containers + unikernels)
+
+The agent holds two `runtime.Runtime` backends and selects per component via
+`a.runtimeFor(comp.Runtime)`:
+- **Podman** (`internal/runtime/podman.go`) — containers (default).
+- **QEMU** (`internal/runtime/qemu.go`) — Nanos unikernel VMs, when a component
+  sets `runtime = "unikernel"` and the node has KVM + `ops`.
+
+`listAllContainers()` merges both backends so status/drift see VMs and
+containers uniformly. See the root repo's `docs/unikernels.md` for the full
+operator + developer guide, and `docs/hypervisor-design.md` for the rationale.
+Service-def fields: `runtime`, `memory`, `vcpus` (proto `ComponentSpec`
+fields 11–13; registry migration 5). **All container behavior is unchanged.**
+
 Services have one or more components (containers). Container naming: `<service>-<component>`.
 
 ## v2 Development (Multi-Node)