docs: catch up post-#658/#604/#660 + add operator hivectl section (#124)

docs/gotchas.md

@@ -65,17 +65,20 @@ propagate in. Operators don't need to set anything on their side.
 ## Claude credentials are per-agent
 
 `/var/lib/hyperhive/agents/<name>/claude/` bind-mounts to
-`/root/.claude` (RW). Sharing one dir across agents is NOT viable —
+`/home/<name>/.claude` (RW; was `/root/.claude` pre-#658 when every
+harness ran as root). Sharing one dir across agents is NOT viable —
 OAuth refresh tokens rotate, so any sibling refresh invalidates all
 the others. Login flow runs from the per-agent web UI; creds persist
 across `destroy`/recreate (`--purge` wipes them).
 
 ## Persistent notes dir per agent
 
-`/var/lib/hyperhive/agents/<name>/state/` bind-mounts to `/state`
-(RW). System prompts tell agents to keep durable knowledge here
-(`/state/notes.md`, anything else under `/state/`). The harness also
-writes its events log here (`/state/hyperhive-events.sqlite`).
+`/var/lib/hyperhive/agents/<name>/state/` bind-mounts to
+`/agents/<name>/state` (RW; uniform for sub-agents + manager
+post-#604, was `/state` pre-#604). The harness exposes the same path
+via `$HYPERHIVE_STATE_DIR`. System prompts tell agents to keep
+durable knowledge here (`notes.md`, anything else). The harness also
+writes its events log here (`hyperhive-events.sqlite`).
 Survives `destroy`/recreate alongside the claude dir.
 
 ## Web UI ports collide on hash

docs/persistence.md

@@ -136,11 +136,13 @@ Under `/var/lib/hyperhive/agents/<name>/`:
   precise changes from the manager; RW into the manager via the
   `/agents` tree bind.
 - `claude/` — claude OAuth credentials, bind-mounted RW to
-  `/root/.claude` inside the container.
+  `/home/<name>/.claude` inside the container (post-#658 — was
+  `/root/.claude` pre-#658 when every harness ran as root).
 - `state/` — durable notes, the events.sqlite db, and the
   turn-stats sqlite db. Bind-mounted to `/agents/<name>/state`
-  inside the container (the manager still uses the legacy
-  `/state` mount point — same host path either way).
+  inside the container (uniform for sub-agents + manager
+  post-#604). The `$HYPERHIVE_STATE_DIR` env var exposes the
+  same path to in-container scripts.
 
 Under `/var/lib/hyperhive/applied/<name>/` — the hive-c0re-only
 applied repo. Tracks `flake.nix` (module-only boilerplate; never

docs/security.md

@@ -18,8 +18,12 @@ any file in the container that the nixbld user can read.
 
 **What is NOT exposed**:
 
-- `/root/.claude/` — mode `0700`, owned by root. nixbld users cannot read it.
-- `/state/forge-token` — written at mode `0600` by `hive-c0re/src/forge.rs`.
+- `/home/<name>/.claude/` — mode `0700`, owned by the per-agent
+  user `<name>` (post-#658 — was `/root/.claude` owned by root
+  pre-#658). nixbld users cannot read it.
+- `$HYPERHIVE_STATE_DIR/forge-token` (= `/agents/<name>/state/forge-token`)
+  — written at mode `0600` by `hive-c0re/src/forge.rs` and chowned to the
+  per-agent uid:gid by `lifecycle::chown_to_agent` (post-#673/#678).
   nixbld users cannot read it.
 
 **Policy**: all credential files written to agent state directories MUST be mode