| Filename | Latest commit message | Latest commit date |
|---|---|---|
07b62612b0
Per mara's go-ahead on hyperhive#3902 ("getting started is good, but
terminal rendering does not go in there i think"):
Moved 21 top-level docs/*.md files into 7 new topic subdirectories
(existing web-ui/, turn-loop/, swarm/, tools/, crates/ untouched):
getting-started/ setup.md
agent-lifecycle/ agent-hierarchy.md, approvals.md, persistence.md
trust-boundary/ boundary.md, security.md
integrations/ forge.md, matrix.md, github.md, knowledge.md
networking/ gateway.md, network.md, snapshot-store.md
scheduler/ jobq.md, coordinator.md, ci.md, observability.md
process/ conventions.md, gotchas.md, pr-review-gate.md
web-ui/ terminal-rendering.md (moved into the EXISTING dir,
per mara's correction to the original getting-started
guess -- it's UI implementation detail, not onboarding)
The physical layout now matches docs/README.md's own topical headers,
which already amounted to this taxonomy -- see the scoping comment on
the issue for the two findings that motivated this (a genuine
duplication between CLAUDE.md's old "Reading paths" list and
docs/README.md's grouped one, since drifted out of sync with each
other; and the flat layout not matching the grouping we already had).
Fixed every cross-reference this moved across the whole repo (~120
files: docs/ internal links at every depth, Rust doc comments, nix
module option docs, crate READMEs) -- verified two ways: a grep sweep
confirming zero remaining references to any old path, and a script
that resolves every markdown link in docs/**/*.md + CLAUDE.md +
README.md against the filesystem and reports anything that doesn't
exist (zero broken links).
Collapsed CLAUDE.md's "Reading paths" section (the duplicate) down to
a pointer at docs/README.md, now the single index. Rewrote
docs/README.md itself to use the new subdirectory paths and added the
one doc it was missing that CLAUDE.md's old copy had (pr-review-gate.md).
Classified all 22 docs/*.md files first via a haiku subagent (mara's
suggestion) on two axes -- proposed grouping and operator-vs-
implementation focus -- before finalizing the taxonomy; spot-checked
the report and found internal inconsistencies (its classification
table disagreed with its own summary section for a few files), so this
taxonomy is my original proposal + the one correction mara gave
directly, not a blind application of the subagent's table. The
operator-focus data it gathered is still useful for a follow-up
content pass (docs skewing 'mixed' rather than pure operator-facing),
not addressed in this PR -- structure only.
nix fmt clean, both pre-push lints clean.
|
||
| .. | ||
| agent.md | ||
| css-vars.md | ||
| dashboard.md | ||
| design-guide.md | ||
| README.md | ||
| shape.md | ||
| terminal-rendering.md | ||
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, Per-agent page, Shape, and CSS theme variables 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 click 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 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.
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 (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 — every tab and standalone page, in full implementation detail: endpoint shapes, event wiring, exact badge-derivation rules.
- Per-agent page — the per-agent terminal, composer, side panel, slash commands, and per-agent endpoints.
- Shape (shared by both) — the SPA skeleton, SSE multiplexing, and other plumbing shared across every page.
- CSS theme variables — the colour system, for anyone touching the frontend's CSS.