diff --git a/CLAUDE.md b/CLAUDE.md
index 438b7c41..52427f3a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -19,7 +19,8 @@ when you need depth on a subsystem. This file is the index.
 hive-c0re/         host daemon + CLI (one binary, subcommand-dispatched)
   src/main.rs           clap setup; serve / spawn / kill / rebuild / list /
                          pending / approve / deny / destroy [--purge] /
-                         request-spawn; periodic vacuum tasks
+                         request-spawn / set-parent (--parent / --root);
+                         periodic vacuum tasks
   src/server.rs         host admin socket (HostRequest → dispatch)
   src/client.rs         admin-socket client
   src/manager_server.rs manager-privileged socket (ManagerRequest)
diff --git a/docs/agent-hierarchy.md b/docs/agent-hierarchy.md
index b00eee6d..ee31411c 100644
--- a/docs/agent-hierarchy.md
+++ b/docs/agent-hierarchy.md
@@ -18,9 +18,36 @@ Topology lives in the hive-c0re-owned **meta repo**, alongside
 }
 ```
 
-`null` = root-level agent. Today only the manager qualifies. Other
-agents default to `"manager"` as parent on first sync. Operator/manager
-re-parenting via the write API + dashboard UI lands in a follow-up.
+`null` = root-level agent. Today only the manager qualifies by default.
+Other agents land under `"manager"` on first sync. Re-parenting is
+operator-driven (#486 / #487):
+
+- CLI: `hive-c0re set-parent <child> --parent <new>` (or `--root` to
+  promote). Exactly one of `--parent` / `--root` is required.
+- Dashboard: `POST /api/topology/set-parent` (form fields `child`,
+  optional `new_parent` — absent / empty ⇒ promote to root).
+- Wire: `HostRequest::SetParent { child, new_parent: Option<String> }`.
+
+All three converge on `topology::set_parent`, which delegates the
+validation rules to a pure `apply_set_parent` helper. Refuses:
+- reparenting the manager (structurally root),
+- unknown `child` / `new_parent` (typo guard),
+- self-parenting,
+- cycles (32-hop ancestor walk, mirroring `is_descendant_of`).
+
+Idempotent no-op fast path skips the disk write when the parent is
+already what's requested. After a successful write the surfaces call
+`Coordinator::rescan_containers_and_emit` so connected dashboard
+viewers see the tree repaint without polling
+(`ContainerView.parent` is sourced from `topology.json`).
+
+**Today's caveat (#361 follow-up):** the move is purely a JSON edit.
+Only the top-level manager (`hm1nd`) gets `/var/lib/hyperhive/agents`
+bind-mounted at `/agents` in its container, so sub-agents don't yet
+see their would-be children's state. Once sub-manager bind mounts
+land alongside #361 enforcement, `set_parent` grows a companion
+umount-old / mount-new / restart-cascade step (tracked via the
+cross-ref comment on #361).
 
 ### Why meta, not per-agent `agent.nix`