From 025cc4f18d803afded41c0b348e70ab93299ff39 Mon Sep 17 00:00:00 2001 From: iris Date: Sun, 2 Aug 2026 23:26:29 +0200 Subject: [PATCH] docs(web-ui): add an operator-facing README as the subdir landing page docs/web-ui/ had four pages, all written as deep implementation reference (dashboard.md alone is 1466 lines of wire shapes and DOM mechanics) - there was nothing here written for an operator actually using the dashboard day to day. Add docs/web-ui/README.md: genuinely task-oriented content (what the dashboard is, where the tabs are, the things you'd actually do - checking an agent, answering a pending question, approving a config change, granting a permission, reading logs) with pointers into the existing pages for implementation depth. Point docs/web-ui.md at it as the operator starting point. Deliberately not touching dashboard.md/agent.md/shape.md/css-vars.md - reflowing 1466 lines of dense, working reference content in place turned out to be a much bigger and more error-prone task than "lead with the user fact" suggested at a glance (see hyperhive#1898). The subdir's landing page carries the user-facing content; the existing pages stay exactly as they are, as the depth layer underneath it. Verified the new page actually renders as the subdir's index via the website repo's new subdir-landing-page support (hyperhive/website PR #46): a real build of the prose-docs derivation confirms web-ui/index.html now exists, the root index links straight to it, and every internal link resolves correctly. --- docs/web-ui.md | 5 ++- docs/web-ui/README.md | 97 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 101 insertions(+), 1 deletion(-) create mode 100644 docs/web-ui/README.md diff --git a/docs/web-ui.md b/docs/web-ui.md index 089b5868..61901099 100644 --- a/docs/web-ui.md +++ b/docs/web-ui.md @@ -6,7 +6,10 @@ and the per-agent UIs (every container hashes into :8100-8999 via Both are SPAs — `GET /` returns a static shell, `/api/state` returns JSON, JS renders. No full-page reloads. -This doc has been split for readability. Pick the section you need: +This doc has been split for readability. Pick the section you need — +or, if you're the operator looking for how to actually *use* the +dashboard rather than how it's built, start at +**[web-ui/README.md](web-ui/README.md)** instead. - **[Shape (shared by both)](web-ui/shape.md)** — shared SPA skeleton, SSE multiplexing, terminal pane, listener bind, diff --git a/docs/web-ui/README.md b/docs/web-ui/README.md new file mode 100644 index 00000000..f7ec1b78 --- /dev/null +++ b/docs/web-ui/README.md @@ -0,0 +1,97 @@ +# Dashboard & Web UI + +The operator-facing entry point for running a hive day to day. If you +want implementation detail — wire formats, DOM structure, event +plumbing — see [Dashboard layout](dashboard.md), [Per-agent +page](agent.md), [Shape](shape.md), and [CSS theme variables](css-vars.md) +below; this page only covers what you actually do here. + +## Where things are + +Everything starts at the **H0M3 hub**, served at `/` — a grid of tiles +linking to every surface (Dashboard, Flow, Logs, Builds, Stats, +Settings, Core, Credentials, plus Matrix/Forge when enabled). Every +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 a handful of tabs: + +- **SW4RM** — every agent, live. This is the default tab and the one + you'll check most. +- **Y3R C4LL** — anything waiting on *you*: pending approvals and + agent questions. If an agent needs a decision from you, it's here. +- **P3RM1SS10NS** — what tools and system-level access each agent has. +- **SCH3DUL3S** — scheduled prompts and agent self-reminders. +- **ST4TS** / **P33RS** / **S3TT1NGS** — swarm-wide usage stats, peer + hives (if any are configured), and your local browser preferences. + +A few things live on their own pages instead of dashboard tabs, all +reachable from the H0M3 hub: **Flow** (`/flow.html`, the raw live +message stream across the whole swarm), **Logs** (`/logs.html`, +per-agent and host journals), **Builds** (`/builds.html`, the rebuild +queue and build history), **Core** (`/core.html`, tombstones and +container resource use), and **Credentials** (`/credentials.html`, +provisioning matrix/GitHub/forge accounts per agent). + +Each agent also has its own page — a full terminal view of that +agent's session, reachable by clicking its name anywhere in the +dashboard, or directly at `/agent//` (or `http://:/` +if the gateway isn't in front). + +## The things you'll actually do + +**Check on an agent.** SW4RM shows every container as a row: name, +whether it's running, what it's currently doing (a live status pill — +`rebuilding…`, `starting…`, and so on — while something's in flight), +and quick links (stats, screen, forge profile). Click the name to open +its terminal and watch it work in real time. + +**Answer something an agent is waiting on.** Y3R C4LL is the one tab +worth checking regularly — it's everything that needs *you*: approvals +for config changes, and questions an agent has asked and is blocked on. +The tab's count pill tells you at a glance if anything's pending. + +**Approve or reject a config change.** Agent config changes (new +packages, env vars, MCP servers) go through an approval queue rather +than landing automatically — you'll see them on Y3R C4LL, with a diff +of what's changing. + +**Start, stop, restart, or rebuild an agent.** Select one or more +agents on SW4RM (click the icon) and use the selection bar, or use the +per-agent `⋮` menu on a single row. Rebuilding re-applies that agent's +current config; use it after approving a change, or whenever an agent +shows as "needs update." + +**Watch a build.** BU1LDS shows the rebuild queue live, plus a +streaming log of whatever's currently building. Useful right after +approving a change or bumping a flake input. + +**Grant or revoke a tool/capability.** P3RM1SS10NS is a checkbox matrix +— rows are agents, columns are tool groups or capabilities. Nothing +takes effect until you hit **save all** at the bottom of the tab; a +save queues a rebuild for whichever agents actually changed. + +**Read an agent's logs.** The Logs page's AGENT tab pulls a live +journald view for any agent + service; the per-agent `⋮` menu's +**journal logs →** link jumps straight there, pre-filtered. + +**Set up a schedule or check on a reminder.** SCH3DUL3S covers both — +recurring or one-shot prompts you schedule for one or more agents, and +reminders agents have set for themselves. + +**Provision an account for an agent.** The Credentials page covers +Matrix, GitHub, and external-forge accounts per agent, without editing +that agent's config repo. + +## More depth + +- **[Dashboard layout](dashboard.md)** — every tab and standalone page, + in full implementation detail: endpoint shapes, event wiring, exact + badge-derivation rules. +- **[Per-agent page](agent.md)** — the per-agent terminal, composer, + side panel, slash commands, and per-agent endpoints. +- **[Shape (shared by both)](shape.md)** — the SPA skeleton, SSE + multiplexing, and other plumbing shared across every page. +- **[CSS theme variables](css-vars.md)** — the colour system, for + anyone touching the frontend's CSS.