diff --git a/docs/matrix.md b/docs/matrix.md
index dc361844..5bc4328e 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 default under the **swarm** domain, because a swarm runs one
+Both now 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,12 +54,10 @@ 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.
 
-### 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:
+**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:
 
 ```nix
 services.hyperhive.swarm.matrix = {
@@ -84,6 +82,10 @@ 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