From 822a1b15fa8f312626bf7b45da655aecabb1cf06 Mon Sep 17 00:00:00 2001
From: lexis <lexis@hyperhive>
Date: Sat, 30 May 2026 15:51:17 +0200
Subject: [PATCH] docs: matrix gui.enable defaults to matrix.enable, gateway
 serves /matrix/ (follow-up to #635)

---
 README.md      |  9 ++++++---
 docs/web-ui.md | 37 +++++++++++++++++++------------------
 2 files changed, 25 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 4a0a708e..6650dd2d 100644
--- a/README.md
+++ b/README.md
@@ -116,10 +116,13 @@ lives at `/var/lib/nixos-containers/hive-matrix/`. Federation is
 enabled with an empty `trusted_servers` list; e2ee is deferred to
 a follow-up (#551).
 
-Optional: set `services.hyperhive.matrix.gui.enable = true;` to serve a
+The hive-gateway nginx container serves a
 [fluffychat-web](https://fluffychat.im) matrix client at `/matrix/`
-via the hive-gateway nginx container (see gateway option above). Disabled by default. The `◆ M4TR1X ◆ →`
-tab appears in the dashboard chrome when enabled. The web client can
+when `services.hyperhive.matrix.gui.enable` is on. This defaults to
+`services.hyperhive.matrix.enable`, so enabling the homeserver enables
+the web client by default; set `gui.enable = false` explicitly to keep
+the homeserver without the GUI. The `◆ M4TR1X ◆ →` tab appears in
+the dashboard chrome when enabled. The web client can
 connect to any Matrix homeserver; enter the URL at first visit (e.g.
 the local tuwunel instance if `services.hyperhive.matrix.enable = true`, or
 any external homeserver).
diff --git a/docs/web-ui.md b/docs/web-ui.md
index 84179763..ec734dfd 100644
--- a/docs/web-ui.md
+++ b/docs/web-ui.md
@@ -145,10 +145,10 @@ cross-page link (`◆ FL0W ◆ →`), not a pane swap.
   count), Y3R C4LL (pending approvals + questions), and SCH3DUL3S
   (active schedules); FL0W pill mirrors the operator inbox length
   (hidden when zero). The M4TR1X → entry is hidden when
-  `hyperhive.matrix.gui.enable = false` (default) so operators
-  without the matrix GUI on don't see a dead link — tabs.js gates
-  the `hidden` attribute on `state.matrix_gui_enabled` from
-  `/api/state` (#607).
+  `services.hyperhive.matrix.gui.enable` is off (defaults to
+  `matrix.enable`) so operators without the matrix GUI on don't
+  see a dead link — tabs.js gates the `hidden` attribute on
+  `state.matrix_gui_enabled` from `/api/state` (#607).
 - **Notification controls**: `🔔 enable notifications` when
   permission ungranted; `🔕 mute / 🔔 unmute` toggle once granted.
   Always visible in the chrome regardless of active tab.
@@ -307,21 +307,22 @@ operator has one place for everything time-fired (#460).
 
 ### M4TR1X page (`/matrix/`, optional)
 
-A static matrix web client (default `pkgs.fluffychat-web`, swappable
-via `hyperhive.matrix.gui.package`) mounted by hive-c0re's dashboard
-router as a sibling `nest_service("/matrix", ServeDir::new(dir))`
-when `hyperhive.matrix.gui.enable = true` + `HIVE_MATRIX_GUI_DIR` env
-points at the dist root. Same-origin with the dashboard; the
-operator opens `/matrix/` in the same tab from the M4TR1X → strip
-entry, logs in once with the in-host tuwunel homeserver URL
-(`http://localhost:8008` or whatever the matrix module exposes),
-then has matrix chat alongside the agent dashboard without leaving
-the host's origin.
+A static matrix web client (default `pkgs.fluffychat-web` rebuilt
+with `--base-href /matrix/`, swappable via
+`services.hyperhive.matrix.gui.package`) served by the hive-gateway
+nginx container at `/matrix/` when
+`services.hyperhive.matrix.gui.enable` is on (defaults to
+`matrix.enable`, #635). c0re signals availability via the
+`HIVE_MATRIX_GUI_ENABLED` env var → `state.matrix_gui_enabled` in
+`/api/state`; the gateway does the actual static serving.
 
-v0 same-origin shape via hive-c0re ServeDir (#607 / #610); the
-unified nginx-front re-root to `https://matrix.${hyperhive.domain}`
-+ `.well-known/matrix/client` auto-discovery is tracked in #609
-(atlas's lane, post-#15).
+The operator opens `/matrix/` from the M4TR1X → strip entry, logs
+in once with the in-host tuwunel homeserver URL
+(`http://localhost:8008` or whatever the matrix module exposes).
+
+The unified nginx-front re-root to
+`https://matrix.${hyperhive.domain}` + `.well-known/matrix/client`
+auto-discovery is tracked in #609 (atlas's lane, post-#15).
 
 ### FL0W page (`/flow.html`)