diff --git a/nix/modules/hive-matrix.nix b/nix/modules/hive-matrix.nix
index 5903b5a2..c1575d9e 100644
--- a/nix/modules/hive-matrix.nix
+++ b/nix/modules/hive-matrix.nix
@@ -84,6 +84,13 @@ in
         different server_name shape (e.g. `matrix.<domain>` if you
         want the subdomain split, or `chat.example.org` for a
         bespoke hostname).
+
+        **Breaking change as of #660**: this used to default to
+        `matrix.''${services.hyperhive.domain}`. matrix IDs embed
+        the server_name irrevocably, so existing homeservers must
+        set `services.hyperhive.matrix.serverName = "matrix.''${services.hyperhive.domain}";`
+        explicitly to preserve their pre-#660 user / room IDs
+        before rebuilding.
       '';
     };