From f0271f95e4250b5ca08475b74f77c2c794bb9e6e Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Thu, 4 Jun 2026 20:14:58 +0200
Subject: [PATCH] docs(web-ui): update dashboard.md for dashboard-state
 endpoint
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the stale GET /api/agent/{name}/links reference with
GET /api/dashboard-state (merged in #1292). The new endpoint is
served by the agent backend and returns DashboardState carrying
links, status_text, rate_limited, ctx_tokens, and
context_window_tokens — all agent-owned fields that were previously
(mis)read by hive-c0re from disk.

Also update the ctx_tokens description: it's now sourced from
DashboardState rather than ContainerView (which no longer carries
ctx_tokens/context_window_tokens).
---
 docs/web-ui/dashboard.md | 76 ++++++++++++++++++++--------------------
 1 file changed, 38 insertions(+), 38 deletions(-)

diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md
index 79f56f86..3d97d628 100644
--- a/docs/web-ui/dashboard.md
+++ b/docs/web-ui/dashboard.md
@@ -403,34 +403,36 @@ fallback fires immediately, skipping the doomed `<url>/icon`
 fetch entirely.
 
 - Line 1: agent name (link → new tab), m1nd/ag3nt chip, an
-  **icon-only nav strip** populated async from the agent backend
-  (`📊 stats`, `🖥 screen` when GUI is enabled, `⬡ forge profile`,
-  `↳ agent-configs mirror`, plus any agent-declared
-  `dashboardLinks` extras). The dashboard JS fetches
-  `GET /api/agent/{name}/links`, a same-origin passthrough proxy
-  that forwards the agent's own link list; the agent backend is
-  the single source of truth. The frontend resolves each
-  `AgentLink.kind` against a per-agent base URL that depends on
-  whether hive-gateway is in front (`StateSnapshot.gateway_enabled`,
-  sourced from the `HIVE_GATEWAY_ENABLED` env the c0re NixOS
-  module sets when `services.hyperhive.gateway.enable = true`).
-  Gateway-on (default): `container` → `/agent/<name>/<url>` (same
-  origin, gateway proxies to the per-agent harness — TCP or
-  unix-domain depending on the agent's `HIVE_WEB_SOCKET` opt-in,
-  see `docs/gateway.md::Per-agent unix-socket upstream`).
-  Gateway-off (legacy / local dev):
-  `container` → `http://<host>:<container.port>/<url>` (direct TCP
-  fallback). Forge links resolve against `http://<host>:3000`,
-  external links are already absolute. The same flag drives the
-  primary agent-name link + favicon fetch (`<url>/icon`), so the
-  whole row routes through the gateway as a unit.
+  **icon-only nav strip** plus live agent-owned state, all populated
+  async from a single `GET /api/dashboard-state` call to the
+  agent's own backend. The response (`DashboardState`) carries:
+  `links` (nav strip entries — `📊 stats`, `🖥 screen` when GUI is
+  enabled, `⬡ forge profile`, `↳ agent-configs mirror`, plus any
+  agent-declared `dashboardLinks` extras), `status_text` /
+  `status_set_at` (agent self-reported status), `rate_limited`,
+  `ctx_tokens` / `context_window_tokens` (context-window badge
+  data). The agent backend is the single source of truth for all
+  of these. The dashboard resolves each `AgentLink.kind` against a
+  per-agent base URL depending on whether hive-gateway is in front
+  (`StateSnapshot.gateway_enabled`, sourced from the
+  `HIVE_GATEWAY_ENABLED` env the c0re NixOS module sets when
+  `services.hyperhive.gateway.enable = true`). Gateway-on (default):
+  base URL is `/agent/<name>` (same origin, gateway proxies to the
+  per-agent harness — TCP or unix-domain depending on the agent's
+  `HIVE_WEB_SOCKET` opt-in, see
+  `docs/gateway.md::Per-agent unix-socket upstream`).
+  Gateway-off (legacy / local dev): base URL is
+  `http://<host>:<container.port>` (direct TCP fallback). Forge
+  links resolve against `http://<host>:3000`, external links are
+  already absolute. The same base URL drives the primary agent-name
+  link + favicon fetch, so the whole row routes through the gateway
+  as a unit.
   **When the container is stopped** (`ContainerView.running = false`),
-  the host clears live-only fields before emitting the state, so
-  the dashboard never renders stale data: the badge chain is
-  replaced by a single muted `■ not running` badge, the nav-strip
-  fetch is skipped (the agent web server is down), and the
-  self-reported status text is suppressed. The agent icon goes
-  straight to the dimmed `/favicon.svg` fallback instead of
+  the async `dashboard-state` fetch is skipped entirely (the agent
+  web server is down), so the badge chain is replaced by a single
+  muted `■ not running` badge, the nav strip is empty, and status
+  text / rate-limited / ctx badges are suppressed. The agent icon
+  goes straight to the dimmed `/favicon.svg` fallback instead of
   attempting a doomed load from the container's URL. Static fields
   — `needs_update`, `deployed_sha`, `pending_reminders`, `parent`,
   `config` link — remain visible regardless of run state.
@@ -465,17 +467,15 @@ fetch entirely.
   `opRunning` flag (driving the `pending-running` row class +
   spinner) is true when (1) is set OR (2) is in `running` state;
   queued entries leave `opRunning` false.
-  Container name + port, and a `ctx · Nk` chip showing the
-  agent's last-turn context size (from `ContainerView.ctx_tokens`,
-  read from the turn-stats sqlite on each `build_all` sweep;
-  absent until the first turn). The chip colour (green / yellow /
-  red) is keyed off the model's real context window: `build_all`
-  resolves the last turn's model against the host's per-model
-  `contextWindowTokens` config and exposes it as
-  `ContainerView.context_window_tokens`; the badge goes yellow
-  ≥ 50% and red ≥ 75% of that window (the harness compaction
-  watermarks). When the window can't be resolved the badge falls
-  back to fixed 100k / 150k thresholds.
+  A `ctx · Nk` chip showing the agent's last-turn context size,
+  populated from `DashboardState.ctx_tokens` (absent until the
+  agent has completed at least one turn). The chip colour (green /
+  yellow / red) is keyed off `DashboardState.context_window_tokens`
+  (the real context window for the model the agent last ran on,
+  authoritative from the agent side); the badge goes yellow ≥ 50%
+  and red ≥ 75% of that window, matching the harness compaction
+  watermarks. When the window value is absent the badge falls back
+  to fixed 100k / 150k thresholds.
 - Line 2: status badges only (no per-card action buttons — actions
   moved to the **selection bar**, see below).
 - Line 3: drill-in triggers —