diff --git a/docs/swarm/README.md b/docs/swarm/README.md
index 0c87c059..2e89061b 100644
--- a/docs/swarm/README.md
+++ b/docs/swarm/README.md
@@ -339,7 +339,10 @@ same third hive, such as a stale endpoint.
 is names only. Set it only for a hive addressed by something else. This
 hive's own `services.hyperhive.domain` comes from its entry; it drives
 `HYPERHIVE_HIVE_DOMAIN` in every container so agents can form qualified
-labels (`iris@pr1ma.example.com`).
+labels (`iris@pr1ma.example.com`). Setting `services.hyperhive.domain`
+directly overrides the directory entry, with a deprecation warning: the
+option is local to this host while every host shares the directory, so a
+value written only here is invisible to the rest of the swarm.
 
 `swarm.name` is display only — the dashboard chrome header and per-agent
 system prompts — and federated hives at different domains can share one.
@@ -354,20 +357,6 @@ chains to it, so there is no per-hive CA field and no per-hive cert pinning.
 Trusting a hive whose root this swarm doesn't own — another swarm's — has no
 mechanism.
 
-<details><summary>Upgrading an existing hive</summary>
-
-- Set `swarm.domain` and `hiveName` once; eval fails naming each until you do.
-- Add the hive's own directory entry,
-  `services.hyperhive.swarm.hives.<hiveName> = { };` — one line, no value.
-  Eval fails naming it if you forget.
-- Setting `services.hyperhive.domain` directly still works and still wins,
-  with a **deprecation warning**: the option is local to one host while
-  every host holds the directory, so a value written only there leaves every
-  peer pointing somewhere else. Move it into the hive's directory entry, or
-  drop it if it's the conventional `<hiveName>.<swarm.domain>`.
-
-</details>
-
 ### What the directory feeds
 
 1. **Swarm-wide hive roster** — swarm-controller reads this same