Watch

iris 67207ae32f docs: pilot split of github.md into operator-facing + collapsed implementation

hyperhive#3902, mara: option (a) - a content pass splitting mixed docs
into operator-facing content plus implementation detail. One file
first, to agree on the split pattern before doing the other ~19.

Went through 3 shapes on review before landing here: a sibling
-internals.md file (mara: clutters the navigation), then two
tree-precedent alternatives damocles raised (subdir+README like
web-ui/; or only split docs with a pre-existing boundary marker,
which would've covered 3-4 of the ~20 flagged docs and left the rest
untouched), then mara's own proposal - a collapsed <details> section
in the same file. Verified empirically (cmark-gfm --unsafe, the
website's own render pipeline) that markdown headings nested inside a
<details> block still parse as real headings with heading-id anchors
once separated from <summary> by a blank line, so anchor links into
the collapsed section keep working.

github.md keeps enabling/provisioning/security up top; its
'Implementation' section is now a <details> block holding what was
briefly a separate github-internals.md (deleted again) - how the
agent's gh/git-push actually authenticate, and the notification
poller's internals. Reverted the two cross-references + the
docs/README.md entry back to pointing at github.md now that the
content lives there again.

Added a short CLAUDE.md note recording the pattern per mara's ask,
including the one real caveat damocles flagged: <details> only
collapses in a rendered browser, a raw-text read (cat, the Read tool)
still sees everything, same as today.

2026-09-02 20:38:02 +02:00

5.5 KiB

Raw Blame History

hyperhive docs

Depth reference for hyperhive — the substrate, not the pitch (that's the top-level README / website). Every page here stands alone; pick the one matching your task rather than reading top to bottom. For the auto-generated NixOS options reference (every services.hyperhive.* / hyperhive.* option, host and agent), see the options site instead — this tree is prose, that one's generated straight from the module declarations.

Getting started

Bringing a fresh hive online? → getting-started/setup.md (first-run hivectl bootstrap).
What does the dashboard look like, and how do I use it? → web-ui/ — the operator-facing starting point; its own sub-pages (shape, dashboard, agent, css-vars, terminal-rendering) go deeper into implementation.
What tools does an agent (or the operator) have available? → tools/ — hivectl (yours) plus every agent's MCP tool surface (bash, forge, lifecycle, matrix, scheduling).

Agent lifecycle

How do config changes flow from manager to operator to container? → agent-lifecycle/approvals.md (two-step spawn, approval state machine, flake.lock validation).
What state survives destroy / purge / restart? → agent-lifecycle/persistence.md.
Who can do what to whom — agent hierarchy and privilege? → agent-lifecycle/agent-hierarchy.md.
How does claude get its prompt, and what tools does it have? → turn-loop/ — the loop, binary shape, turn outcomes; sub-pages: claude-invocation, config, mcp.

Trust boundary & security

What's the operator/agent trust boundary? What's a capability? → trust-boundary/boundary.md.
Agent trust model, prompt-injection threat model, credential isolation? → trust-boundary/security.md.

Accounts & integrations

How do per-agent forge accounts work? What does forge_notify poll, and how does it format wake messages? → integrations/forge.md (the hive's own Forgejo); tools/forge.md for the hive-forge CLI verbs agents actually call.
How does the matrix-tuwunel container work? Multiple accounts per agent? → integrations/matrix.md (the homeserver); tools/matrix.md for the MCP tool surface and hyperhive.matrixAccounts.
How do I give an agent a GitHub account (gh + git push)? How is the PAT injected? → integrations/github.md (operator content up top; the gh/git-push + notification-poller mechanics are in a collapsed "Implementation" section at the bottom).
What is /knowledge? How does the hive-wide knowledge repo sync, and how do I contribute a document? → integrations/knowledge.md.
What does hivectl do? Provisioning, gateway users, container shells? → tools/hivectl.md (the curated guide); tools/hivectl-cli.md for the exhaustive, auto-generated flag reference.

Networking & swarms

What nginx vhosts does the gateway serve? How does matrix discovery work? → networking/gateway.md.
How does DNS resolution work in agent containers? What's the bridge network for? → networking/network.md.
How do I connect two hives into a swarm? → swarm/ (peer hives, TLS trust).
Where do agent snapshots go? How does the swarm's btrfs receive endpoint authenticate a pushing hive? → networking/snapshot-store.md.

Scheduler, CI, observability

What is the job queue, as a general idea (not hive-c0re specifics)? → scheduler/jobq.md — operator-facing, no implementation detail.
How does the rebuild queue work? What are the concrete step kinds, queue sources, scheduler internals? → scheduler/coordinator.md.
How does the CI runner work? What's the auto-registration flow? → scheduler/ci.md.
How do I export Claude Code metrics (tokens, cost, tool calls) to Prometheus/Grafana? → scheduler/observability.md.

Crate reference

What does a specific Rust crate do, on its own terms? → crates/ — every workspace crate's own README.md, one level up from source (hyperhive#3051); the crate itself is still the source of truth, this is just a walkable mirror.

Process & conventions

Naming, commit style, wire protocol, the data-async pattern? → process/conventions.md.
Why does the nspawn flag look like that? → process/gotchas.md (bind mounts, conf flags, other NixOS/nspawn quirks).
What does a PR review verdict actually gate? → process/pr-review-gate.md.

5.5 KiB Raw Blame History