diff --git a/CLAUDE.md b/CLAUDE.md
index 03bb7eb6..f0f29ffc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -259,10 +259,11 @@ nix/
                                  `services.hyperhive.domain` (#660); gateway serves
                                  `.well-known/matrix/{client,server}` for
                                  auto-discovery; federation on, e2ee deferred (#551)
-  templates/harness-base.nix    shared scaffolding for sub-agents + manager;
-                                 `hyperhive.model` option (HIVE_DEFAULT_MODEL)
-  templates/agent-base.nix      sub-agent nixosConfiguration
-  templates/manager.nix         manager nixosConfiguration
+  templates/harness-base.nix    shared harness for all containers; `hyperhive.role`
+                                 (`"agent"` | `"manager"`) drives service unit + forge
+                                 defaults; `hyperhive.model` option (HIVE_DEFAULT_MODEL)
+  templates/agent-base.nix      thin role-setter (`hyperhive.role = "agent"`)
+  templates/manager.nix         thin role-setter (`hyperhive.role = "manager"`)
   templates/weston-vnc.nix      optional `hyperhive.gui.enable`
                                  — weston + VNC backend systemd unit; writes
                                  /etc/hyperhive/gui.json (vnc_port + auth) for