diff --git a/docs/matrix.md b/docs/matrix.md
index 5bc4328e..dc361844 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,12 @@ 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. 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,10 +84,6 @@ 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.
-
 Federation port 8448 is intentionally not opened here — tuwunel
 serves the federation API on the same `httpPort` as client-server
 by default. Reaching it on 8448 needs either an explicit tuwunel