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.
This commit is contained in:
iris
parent
d77f81cd1e
commit
025cc4f18d
2 changed files with 101 additions and 1 deletions
|
|
@ -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,
|
||||
|
|
|
|||
97
docs/web-ui/README.md
Normal file
97
docs/web-ui/README.md
Normal file
|
|
@ -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/<name>/` (or `http://<host>:<port>/`
|
||||
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.
|
||||
Loading…
Reference in a new issue