docs/web-ui/README.md

@@ -10,8 +10,9 @@ below; this page only covers what you actually do here.
 
 Everything starts at the **H0M3 hub**, served at `/` — a grid of tiles
 linking to every surface (Dashboard, Flow, Logs, Builds, Stats,
-Settings, Core, Credentials). Every page links back to H0M3, so you're
+Settings, Core, Credentials, plus Matrix/Forge when enabled). Every
-never more than one click from the hub.
+page links back to H0M3, so you're never more than one click from the
+hub.
 
 The **dashboard** itself (`/dashboard.html`) is where you'll spend most
 of your time. It's a single page with exactly four tabs:

docs/web-ui/dashboard.md

@@ -636,11 +636,9 @@ nginx container at `/matrix/` when
 `HIVE_MATRIX_GUI_ENABLED` env var → `state.matrix_gui_enabled` in
 `/api/state`; the gateway does the actual static serving.
 
-There's no tile for it on the H0M3 hub (removed along with Forge's —
+The operator opens `/matrix/` from the Matrix tile on the H0M3 hub, logs
-see the H0M3 section above). The operator reaches it from the swarm-ui
+in once with the in-host tuwunel homeserver URL
-LinksMenu instead (see `docs/swarm/ui.md::Quick links`), and logs in
+(`http://localhost:8008` or whatever the matrix module exposes).
-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://chat.${hyperhive.swarm.domain}` + `.well-known/matrix/client`
@@ -689,16 +687,25 @@ re-renders the terminal row. The root agent is addressed as `@root`.
 ## H0M3 page (`/`)
 
 The H0M3 hub is the primary landing page (served at `/` by default). A
