Watch
0
0
Fork
You've already forked hyperhive
0

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 2026-11-06 18:30:12 +01:00 • committed by mara
commit 6739bb903d
232 changed files with 736 additions and 701 deletions

View file

@ -4,25 +4,25 @@
# generator, not the formatter, owns these files' layout. Every CLI
# reference doc belongs here — adding one and forgetting this line is
# what made swarmctl's fail.
docs/tools/hivectl-cli.md
docs/tools/swarmctl-cli.md
docs/tools/forge-cli.md
docs/tools/swarm-logs-cli.md
docs/tools/swarm-metrics-cli.md
docs/2-handbook/reference/hivectl-cli.md
docs/2-handbook/reference/swarmctl-cli.md
docs/2-handbook/reference/forge-cli.md
docs/2-handbook/reference/swarm-logs-cli.md
docs/2-handbook/reference/swarm-metrics-cli.md
# Files with multi-line list-item continuations that prettier strips to col 0.
# prettier's `proseWrap: "preserve"` prevents prose reflow but not list-item
# indentation normalisation, so these files need manual re-wrap before
# adding them back to the formatter scope.
AGENTS.md
docs/agent-lifecycle/config-changes.md
docs/process/conventions.md
docs/networking/gateway.md
docs/integrations/matrix.md
docs/agent-lifecycle/persistence.md
docs/web-ui/terminal-rendering.md
docs/tools/forge.md
docs/tools/matrix.md
docs/turn-loop/README.md
docs/web-ui/agent.md
docs/web-ui/dashboard.md
docs/2-handbook/agent-lifecycle/config-changes.md
docs/5-project/process/conventions.md
docs/4-implementation/networking/gateway.md
docs/2-handbook/integrations/matrix.md
docs/2-handbook/agent-lifecycle/persistence.md
docs/4-implementation/web-ui/terminal-rendering.md
docs/2-handbook/tools/forge.md
docs/2-handbook/tools/matrix.md
docs/4-implementation/turn-loop/README.md
docs/2-handbook/web-ui/agent.md
docs/2-handbook/web-ui/dashboard.md

View file

