a8fb08a7e8
Part of #4041's forgotten remainder (UIVerbs was scoped as pure execution work, no decision needed -- see comment 71586). 29 genuine input-device-neutral rewrites ("click"/"clicking"/"clicked" -> "select"/"selecting"/"selected", a few reworded where a direct verb swap didn't read naturally: "one click from the hub" -> "one step from the hub", "click straight from X into Y" -> "go straight from X into Y", "the operator never clicked" -> "the operator never triggered"). Left 5 hits unfixed, each read in context and genuinely not a device-assumption problem: - docs/process/gotchas.md:439 -- "click-to-unlock screen" names a specific OS lock-screen pattern, not an instruction to the reader. - docs/web-ui/agent.md:377 -- "clicks" describes literal RFB pointer events forwarded by hive-screen-mcp's sendPointer, genuinely mouse-specific. - docs/web-ui/agent.md:78 -- "ctrl/middle-click" names a specific keyboard-modifier + mouse-button combination with no "select" equivalent. - docs/web-ui/dashboard.md:741 -- explicitly contrasts "click (or Enter/Space)" as two named input methods; replacing "click" with "select" would conflate the two the sentence is distinguishing. - docs/web-ui/shape.md:253 -- "swipes in from the right" describes the panel's own slide animation, not a user touch gesture. Verified: fresh `vale --filter '.Name == "Microsoft.UIVerbs"' docs` after the fix shows exactly those 5, `nix fmt` reports 0 changes.
133 lines
6.2 KiB
Markdown
133 lines
6.2 KiB
Markdown
# 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). Every page links back to H0M3, so you're
|
|
never more than one step 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:
|
|
|
|
- **SW4RM** — every agent, live. This is the default tab and the one
|
|
you'll check most.
|
|
- **Y3R C4LL** — anything waiting on _you_: pending approvals. 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.
|
|
|
|
Everything else lives on its own page instead, 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), **Stats** (`/stats.html`, swarm-wide usage stats),
|
|
**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). Your local browser preferences (notifications)
|
|
live in the dashboard's Y3R C4LL tab now, not a separate page.
|
|
|
|
Each agent also has its own page — a full terminal view of that
|
|
agent's session, reachable by selecting 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). Select the name to open
|
|
its terminal and watch it work in real time.
|
|
|
|
**Approve 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. 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 (select 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
|
|
|
|
Both the dashboard and the per-agent pages are SPAs sharing one
|
|
skeleton: `GET /` returns a static shell, `/api/state` returns JSON,
|
|
JS renders — no full-page reloads.
|
|
|
|
- **[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, terminal pane, listener bind, per-agent relative
|
|
paths, `data-async` form pattern, side panel, atomic repaint.
|
|
- **[CSS theme variables](css-vars.md)** — the Catppuccin Mocha custom
|
|
properties declared once in `base.css` and the rule that per-page
|
|
stylesheets reference (never redeclare) them.
|
|
- **[swarm-ui design guide](design-guide.md)** — visual language,
|
|
motion, theming, error-UX, and component-first principles for the
|
|
swarm-level Preact app specifically (not this page's dashboard/agent
|
|
UIs). `/components` on a running swarm-ui is the companion living
|
|
demo of every primitive it references.
|
|
|
|
### Implementation reading paths
|
|
|
|
Task-oriented jumps straight to the relevant section, for when you're
|
|
touching the code rather than using the UI:
|
|
|
|
- **"How does the dashboard SPA stay live without polling?"** →
|
|
[`shape.md`](shape.md) (SSE multiplexing, Worker-death self-heal,
|
|
atomic repaint).
|
|
- **"What does a container row contain?"** →
|
|
[`dashboard.md`](dashboard.md) (Container row, Topology tree,
|
|
Selection bar).
|
|
- **"What endpoints does the dashboard expose?"** →
|
|
[`dashboard.md`](dashboard.md) (Dashboard endpoints, Dashboard event
|
|
channel).
|
|
- **"How does the per-agent terminal render tool calls?"** →
|
|
[`terminal-rendering.md`](terminal-rendering.md) (full row taxonomy
|
|
and dispatch walkthrough); for a high-level summary see
|
|
[`agent.md`](agent.md) (Per-stream rendering).
|
|
- **"What slash commands does the agent accept?"** →
|
|
[`agent.md`](agent.md) (Terminal-embedded prompt).
|
|
- **"What are the per-agent HTTP endpoints?"** →
|
|
[`agent.md`](agent.md) (Per-agent endpoints).
|
|
- **"Which CSS variable do I use / where are colours defined?"** →
|
|
[`css-vars.md`](css-vars.md) (Palette, single-source `base.css`
|
|
rule).
|