diff --git a/docs/networking/gateway.md b/docs/networking/gateway.md
index e251bd60..cbf87e18 100644
--- a/docs/networking/gateway.md
+++ b/docs/networking/gateway.md
@@ -73,7 +73,7 @@ Each location carries a duplicated `auth_basic` block (separate locations don't
 Operator decision: sub-domain over sub-path for forge + matrix, sub-path for per-agent UIs.
 
 - forgejo's default `ROOT_URL = http://<host>/` works without any `X-Forwarded-Prefix` gymnastics — sub-domain hosting is the canonical Forgejo deploy shape.
-- matrix-spec deployments universally use `matrix.<server_name>` for the actual API listener — federation already expects this.
+- matrix-spec deployments universally use `matrix.<server_name>` for the actual API listener — federation already expects this. (`gatewayHost`'s own default departs from that convention — `chat.<swarm-domain>`, not `matrix.<server_name>` — since `serverName` is swarm-wide but `gatewayHost` is per-hive; operators who want the spec-conventional label can still set it explicitly.)
 - per-agent UIs are hyperhive-internal and base-path-aware specifically for `/agent/<name>/`. Sub-domain per agent would multiply DNS + TLS-per-subdomain cost without per-app config wins.
 - cookie / storage isolation: a future forge XSS can't reach the dashboard session because they're different origins.
 
diff --git a/nix/agent-modules/matrix.nix b/nix/agent-modules/matrix.nix
index 691a2005..37dcaeb8 100644
--- a/nix/agent-modules/matrix.nix
+++ b/nix/agent-modules/matrix.nix
@@ -63,7 +63,8 @@ in
     description = ''
       Matrix homeserver URL the agent's `hive-matrix-daemon` connects
       to. hive-c0re writes this per agent from the hive's own
-      isolation-aware URL (`matrix.<domain>` via the gateway), so a
+      isolation-aware URL (`gatewayHost`'s vhost via the gateway,
+      `chat.<swarm-domain>` by default), so a
       generated agent config always carries a real value; set it by
       hand only when an agent should talk to an external homeserver
       instead (a federation-only setup, or a remote hive's tuwunel
@@ -246,7 +247,8 @@ in
         RUST_LOG = "info";
       }
       # Homeserver URL. hive-c0re writes this option per agent from the
-      # hive's own `matrix.<domain>` gateway URL (agents run in a private
+      # hive's own gateway URL (`gatewayHost`'s vhost, `chat.<swarm-domain>`
+      # by default — agents run in a private
       # netns and cannot reach host loopback), so on a real hive it is
       # always set; `null` is the honest "this agent has no homeserver"
       # and leaves the daemon without one, which it treats like a missing
diff --git a/nix/host-modules/hive-c0re/environment.nix b/nix/host-modules/hive-c0re/environment.nix
index 5a56cf7b..9dbecbe3 100644
--- a/nix/host-modules/hive-c0re/environment.nix
+++ b/nix/host-modules/hive-c0re/environment.nix
@@ -234,7 +234,7 @@ in
     )
     {
       # Browser-facing matrix GUI (fluffychat) URL — the gateway
-      # vhost (`matrix.<domain>`). Surfaced via the daemon's `Urls`
+      # vhost (`gatewayHost`, `chat.<swarm-domain>` by default). Surfaced via the daemon's `Urls`
       # request for `hivectl open matrix`. Absent when the GUI is off
       # or no gatewayHost is set (no browser-reachable matrix vhost).
       HIVE_MATRIX_PUBLIC_URL = "https://${config.services.hyperhive.swarm.matrix.gatewayHost}/";
diff --git a/nix/host-modules/hive-gateway/vhosts.nix b/nix/host-modules/hive-gateway/vhosts.nix
index 7c4b1ce9..1e0491f3 100644
--- a/nix/host-modules/hive-gateway/vhosts.nix
+++ b/nix/host-modules/hive-gateway/vhosts.nix
@@ -42,8 +42,9 @@ let
   publicPort = cfg.httpsPort;
   publicPortSuffix = if publicPort == 443 then "" else ":${toString publicPort}";
 
-  # `<hive>/matrix/*` → 301 → `matrix.<hive>/$1` (legacy deep-link
-  # shim during the fluffychat sub-domain move). See `docs/networking/gateway.md`.
+  # `<hive>/matrix/*` → 301 → `gatewayHost`'s vhost/$1 (`chat.<swarm-domain>`
+  # by default; legacy deep-link shim during the fluffychat sub-domain move).
+  # See `docs/networking/gateway.md`.
   matrixRedirectLocations =
     lib.optionalAttrs
       (matrixDeployCfg.enable && matrixDeployCfg.gui.enable && matrixCfg.gatewayHost != null)
diff --git a/nix/host-modules/hive-matrix.nix b/nix/host-modules/hive-matrix.nix
index 49861540..9ede108a 100644
--- a/nix/host-modules/hive-matrix.nix
+++ b/nix/host-modules/hive-matrix.nix
@@ -156,7 +156,8 @@ let
 in
 {
   # Private matrix-tuwunel homeserver wrapped in a nixos-container,
-  # optional fluffychat-web client at matrix.<hive>/. Container shape,
+  # optional fluffychat-web client at chat.<swarm-domain>/ (gatewayHost's
+  # default). Container shape,
   # serverName vs gatewayHost split, provisioning flow (registration
   # token + LoadCredential), assertion rationale, initial rollout
   # settings: docs/integrations/matrix.md. Vhost map + discovery flow + tuning
@@ -347,7 +348,8 @@ in
           the three files `flutter341.buildFlutterApplication` skips.
         '';
         description = ''
-          Static web client dist served at `matrix.<hive>/`. Override
+          Static web client dist served at `gatewayHost`'s vhost
+          (`chat.<swarm-domain>` by default). 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 "/">`,
@@ -410,8 +412,8 @@ in
       description = ''
         Open `httpPort` in the host firewall. Off by default
         (secure-by-default): the host reaches the homeserver on
-        loopback, and agent containers reach it at `matrix.<domain>`
-        via the gateway — so the firewall open only matters for
+        loopback, and agent containers reach it at `gatewayHost`'s vhost
+        (`chat.<swarm-domain>` by default) via the gateway — so the firewall open only 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.
@@ -498,9 +500,8 @@ in
       default = deployCfg.matrix.enable;
       defaultText = lib.literalExpression "config.services.hyperhive.deploy.matrix.enable";
       description = ''
-        Serve a matrix web client at `matrix.''${services.hyperhive.domain}/`.
-        Requires `swarm.matrix.gatewayHost != null` (default `matrix.<hive>`
-        when hive-domain set); the gateway itself always runs. When
+        Serve a matrix web client at `gatewayHost`'s vhost (`chat.<swarm-domain>`
+        by default). Requires `gatewayHost != null`; the gateway itself always runs. When
         off, the dashboard's `M4TR1X →` tab is hidden. See
         `docs/networking/gateway.md` for the discovery flow that lets clients
         auto-find the sub-domain. The client build itself is