Per #1407 review: the options reference should be markdown here; the
HTML + CSS belongs in the website repo where the theme lives and the
stylesheet can be shared with /docs.
- nix/docs/default.nix: drop the cmark-gfm HTML rendering, the inline
<style>, and the HTML index. Emit index.md + host.md + agent.md only
(CommonMark from nixosOptionsDoc).
- Remove nix/docs/style.css.
- Update docs/gotchas.md + CLAUDE.md to describe the md-only output and
point at the website for HTML rendering.
The website (hyperhive/website#26) renders these .md to themed HTML for
/options/, sharing one docs.css with the prose /docs/ tree.
The CSS theme-variable reference documents the dashboard/agent web-UI
stylesheets, so it belongs under docs/web-ui/ alongside shape/dashboard/
agent. Wire it into the web-ui.md index (split list + reading path) and
the CLAUDE.md file map. Closes#1405.
The "hive-forge container shape" section described the container
isolation model but omitted the port and firewall knobs that operators
need when exposing forge externally or overriding the Forgejo ROOT_URL.
Add two subsections:
"Network and port configuration" — covers httpPort (default 3000),
sshPort (default 2222), and openFirewall (default false, was previously
true — breaking change note included). Explains the shared-netns
rationale for why openFirewall is safe to leave off for agent use but
must be set for browser/external-git-client access. Clarifies that
forge.behindGateway obviates forge.openFirewall for HTTP reach.
"rootUrl override" — documents forge.rootUrl (default null) with the
auto-derivation table (behindGateway ? http://domain/ : http://domain:port/)
and explains when to override (TLS, https:// clone URLs, bespoke shapes).
Notes the auto-derivation always produces http://, so TLS operators must
set rootUrl explicitly.
The sentence 'ruth is always reachable regardless of the list' documents
a bug in check_send_allowed (name-based carve-out), not intended
behavior. The structural parent carve-out is fine to mention since it's
topology-based, not name-based.
Updated example to show [ "operator" ] (restrict to operator-only)
and replaced the ruth-name claim with a note about the parent carve-out.
Five per-agent agent.nix options were undocumented:
- hyperhive.allowedRecipients — restricts which peers send() accepts;
note added inline to the send tool description
- hyperhive.claudeMarketplaces — Claude Code plugin marketplace sources
(default: official Anthropic marketplace)
- hyperhive.claudePlugins — plugin specs installed at harness boot
- hyperhive.claudePluginsAutoUpdate — pull latest marketplace index
before install; off by default
- hyperhive.cargo.shortMessages — shell wrapper injecting
--message-format short on cargo compile subcommands; on by default
The daemon does not call join_room_by_id. It fires a wake and writes
to mcp-loose-ends/matrix.json; the agent calls list_invites + join_room.
Replace the inaccurate 'Auto-accept invites' paragraph with 'Invite
wakes' describing the actual flow. Merge the pending-invites paragraph
into a single accurate block.
The matrix.md provisioning section mentioned trustedServers in passing
("wired up later by extending trustedServers") but never explained it
as a configurable option, and maxRequestSize was undocumented entirely.
Add a "Configuration tuning" subsection before "Assertion rationale":
- trustedServers (default []) — list of peer homeserver names to trust;
federation is protocol-on but no peer trusted until listed; link to
swarm.md for the multi-hive use case.
- maxRequestSize (default 20 MB) — request body limit matching the
matrix-spec recommendation; when and why to raise or lower it.
SVG path for per-agent visual identity — used in the page header,
favicon, Forgejo profile avatar (forge-avatar-sync), and Matrix
profile avatar (matrix-avatar-sync).
The compaction section already documented HIVE_COMPACT_WATERMARK_TOKENS
but didn't mention the per-agent nix option (hyperhive.autoCompact,
default true) that maps to it.
Add a short note after the watermark paragraph explaining that operators
can set autoCompact = false in agent.nix to disable proactive compaction,
and note the reactive path still applies. Useful for sonnet/opus agents
where the 75% heuristic fires before the session is actually full.
Three host-level NixOS options in services.hyperhive.c0re were
undocumented. Add a new 'Host-level resource + performance options'
section to coordinator.md covering:
- agentCpuQuota (default 200%) — CPUQuota= drop-in per container
- agentMemoryMax (default 4G) — MemoryMax= drop-in per container
- preBuildAgentTemplates (default false) — pre-fetch agent closures
into host nix store; trade system closure size for first-spawn speed;
warn against enabling on aarch64 hosts
GET /api/tool-groups and GET /api/capabilities both return a
descriptions map (name → short string) added in feat(#1082). The
map drives native browser tooltips on column headers in the
P3RM1SS10NS tab. The API docs still showed the old 2-field shape.
The matrix wake body description said '[matrix] <sender> in <room>:
<first-100c>...' (old single-line teaser). After feat(#1137) it's now
a richer format:
- Single room, 1 message: terse one-liner with sender + body
- Single room, N messages: count + room name
- Multi-room: bulleted list with per-room summaries
Also note that the same breakdown appears in get_loose_ends via the
UnreadMatrix entry.
The internal/knowledge forge repo and its /knowledge container bind-mount
have been live since feat(#1167) but had no docs/ entry — only a mention
in the agent system prompt.
Add docs/knowledge.md covering:
- Agent access (/knowledge read-only bind-mount inside every container)
- Repository layout (internal/knowledge, auto-seeded README)
- Sync mechanism (webhook on push + periodic pull fallback)
- State paths (/var/lib/hyperhive/knowledge on host)
- Contribution workflow (fork + PR, no direct push)
Also add a file-map entry and reading-path bullet in CLAUDE.md.
hivectl has verbs scattered across CLAUDE.md and domain docs (gateway.md
has the gateway subcommands, matrix.md has a brief mention) but no
single cheatsheet. Add docs/tools/hivectl.md covering all subcommands:
- forge create-user: provision/refresh agent or human forge accounts
- matrix create-user / sync-admin / promote-user / reset-password
- gateway create-user / delete-user / list-users (htpasswd management)
- agents restart / restart-all (container lifecycle via admin socket)
- choom <name> [--fresh]: interactive claude session in agent container
Also add a reading-path entry to CLAUDE.md pointing at the new file.
persistence.md: bash-tasks/ says "persist until container purge" but
bash_tasks_vacuum now runs hourly and deletes terminal task trios older
than 48 hours. Update the description to reflect actual retention policy.
matrix.md: add step 6 to the Provisioning flow section documenting that
hive-c0re restarts hive-matrix-daemon immediately after writing the
access_token (fix for issue #1329). Previously the doc stopped at token
write; the restart + .path-trigger fallback interplay was undocumented.
Adds ?agent=name and ?unit=svc URL params to pre-select the agent on
the AGENT tab (used by the per-agent overflow menu journal logs link).
Last-fetched timestamp chip shows how stale the output is.
Agent selection is NOT persisted to localStorage — URL params only.
The M1ND H4S QU3STI0NS paragraph was a minimal stub that omitted
most of the questions UI:
- Filter chips row (all · N / @operator / @peer / per-participant)
with localStorage persistence
- Peer-targeted questions (agent-to-agent asks) and the
operator's ability to override-answer them (0V3RR1D3 button)
- Full answer-form anatomy (textarea, option list, merge logic,
Enter-to-submit, separate cancel form)
- Answered-history collapsible (◆ answ3red (N) details element)
Also clarify the P3NDING APPR0VALS paragraph: explicitly mention
the pending/history tab pair (it was documented in the Approval
card section but not called out at the tab level).
The BUILD sub-tab description was written before the auto-scroll,
live elapsed-time ticker, and SSE-driven list refresh were added.
Update it to cover:
- Live elapsed-time chip: ticks every second via setInterval,
cleared on finish/error
- Sticky-bottom auto-scroll: follows new output while the operator
is at the bottom; silently appends when scrolled up
- SSE-driven list refresh: rebuild_queue_changed fires a 2s-debounced
fetchBuild() while on the BUILD tab; refresh button still works for
immediate re-fetch
The dashboard.md 'Line 3: drill-in triggers' section described inline
↳ logs and ↳ build logs side-panel affordances that were removed from
the container row some time ago (navigation links were consolidated onto
the Line 1 nav strip; journal + build-log viewing moved to /logs.html).
Replace that stale section with accurate documentation of the per-agent
⋮ overflow menu (restart/stop/start/rebuild + journal-logs deep-link +
destroy/purge + deployed-sha forge link).
Also update the AGENT and SYSTEM sub-tab descriptions to cover:
- localStorage persistence of agent/unit selection across page loads
- ?agent= / ?unit= URL params for deep-linking (used by the ⋮ menu)
- 'fetched N ago' chip after each successful fetch (ticks every 30 s)
Add CapabilitiesChanged and ToolGroupsChanged DashboardEvent variants
so the P3RM1SS10NS tab reflects perm changes without the operator
navigating away and back.
Backend:
- DashboardEvent::CapabilitiesChanged { seq, caps, descriptions,
assignments } — same payload shape as GET /api/capabilities
- DashboardEvent::ToolGroupsChanged { seq, groups, descriptions,
assignments } — same payload shape as GET /api/tool-groups
- Coordinator::emit_capabilities_snapshot() and
emit_tool_groups_snapshot() — read from the JSON files and broadcast
- rebuild_queue.rs PermChange worker: emit after each successful
commit_capabilities / commit_tool_groups call
Frontend:
- applyCapabilitiesChanged(ev): calls renderCapabilities(root, ev)
- applyToolGroupsChanged(ev): calls renderToolGroups(root, ev)
- Both registered in MUTATION_HANDLERS
- activateTab comment updated (SSE now covers perm changes)
Docs: dashboard.md and CLAUDE.md updated.
This completes SSE coverage for all dashboard sections: SW4RM,
Y3R C4LL, SYST3M, SCH3DUL3S/reminders, and P3RM1SS10NS all
derive live updates from /dashboard/stream.
Add RemindersChanged SSE event so the pending-reminders list in the
SYST3M tab updates live without polling.
Backend emission sites (every path that mutates the reminders table):
- agent_server: store_remind (remind MCP call)
- dashboard.rs: post_cancel_reminder, post_retry_reminder
- questions.rs: cancel_loose_end Reminder kind
- reminder_scheduler: after each delivery batch (any_delivered)
Coordinator gets emit_reminders_snapshot() mirroring the existing
emit_schedules_snapshot() pattern: lists PendingReminder rows from the
broker and emits DashboardEvent::RemindersChanged.
Frontend: applyRemindersChanged(ev) calls renderReminders(ev.reminders)
and is registered as reminders_changed in MUTATION_HANDLERS.
Docs: dashboard.md reminders_changed entry; CLAUDE.md file map updated.
Add `SchedulesChanged` to the dashboard event channel so the
operator's schedule list updates in real time without requiring a
tab-activation or form-submit refresh.
Backend:
- `dashboard_events.rs`: new `SchedulesChanged { seq, schedules }`
variant carrying a full `Vec<WireSchedule>` snapshot (same
snapshot-over-diff rationale as `RebuildQueueChanged`).
- `coordinator.rs`: `emit_schedules_snapshot()` helper — queries the
scheduled_prompts list, converts to wire shape, broadcasts the event.
- `dashboard.rs`: call `emit_schedules_snapshot()` at the end of each
operator API handler that mutates a schedule:
`post_schedule_new`, `post_schedule_fire_now`,
`patch_schedule`, `post_schedule_cancel`.
- `scheduled_prompts_worker.rs`: call `emit_schedules_snapshot()`
after each tick that fires schedules, so `last_fired_at_unix`,
`next_fire_at_unix`, and reaped one-shots surface live.
Frontend:
- `tabs.js`: add `applySchedulesChanged(ev)` — replaces
`schedulesState` from the snapshot and calls `renderSchedulesList()`.
Registered in `MUTATION_HANDLERS` as `schedules_changed`.
Tab-activation re-fetch kept as safety net for approval-path
inserts and disconnect windows; comment updated to reflect this.
Docs:
- `docs/web-ui/dashboard.md`: document `schedules_changed` event.
- `CLAUDE.md`: add `SchedulesChanged` to the file-map entry.
