e41417d00e
Fixes hyperhive#3014. docs/README.md is a genuine hand-written index for the docs/ tree - task-oriented reading paths grouped by topic, covering every top-level doc plus the three subdirectories that already have their own landing page (web-ui/, tools/, turn-loop/). Adapted from CLAUDE.md's existing "Reading paths" section (already curated and kept current) rather than written from scratch, reorganized into headed groups since this is a landing page, not a flat reference list. Explicitly covers docs/tools/matrix.md and docs/github.md, per the note on hyperhive#3014 about the content that moved out of README.md's deleted section on PR #3006 not going undiscoverable. Top-level README.md's reading-path table (enumerating every doc) replaced with a single prominent docs-site link, per mara's "replace docs links table in readme md with a prominent link to the docs (public host and git relative path)" - both forms present (rendered site URL, git-relative docs/ path). Verified every link in docs/README.md resolves to a real file (33 files checked). nix fmt clean, tracker-tag grep clean. Companion to hyperhive/website#47/#48 - this is what that PRs "index.html half" needs to exist before it can render, per atlas's note on #48.
96 lines
4.4 KiB
Markdown
96 lines
4.4 KiB
Markdown
# hyperhive docs
|
|
|
|
Depth reference for hyperhive — the substrate, not the pitch (that's the
|
|
[top-level README](../README.md) / [website](https://hyperhive.darkest.space)).
|
|
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](https://hyperhive.darkest.space/options/) instead —
|
|
this tree is prose, that one's generated straight from the module
|
|
declarations.
|
|
|
|
## Getting started
|
|
|
|
- **Bringing a fresh hive online?** → [`setup.md`](setup.md) (first-run
|
|
`hivectl` bootstrap).
|
|
- **What does the dashboard look like, and how do I use it?** →
|
|
[`web-ui/`](web-ui/README.md) — the operator-facing starting point;
|
|
its own sub-pages ([`shape`](web-ui/shape.md),
|
|
[`dashboard`](web-ui/dashboard.md), [`agent`](web-ui/agent.md),
|
|
[`css-vars`](web-ui/css-vars.md)) go deeper into implementation.
|
|
- **What tools does an agent (or the operator) have available?** →
|
|
[`tools/`](tools/README.md) — `hivectl` (yours) plus every agent's MCP
|
|
tool surface (bash, forge, lifecycle, matrix, scheduling).
|
|
|
|
## Dashboard & agent UI internals
|
|
|
|
- **How does the per-agent terminal classify + colour events?** →
|
|
[`terminal-rendering.md`](terminal-rendering.md).
|
|
|
|
## Turn loop, config, approvals
|
|
|
|
- **How does claude get its prompt, and what tools does it have?** →
|
|
[`turn-loop/`](turn-loop/README.md) — the loop, binary shape, turn
|
|
outcomes; sub-pages: [`claude-invocation`](turn-loop/claude-invocation.md),
|
|
[`config`](turn-loop/config.md), [`mcp`](turn-loop/mcp.md).
|
|
- **How do config changes flow from manager to operator to container?** →
|
|
[`approvals.md`](approvals.md) (two-step spawn, approval state machine,
|
|
`flake.lock` validation).
|
|
- **What state survives destroy / purge / restart?** →
|
|
[`persistence.md`](persistence.md).
|
|
|
|
## Trust boundary & security
|
|
|
|
- **What's the operator/agent trust boundary? What's a capability?** →
|
|
[`boundary.md`](boundary.md).
|
|
- **Agent trust model, prompt-injection threat model, credential
|
|
isolation?** → [`security.md`](security.md).
|
|
- **Who can do what to whom — agent hierarchy and privilege?** →
|
|
[`agent-hierarchy.md`](agent-hierarchy.md).
|
|
|
|
## Accounts & integrations
|
|
|
|
- **How do per-agent forge accounts work? What does `forge_notify` poll,
|
|
and how does it format wake messages?** → [`forge.md`](forge.md) (the
|
|
hive's own Forgejo); [`tools/forge.md`](tools/forge.md) for the
|
|
`hive-forge` CLI verbs agents actually call.
|
|
- **How does the matrix-tuwunel container work? Multiple accounts per
|
|
agent?** → [`matrix.md`](matrix.md) (the homeserver);
|
|
[`tools/matrix.md`](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?** → [`github.md`](github.md).
|
|
- **What does `hivectl` do? Provisioning, gateway users, container
|
|
shells?** → [`tools/hivectl.md`](tools/hivectl.md) (the curated guide);
|
|
[`tools/hivectl-cli.md`](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?** → [`gateway.md`](gateway.md).
|
|
- **How does DNS resolution work in agent containers? What's the
|
|
bridge network for?** → [`network.md`](network.md).
|
|
- **How do I connect two hives into a swarm?** → [`swarm.md`](swarm.md)
|
|
(peer hives, TLS trust).
|
|
- **Where do agent snapshots go? How does the swarm's `btrfs receive`
|
|
endpoint authenticate a pushing hive?** →
|
|
[`snapshot-store.md`](snapshot-store.md).
|
|
|
|
## Scheduler, CI, observability
|
|
|
|
- **How does the rebuild queue work? What are queue kinds and
|
|
sources?** → [`coordinator.md`](coordinator.md).
|
|
- **How does the CI runner work? What's the auto-registration flow?** →
|
|
[`ci.md`](ci.md).
|
|
- **How do I export Claude Code metrics (tokens, cost, tool calls) to
|
|
Prometheus/Grafana?** → [`observability.md`](observability.md).
|
|
|
|
## Process & conventions
|
|
|
|
- **Naming, commit style, wire protocol, the `data-async` pattern?** →
|
|
[`conventions.md`](conventions.md).
|
|
- **Why does the nspawn flag look like that?** → [`gotchas.md`](gotchas.md)
|
|
(bind mounts, conf flags, other NixOS/nspawn quirks).
|
|
- **What is `/knowledge`? How does the hive-wide knowledge repo sync,
|
|
and how do I contribute a document?** → [`knowledge.md`](knowledge.md).
|