docs: sort the top-level directories into five sections by what the reader wants
Every docs directory moves under 1-getting-started, 2-handbook, 4-implementation or 5-project; the options reference (section 3) comes from the website and has no directory here. trust-boundary stays whole under the handbook for now. web-ui, swarm and tools split between handbook and implementation, and the command-line references move to 2-handbook/reference. Links, path references in code and nix, and the docs index follow the moves; no page content changes.
This commit is contained in:
iris
mara
parent
53ccbcb4b3
commit
6739bb903d
1 changed files with 736 additions and 701 deletions
189
docs/README.md
189
docs/README.md
|
|
@ -3,132 +3,167 @@
|
|||
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 autogenerated 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.
|
||||
reading top to bottom. The docs sit in five sections, by what the reader wants:
|
||||
|
||||
## Getting started
|
||||
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?** →
|
||||
[`getting-started/nixos.md`](getting-started/nixos.md).
|
||||
- **Bringing a fresh swarm online?** → [`getting-started/setup.md`](getting-started/setup.md)
|
||||
[`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).
|
||||
- **What does the dashboard look like, and how to 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), [`terminal-rendering`](web-ui/terminal-rendering.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).
|
||||
|
||||
## Agent lifecycle
|
||||
## 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?** →
|
||||
[`agent-lifecycle/config-changes.md`](agent-lifecycle/config-changes.md)
|
||||
[`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?** →
|
||||
[`agent-lifecycle/persistence.md`](agent-lifecycle/persistence.md).
|
||||
[`2-handbook/agent-lifecycle/persistence.md`](2-handbook/agent-lifecycle/persistence.md).
|
||||
- **Who can do what to whom — the agent roster and privilege?** →
|
||||
[`agent-lifecycle/agent-roster.md`](agent-lifecycle/agent-roster.md).
|
||||
- **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).
|
||||
[`2-handbook/agent-lifecycle/agent-roster.md`](2-handbook/agent-lifecycle/agent-roster.md).
|
||||
|
||||
## Trust boundary & security
|
||||
### Trust boundary and security
|
||||
|
||||
- **What's the operator/agent trust boundary? What's a permission?** →
|
||||
[`trust-boundary/boundary.md`](trust-boundary/boundary.md).
|
||||
[`2-handbook/trust-boundary/boundary.md`](2-handbook/trust-boundary/boundary.md).
|
||||
- **Agent trust model, prompt-injection threat model, credential
|
||||
isolation?** → [`trust-boundary/security.md`](trust-boundary/security.md).
|
||||
isolation?** → [`2-handbook/trust-boundary/security.md`](2-handbook/trust-boundary/security.md).
|
||||
|
||||
## Accounts & integrations
|
||||
### Accounts and integrations
|
||||
|
||||
- **How do per-agent forge accounts work? What does `forge_notify` poll,
|
||||
and how does it format wake messages?** → [`integrations/forge.md`](integrations/forge.md)
|
||||
(the swarm's Forgejo); [`tools/forge.md`](tools/forge.md) for the
|
||||
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?** → [`integrations/matrix.md`](integrations/matrix.md) (the homeserver);
|
||||
[`tools/matrix.md`](tools/matrix.md) for the MCP tool surface and
|
||||
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?** → [`integrations/github.md`](integrations/github.md)
|
||||
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)?** → [`integrations/gitlab.md`](integrations/gitlab.md).
|
||||
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?** → [`integrations/knowledge.md`](integrations/knowledge.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,
|
||||
autogenerated flag reference.
|
||||
and how to contribute a document?** → [`2-handbook/integrations/knowledge.md`](2-handbook/integrations/knowledge.md).
|
||||
|
||||
## Networking & swarms
|
||||
### Swarm
|
||||
|
||||
- **What nginx vhosts does the gateway serve? How does matrix
|
||||
discovery work?** → [`networking/gateway.md`](networking/gateway.md).
|
||||
- **How does DNS resolution work in agent containers? What's the
|
||||
bridge network for?** → [`networking/network.md`](networking/network.md).
|
||||
- **How are two hives connected into a swarm?** → [`swarm/`](swarm/README.md)
|
||||
- **How are two hives connected into a swarm?** → [`2-handbook/swarm/`](2-handbook/swarm/README.md)
|
||||
(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`](networking/snapshot-store.md).
|
||||
- **Who mints each credential, who reads it, and how does it rotate — and
|
||||
where's that shape headed?** → [`swarm/credentials.md`](swarm/credentials.md)
|
||||
where's that shape headed?** → [`2-handbook/swarm/credentials.md`](2-handbook/swarm/credentials.md)
|
||||
(the rules, where each secret goes and why) and
|
||||
[`swarm/credentials-reference.md`](swarm/credentials-reference.md) (the
|
||||
[`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 the secret store come up, who writes its grants, how's it
|
||||
sealed?** → [`swarm/bao.md`](swarm/bao.md).
|
||||
- **How does an agent get a prompt at set times, and why doesn't it fire
|
||||
twice after downtime?** → [`swarm/schedules.md`](swarm/schedules.md).
|
||||
- **How to set an agent's model or effort from the swarm, and what happens
|
||||
to its own pick?** → [`swarm/inference.md`](swarm/inference.md).
|
||||
- **How does a PR get checked against its repo's own yes/no rules before
|
||||
a full review?** → [`swarm/review-classifier.md`](swarm/review-classifier.md).
|
||||
- **Does an agent config PR build before it's merged?** →
|
||||
[`swarm/builder.md`](swarm/builder.md).
|
||||
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?** → [`swarm/archetypes.md`](swarm/archetypes.md).
|
||||
- **How long do CI runs take, per repo and PR, and where does the board get
|
||||
it?** → [`swarm/ci-metrics.md`](swarm/ci-metrics.md).
|
||||
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?** →
|
||||
[`swarm/claude-login.md`](swarm/claude-login.md).
|
||||
- **How does an agent get a todo when someone assigns it an issue, and lose it
|
||||
when the issue closes?** → [`swarm/notify-router.md`](swarm/notify-router.md).
|
||||
[`2-handbook/swarm/claude-login.md`](2-handbook/swarm/claude-login.md).
|
||||
|
||||
## Scheduler, CI, observability
|
||||
## 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)?** →
|
||||
[`scheduler/jobq.md`](scheduler/jobq.md) — operator-facing, no implementation detail.
|
||||
[`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?** → [`scheduler/coordinator.md`](scheduler/coordinator.md).
|
||||
queue sources, scheduler internals?** → [`4-implementation/scheduler/coordinator.md`](4-implementation/scheduler/coordinator.md).
|
||||
- **How does the CI runner work? How does it register?** →
|
||||
[`scheduler/ci.md`](scheduler/ci.md).
|
||||
[`4-implementation/scheduler/ci.md`](4-implementation/scheduler/ci.md).
|
||||
- **How are Claude Code metrics (tokens, cost, tool calls) exported to
|
||||
Prometheus/Grafana?** → [`scheduler/observability.md`](scheduler/observability.md).
|
||||
Prometheus/Grafana?** → [`4-implementation/scheduler/observability.md`](4-implementation/scheduler/observability.md).
|
||||
|
||||
## Crate reference
|
||||
### 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).
|
||||
|
||||
### 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?** →
|
||||
[`crates/`](crates/README.md) — every workspace crate's own
|
||||
[`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.
|
||||
|
||||
## Process & conventions
|
||||
## 5. Project
|
||||
|
||||
How the project itself works: processes, conventions, design guides.
|
||||
|
||||
- **Naming, commit style, wire protocol, the `data-async` pattern?** →
|
||||
[`process/conventions.md`](process/conventions.md).
|
||||
- **Why does the nspawn flag look like that?** → [`process/gotchas.md`](process/gotchas.md)
|
||||
[`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?** →
|
||||
[`process/pr-review-gate.md`](process/pr-review-gate.md).
|
||||
[`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).
|
||||
|
|
|
|||
Loading…
Reference in a new issue