From 3f2fdeac7012b8514dd6ecc48a9b96c9807baf67 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sun, 2 Aug 2026 19:02:46 +0200
Subject: [PATCH] docs: document the OpenAPI spec + Swagger UI, add H0M3 API
 tile
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #2965.

hive-c0re auto-generates an OpenAPI 3 spec via utoipa
(hive-c0re/src/dashboard/mod.rs's ApiDoc), served raw at
/api/openapi.json and browsable as a Swagger UI at /api/docs, but
docs/ never mentioned either — genuinely zero hits grepping the whole
docs/ tree. Documented both in docs/web-ui/dashboard.md's Dashboard
endpoints + H0M3 page sections.

Also added the H0M3 hub's API tile mara suggested ("maybe also add
home page app that opens swagger ui") -- a plain static link to
/api/docs, no gating needed since the endpoint always exists
(unlike Forge/Matrix, which are conditionally enabled).
---
 docs/web-ui/dashboard.md                   | 17 ++++++++++++++++-
 frontend/packages/dashboard/src/index.html | 11 +++++++++++
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md
index ae22d0b3..f059328f 100644
--- a/docs/web-ui/dashboard.md
+++ b/docs/web-ui/dashboard.md
@@ -720,7 +720,11 @@ re-renders the terminal row. The root agent is addressed as `@root`.
 
 The H0M3 hub is the primary landing page (served at `/` by default). A
 responsive grid of link tiles — Dashboard, Flow, Logs, Matrix (when enabled),
-Forge (when enabled) — each pointing to their respective surfaces. The page
+Forge (when enabled), among others (Builds, Stats, Settings, Core,
+Credentials, API) — each pointing to their respective surfaces. The **API**
+tile is a static link straight to `/api/docs` (the Swagger UI — see
+`## Dashboard endpoints` below), always shown since the endpoint always
+exists (no gating, unlike Matrix/Forge). The page
 is a pure portal with no tab-bar or SSE subscriptions. Typography + colours
 inherit from the shared theme (Catppuccin Mocha via `common.css` + `theme.css`).
 Optional tiles are hidden until `home.js` confirms their availability:
@@ -1148,6 +1152,17 @@ that's a browser-level decision, not ours.
 
 ## Dashboard endpoints
 
+Also browsable interactively: `hive-c0re` auto-generates an OpenAPI 3
+spec via [`utoipa`](https://docs.rs/utoipa) (`hive-c0re/src/dashboard/
+mod.rs`'s `ApiDoc`), served raw at `GET /api/openapi.json` and as a
+Swagger UI at `/api/docs` — same loopback dashboard port, reachable
+externally through the gateway's `/api/` proxy prefix like the rest of
+this list. It's deliberately incremental: only routes carrying a
+`#[utoipa::path(...)]` annotation appear, so it's not yet a complete
+mirror of the hand-written list below — an unannotated route still
+works, it just doesn't show up in the spec until someone adds the
+annotation. The H0M3 hub's **API** tile links straight to `/api/docs`.
+
 - `POST /api/approve/{id}` — approve a pending approval. Fires
   `ApprovalResolved` on the dashboard event channel; client
   updates derived approvals state from the event.
diff --git a/frontend/packages/dashboard/src/index.html b/frontend/packages/dashboard/src/index.html
index cabbc40a..1a15ecf5 100644
--- a/frontend/packages/dashboard/src/index.html
+++ b/frontend/packages/dashboard/src/index.html
@@ -100,6 +100,17 @@
         <span class="home-tile-desc">provision per-agent matrix + github accounts</span>
       </a>
 
+      <!-- API tile: no gating, unlike Forge/Matrix below — the OpenAPI
+           spec + Swagger UI are always served by hive-c0re itself
+           (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>
+          <span class="home-tile-label">API</span>
+        </span>
+        <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