nix/matrix: add breaking-change note to serverName description (argus #661)

argus on #661 🟡: "matrix IDs embed server_name irrevocably — anyone
already running with the old default would be broken."

Append a `**Breaking change as of #660**` paragraph to the
`serverName` option description with the exact opt-back-in string,
matching the pattern from #651's openFirewall flip. PR body + commit
already documented the breakage; this surfaces it in the option's
own description so it shows up in `nix flake show` + the auto-
generated options docs right next to the option.

nix/modules/hive-gateway.nix

@@ -168,6 +168,39 @@ in
                     '';
                   };
                 }
+                //
+                  # `.well-known/matrix/*` auto-discovery (#660): when
+                  # `services.hyperhive.matrix.enable` is on and the
+                  # operator's set a hive domain, the gateway serves
+                  # the matrix-spec discovery JSON at the canonical
+                  # location so clients pointed at `${hyperhive.domain}`
+                  # resolve through to the actual tuwunel endpoint
+                  # without needing a `matrix.` subdomain.
+                  #
+                  # `m.homeserver.base_url` advertises the client-server
+                  # API. `m.server` advertises the federation
+                  # `host:port` (tuwunel serves both client + federation
+                  # on the same `httpPort` — see hive-matrix.nix).
+                  #
+                  # CORS `*` on the client endpoint per the matrix spec
+                  # (https://spec.matrix.org/v1.15/client-server-api/#getwell-knownmatrixclient).
+                  # No-op until the operator turns matrix on; until then
+                  # there's no homeserver to advertise.
+                  lib.optionalAttrs (matrixCfg.enable && hyperhiveDomain != null) {
+                    "= /.well-known/matrix/client" = {
+                      extraConfig = ''
+                        default_type application/json;
+                        add_header Access-Control-Allow-Origin *;
+                        return 200 '{"m.homeserver":{"base_url":"http://${hyperhiveDomain}:${toString matrixCfg.httpPort}"}}';
+                      '';
+                    };
+                    "= /.well-known/matrix/server" = {
+                      extraConfig = ''
+                        default_type application/json;
+                        return 200 '{"m.server":"${hyperhiveDomain}:${toString matrixCfg.httpPort}"}';
+                      '';
+                    };
+                  }
                 // {
                   # Everything else proxies to hive-c0re. Upgrade
                   # headers stay set so SSE (`/dashboard/stream`,

nix/modules/hive-matrix.nix

@@ -7,8 +7,7 @@
 let
   cfg = config.services.hyperhive.matrix;
   hyperhiveDomain = config.services.hyperhive.domain;
-  effectiveServerName =
-    if cfg.serverName != null then cfg.serverName else "matrix.${hyperhiveDomain}";
+  effectiveServerName = if cfg.serverName != null then cfg.serverName else hyperhiveDomain;
 in
 {
   # Private Matrix homeserver (matrix-tuwunel — the official conduwuit
@@ -77,10 +76,21 @@ in
         (`@argus:<server_name>`) and room ID minted on this
         homeserver. CRITICAL: must be stable from day one because
         it's embedded irrevocably in the identifiers. Defaults to
-        `matrix.''${services.hyperhive.domain}` (always a subdomain — keeps
-        the root domain free for the dashboard or forge). Override
-        here only if you need a name that doesn't follow the
-        `matrix.<domain>` shape.
+        `services.hyperhive.domain` (the bare hive domain — per mara
+        on #660). Combined with the `.well-known/matrix/{client,server}`
+        routes the hive-gateway serves at that domain (also #660),
+        clients auto-discover the actual matrix endpoint without
+        needing a subdomain. Override here only if you need a
+        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.
       '';
     };