diff --git a/docs/matrix.md b/docs/matrix.md
index 5bc4328e..734bef4b 100644
--- a/docs/matrix.md
+++ b/docs/matrix.md
@@ -41,7 +41,7 @@ Two distinct hostnames:
   `chat.<services.hyperhive.swarm.domain>`. Set to `null` to skip the
   gateway vhost (tuwunel stays direct on `httpPort`).
 
-Both now default under the **swarm** domain, because a swarm runs one
+Both default under the **swarm** domain, because a swarm runs one
 homeserver: tying its identity to a single hive's domain would make
 relocating the container between hives look like a different
 homeserver.
@@ -54,10 +54,14 @@ adopting a new one does **not** rename the existing users and rooms —
 it strands them, because their ids still name a homeserver that no
 longer answers.
 
-**Breaking change — pin `serverName` before rebuilding.** Its default
-has now moved twice: from `matrix.${services.hyperhive.domain}`, to
-the bare hive domain, and now to the swarm domain. Any homeserver that
-has already minted ids must name the value it minted them under:
+### Upgrading a homeserver that already has ids
+
+`serverName`'s default has changed across releases (from
+`matrix.${services.hyperhive.domain}`, to the bare hive domain, to the
+current swarm domain). A homeserver that has already minted ids under
+an older default must **pin the value it actually minted them
+under**, not adopt the new default — see above for why adopting a new
+one strands existing users and rooms:
 
 ```nix
 services.hyperhive.swarm.matrix = {
@@ -82,9 +86,9 @@ matters for access from *outside* the host. Flip to `true` when
 announcing the homeserver to other hives or when an external matrix
 client needs to reach the client-server API directly.
 
-**Breaking change**: used to default to `true`. Operators relying on
-external reach must add
-`services.hyperhive.swarm.matrix.openFirewall = true;` before rebuilding.
+**Upgrading:** earlier releases defaulted `openFirewall` to `true`.
+Operators relying on external reach need to add
+`services.hyperhive.swarm.matrix.openFirewall = true;` explicitly now.
 
 Federation port 8448 is intentionally not opened here — tuwunel
 serves the federation API on the same `httpPort` as client-server