@ -10,20 +10,20 @@ when you need depth on a subsystem. This file is the index.
the env var — inside an agent container `localhost` is the *agent*, not
the forge, so a hardcoded loopback address fails to connect.
- Operator/agent trust-boundary design:
**[docs/trust-boundary/boundary.md](docs/trust-boundary/boundary.md)** (`area/ops` issues
**[docs/2-handbook/trust-boundary/boundary.md](docs/2-handbook/trust-boundary/boundary.md)** (`area/ops` issues
for the deployment/gateway/privsep work — the separator is a **slash**,
and `--label area:ops` now fails with `did you mean "area/ops"?`).
- Agent trust model (trust boundary, prompt-injection threat model,
capability = accepted risk), credential isolation + sandbox threat model:
**[docs/trust-boundary/security.md](docs/trust-boundary/security.md)**.
**[docs/2-handbook/trust-boundary/security.md](docs/2-handbook/trust-boundary/security.md)**.
- Odd-looking nspawn / container plumbing usually has a story:
**[docs/process/gotchas.md](docs/process/gotchas.md)**.
**[docs/5-project/process/gotchas.md](docs/5-project/process/gotchas.md)**.
## Build & check
Always through the devshell — a bare `cargo` fails (`failed to find tool
"cc"`, `cannot find -lsqlite3`). Details:
[`docs/process/conventions.md`](docs/process/conventions.md#building--local-checks).
[`docs/5-project/process/conventions.md`](docs/5-project/process/conventions.md#building--local-checks).
```sh
nix develop -c cargo clippy --all-targets -- -D warnings
@ -33,8 +33,8 @@ nix fmt # treefmt is the CI gate, NOT bare cargo fmt
Changed a `hivectl` / `swarmctl` verb or flag? Regenerate its doc — only
CI's `nix flake check` catches the drift:
`nix develop -c cargo run --bin hivectl -- markdown-docs > docs/tools/hivectl-cli.md`
(same for `swarmctl` → `docs/tools/swarmctl-cli.md`). CI red but local
`nix develop -c cargo run --bin hivectl -- markdown-docs > docs/2-handbook/reference/hivectl-cli.md`
(same for `swarmctl` → `docs/2-handbook/reference/swarmctl-cli.md`). CI red but local
green → build the suspect check (e.g. `nix build
.#checks.x86_64-linux.hivectl-docs`) before blaming the builder.
@ -58,10 +58,10 @@ Per-hive (host + in-container):
crate.
- **`hivectl/`** — operator CLI; talks to `hive-c0re` over the host admin
socket, does NOT link it. Verb reference (CI-enforced):
[`docs/tools/hivectl-cli.md`](docs/tools/hivectl-cli.md).
[`docs/2-handbook/reference/hivectl-cli.md`](docs/2-handbook/reference/hivectl-cli.md).
- **`hive-priv/`** — minimal root helper, socket-activated at
`/run/hive/priv.sock`; the few root ops (bind-mount edits, nsenter)
`hive-c0re` delegates. See `docs/trust-boundary/boundary.md`.
`hive-c0re` delegates. See `docs/2-handbook/trust-boundary/boundary.md`.
- **`hive-agent/`** — the in-container serve loop: turn-loop *policy*
(`turn.rs`) over `hive-runtime`, per-agent web UI, event + turn-stats
sinks, system-prompt renderer, claude launch config (`mcp_config.rs`).
@ -130,7 +130,7 @@ Swarm-level:
**`users.yml` in place**, shared with `swarm-authelia-bridge`; that
crate's README says what both writers must uphold. Verb reference
(CI-enforced):
[`docs/tools/swarmctl-cli.md`](docs/tools/swarmctl-cli.md).
[`docs/2-handbook/reference/swarmctl-cli.md`](docs/2-handbook/reference/swarmctl-cli.md).
- **`swarm-authelia-bridge/`** (+ **`swarm-authelia-bridge-sock/`** wire
types) — the other writer of authelia's users DB; runs inside
`swarm-authelia`.
@ -164,20 +164,20 @@ Swarm-level:
- **`swarm-builder/`** — builds agent config PR heads for commit status,
builds each agent from `internal/meta` before its deploy, and evaluates the
agent archetypes the create form lists.
Design: [`docs/swarm/builder.md`](docs/swarm/builder.md).
Design: [`docs/4-implementation/swarm/builder.md`](docs/4-implementation/swarm/builder.md).
- **`swarm-ci-metrics/`** — polls the forge's Actions runs and pushes each
finished run's duration and queue wait to the metrics store. Design:
[`docs/swarm/ci-metrics.md`](docs/swarm/ci-metrics.md).
[`docs/4-implementation/swarm/ci-metrics.md`](docs/4-implementation/swarm/ci-metrics.md).
- **`swarm-claude-login/`** — runs `claude auth login` for one agent and
stores the credentials at `swarm/agents/<agent>/claude-credentials`.
Design: [`docs/swarm/claude-login.md`](docs/swarm/claude-login.md).
Design: [`docs/2-handbook/swarm/claude-login.md`](docs/2-handbook/swarm/claude-login.md).
- **`swarm-notify-router/`** — forge events from swarm-controller's
webhooks to todos on the agents they concern, through each agent's own
consumer on the `ROUTER_TODOS` stream. Design:
[`docs/swarm/notify-router.md`](docs/swarm/notify-router.md).
[`docs/4-implementation/swarm/notify-router.md`](docs/4-implementation/swarm/notify-router.md).
- **`swarm-review-classifier/`** — one `claude --print` per PR
classification, no tools, no forge credential. Design:
[`docs/swarm/review-classifier.md`](docs/swarm/review-classifier.md).
[`docs/4-implementation/swarm/review-classifier.md`](docs/4-implementation/swarm/review-classifier.md).
### External dependencies with no directory here
@ -213,7 +213,7 @@ in this file and drifted.
- **Never add `#[allow(clippy::…)]`** — fix the lint instead (extract a
helper, add backticks, etc.). Worked examples:
[`docs/process/conventions.md`](docs/process/conventions.md#building--local-checks).
[`docs/5-project/process/conventions.md`](docs/5-project/process/conventions.md#building--local-checks).
- **Pre-push lint hook** (catches tracker-tag and comment-block failures
before CI does — install once per clone):
`ln -sf ../../scripts/pre-push .git/hooks/pre-push`
@ -225,7 +225,7 @@ in this file and drifted.
- **Operator-facing doc with real implementation detail mixed in**: wrap
the implementation part in a `<details><summary>…</summary>` block
(blank line after `<summary>` so the markdown inside renders) rather
than a sibling page — see `docs/integrations/github.md`'s
than a sibling page — see `docs/2-handbook/integrations/github.md`'s
"Implementation" section. It only collapses in a rendered browser, and
the `<summary>` line isn't markdown-processed, so keep it plain prose
with no backticks.

View file

@ -290,5 +290,5 @@ x509-cert = { version = "0.2", default-features = false, features = ["pem"] }
# Test doubles with expectations (canned replies, call counts, argument
# matchers). Dev-dependency only, and used behind `#[cfg(test)]`, so release
# builds never compile it. See "Testing seams and test doubles" in
# `docs/process/conventions.md`.
# `docs/5-project/process/conventions.md`.
mockall = "0.15"

View file

@ -81,24 +81,24 @@ box it gets:
- **messaging** — peers and the operator talk over matrix; `send` / `recv` is the hive-local broker for system traffic and agents without matrix,
`remind` to wake itself, scheduled prompts the operator sets for it at
swarm level, and a todo list that forge notifications and other
producers feed. → [schedules](docs/swarm/schedules.md)
producers feed. → [schedules](docs/2-handbook/swarm/schedules.md)
- **background bash** — long-running commands as tracked tasks
(`run` / `status` / `kill`), so a build doesn't block the turn. →
[bash](docs/tools/bash.md)
[bash](docs/2-handbook/tools/bash.md)
- **subagents** — nested sessions on the agent's own runtime, optionally
re-prompted toward a goal over several turns. →
[subagent](docs/tools/subagent.md)
[subagent](docs/2-handbook/tools/subagent.md)
- **forge** — its own Forgejo account, the `hive-forge` CLI, git
credentials, and notifications turned into todos. Optional linked
accounts on other forges, GitLab (`glab` + push), and GitHub (`gh` + push) via
`services.hyperhive.agent.github.enable`. →
[forge](docs/integrations/forge.md) · [gitlab](docs/integrations/gitlab.md) ·
[github](docs/integrations/github.md)
[forge](docs/2-handbook/integrations/forge.md) · [gitlab](docs/2-handbook/integrations/gitlab.md) ·
[github](docs/2-handbook/integrations/github.md)
- **matrix** — its own account(s) on the swarm homeserver, as MCP tools. →
[matrix](docs/tools/matrix.md)
[matrix](docs/2-handbook/tools/matrix.md)
- **knowledge** — the swarm's shared `internal/knowledge` repo, read-only
at `/knowledge`, plus hyperhive's own docs in the container. →
[knowledge](docs/integrations/knowledge.md)
[knowledge](docs/2-handbook/integrations/knowledge.md)
- **web UI** — a per-agent page behind the gateway: live terminal of the
turn stream, model / effort switching, cancel.
- **GUI** (opt-in, `services.hyperhive.agent.gui.enable`) — a Wayland
@ -106,7 +106,7 @@ box it gets:
the web UI.
- **reverse engineering** (opt-in, `services.hyperhive.agent.rea.enable`, or the
`reverse-engineer` archetype) — REA and Ghidra 12.1 in the container, with
their MCP tools allowed. → [archetypes](docs/swarm/archetypes.md)
their MCP tools allowed. → [archetypes](docs/2-handbook/swarm/archetypes.md)
- **your own tools** — any extra MCP server (stdio or http) via
`services.hyperhive.agent.extraMcpServers`, and any NixOS config you'd
put on a machine.
@ -114,7 +114,7 @@ box it gets:
## Quick start: an all-local swarm
The whole swarm on one box — a hive plus every shared service. Good for a
dev box or a single-host deployment; [`docs/swarm/`](docs/swarm/README.md)
dev box or a single-host deployment; [`docs/swarm/`](docs/2-handbook/swarm/README.md)
covers spreading a swarm across hosts.
```nix
@ -158,7 +158,7 @@ After `nixos-rebuild switch` the swarm UI answers on the swarm domain, and
the hive brings up the manager agent (`ruth`). A few steps stay
deliberately human — initialising the secret store, giving ruth her store
identity, creating your SSO account. Walk through
**[`docs/getting-started/setup.md`](docs/getting-started/setup.md)**
**[`docs/1-getting-started/setup.md`](docs/1-getting-started/setup.md)**
once, top to bottom.
## Operating it
@ -167,14 +167,14 @@ once, top to bottom.
(`admins` group): hive roster and status, every agent with its live
terminal and wanted state, creating agents, linking external forge and
matrix accounts, the job graph, a cross-repo issue report. →
[`docs/swarm/ui.md`](docs/swarm/ui.md)
[`docs/2-handbook/swarm/ui.md`](docs/2-handbook/swarm/ui.md)
- **`swarmctl`** — the swarm's CLI, on the swarm-controller host: create
agents and mint their identities, manage SSO users, make forge admins.
→ [reference](docs/tools/swarmctl-cli.md)
→ [reference](docs/2-handbook/reference/swarmctl-cli.md)
- **per-hive** — each hive's dashboard (container state,
rebuild queue) and `hivectl` for host-level administration and
container shells. → [`docs/web-ui/`](docs/web-ui/README.md) ·
[hivectl](docs/tools/hivectl.md)
container shells. → [`docs/web-ui/`](docs/2-handbook/web-ui/README.md) ·
[hivectl](docs/2-handbook/tools/hivectl.md)
You are an SSO user too: `swarmctl user add <you> --group admins`, and a
first login through authelia creates your forge and matrix accounts;
@ -187,10 +187,10 @@ one becomes a homeserver admin within five minutes of that first login.
pick the page for your task rather than reading front to back. Some
common entry points:
- connecting hives into a swarm → [`swarm/`](docs/swarm/README.md)
- how config changes flow → [`agent-lifecycle/config-changes.md`](docs/agent-lifecycle/config-changes.md)
- trust boundary + threat model → [`trust-boundary/`](docs/trust-boundary/boundary.md)
- what an agent's turn looks like → [`turn-loop/`](docs/turn-loop/README.md)
- connecting hives into a swarm → [`swarm/`](docs/2-handbook/swarm/README.md)
- how config changes flow → [`agent-lifecycle/config-changes.md`](docs/2-handbook/agent-lifecycle/config-changes.md)
- trust boundary + threat model → [`trust-boundary/`](docs/2-handbook/trust-boundary/boundary.md)
- what an agent's turn looks like → [`turn-loop/`](docs/4-implementation/turn-loop/README.md)
- every `services.hyperhive.*` option → [options reference](https://hyperhive.darkest.space/options/)
## Hacking on it
@ -205,6 +205,6 @@ sudo nixos-rebuild switch --flake .#<host>
```
Conventions (commit style, no `#[allow(clippy::…)]`, the pre-push hook)
live in [`docs/process/conventions.md`](docs/process/conventions.md).
live in [`docs/5-project/process/conventions.md`](docs/5-project/process/conventions.md).
Issues + backlog are on the
[forge](https://forge.darkest.space/hyperhive/hyperhive/issues).

View file

@ -84,11 +84,11 @@ Run `nixos-rebuild switch --flake .#my-host`. The swarm UI then answers at
Leave the other options at their defaults until you need them:
- Spreading a swarm over more than one host, and the credentials a split swarm
needs: [`swarm/README.md`](../swarm/README.md) and
[`swarm/credentials.md`](../swarm/credentials.md).
needs: [`swarm/README.md`](../2-handbook/swarm/README.md) and
[`swarm/credentials.md`](../2-handbook/swarm/credentials.md).
- Every option, with its type and default:
[the options reference](https://hyperhive.darkest.space/options/).
- The secret store's seal and the granter: [`swarm/bao.md`](../swarm/bao.md).
- The secret store's seal and the granter: [`swarm/bao.md`](../4-implementation/swarm/bao.md).
## Next

View file

@ -10,7 +10,7 @@ Every command runs as **root on the host**.
> **Not all-local?** Each step says which host it runs on. A split swarm
> also has credentials you can't generate where they're read — each
> host's mTLS identity at the secret store. Read [`swarm/credentials.md`](../swarm/credentials.md) first; it
> host's mTLS identity at the secret store. Read [`swarm/credentials.md`](../2-handbook/swarm/credentials.md) first; it
> says which files you place, and where.
## 1 · Secret store
@ -53,7 +53,7 @@ active` while the store comes up; the units retry every 30s for a day.
With the default `pkcs11` seal the store unseals itself from here on. With
`deploy.bao.seal = "shamir"`, run `bao operator unseal` after every restart.
What the granter is, why it's root-equivalent, and the store's TLS:
[`swarm/bao.md`](../swarm/bao.md).
[`swarm/bao.md`](../4-implementation/swarm/bao.md).
## 2 · Your SSO account
@ -71,13 +71,13 @@ It prints a generated password once — record it. Keep both flags:
- **`--email`** — the forge won't create an account without one.
Fix either afterwards with `swarmctl user update mara --add-group admins
--email …`. Details: [`swarm/sso.md`](../swarm/sso.md).
--email …`. Details: [`swarm/sso.md`](../2-handbook/swarm/sso.md).
## 3 · Swarm UI login
Open `https://<swarm.domain>/` and sign in with the account from step 2. The
name resolves on the box itself through `/etc/hosts`; from anywhere else it
needs a real DNS record. → [`swarm/ui.md`](../swarm/ui.md)
needs a real DNS record. → [`swarm/ui.md`](../2-handbook/swarm/ui.md)
Signing in to the forge once through SSO creates your forge account under the
same username. Then, _on the swarm-controller's host_:
@ -114,7 +114,7 @@ container keeps starting with the hive meanwhile.
From here on, ask ruth. Open her card on `/agents` in the swarm UI and use the
message box under her terminal. She is the manager agent: her MCP surface is the
privileged one that configures agents, and she can recover the others. Changes to
an agent's config arrive as PRs you merge. → [`agent-lifecycle/agent-roster.md`](../agent-lifecycle/agent-roster.md)
an agent's config arrive as PRs you merge. → [`agent-lifecycle/agent-roster.md`](../2-handbook/agent-lifecycle/agent-roster.md)
To create an agent yourself instead, use the swarm UI, or:
@ -129,10 +129,10 @@ swarm UI's job view for progress.
Later config changes are PRs on `agent-configs/iris`; you merge them on the
forge, and the merge deploys them. →
[`agent-lifecycle/config-changes.md`](../agent-lifecycle/config-changes.md#config-changes)
[`agent-lifecycle/config-changes.md`](../2-handbook/agent-lifecycle/config-changes.md#config-changes)
## After setup: use the swarm UI
Day-to-day operation happens in the swarm UI at `https://<swarm.domain>/`:
agents, hives, jobs and messages. Swarm-level operations take over from the
per-hive dashboard and `hivectl`. → [`swarm/ui.md`](../swarm/ui.md)
per-hive dashboard and `hivectl`. → [`swarm/ui.md`](../2-handbook/swarm/ui.md)

View file

@ -13,7 +13,7 @@ This doc covers what the roster file holds, the map-shaped alternative
## Where the roster lives
"The roster" means two different, non-overlapping things depending on
scope. The [README](../../README.md)'s control-plane row ("`swarm-controller`
scope. The [README](../../../README.md)'s control-plane row ("`swarm-controller`
holds the hive directory, the agent roster and the job graph") is the
**swarm-wide** one: `GET /api/agents` on swarm-controller reads
straight from the swarm's authelia identity store over
@ -96,7 +96,7 @@ state dirs work as for every other agent.
into the caller's own inbox) is on this socket too, unprivileged on
both flavours; matrix, bash and forge don't call it — their
notifications push a todo on the harness's in-agent socket (see
[`docs/turn-loop/mcp.md`](../turn-loop/mcp.md#waking-the-agent-from-inside-the-container)).
[`docs/4-implementation/turn-loop/mcp.md`](../../4-implementation/turn-loop/mcp.md#waking-the-agent-from-inside-the-container)).
- **Storage/mounts** — the `manage_root_agent` permission, which the swarm
UI's setup assistant creates ruth with, gets a container
`/var/lib/hyperhive/agents` bind-mounted RW at `/agents` (so it can
@ -115,7 +115,7 @@ state dirs work as for every other agent.
from an [archetype](../swarm/archetypes.md) is told it has no config repo.
- **Tool allow-list** — the MCP tools claude sees come from the agent's
permissions alone, the same mechanism for every agent
([`docs/turn-loop/mcp.md`](../turn-loop/mcp.md)). Ruth's permissions
([`docs/4-implementation/turn-loop/mcp.md`](../../4-implementation/turn-loop/mcp.md)). Ruth's permissions
are the default plus `manage_root_agent`, stored for her like any grant.
- **State dirs** — _not_ treated as an exception: `HYPERHIVE_STATE_DIR` is
injected uniformly via `systemd.globalEnvironment` for every

View file

@ -116,7 +116,7 @@ agent's forge config repo, the one config PRs merge into) and one
(the dashboard port, the pinned claude-code, extra OTEL labels, the queue
address) aren't in it:
`hive-priv` writes them to the container's `/etc/hyperhive-hive-facts` at
start (see `docs/process/conventions.md`).
start (see `docs/5-project/process/conventions.md`).
A config that sits only in a local checkout, not on forge `main`, never
deploys.
@ -134,14 +134,14 @@ is unset, since every agent would come up with no forge.
swarm-controller commits `internal/meta`: one `flake.nix` and `flake.lock` for
every agent any hive places (the pins:
[`docs/swarm/builder.md`](../swarm/builder.md#meta-flake-lock)). The swarm
[`docs/4-implementation/swarm/builder.md`](../../4-implementation/swarm/builder.md#meta-flake-lock)). The swarm
builder builds every agent from it, and a hive deploys that build. While the
swarm has recorded no build of an agent, that agent's deploy fails and names the
agent. The controller queues
its update of the repo before the deploy request for a merged config commit
and for a new agent, and sends the deploy only when that update succeeded and
the swarm builder built the agent from the updated repo (the
[deploy gate](../swarm/builder.md#deploy-gate)). A failed build skips the deploy, and the timer builds again. A merge whose webhook delivery never arrives gets the same update, build and deploy within five minutes, from the controller's drift pass (see the paragraph on config drift in the deploy gate section).
[deploy gate](../../4-implementation/swarm/builder.md#deploy-gate)). A failed build skips the deploy, and the timer builds again. A merge whose webhook delivery never arrives gets the same update, build and deploy within five minutes, from the controller's drift pass (see the paragraph on config drift in the deploy gate section).
- **Choosing the closure.** The hive doesn't choose. It deploys the closure the
agent's record in `agent-closures` declares, whichever `internal/meta` commit
@ -163,7 +163,7 @@ the swarm builder built the agent from the updated repo (the
`{"op":"update_container","name":"atlas","stream":true,"toplevel":"/nix/store/<hash>-nixos-system-atlas"}`.
A rebuild with no record, or none the builder pushed, fails with an error
that names the agent; see
[`docs/swarm/builder.md`](../swarm/builder.md#rebuilds-download-the-closure).
[`docs/4-implementation/swarm/builder.md`](../../4-implementation/swarm/builder.md#rebuilds-download-the-closure).
- **Hyperhive.** The commit pins one hyperhive rev for the swarm, so an agent
runs the hyperhive of the controller's deploy, not its hive's.
- **Marker.** After a successful swap or create `hive-c0re` writes the closure's
@ -218,7 +218,7 @@ each `git` call inline, never writing it into a repo's config, so
no stored token sits in a repo an agent might one day read.
The dashboard deep-links into this org — a `config repo` link
per container row. See `docs/web-ui/dashboard.md`.
per container row. See `docs/2-handbook/web-ui/dashboard.md`.
### Submitting agent's view of config repos
@ -234,7 +234,7 @@ path reaches the same file without the review.
Agents holding the `manage_root_agent` permission (granted per agent in
the swarm's `agent-permissions` record; see
`docs/process/conventions.md#permissions`) get additional host-side bind
`docs/5-project/process/conventions.md#permissions`) get additional host-side bind
mounts via `set_nspawn_flags`:
- `/var/lib/hyperhive/agents/<n>/state` → `/agents/<n>/state` (RW) for
@ -329,7 +329,7 @@ Today hive-c0re sends two: the `/knowledge updated` broadcast
detected"`; a swarm-level grafana alert matches that log line directly
and pages the operator, with no agent (and no per-hive dashboard
banner) in the loop. See
[`docs/scheduler/observability.md`](../scheduler/observability.md#container-crash-alerting-hive-c0re).
[`docs/4-implementation/scheduler/observability.md`](../../4-implementation/scheduler/observability.md#container-crash-alerting-hive-c0re).
The remaining lower-urgency lifecycle notices — `Rebuilt`, `Killed`,
`Destroyed`, `NeedsLogin`, `LoggedIn` — are "FYI, check

View file

@ -62,8 +62,8 @@ table, and the per-agent power-intent registry:
This is the durable power *intent* the job queue reconciles the
observed container state against; intent survives hive-c0re
restarts even though in-flight queue work doesn't. See
[`docs/scheduler/coordinator.md`'s Desired-state
section](../scheduler/coordinator.md#desired-state-spec-vs-status) for who
[`docs/4-implementation/scheduler/coordinator.md`'s Desired-state
section](../../4-implementation/scheduler/coordinator.md#desired-state-spec-vs-status) for who
writes and reads it and how reconciliation works.
On a host whose hive-c0re once kept scheduled prompts, the file also
@ -114,7 +114,7 @@ back through when debugging a regression. Age-only within the
history sooner than a quiet one. The trade-off (accepted): a
misbehaving harness can skip its own cleanup — but a compromised harness is
already inside the container trust boundary
([`docs/trust-boundary/security.md`](../trust-boundary/security.md)), and these are ephemeral local
([`docs/2-handbook/trust-boundary/security.md`](../trust-boundary/security.md)), and these are ephemeral local
artifacts, so cleaning them up where they live is the honest fix.
<!-- vale write-good.Passive = YES -->
@ -236,7 +236,7 @@ destroy/recreate, gone on `--purge`.
Empty marker file. Its presence parks the agent's turn loop: the
harness keeps serving its web UI and MCP daemons but drives no turns,
and inbox messages queue unacked until it's removed (see
[turn loop](../turn-loop/README.md#the-loop)).
[turn loop](../../4-implementation/turn-loop/README.md#the-loop)).
<!-- vale write-good.Passive = NO -->
Unusually, it's read and written from **both** sides of the harness
@ -278,7 +278,7 @@ Under `/var/lib/hyperhive/agents/<name>/`:
has a value.
- `hyperhive-harness.json` — rate-limited / needs-login flags read
by the dashboard's async container-state fetch. See
`docs/web-ui/dashboard.md::Container row`.
`docs/2-handbook/web-ui/dashboard.md::Container row`.
The agent writes its own instructions to `AGENTS.md` here; claude and
opencode load it automatically from their cwd, `state/`. At boot,
@ -289,7 +289,7 @@ Under `/var/lib/hyperhive/agents/<name>/`:
to the swarm, which reads that copy, and applies the git diffs the
swarm sends to edit it. A new agent's first start writes the text given at
create, only when no file exists. This file stays the only copy that counts:
[`docs/swarm/README.md`](../swarm/README.md#an-agents-agentsmd).
[`docs/2-handbook/swarm/README.md`](../swarm/README.md#an-agents-agentsmd).
- `harness/` — harness-internal ephemeral state; not intended for
agent consumption. Bind-mounted to `/agents/<name>/harness`
inside the container (`$HYPERHIVE_HARNESS_DIR`). Contents:
@ -667,7 +667,7 @@ subvolume creation/deletion above.
This is the same subvolume `hivectl agent <name> subvol snapshot push`
sends to the swarm's snapshot store — see
[`docs/networking/snapshot-store.md`](../networking/snapshot-store.md) for what a pushed
[`docs/4-implementation/networking/snapshot-store.md`](../../4-implementation/networking/snapshot-store.md) for what a pushed
snapshot contains and how the store authenticates a sender.
The subvolume is the whole agent state root, so `work/` is part of every
@ -704,7 +704,7 @@ the store answers that it holds none, never because a read failed.
place; a missing file is an empty set. A file the controller can't
read or parse stops the sync, grants included, and the controller logs
`operator matrix admin: pass failed` on every pass. See
[`docs/integrations/matrix.md`](../integrations/matrix.md#operators-are-homeserver-admins).
[`docs/2-handbook/integrations/matrix.md`](../integrations/matrix.md#operators-are-homeserver-admins).
## Run-time dirs

View file

@ -10,7 +10,7 @@ which build it runs, how it's served, what it mirrors, where its
host-local secrets sit).
Container
shape, ROOT_URL / sub-domain routing, and operator-vs-in-cluster URL
handling live in [`docs/networking/gateway.md`](../networking/gateway.md); this file owns the
handling live in [`docs/4-implementation/networking/gateway.md`](../../4-implementation/networking/gateway.md); this file owns the
per-agent integration story and the notification pump that wakes
each agent on relevant activity.
@ -114,7 +114,7 @@ git+<forge>/agent-configs/<n>.git?rev=<sha>`; see
[config-changes.md § Meta flake](../agent-lifecycle/config-changes.md#meta-flake)).
The `hive-forge` CLI (separate workspace crate, see
[`README.md`](../README.md) file map) wraps the Forgejo REST API
[`README.md`](../../README.md) file map) wraps the Forgejo REST API
with the per-agent token; agents call it for issue / PR / comment
ops as if it were a peer. All REST calls across the workspace
(`hive-forge` verbs, hive-c0re provisioning, this poller) go through
@ -392,4 +392,4 @@ delivers every unread notification it's handed. A hive-forge CLI
subscription verb bounds the firehose explicitly (dropping broad repo
watches an agent doesn't need) — the poller never guesses which
watches to drop. See the `subscription` verb in
[`docs/tools/forge.md`](../tools/forge.md).
[`docs/2-handbook/tools/forge.md`](../tools/forge.md).

View file

@ -44,7 +44,7 @@ hive-c0re maintains the local clone at
`/var/lib/hyperhive/knowledge` via two paths:
1. **Swarm event** — the swarm controller holds the single push hook on
`internal/knowledge` (see `docs/swarm/README.md` § Swarm-wide forge
`internal/knowledge` (see `docs/2-handbook/swarm/README.md` § Swarm-wide forge
webhooks). On any push to main, including merge commits, it sends an
event to every hive over the swarm queue and each hive runs `git
pull`, so agents see the new content on their next turn.

View file

@ -11,11 +11,11 @@ homeserver, on one host. Two namespaces configure it:
`enable`, `gui.package`, `trustedServers`,
`maxRequestSize`, `sso.clientSecretFile`.
Vhost routing lives in [`gateway.md`](../networking/gateway.md).
Vhost routing lives in [`gateway.md`](../../4-implementation/networking/gateway.md).
## Container shape
Same shape as [`gateway.md::hive-forge container shape`](../networking/gateway.md):
Same shape as [`gateway.md::hive-forge container shape`](../../4-implementation/networking/gateway.md):
- Container name `hive-matrix` (not `h-*`) so c0re's lifecycle
scanner ignores it; operator manages via the standard
@ -101,7 +101,7 @@ the hive has no matrix API URL to set.
Federation peers find the homeserver through `.well-known/matrix/server`
at the server name, which names `<gatewayHost>:443`
([`gateway.md::Discovery flow`](../networking/gateway.md#discovery-flow-matrix)).
([`gateway.md::Discovery flow`](../../4-implementation/networking/gateway.md#discovery-flow-matrix)).
Port 8448 isn't used.
Outbound, the container sits on the hive bridge like the CI runner: it
@ -392,7 +392,7 @@ homeserver at all rather than of a setting:
`server_name`'s own bogus-value guard lives in `hive-network.nix`
(`services.hyperhive.domain != null`), not here — see
[`docs/networking/network.md`](../networking/network.md).
[`docs/4-implementation/networking/network.md`](../../4-implementation/networking/network.md).
## fluffychat-web build fixes

View file

@ -8,8 +8,8 @@ host is a swarm of one.
This page is for the operator. It covers the control plane, how a hive
joins the directory, and how hives and agents report upward. The steps for a
fresh swarm are in [`setup.md`](../getting-started/setup.md); the all-local
config is the [README quick start](../../README.md#quick-start-an-all-local-swarm).
fresh swarm are in [`setup.md`](../../1-getting-started/setup.md); the all-local
config is the [README quick start](../../../README.md#quick-start-an-all-local-swarm).
Option reference: `services.hyperhive.swarm.*` (swarm-wide facts, identical
on every host) and `services.hyperhive.deploy.*` (whether _this_ host runs
@ -24,17 +24,17 @@ grafana, the controller, authelia, …) →
- **scheduled prompts** — named prompts for one or more agents at set times,
kept by the swarm and fired in each agent's container. → [`schedules.md`](schedules.md)
- **inference settings** — the model and effort the swarm sets for an agent,
over its own. → [`inference.md`](inference.md)
over its own. → [`inference.md`](../../4-implementation/swarm/inference.md)
- **resource caps** — the CPU and memory cap the swarm sets for an agent,
over its hive's. →
[`coordinator.md`](../scheduler/coordinator.md#container-resource-limits)
[`coordinator.md`](../../4-implementation/scheduler/coordinator.md#container-resource-limits)
- **review classifier** — checks a PR against its repo's own yes/no rules
and posts the result as a review. →
[`review-classifier.md`](review-classifier.md)
[`review-classifier.md`](../../4-implementation/swarm/review-classifier.md)
- **notification router** — forge events turned into todos on the agents
they concern: assigned, unassigned, cleared on close; and the classifier's
review requested on a push. →
[`notify-router.md`](notify-router.md)
[`notify-router.md`](../../4-implementation/swarm/notify-router.md)
- **swarm UI** — the operator's day-to-day surface, on the swarm apex,
`admins` only. → [`ui.md`](ui.md)
- **shared services** — one forge, homeserver, SSO, queue and metrics/logs
@ -45,12 +45,12 @@ grafana, the controller, authelia, …) →
every credential the swarm holds, who mints it, who reads it, how it renews
and where it lives → [`credentials-reference.md`](credentials-reference.md) ·
how the store comes up, who writes its grants and how it unseals →
[`bao.md`](bao.md)
[`bao.md`](../../4-implementation/swarm/bao.md)
- **swarm CA** — the store root every hive's gateway leaf chains to, and what to
hand a peer. → [`ca.md`](ca.md)
hand a peer. → [`ca.md`](../../4-implementation/swarm/ca.md)
- **snapshot store** — the swarm's one `btrfs receive` endpoint,
`swarm.snapshotStore.{address,port}`. →
[`snapshot-store.md`](../networking/snapshot-store.md)
[`snapshot-store.md`](../../4-implementation/networking/snapshot-store.md)
## Swarm controller
@ -74,7 +74,7 @@ fact about swarm topology, not about whether this host runs a hive.
What it serves, why it's a unix socket rather than a port, and the
socket-directory constraint that governs where `socketPath` may point:
[`swarm-controller/README.md`](../../swarm-controller/README.md).
[`swarm-controller/README.md`](../../../swarm-controller/README.md).
### Per-hive status (`GET /api/hives/status`)
@ -102,7 +102,7 @@ needs. A hive on an older release lists none.
The snapshot also carries `egress_deny_applied`, the revision of the egress deny
list the hive last rendered into its proxy (`0` when the swarm has none). A hive
on an older release, or one that hasn't read the list yet, leaves it out; see
[the egress proxy](../networking/network.md#egress-proxy-squid).
[the egress proxy](../../4-implementation/networking/network.md#egress-proxy-squid).
Every row also carries `last_seen_unix` and `age_seconds` if you want to
apply your own threshold. The timestamp is the one the queue recorded on
@ -292,7 +292,7 @@ Swarm-side, `GET /api/agents/<name>/state/stream` relays that subject as SSE,
resolving the agent's hive at request time exactly as the terminal stream does.
The payload passes through opaquely. Separately, the controller keeps each
agent's latest `model`, `effort` and their sources for
`GET /api/agents/<name>/inference` ([`inference.md`](inference.md)), and each
`GET /api/agents/<name>/inference` ([`inference.md`](../../4-implementation/swarm/inference.md)), and each
agent's latest `needs_login` for the `needs_login` field of
`GET /api/agents/status`. That field is `null` until a header carrying the flag
arrives, so for up to a minute after the controller starts, and for an agent
@ -434,12 +434,12 @@ itself, all under `https://<swarm.domain>/webhook/forge/`:
- a `pull_request` hook on the `agent-configs` org
- an instance-wide `push` system hook, for commit metrics
- an instance-wide `pull_request_review_request` system hook, which starts
the [review classifier](review-classifier.md#trigger-and-lifecycle)
the [review classifier](../../4-implementation/swarm/review-classifier.md#trigger-and-lifecycle)
- instance-wide `issues` + `issue_assign` and `pull_request` +
`pull_request_assign` + `pull_request_sync` + `pull_request_review_approved` +
`pull_request_review_rejected` + `pull_request_review_comment` system hooks, whose deliveries it
keeps in the `SWARM_EVENTS` stream for the
[notification router](notify-router.md#the-path)
[notification router](../../4-implementation/swarm/notify-router.md#the-path)
The controller **interprets** a delivery and sends hives a specific
message — _the knowledge repo changed_, _deploy agent `foo` at rev
@ -478,7 +478,7 @@ host also serves the swarm UI vhost — that's what publishes the
endpoint, and a hook the forge can't reach would collect failed
deliveries while looking healthy. The controller generates the HMAC
secret on first start and keeps it
(see [`docs/agent-lifecycle/persistence.md`](../agent-lifecycle/persistence.md)).
(see [`docs/2-handbook/agent-lifecycle/persistence.md`](../agent-lifecycle/persistence.md)).
To check it's working, push to `internal/knowledge` and look for
`webhook: verified delivery` in `journalctl -u swarm-controller`. A
@ -559,10 +559,10 @@ system prompts — and federated hives at different domains can share one.
hive's domain. `swarm.name` names the group; `hiveName` names this hive.
The env-var chain and `qualify()` semantics:
[`conventions.md`](../process/conventions.md) § Hive identity.
[`conventions.md`](../../5-project/process/conventions.md) § Hive identity.
Trust inside a swarm comes from the secret store's `pki` root
([`ca.md`](ca.md)): every hive's gateway leaf chains to it. Trusting a
([`ca.md`](../../4-implementation/swarm/ca.md)): every hive's gateway leaf chains to it. Trusting a
hive whose root this swarm doesn't own — another swarm's — has no
mechanism.
@ -672,11 +672,11 @@ If both hosts are behind NAT, you need a STUN relay or a third host
## Cross-references
- [`ui.md`](ui.md) — the swarm UI, the operator surface for "what hives exist"
- [`../networking/snapshot-store.md`](../networking/snapshot-store.md) — the
- [`../networking/snapshot-store.md`](../../4-implementation/networking/snapshot-store.md) — the
swarm's `btrfs receive` endpoint and the `swarm.snapshotStore` option
- [`../process/conventions.md`](../process/conventions.md) § Hive identity —
- [`../process/conventions.md`](../../5-project/process/conventions.md) § Hive identity —
env vars, qualified labels
- [`../integrations/matrix.md`](../integrations/matrix.md) — matrix
federation, TLS cert autogeneration, firewall posture
- [`../networking/gateway.md`](../networking/gateway.md) — nginx vhosts and
- [`../networking/gateway.md`](../../4-implementation/networking/gateway.md) — nginx vhosts and
the `.well-known/matrix/` autodiscovery scheme

Some files were not shown because too many files have changed in this diff Show more