docs(networking): facts + structure pass on gateway, network, jobq, observability, matrix

gateway.md: split the opener into what/audience/enable; vhost map in two
tables (swarm-service vhosts declared by their own modules, then the hive
vhost) matching vhosts.nix and the service modules; gateway.enable exists
and is set with mkDefault by the modules that need it; Basic auth scope,
dashboard /health/ prefix, error-page rendering, matrix body limit and
forge link source corrected; nginx internals grouped under one Internals
section with their headings unchanged.

network.md: gateway and dnsmasq run on the host, not in a container;
network.enable is set by the modules that need it; shared-netns firewall
rule covers every swarm service container; hive-priv writes the nspawn
conf; domain sentence rewritten; removed options moved into <details>.

jobq.md: swarm-controller runs its own graph; swarm UI /jobs and BU1LDS
show different graphs drawn by the same component.

observability.md: swarm tier first; history narration cut; network access
deduplicated into a link to network.md; options link made absolute.

matrix.md: swarm.matrix vs deploy.matrix namespaces; tuning, firewall and
SSO options under deploy.matrix; .well-known is served on the hive domain;
roadmap sentence deleted; stale hive-c0re provisioning claims fixed;
serverName upgrade note moved into <details>.

Refs #3902

docs/integrations/matrix.md

@@ -2,9 +2,16 @@
 
 Private Matrix homeserver (matrix-tuwunel — the conduwuit
 successor) wrapped in a nixos-container, plus optional fluffychat-web
-client at `chat.<swarm-domain>/` (the `gatewayHost` vhost). Configured via
-`services.hyperhive.swarm.matrix.*`; vhost routing lives in
-[`gateway.md`](../networking/gateway.md).
+client at `chat.<swarm-domain>/` (the `gatewayHost` vhost). A swarm runs one
+homeserver, on one host. Two namespaces configure it:
+
+- `services.hyperhive.swarm.matrix.*` — what the homeserver **is**, as
+  every hive sees it: `serverName`, `gatewayHost`, ports, `allowEncryption`.
+- `services.hyperhive.deploy.matrix.*` — what the host running it decides:
+  `enable`, `gui.enable`, `openFirewall`, `trustedServers`,
+  `maxRequestSize`, `sso.clientSecretFile`.
+
+Vhost routing lives in [`gateway.md`](../networking/gateway.md).
 
 ## Container shape
 
@@ -33,9 +40,10 @@ Two distinct hostnames:
   *irrevocably* in every `@user:<server_name>` and `!room:<server_name>`
   identifier minted on this homeserver. You can't change it later
   without abandoning every account and chat history. Defaults to the
-  bare `services.hyperhive.swarm.domain`; clients autodiscover the
-  actual API endpoint via the `.well-known/matrix/{client,server}`
-  routes the gateway serves at that domain.
+  bare `services.hyperhive.swarm.domain`. The gateway serves the
+  `.well-known/matrix/{client,server}` discovery routes on the matrix
+  host's **hive** domain, not the swarm domain
+  ([Discovery flow](../networking/gateway.md#discovery-flow-matrix)).
 - **`gatewayHost`** — the API listener hostname, where the gateway's
   matrix vhost proxies `/_matrix/*` to tuwunel. Defaults to
   `chat.<services.hyperhive.swarm.domain>`. Set to `null` to skip the
@@ -54,12 +62,12 @@ room id, so 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
+<details><summary>Upgrading a homeserver that already has ids</summary>
 
-`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:
+A homeserver that minted ids under an older `serverName` default must
+**pin the value it actually minted them under**, not adopt the current
+default — see above for why adopting a new one strands existing users
+and rooms:
 
 ```nix
 services.hyperhive.swarm.matrix = {
@@ -71,13 +79,14 @@ services.hyperhive.swarm.matrix = {
 
 A rebuild on a host that already has a homeserver prints a
 `hive-matrix: WARNING — … serverName is unset` line when this is missing,
-naming the value it's about to default to. That warning is why this
-section exists; it never fails the rebuild, so it's on you to act on it
-before the homeserver mints the ids.
+naming the value it's about to default to. It never fails the rebuild, so act on
+it before the homeserver mints the ids.
+
+</details>
 
 ## Default-closed firewall
 
-`openFirewall` defaults to `false` (secure-by-default): the host
+`deploy.matrix.openFirewall` defaults to `false`: the host
 reaches the homeserver on loopback, and agent containers reach it
 at `chat.<swarm-domain>` via the gateway — so the firewall hole only
 matters for access from *outside* the host. Flip to `true` when
@@ -198,9 +207,8 @@ tuwunel has none.
 Promoting a user to homeserver admin and resetting a password both need an
 admin **sender**: `!admin …` messages into `#admins:<server_name>`, and
 tuwunel only treats a message as a command when its sender is already an
-admin. `@hive-<hive>:` has no admin sender to make that call with. They're
-swarm-level operations: matrix admin should eventually come from
-membership in authelia's `admins` group; nobody has built that sync yet.
+admin. `@hive-<hive>:` has no admin sender to make that call with. Both are
+swarm-level operations.
 
 <details><summary>Upgrading a hive that shared one sender account with every other hive</summary>
 
@@ -274,8 +282,8 @@ Initial rollout settings:
   restart. `trusted_servers = []` keeps it effectively closed
   until you list peers.
 - `allow_registration = false`. tuwunel checks this flag only for
-  requests that arrive **without** an appservice token, so hive-c0re
-  provisions exactly as before and tuwunel refuses everyone else. It's not a
+  requests that arrive **without** an appservice token, so the appservices
+  still create accounts and tuwunel refuses everyone else. It's not a
   hardening afterthought: with no registration token configured,
   `allow_registration = true` makes tuwunel refuse to start unless
   `yes_i_am_very_very_sure_…_open_registration_…` is also set.
@@ -298,8 +306,7 @@ Initial rollout settings:
 
 ## Hive Matrix Space
 
-On first boot, after hive-c0re provisions all agent accounts, it
-creates a private **Matrix Space** named `"hive"` using its own hive
+On first boot hive-c0re creates a private **Matrix Space** named `"hive"` using its own hive
 account (`@hive-<hive>:<server_name>`) and invites every provisioned agent
 into it. This gives the operator a single Space in FluffyChat or any
 Matrix client that groups all agent-to-agent + operator rooms in one
@@ -331,7 +338,7 @@ re-creation (for example after a homeserver wipe).
 ## Configuration tuning
 
 ```nix
-services.hyperhive.swarm.matrix = {
+services.hyperhive.deploy.matrix = {
   trustedServers  = [ "matrix.org" "example.com" ];   # default: []
   maxRequestSize  = 20000000;                          # default: 20 MB
 };
@@ -364,14 +371,14 @@ surprising behaviour:
 SSO is unconditional, so the three below are requirements of running a
 homeserver at all rather than of a setting:
 
-- **Set `sso.clientSecretFile`** — fails at eval, not at boot:
+- **Set `deploy.matrix.sso.clientSecretFile`** — fails at eval, not at boot:
   tuwunel reads its identity providers from the config file, so a
   half-configured one can stop the homeserver from starting outright
   rather than merely hiding a login button. On a host that also runs
   the swarm's authelia it's wired up for you.
 - **Set `swarm.authelia.url`** — without a provider URL there
   is nothing to discover against.
-- **Set `gatewayHost != null`** — the SSO callback URL is
+- **Set `swarm.matrix.gatewayHost != null`** — the SSO callback URL is
   format-locked to `<homeserver>/_matrix/client/unstable/login/sso/callback/<client_id>`,
   and the identity provider needs a public name to redirect the
   browser to.