diff --git a/README.md b/README.md index 41afa1aa..02fa53b7 100644 --- a/README.md +++ b/README.md @@ -39,19 +39,13 @@ host (NixOS, runs hive-c0re.service) ``` **[→ website](https://hyperhive.darkest.space)** · +**[→ docs](https://hyperhive.darkest.space/docs/)** · **[→ options reference](https://hyperhive.darkest.space/options/)** -Depth lives in [`docs/`](docs/) — pick the one matching your task: - -| reading path | doc | -| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| dashboard layout + endpoints | [`docs/web-ui.md`](docs/web-ui.md) ([shape](docs/web-ui/shape.md) · [dashboard](docs/web-ui/dashboard.md) · [agent](docs/web-ui/agent.md)) | -| claude turn loop + MCP tools | [`docs/turn-loop/`](docs/turn-loop/README.md) | -| config-edit + approval state machine | [`docs/approvals.md`](docs/approvals.md) | -| what survives destroy / purge / restart | [`docs/persistence.md`](docs/persistence.md) | -| naming, wire protocol, commit style | [`docs/conventions.md`](docs/conventions.md) | -| nginx vhost map + sub-domain routing | [`docs/gateway.md`](docs/gateway.md) | -| NixOS / nspawn gotchas | [`docs/gotchas.md`](docs/gotchas.md) | +Depth lives in [`docs/`](docs/) (rendered at +[hyperhive.darkest.space/docs/](https://hyperhive.darkest.space/docs/)) — +start at [`docs/README.md`](docs/README.md) and pick the page matching +your task rather than reading front to back. ## Quick start diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..328e0998 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,96 @@ +# 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).