nix/hive-matrix: trim option-description prose to docs/gateway.md refs (argus #775 🔴)

argus on #775 v3: "the `gatewayHost` option description's
server_name-vs-gatewayHost essay + federation SRV note are also
candidates for [docs/gateway.md] section."

Cuts the gatewayHost option's description from ~40 lines (with
inline duplication of the discovery flow, when-to-set-which, and
federation port caveat) down to ~8 lines pointing at
`docs/gateway.md`. The brief `server_name vs gatewayHost` clarifier
stays in code because it disambiguates two SIMILAR-LOOKING options
on the same module — operators reading option docs need the
distinction inline, not behind a doc link.

Also trimmed `matrix.gui.enable` + `matrix.gui.package` descriptions
to similar shapes — point at docs/gateway.md for the architecture,
keep the override-shape hints in code.

Push includes the rebase onto current main (#764 + 0af6ea1 + others
landed since #775 was opened; cherry-picked commits get skipped
cleanly).

Net: matrix.nix loses ~70 lines of inline prose. No behavioral
change (verified gatewayHost still resolves to `matrix.<hive>`).

nix/modules/hive-matrix.nix

@@ -205,49 +205,17 @@ in
       '';
       example = "matrix.example.com";
       description = ''
-        Public hostname for the matrix homeserver behind the
-        hive-gateway nginx (#747, mara verdict on #749:9609 — sub-domain
-        over sub-path for matrix, but **not user-visible** because the
-        `.well-known/matrix/{client,server}` redirect routes clients
-        through automatically).
+        Public hostname for the matrix homeserver behind the gateway.
+        Defaults to `matrix.''${services.hyperhive.domain}` (sub-domain
+        shape per mara on #749:9609). Set to `null` to skip the gateway
+        vhost (tuwunel stays direct on `httpPort`). See
+        `docs/gateway.md` for the vhost map + matrix discovery flow,
+        and the federation port-8448 caveat at the bottom of that doc.
 
-        When set + gateway is on, the gateway adds a `server { server_name
-        = gatewayHost; }` block that proxies `/_matrix/...` →
-        `http://127.0.0.1:''${httpPort}/_matrix/...`. The
-        `.well-known/matrix/{client,server}` endpoints (served by the
-        gateway at the bare hive-domain) then point at
-        `http(s)://''${gatewayHost}/` — matrix clients automatically
-        discover + follow that delegation.
-
-        Defaults to `matrix.''${services.hyperhive.domain}` when the
-        hive-domain is set (idiomatic matrix-spec shape — `matrix`
-        labelled under the hive's bare server_name domain). Defaults to
-        `null` when the hive-domain is unset (gateway vhost not added;
-        clients reach tuwunel directly on `httpPort`).
-
-        Set to a full hostname (`matrix.example.com`,
-        `homeserver.internal.lan`) for a bespoke vhost shape. Set to
-        `null` to disable the gateway vhost entirely (tuwunel stays
-        direct on `httpPort`).
-
-        **server_name vs gatewayHost**: `serverName` is the matrix
-        identifier domain embedded in user/room IDs irrevocably (per
-        #660 default = bare hive-domain). `gatewayHost` is just where
-        the API listens behind nginx. The two are different — see the
-        matrix-spec server-discovery flow.
-
-        **Federation port caveat**: the `.well-known/matrix/server`
-        delegation advertises `''${gatewayHost}` with no port suffix
-        when the gateway listens on 80. Per the matrix federation
-        spec, peers fall back to port 8448 when no explicit port is
-        present — but the gateway only listens on the configured
-        `services.hyperhive.gateway.port`. Cross-hive federation
-        therefore needs either:
-        - a DNS SRV record (`_matrix._tcp.''${gatewayHost}` → port 80),
-        - or `services.hyperhive.matrix.openFirewall = true` so peers
-          can reach tuwunel's federation port directly.
-        Hyperhive is mostly closed/internal, so this rarely bites in
-        practice — but flagging for the federation-curious operator.
+        Note: `gatewayHost` is the API listener hostname (where nginx
+        proxies `/_matrix/*`); `serverName` is the matrix-identifier
+        domain embedded irrevocably in user/room IDs (per #660
+        default = bare hive-domain). The two are distinct.
       '';
     };
 
@@ -326,23 +294,12 @@ in
         default = cfg.enable;
         defaultText = lib.literalExpression "config.services.hyperhive.matrix.enable";
         description = ''
-          Serve a matrix web client (default `pkgs.fluffychat-web`) as
-          a static dist at the root of the matrix sub-domain vhost
-          (`matrix.''${services.hyperhive.domain}/`, via the hive-gateway
-          nginx — #607 / #634 / #772). Defaults to whatever
-          `services.hyperhive.matrix.enable` is — turning on the
-          homeserver gives you the web client by default; set to
-          `false` explicitly to opt out of the GUI while keeping the
-          homeserver running for agents. Requires
-          `services.hyperhive.gateway.enable` (default on) +
-          `services.hyperhive.matrix.gatewayHost != null` (default
-          `matrix.<hive>`); when either is off no one hosts the GUI
-          and the `M4TR1X →` dashboard tab is hidden.
-
-          The `.well-known/matrix/{client,server}` delegation (served
-          on the bare hive-domain) advertises this sub-domain, so
-          clients opened at `http://<hive>/` auto-discover the
-          fluffychat root automatically.
+          Serve a matrix web client at `matrix.''${services.hyperhive.domain}/`.
+          Requires `gateway.enable` + `matrix.gatewayHost != null`
+          (default true / `matrix.<hive>` when hive-domain set). When
+          off, the dashboard's `M4TR1X →` tab is hidden. See
+          `docs/gateway.md` for the discovery flow that lets clients
+          auto-find the sub-domain.
         '';
       };
 
@@ -350,25 +307,15 @@ in
         type = lib.types.package;
         default = fluffychat-web-fixed;
         defaultText = lib.literalMD ''
-          `pkgs.fluffychat-web` patched via `postInstall` to add the
-          three files `flutter341.buildFlutterApplication` skips:
-          `native_executor.js` (compiled via `dart compile js` from
-          `web/native_executor.dart`), plus `Imaging.js` +
-          `Imaging.wasm` (built from the `native_imaging` dart
-          package's C source via `pkgs.emscripten`). See the `let`
-          block in `nix/modules/hive-matrix.nix` for the full
-          rationale (#685, #772).
+          `pkgs.fluffychat-web` + #685 `postInstall` patch (adds the
+          three files `flutter341.buildFlutterApplication` skips).
         '';
         description = ''
-          Static web client dist to serve at the matrix sub-domain
-          root (`matrix.''${services.hyperhive.domain}/`). Defaults
-          to `pkgs.fluffychat-web` with the #685 `postInstall` patch
-          for the three missing files. Override to swap for
-          `hydrogen-web` (lightest), `cinny` (no threads),
-          `element-web` (heaviest, full features), or an out-of-tree
-          client dist — any replacement gets served at the sub-domain
-          root with the upstream-default `<base href "/">`, no
-          sub-path gymnastics needed.
+          Static web client dist served at `matrix.<hive>/`. Override
+          to swap fluffychat for hydrogen-web, cinny, element-web, or
+          an out-of-tree dist — any replacement is mounted at the
+          sub-domain root with the upstream-default `<base href "/">`,
+          no sub-path gymnastics needed.
         '';
       };
     };