-responsive grid of link tiles — Dashboard, Flow, Logs, Builds, Stats,
+responsive grid of link tiles — Dashboard, Flow, Logs, Matrix (when enabled),
-Settings, Core, Credentials, API — each pointing to their respective
+Forge (when enabled), among others (Builds, Stats, Settings, Core,
-surfaces, all unconditionally shown (no gating). The page is a pure
+Credentials, API) — each pointing to their respective surfaces. The **API**
-portal with no tab-bar or SSE subscriptions. Typography + colours inherit
+tile always shows (unlike Matrix/Forge, see below) and links to the
-from the shared theme (Catppuccin Mocha via `common.css` + `theme.css`).
+Swagger UI at `/api/docs`. The page
-`home.js` fills the swarm/hive identity line at the top. All dashboard
+is a pure portal with no tab-bar or SSE subscriptions. Typography + colours
-sub-pages include a `← Home` back-link for navigation.
+inherit from the shared theme (Catppuccin Mocha via `common.css` + `theme.css`).
-
+Optional tiles are hidden until `home.js` confirms their availability:
-No Matrix or Forge tile here — those surfaces (`/matrix/`, the forge's own
+Matrix is hidden until `home.js` confirms `matrix_gui_enabled` (same gating as
-public URL) are reached directly, not linked from the dashboard UI.
+the dashboard's M4TR1X tab); Forge is hidden until `home.js` confirms both
+`state.forge_present` **and** `state.forge_public_url` (sourced from
+`services.hyperhive.forge.publicUrl`, which defaults to the gateway vhost URL
+when `behindGateway=true` and is `null` otherwise) and fills the href from the
+latter — never guessed from the operator's browser hostname + a container
+port, which is only right by accident off plain localhost. Operators without
+matrix or forge enabled — or with forge on but no public URL configured —
+never see a dead or wrong link. `home.js` also fills the swarm/hive identity
+line at the top. All dashboard sub-pages include a `← Home` back-link for
+navigation.
 
 ## L0GS page (`/logs.html`)
 

frontend/packages/dashboard/src/home.js

@@ -1,7 +1,9 @@
 // H0M3 page script. The page is static markup; this only does
 // a few small things off a single `/api/state` read:
-//   1. fill the swarm/hive identity line when configured;
+//   1. reveal the Matrix tile when the matrix GUI is enabled (same
-//   2. render the shared server-warnings banner (top of every page).
+//      gating as the dashboard's M4TR1X tab — no dead link otherwise);
+//   2. fill the swarm/hive identity line when configured;
+//   3. render the shared server-warnings banner (top of every page).
 // No SSE — a portal doesn't need live updates.
 //
 // It also drives the decorative matrix-rain backdrop (#matrix-rain) —
@@ -23,6 +25,25 @@ async function init() {
 
   renderServerWarnings(state.server_warnings);
 
+  if (state.matrix_gui_enabled) {
+    const tile = $('home-tile-matrix');
+    if (tile) tile.hidden = false;
+  }
+
+  // Forge tile: reveal only when the hive-forge container is up AND
+  // the operator has stated a public URL for it
+  // (services.hyperhive.forge.publicUrl, surfaced as
+  // state.forge_public_url) — hidden rather than guessed from
+  // `location.hostname` + the direct :3000 port, which is only
+  // correct by accident on deployments that aren't plain localhost.
+  if (state.forge_present && state.forge_public_url) {
+    const tile = $('home-tile-forge');
+    if (tile) {
+      tile.href = state.forge_public_url;
+      tile.hidden = false;
+    }
+  }
+
   const ident = $('hive-identity');
   if (ident && (state.swarm_name || state.hive_name)) {
     const parts = [state.swarm_name, state.hive_name].filter(Boolean);

frontend/packages/dashboard/src/index.html

@@ -100,9 +100,9 @@
         <span class="home-tile-desc">provision per-agent matrix + github accounts</span>
       </a>
 
-      <!-- API tile: the OpenAPI spec + Swagger UI are always served by
+      <!-- API tile: no gating, unlike Forge/Matrix below — the OpenAPI
-           hive-c0re itself (docs/web-ui/dashboard.md::Dashboard
+           spec + Swagger UI are always served by hive-c0re itself
-           endpoints), so this tile is never gated/hidden. -->
+           (docs/web-ui/dashboard.md::Dashboard endpoints). -->
       <a class="home-tile" href="/api/docs">
         <span class="home-tile-head">
           <span class="home-tile-icon" aria-hidden="true">🧬</span>
@@ -111,6 +111,29 @@
         <span class="home-tile-desc">interactive OpenAPI spec (Swagger UI)</span>
       </a>
 
+      <!-- Forge tile: hidden until home.js confirms the hive-forge
+           container is up (state.forge_present); home.js also fills the
+           href from state.forge_public_url (or the :3000 fallback), so
+           operators without a forge never see a dead link. -->
+      <a class="home-tile" id="home-tile-forge" href="#" target="_blank" rel="noopener" hidden>
+        <span class="home-tile-head">
+          <span class="home-tile-icon" aria-hidden="true">⚒</span>
+          <span class="home-tile-label">Forge</span>
+        </span>
+        <span class="home-tile-desc">issues · pull requests · agent-config repos</span>
+      </a>
+
+      <!-- Matrix tile: hidden until home.js confirms the matrix GUI is
+           enabled (state.matrix_gui_enabled), mirroring the dashboard
+           tab gating so operators without it don't see a dead link. -->
+      <a class="home-tile" id="home-tile-matrix" href="/matrix/" hidden>
+        <span class="home-tile-head">
+          <span class="home-tile-icon" aria-hidden="true">💬</span>
+          <span class="home-tile-label">Matrix</span>
+        </span>
+        <span class="home-tile-desc">matrix chat client</span>
+      </a>
+
     </nav>
   </main>
   </div><!-- /.page-content -->

frontend/packages/dashboard/src/tabs.js

@@ -188,8 +188,8 @@ window.marked = marked;
       // names from here instead of refetching on every keystroke).
       window.__hyperhive_state = s;
       renderServerWarnings(s.server_warnings);
-      // (The M4TR1X surface is reachable directly at /matrix/ when enabled
+      // (The M4TR1X surface is reachable from the H0M3 hub now, not the
-      // — no link in the dashboard tab strip or the H0M3 hub.)
+      // dashboard tab strip — home.js gates its tile on matrix_gui_enabled.)
       // Hive identity: render the swarm/hive name as a headline at the
       // top of the SW4RM pane + update the page title once the
       // server-side display names are known. `hive_name` / `swarm_name`

nix/host-modules/hive-matrix.nix

@@ -513,12 +513,10 @@ in
 
     # This swarm-ui quick-links entry. Gated on `gui.enable` too, not just
     # `gatewayHost != null`: `/` on that vhost only serves fluffychat
-    # (below) when the GUI is on — otherwise the link would 404. Same
+    # (below) when the GUI is on — otherwise the link would 404, the same
-    # `gatewayHost && gui.enable` condition the removed hive-dashboard
+    # reason the old dashboard's H0M3 page hides its Matrix tile on
-    # H0M3 tile used to check via `state.matrix_gui_enabled` before this
+    # `state.matrix_gui_enabled` rather than `gatewayHost` alone. See
-    # link became the only way in (docs/web-ui/dashboard.md::M4TR1X
+    # `services.hyperhive.swarm.controller.links`'s description.
-    # page). See `services.hyperhive.swarm.controller.links`'s
-    # description.
     services.hyperhive.swarm.controller.links =
       lib.optional (cfg.gatewayHost != null && cfg.gui.enable)
         {