From adb76f3cdf292a2ff57844b79fd02158c2398fa3 Mon Sep 17 00:00:00 2001
From: iris <iris@pr1ma.darkest.space>
Date: Tue, 23 Jun 2026 12:01:40 +0200
Subject: [PATCH] docs(persistence): reframe stale 'the manager' as the root
 agent

Config-repo editor, meta RO-mount, non-destroyable container, and the
topology.json example now refer to the root agent / bootstrap container
rather than 'the manager'. The /run/hyperhive/manager/mcp.sock path is a
real runtime path, kept (clarified as the root agent's manager-flavour
socket).
---
 docs/persistence.md | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/docs/persistence.md b/docs/persistence.md
index 233fedfa..7c7496c3 100644
--- a/docs/persistence.md
+++ b/docs/persistence.md
@@ -180,16 +180,16 @@ Survives destroy/recreate, gone on `--purge`.
 
 Under `/var/lib/hyperhive/agents/<name>/`:
 
-- `config/` — the proposed nix repo (manager-editable). Bind-mounted
+- `config/` — the proposed nix repo (root-agent-editable). Bind-mounted
   **read-only** to `/agents/<name>/config` inside the sub-agent's own
   container so the agent can inspect what defines it and request
-  precise changes from the manager; RW into the manager via the
+  precise changes from the root agent; RW into the root agent via the
   `/agents` tree bind.
 - `claude/` — claude OAuth credentials, bind-mounted RW to
   `/home/<name>/.claude` inside the container.
 - `state/` — durable notes and `hyperhive-harness.json`. Bind-mounted
   to `/agents/<name>/state` inside the container (uniform for
-  sub-agents + manager). The `$HYPERHIVE_STATE_DIR` env var exposes
+  all agents — sub-agents + root). The `$HYPERHIVE_STATE_DIR` env var exposes
   the same path to in-container scripts. Notable files written here
   by the harness:
   - `hyperhive-status` — single-line free-text status string written
@@ -237,8 +237,8 @@ sibling's.
 Under `/var/lib/hyperhive/applied/<name>/` — the hive-c0re-only
 applied repo. Tracks `flake.nix` (module-only boilerplate; never
 edited after first spawn) + `agent.nix` (the actual config; the
-manager's edits land here via the approval flow) + any other
-files the manager committed. `.git/` carries the proposal /
+root agent's edits land here via the approval flow) + any other
+files committed via the approval flow. `.git/` carries the proposal /
 approved / building / deployed / failed / denied tag history.
 
 Under `/var/lib/hyperhive/meta/` — the swarm-wide deploy flake plus
@@ -251,7 +251,7 @@ Contents:
   canonical "what's deployed where." The git log is the deploy
   audit trail (one commit per successful deploy or hyperhive bump).
 - `topology.json` — parent/child agent graph
-  (`{ "alice": "manager", "bob": "alice", "manager": null }`).
+  (`{ "alice": "root", "bob": "alice", "root": null }`).
   Written by `topology::set_parent`; read by the dashboard, the
   renderer, and `<parent>` / `<children>` recipient resolution.
 - `tool-groups.json` — per-agent MCP tool group grants
@@ -263,7 +263,7 @@ Contents:
   `capabilities::set_caps`; injected as `HIVE_CAPABILITIES` env
   var. Absent agents have no extra capabilities.
 
-Manager has the meta dir RO-mounted at `/meta/`.
+The root agent has the meta dir RO-mounted at `/meta/`.
 
 Marker file `/var/lib/hyperhive/.meta-migration-done` is
 written by the startup migration after every container has
@@ -285,8 +285,8 @@ step would re-fire).
   claude creds, /state/ notes, and the harness dir are all gone.
   No undo.
 
-The manager is non-destroyable from both paths (declarative
-container; would fight with the host's NixOS config).
+The root/bootstrap container is non-destroyable from both paths
+(declarative container; would fight with the host's NixOS config).
 
 ### btrfs subvolumes for `/var/lib/hyperhive/agents/<name>`
 
@@ -323,7 +323,8 @@ Without that, every restart wipes bind sources and existing
 containers can't be started.
 
 - `/run/hyperhive/host.sock` — admin socket (host-side CLI).
-- `/run/hyperhive/manager/mcp.sock` — manager-privileged socket.
+- `/run/hyperhive/manager/mcp.sock` — the root agent's privileged
+  (manager-flavour) socket.
 - `/run/hyperhive/agents/<name>/mcp.sock` — per-sub-agent socket
   (bind-mounted into the container as `/run/hive/mcp.sock`).