hyperhive/docs/README.md

# 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. The docs sit in five sections, by what the reader wants:

1. [Getting started](#1-getting-started): what hyperhive is, and how to bring one up.
2. [Handbook](#2-handbook): running and using a hive and a swarm.
3. [Options reference](#3-options-reference): every NixOS option.
4. [Implementation](#4-implementation): how it works inside.
5. [Project](#5-project): how the project itself works.

## 1. Getting started

- **Adding hyperhive to a NixOS flake? Which options does it need?** →
  [`1-getting-started/nixos.md`](1-getting-started/nixos.md).
- **Bringing a fresh swarm online?** → [`1-getting-started/setup.md`](1-getting-started/setup.md)
  (the hand steps after the first switch).

## 2. Handbook

Using and operating the hive and the swarm. Some pages here still carry
implementation detail next to the operator content; sorting those out is
later work.

### Web UI and tools

- **What does the dashboard look like, and how to use it?** →
  [`2-handbook/web-ui/`](2-handbook/web-ui/README.md) — the operator-facing starting point,
  with [`dashboard`](2-handbook/web-ui/dashboard.md) and [`agent`](2-handbook/web-ui/agent.md).
- **What tools does an agent (or the operator) have available?** →
  [`2-handbook/tools/`](2-handbook/tools/README.md) — `hivectl` (yours) plus every agent's MCP
  tool surface (bash, forge, lifecycle, matrix).
- **What does `hivectl` do? Provisioning, gateway users, container
  shells?** → [`2-handbook/tools/hivectl.md`](2-handbook/tools/hivectl.md) (the curated guide);
  [`2-handbook/reference/hivectl-cli.md`](2-handbook/reference/hivectl-cli.md) for the exhaustive,
  autogenerated flag reference. The other command-line references sit beside it in
  [`2-handbook/reference/`](2-handbook/reference/).

### Agent lifecycle

- **How do config changes flow from manager to operator to container?** →
  [`2-handbook/agent-lifecycle/config-changes.md`](2-handbook/agent-lifecycle/config-changes.md)
  (config PRs, the meta flake, system messages).
- **What state survives destroy / purge / restart?** →
  [`2-handbook/agent-lifecycle/persistence.md`](2-handbook/agent-lifecycle/persistence.md).
- **Who can do what to whom — the agent roster and privilege?** →
  [`2-handbook/agent-lifecycle/agent-roster.md`](2-handbook/agent-lifecycle/agent-roster.md).

### Trust boundary and security

- **What's the operator/agent trust boundary? What's a permission?** →
  [`2-handbook/trust-boundary/boundary.md`](2-handbook/trust-boundary/boundary.md).
- **Agent trust model, prompt-injection threat model, credential
  isolation?** → [`2-handbook/trust-boundary/security.md`](2-handbook/trust-boundary/security.md).

### Accounts and integrations

- **How do per-agent forge accounts work? What does `forge_notify` poll,
  and how does it format wake messages?** → [`2-handbook/integrations/forge.md`](2-handbook/integrations/forge.md)
  (the swarm's Forgejo); [`2-handbook/tools/forge.md`](2-handbook/tools/forge.md) for the
  `hive-forge` CLI verbs agents actually call.
- **How does the matrix-tuwunel container work? Multiple accounts per
  agent?** → [`2-handbook/integrations/matrix.md`](2-handbook/integrations/matrix.md) (the homeserver);
  [`2-handbook/tools/matrix.md`](2-handbook/tools/matrix.md) for the MCP tool surface and
  `services.hyperhive.agent.matrixAccounts`.
- **How to give an agent a GitHub account (`gh` + `git push`)? how's
  the PAT injected?** → [`2-handbook/integrations/github.md`](2-handbook/integrations/github.md)
  (operator content up top; the `gh`/git-push + notification-poller
  mechanics are in a collapsed "Implementation" section at the bottom).
- **How to give an agent GitLab accounts (`glab` + `git push`, more than one
  instance)?** → [`2-handbook/integrations/gitlab.md`](2-handbook/integrations/gitlab.md).
- **What's `/knowledge`? How does the swarm-wide knowledge repo sync,
  and how to contribute a document?** → [`2-handbook/integrations/knowledge.md`](2-handbook/integrations/knowledge.md).

### Swarm

- **How are two hives connected into a swarm?** → [`2-handbook/swarm/`](2-handbook/swarm/README.md)
  (peer hives, TLS trust).
- **Who mints each credential, who reads it, and how does it rotate — and
  where's that shape headed?** → [`2-handbook/swarm/credentials.md`](2-handbook/swarm/credentials.md)
  (the rules, where each secret goes and why) and
  [`2-handbook/swarm/credentials-reference.md`](2-handbook/swarm/credentials-reference.md) (the
  tables: each credential, current state and target state, and where each
  file lives today).
- **How does an agent get a prompt at set times, and why doesn't it fire
  twice after downtime?** → [`2-handbook/swarm/schedules.md`](2-handbook/swarm/schedules.md).
- **How to create an agent from a ready-made set of permissions and
  settings?** → [`2-handbook/swarm/archetypes.md`](2-handbook/swarm/archetypes.md).
- **How to log an agent in to claude from the swarm UI, and why doesn't a
  stale stored copy log it out again?** →
  [`2-handbook/swarm/claude-login.md`](2-handbook/swarm/claude-login.md).

## 3. Options reference

The autogenerated NixOS options reference (every `services.hyperhive.*` /
`hyperhive.*` option, host and agent) lives on the website, built from the
module declarations: [the options site](https://hyperhive.darkest.space/options/).
Nothing of it sits in this tree.

## 4. Implementation

### Turn loop, scheduler, CI, observability

- **How does claude get its prompt, and what tools does it have?** →
  [`4-implementation/turn-loop/`](4-implementation/turn-loop/README.md) — the loop, binary shape, turn
  outcomes; sub-pages: [`claude-invocation`](4-implementation/turn-loop/claude-invocation.md),
  [`config`](4-implementation/turn-loop/config.md), [`mcp`](4-implementation/turn-loop/mcp.md).
- **what's the job queue, as a general idea (not hive-c0re specifics)?** →
  [`4-implementation/scheduler/jobq.md`](4-implementation/scheduler/jobq.md) — operator-facing, no implementation detail.
- **How does the rebuild queue work? What are the concrete step kinds,
  queue sources, scheduler internals?** → [`4-implementation/scheduler/coordinator.md`](4-implementation/scheduler/coordinator.md).
- **How does the CI runner work? How does it register?** →
  [`4-implementation/scheduler/ci.md`](4-implementation/scheduler/ci.md).
- **How are Claude Code metrics (tokens, cost, tool calls) exported to
  Prometheus/Grafana?** → [`4-implementation/scheduler/observability.md`](4-implementation/scheduler/observability.md).

### Networking

- **What nginx vhosts does the gateway serve? How does matrix
  discovery work?** → [`4-implementation/networking/gateway.md`](4-implementation/networking/gateway.md).
- **How does DNS resolution work in agent containers? What's the
  bridge network for?** → [`4-implementation/networking/network.md`](4-implementation/networking/network.md).
- **Where do agent snapshots go? How does the swarm's `btrfs receive`
  endpoint authenticate a pushing hive?** →
  [`4-implementation/networking/snapshot-store.md`](4-implementation/networking/snapshot-store.md).

### Swarm services

- **How does the secret store come up, who writes its grants, how's it
  sealed?** → [`4-implementation/swarm/bao.md`](4-implementation/swarm/bao.md).
- **How to set an agent's model or effort from the swarm, and what happens
  to its own pick?** → [`4-implementation/swarm/inference.md`](4-implementation/swarm/inference.md).
- **How does a PR get checked against its repo's own yes/no rules before
  a full review?** → [`4-implementation/swarm/review-classifier.md`](4-implementation/swarm/review-classifier.md).
- **Does an agent config PR build before it's merged?** →
  [`4-implementation/swarm/builder.md`](4-implementation/swarm/builder.md).
- **How long do CI runs take, per repo and PR, and where does the board get
  it?** → [`4-implementation/swarm/ci-metrics.md`](4-implementation/swarm/ci-metrics.md).
- **How does an agent get a todo when someone assigns it an issue, and lose it
  when the issue closes?** → [`4-implementation/swarm/notify-router.md`](4-implementation/swarm/notify-router.md).

### Trust boundary mechanics

- **How does systemd activate `hive-priv`, and how does the per-agent socket
  directory get its owner and mode?** → [`4-implementation/trust-boundary/boundary-mechanism.md`](4-implementation/trust-boundary/boundary-mechanism.md).
- **How does `hive-c0re` run unprivileged and delegate root operations?** →
  [`4-implementation/trust-boundary/hive-c0re-privilege.md`](4-implementation/trust-boundary/hive-c0re-privilege.md).
- **How do in-container nix builds stay apart from the credentials?** →
  [`4-implementation/trust-boundary/nix-builds.md`](4-implementation/trust-boundary/nix-builds.md).

### Web UI internals

- **How's the dashboard built, and how does the terminal render?** →
  [`shape`](4-implementation/web-ui/shape.md),
  [`css-vars`](4-implementation/web-ui/css-vars.md),
  [`terminal-rendering`](4-implementation/web-ui/terminal-rendering.md).

### Crate reference

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

## 5. Project

How the project itself works: processes, conventions, design guides.

- **Naming, commit style, wire protocol, the `data-async` pattern?** →
  [`5-project/process/conventions.md`](5-project/process/conventions.md).
- **Why does the nspawn flag look like that?** → [`5-project/process/gotchas.md`](5-project/process/gotchas.md)
  (bind mounts, conf flags, other NixOS/nspawn quirks).
- **What does a PR review verdict actually gate?** →
  [`5-project/process/pr-review-gate.md`](5-project/process/pr-review-gate.md).
- **How are the web UIs designed to look and behave?** →
  [`5-project/web-ui/design-guide.md`](5-project/web-ui/design-guide.md).