Watch
0
0
Fork
You've already forked hyperhive
0

docs: restructure into topic subdirectories, collapse duplicated index

Per mara's go-ahead on hyperhive#3902 ("getting started is good, but
terminal rendering does not go in there i think"):

Moved 21 top-level docs/*.md files into 7 new topic subdirectories
(existing web-ui/, turn-loop/, swarm/, tools/, crates/ untouched):
  getting-started/  setup.md
  agent-lifecycle/  agent-hierarchy.md, approvals.md, persistence.md
  trust-boundary/   boundary.md, security.md
  integrations/     forge.md, matrix.md, github.md, knowledge.md
  networking/       gateway.md, network.md, snapshot-store.md
  scheduler/        jobq.md, coordinator.md, ci.md, observability.md
  process/          conventions.md, gotchas.md, pr-review-gate.md
  web-ui/           terminal-rendering.md (moved into the EXISTING dir,
                    per mara's correction to the original getting-started
                    guess -- it's UI implementation detail, not onboarding)

The physical layout now matches docs/README.md's own topical headers,
which already amounted to this taxonomy -- see the scoping comment on
the issue for the two findings that motivated this (a genuine
duplication between CLAUDE.md's old "Reading paths" list and
docs/README.md's grouped one, since drifted out of sync with each
other; and the flat layout not matching the grouping we already had).

Fixed every cross-reference this moved across the whole repo (~120
files: docs/ internal links at every depth, Rust doc comments, nix
module option docs, crate READMEs) -- verified two ways: a grep sweep
confirming zero remaining references to any old path, and a script
that resolves every markdown link in docs/**/*.md + CLAUDE.md +
README.md against the filesystem and reports anything that doesn't
exist (zero broken links).

Collapsed CLAUDE.md's "Reading paths" section (the duplicate) down to
a pointer at docs/README.md, now the single index. Rewrote
docs/README.md itself to use the new subdirectory paths and added the
one doc it was missing that CLAUDE.md's old copy had (pr-review-gate.md).

Classified all 22 docs/*.md files first via a haiku subagent (mara's
suggestion) on two axes -- proposed grouping and operator-vs-
implementation focus -- before finalizing the taxonomy; spot-checked
the report and found internal inconsistencies (its classification
table disagreed with its own summary section for a few files), so this
taxonomy is my original proposal + the one correction mara gave
directly, not a blind application of the subagent's table. The
operator-focus data it gathered is still useful for a follow-up
content pass (docs skewing 'mixed' rather than pure operator-facing),
not addressed in this PR -- structure only.

nix fmt clean, both pre-push lints clean.
This commit is contained in:
iris 2026-09-02 01:47:05 +02:00 • committed by mara
commit 07b62612b0
124 changed files with 301 additions and 377 deletions

View file

@ -10,12 +10,12 @@ 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/boundary.md](docs/boundary.md)** (`area/ops` issues
**[docs/trust-boundary/boundary.md](docs/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/security.md](docs/security.md)**.
**[docs/trust-boundary/security.md](docs/trust-boundary/security.md)**.
## Repo map
@ -38,7 +38,7 @@ hand-maintained per-file tree drifts out of sync with the code.
- **`hivectl/`** — standalone operator CLI (`hivectl` binary). Talks to
the `hive-c0re` daemon over the host admin socket (`hive-host-sock`
wire types) — does NOT link `hive-c0re`. Full, always-current verb
reference (CI-enforced against the clap tree, see `docs/conventions.md`):
reference (CI-enforced against the clap tree, see `docs/process/conventions.md`):
[`docs/tools/hivectl-cli.md`](docs/tools/hivectl-cli.md).
- **`hive-agent/`**, **`hive-agent-mcp/`** —
in-container harness, two sibling crates for every agent (not a
@ -80,7 +80,7 @@ hand-maintained per-file tree drifts out of sync with the code.
- **`hive-priv/`** — minimal root privileged-helper, socket-activated at
`/run/hive/priv.sock`; performs the few root operations (bind-mount
edits, nsenter) the unprivileged `hive-c0re` delegates to it. See
`docs/boundary.md`.
`docs/trust-boundary/boundary.md`.
- **`hive-forge/`** — `hive-forge` Forgejo CLI wrapper; one module per
verb under `src/verbs/`.
- **`hive-forge-notify/`** — per-agent notification poller daemons; turns
@ -156,7 +156,7 @@ hand-maintained per-file tree drifts out of sync with the code.
written in place** — one file, shared with `swarm-authelia-bridge`; see
that crate's README for what both writers must uphold. Full, always-current
verb reference (CI-enforced against the clap tree, same pattern as
`hivectl`'s — see `docs/conventions.md`):
`hivectl`'s — see `docs/process/conventions.md`):
[`docs/tools/swarmctl-cli.md`](docs/tools/swarmctl-cli.md).
### External dependencies with no directory here
@ -191,91 +191,17 @@ hand-maintained per-file tree drifts out of sync with the code.
## Reading paths
Pick the doc that matches your task. None depend on the others —
read them à la carte.
- **"How do I bring a fresh hive online (first-run hivectl
bootstrap)?"** → [`docs/setup.md`](docs/setup.md).
- **"What does the dashboard look like?"** →
[`docs/web-ui.md`](docs/web-ui.md) (index; sub-pages:
[`shape`](docs/web-ui/shape.md),
[`dashboard`](docs/web-ui/dashboard.md),
[`agent`](docs/web-ui/agent.md)).
- **"How does the per-agent terminal classify + colour
events?"** → [`docs/terminal-rendering.md`](docs/terminal-rendering.md).
- **"How does claude get its prompt and what tools does it have?"** →
[`docs/turn-loop/`](docs/turn-loop/README.md) (index: the loop, binary shape,
turn outcomes; sub-pages:
[`claude-invocation`](docs/turn-loop/claude-invocation.md),
[`config`](docs/turn-loop/config.md), [`mcp`](docs/turn-loop/mcp.md)).
- **"How do config changes flow from manager to operator to
container?"** → [`docs/approvals.md`](docs/approvals.md).
- **"What state survives destroy / purge / restart?"** →
[`docs/persistence.md`](docs/persistence.md).
- **"Naming, commit style, wire protocol, the `data-async`
pattern."** → [`docs/conventions.md`](docs/conventions.md).
- **"Why does the nspawn flag look like that?"** →
[`docs/gotchas.md`](docs/gotchas.md).
- **"What nginx vhosts does the gateway serve? How does matrix
discovery work?"** → [`docs/gateway.md`](docs/gateway.md).
- **"How do per-agent forge accounts work? What does forge_notify
poll + how does it format wake messages?"** →
[`docs/forge.md`](docs/forge.md).
- **"What verbs does `hive-forge` support? How do I post a comment,
upload an attachment, manage subscriptions?"** →
[`docs/tools/forge.md`](docs/tools/forge.md).
- **"What does `hivectl` do? How do I provision a forge/matrix account,
manage gateway users, restart containers, or drop into an agent shell?"** →
[`docs/tools/hivectl.md`](docs/tools/hivectl.md).
- **"How does the matrix-tuwunel container work? What about
fluffychat-web and per-agent matrix accounts?"** →
[`docs/matrix.md`](docs/matrix.md).
- **"How do I give an agent a GitHub account (`gh` + `git push`)?
How is the PAT injected?"** → [`docs/github.md`](docs/github.md).
- **"How does DNS resolution work in agent containers? What's the
bridge network for?"** → [`docs/network.md`](docs/network.md).
- **"How do I connect two hives into a swarm? How do I declare peer
hives and configure TLS trust?"** →
[`docs/swarm/`](docs/swarm/README.md).
- **"Which deployment shapes are supported — all-local, services on the
controller host, fully spread out?"** →
[`docs/swarm/services.md`](docs/swarm/services.md#deployment-shapes).
- **"Where do agent snapshots go? How does the swarm's `btrfs receive`
endpoint authenticate a pushing hive, and what does a snapshot
actually contain?"** →
[`docs/snapshot-store.md`](docs/snapshot-store.md).
- **"What is the job queue, as a general idea?"** →
[`docs/jobq.md`](docs/jobq.md) (operator-facing, no hive-c0re specifics).
- **"How does the rebuild queue work? What are the concrete step kinds,
queue sources, scheduler internals?"** →
[`docs/coordinator.md`](docs/coordinator.md).
- **"How does the CI runner work? What's the auto-registration flow?"** →
[`docs/ci.md`](docs/ci.md).
- **"What is `/knowledge`? How does the hive-wide knowledge repo sync,
and how do I contribute a document?"** →
[`docs/knowledge.md`](docs/knowledge.md).
- **"How do I export Claude Code metrics (tokens, cost, tool calls) to
a Prometheus/Grafana collector? What OTEL options are available?"** →
[`docs/observability.md`](docs/observability.md).
- **"What does a PR review verdict actually gate? Should a reviewer
wait for CI before approving? What does arming auto-merge commit an
operator to?"** → [`docs/pr-review-gate.md`](docs/pr-review-gate.md).
**[`docs/README.md`](docs/README.md) is the single index** — grouped by topic
(getting started, agent lifecycle, trust boundary, integrations, networking,
scheduler, process). Read it instead of a second copy here; this file used to
carry its own parallel "Reading paths" list, and the two drifted out of sync
with each other.
## Conventions & process
The docs below own the details — this section just points at them.
- **Commit style, naming, identity, reconcile verb:** →
[`docs/conventions.md`](docs/conventions.md).
- **Never add `#[allow(clippy::…)]`** — fix the lint instead (extract a
helper, add backticks, etc.). Details + worked examples: →
[`docs/conventions.md`](docs/conventions.md#building--local-checks).
- **NixOS / nspawn quirks** (bind mounts, conf flags, etc.): →
[`docs/gotchas.md`](docs/gotchas.md).
- **Turn loop, sentinels (rate-limit, auth-failed), context
window:** → [`docs/turn-loop/`](docs/turn-loop/README.md).
- **Two-step spawn, approval flow, flake.lock validation:** →
[`docs/approvals.md`](docs/approvals.md).
[`docs/process/conventions.md`](docs/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`

View file

@ -11,55 +11,53 @@ declarations.
## Getting started
- **Bringing a fresh hive online?** → [`setup.md`](setup.md) (first-run
`hivectl` bootstrap).
- **Bringing a fresh hive online?** → [`getting-started/setup.md`](getting-started/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.
[`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, scheduling).
## Dashboard & agent UI internals
- **How does the per-agent terminal classify + colour events?** →
[`terminal-rendering.md`](terminal-rendering.md).
## Turn loop, config, approvals
## Agent lifecycle
- **How do config changes flow from manager to operator to container?** →
[`agent-lifecycle/approvals.md`](agent-lifecycle/approvals.md) (two-step spawn, approval
state machine, `flake.lock` validation).
- **What state survives destroy / purge / restart?** →
[`agent-lifecycle/persistence.md`](agent-lifecycle/persistence.md).
- **Who can do what to whom — agent hierarchy and privilege?** →
[`agent-lifecycle/agent-hierarchy.md`](agent-lifecycle/agent-hierarchy.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).
- **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).
[`trust-boundary/boundary.md`](trust-boundary/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).
isolation?** → [`trust-boundary/security.md`](trust-boundary/security.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
and how does it format wake messages?** → [`integrations/forge.md`](integrations/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);
agent?** → [`integrations/matrix.md`](integrations/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).
the PAT injected?** → [`integrations/github.md`](integrations/github.md).
- **What is `/knowledge`? How does the hive-wide knowledge repo sync,
and how do I 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,
@ -68,25 +66,25 @@ declarations.
## Networking & swarms
- **What nginx vhosts does the gateway serve? How does matrix
discovery work?** → [`gateway.md`](gateway.md).
discovery work?** → [`networking/gateway.md`](networking/gateway.md).
- **How does DNS resolution work in agent containers? What's the
bridge network for?** → [`network.md`](network.md).
bridge network for?** → [`networking/network.md`](networking/network.md).
- **How do I connect two hives into a swarm?** → [`swarm/`](swarm/README.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).
[`networking/snapshot-store.md`](networking/snapshot-store.md).
## Scheduler, CI, observability
- **What is the job queue, as a general idea (not hive-c0re specifics)?** →
[`jobq.md`](jobq.md) — operator-facing, no implementation detail.
[`scheduler/jobq.md`](scheduler/jobq.md) — operator-facing, no implementation detail.
- **How does the rebuild queue work? What are the concrete step kinds,
queue sources, scheduler internals?** → [`coordinator.md`](coordinator.md).
queue sources, scheduler internals?** → [`scheduler/coordinator.md`](scheduler/coordinator.md).
- **How does the CI runner work? What's the auto-registration flow?** →
[`ci.md`](ci.md).
[`scheduler/ci.md`](scheduler/ci.md).
- **How do I export Claude Code metrics (tokens, cost, tool calls) to
Prometheus/Grafana?** → [`observability.md`](observability.md).
Prometheus/Grafana?** → [`scheduler/observability.md`](scheduler/observability.md).
## Crate reference
@ -98,8 +96,8 @@ declarations.
## 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)
[`process/conventions.md`](process/conventions.md).
- **Why does the nspawn flag look like that?** → [`process/gotchas.md`](process/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).
- **What does a PR review verdict actually gate?** →
[`process/pr-review-gate.md`](process/pr-review-gate.md).

View file

@ -212,7 +212,7 @@ path = [ "/run/wrappers" "/run/current-system/sw" ];
`/run/wrappers` (not `/run/wrappers/bin`) comes first so setuid
wrappers — notably `sudo` — resolve before bare nix-store binaries; see
[`docs/gotchas.md`](gotchas.md) ("`systemd.services.*.path` appends
[`docs/process/gotchas.md`](../process/gotchas.md) ("`systemd.services.*.path` appends
`/bin` to every entry") for why the trailing `/bin` matters in
general. It's load-bearing here because the harness runs as the
per-agent user: without the wrapper dir on `PATH`, `sudo` resolves to
@ -243,4 +243,4 @@ uid 0 and have the setuid bit set."
(`$HIVE_FORGE_URL/hyperhive/hyperhive/issues/363`)
- Audit table source: milestone comment
(`$HIVE_FORGE_URL/hyperhive/hyperhive/issues/361#issuecomment-3335`)
- Operator/agent trust boundary (orthogonal axis): [`boundary.md`](boundary.md)
- Operator/agent trust boundary (orthogonal axis): [`boundary.md`](../trust-boundary/boundary.md)

View file

@ -77,8 +77,8 @@ 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/coordinator.md`'s Desired-state
section](coordinator.md#desired-state-spec-vs-status) for who
[`docs/scheduler/coordinator.md`'s Desired-state
section](../scheduler/coordinator.md#desired-state-spec-vs-status) for who
writes and reads it and how reconciliation works.
Retention:
@ -126,7 +126,7 @@ history sooner than a quiet one. The trade-off (accepted): a
misbehaving harness could now skip its own cleanup, which the old
host-side sweep was meant to prevent — but a compromised harness is
already inside the container trust boundary
([`docs/security.md`](security.md)), and these are ephemeral local
([`docs/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.
Path overridable via `HYPERHIVE_EVENTS_DB` (for dev / no-`/harness`
@ -236,7 +236,7 @@ Survives 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](../turn-loop/README.md#the-loop)).
Unusually, it's read and written from **both** sides of the harness
bind-mount, and that's the whole design: the harness stats it
@ -383,7 +383,7 @@ Contents:
(`{ "alice": "root", "bob": "alice", "root": null }`).
Written by `topology::apply_set_parent` (the pure move-validating
transform) via `meta::bulk_commit_topology` (the committer — see the
`Reparent` node in [`docs/coordinator.md`](coordinator.md)); read by
`Reparent` node in [`docs/scheduler/coordinator.md`](../scheduler/coordinator.md)); read by
the dashboard, the renderer, and `<parent>` / `<children>` recipient
resolution.
- `tool-groups.json` — per-agent MCP tool group grants
@ -466,7 +466,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/snapshot-store.md`](snapshot-store.md) for what a pushed
[`docs/snapshot-store.md`](../networking/snapshot-store.md) for what a pushed
snapshot contains and how the store authenticates a sender.
## `/var/lib/swarm-controller/` (swarm-controller host only)

View file

@ -11,7 +11,7 @@ inside an agent container); the `request_*` steps run from ruth's own
turn via the MCP tools.
**Bringing up a hive that does not host its own swarm services?** Read
[`swarm/secrets.md`](swarm/secrets.md) first. Everything below assumes
[`swarm/secrets.md`](../swarm/secrets.md) first. Everything below assumes
each credential is generated where it is read, which is true on an
all-local deploy and not otherwise — that page says which files an
operator has to place, and where.
@ -105,7 +105,7 @@ than amend — adding the group afterwards is `swarmctl user update mara
--add-group admins`.
Detail, including what the password is and why this stays manual:
[`swarm/sso.md`](swarm/sso.md).
[`swarm/sso.md`](../swarm/sso.md).
### 5 · Swarm UI (only when `deploy.swarm-ui`, on by default with the controller)
@ -121,7 +121,7 @@ decide whether you can actually open it:
anywhere else it needs a real DNS record like any other public name.
Detail, including why reachability is deliberately not the access
control: [`swarm/ui.md`](swarm/ui.md).
control: [`swarm/ui.md`](../swarm/ui.md).
### 6 · Matrix
@ -163,7 +163,7 @@ request_init_config(name: "iris")
# the operator reviews + approves it — no MCP tool call.
```
See [`approvals.md`](approvals.md) for the full flow.
See [`approvals.md`](../agent-lifecycle/approvals.md) for the full flow.
### 8 · Useful host commands
@ -183,7 +183,7 @@ hivectl open forge # Forgejo
hivectl open matrix # Matrix GUI (fluffychat)
```
See [`tools/hivectl.md`](tools/hivectl.md) for every `hivectl` verb.
See [`tools/hivectl.md`](../tools/hivectl.md) for every `hivectl` verb.
## Security notes
@ -192,12 +192,12 @@ See [`tools/hivectl.md`](tools/hivectl.md) for every `hivectl` verb.
creds (the core token, the matrix admin token) live on the host.
- All config changes (forge PRs on `agent-configs/<name>`) go through
operator approval — agents can't unilaterally rebuild containers, by design.
See [`boundary.md`](boundary.md) and [`security.md`](security.md).
See [`boundary.md`](../trust-boundary/boundary.md) and [`security.md`](../trust-boundary/security.md).
- **Telemetry ingest is authenticated per hive**, and the `hive` label comes
from which hive authenticated rather than from the payload — so no hive can
report metrics as another. A first-run all-local hive gets this with nothing
to configure; joining a swarm you don't host needs one secret copied across.
See [`observability.md`](observability.md#authenticated-ingest).
See [`observability.md`](../scheduler/observability.md#authenticated-ingest).
Once the hive is running, ruth records anything it needs to remember
across restarts in `/agents/ruth/state/notes.md`.

View file

@ -4,7 +4,7 @@ Private Forgejo instance running in a nixos-container, used as the
swarm's persistent code-collaboration surface (issues, PRs, reviews,
attachments). Configured via `services.hyperhive.swarm.forge.*`. Container
shape, ROOT_URL / sub-domain routing, and operator-vs-in-cluster URL
handling live in [`docs/gateway.md`](gateway.md); this file owns the
handling live in [`docs/networking/gateway.md`](../networking/gateway.md); this file owns the
per-agent integration story and the notification pump that wakes
each agent on relevant activity.
@ -69,7 +69,7 @@ Two things live in the `agent-configs` Forgejo organization:
agent's config. (Agents remain read-only collaborators on `core/meta`.)
hive-c0re also references this repo as the agent's **persistent meta
flake input** (`agent-<n>.url = git+http://<forge>/agent-configs/<n>.git`;
see [approvals.md § Meta flake](approvals.md)), fetching it as the `core`
see [approvals.md § Meta flake](../agent-lifecycle/approvals.md)), fetching it as the `core`
user via a git credential helper that reads the live forge-core token —
so the config lives on the forge, not a hand-synced local checkout.
- The dashboard links each container's "config" anchor to this
@ -332,4 +332,4 @@ delivers every unread notification it's handed. Bounding the
firehose (dropping broad repo watches an agent doesn't need) is done
explicitly via a hive-forge CLI subscription verb, not by the poller
guessing which watches to drop. See the `subscription` verb in
[`docs/tools/forge.md`](tools/forge.md).
[`docs/tools/forge.md`](../tools/forge.md).

View file

@ -46,7 +46,7 @@ hivectl github set-token <agent> --token <pat> # inline (visible in shell his
Either path has hive-c0re delegate the write to hive-priv, which stores the
file `0600` owned by the agent (so the container can read it) — the same
credential-injection path as forge/matrix tokens. See
[hivectl → GitHub](tools/hivectl.md#github).
[hivectl → GitHub](../tools/hivectl.md#github).
## Security
@ -55,7 +55,7 @@ credential-injection path as forge/matrix tokens. See
workflow needs. Agents have passwordless sudo, so a compromised or
hallucinating agent can act as the account within the token's scopes;
scope is the real blast-radius limiter, and the container boundary is
the enforcement. See [security.md](security.md).
the enforcement. See [security.md](../trust-boundary/security.md).
Everything below this point is implementation detail (how the agent
actually uses the token, and the notification poller's internals).

View file

@ -4,11 +4,11 @@ Private Matrix homeserver (matrix-tuwunel — the conduwuit
successor) wrapped in a nixos-container, plus optional fluffychat-web
client at `chat.<swarm-domain>/` (the `gatewayHost` vhost). Configured via
`services.hyperhive.swarm.matrix.*`; vhost routing lives in
[`gateway.md`](gateway.md).
[`gateway.md`](../networking/gateway.md).
## Container shape
Same shape as [`gateway.md::hive-forge container shape`](gateway.md):
Same shape as [`gateway.md::hive-forge container shape`](../networking/gateway.md):
- Container name `hive-matrix` (not `h-*`) so c0re's lifecycle
scanner ignores it; operator manages via the standard
@ -202,7 +202,7 @@ at the protocol level from first boot (`allow_federation = true`) but
no remote homeserver is trusted until listed here. For a closed
single-hive deployment the default empty list is correct — add peer
hive domains here when connecting hives into a swarm (see
[`docs/swarm/`](swarm/README.md)).
[`docs/swarm/`](../swarm/README.md)).
**`maxRequestSize`** (default `20_000_000` bytes = 20 MB) — maximum
size of a single matrix client request body. Matches the matrix-spec
@ -237,7 +237,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/network.md`](network.md).
[`docs/networking/network.md`](../networking/network.md).
## fluffychat-web build fixes

View file

@ -19,7 +19,7 @@ Single nginx in front of every hyperhive web surface. Runs on the **host**, next
The authelia vhost is declared only by the host that **runs** authelia, not by every hive that uses it — a client hive knows the swarm's `authelia.url` but must not answer for a name it doesn't serve. Its server name is exactly `swarm.authelia.domain`: authelia validates `authelia_url ⊂ session cookie domain` at startup, so a near-miss is a container that refuses to boot. It carries no `auth_basic` — the login page must not sit behind the login mechanism it replaces — and sets the four `X-Forwarded-{Proto,Host,Uri,For}` headers, since authelia decides by the *original* request rather than the hop it sees.
⚠️ **A `502` from this vhost usually means authelia has no users yet, not that the proxy is misconfigured.** Authelia treats an empty user store as a fatal startup error, so an enabled-but-unbootstrapped swarm crash-loops the container while the vhost in front of it works perfectly. Check `journalctl -M swarm-authelia -u authelia-swarm` before suspecting anything here; the bootstrap step is in [`swarm/sso.md`](swarm/sso.md).
⚠️ **A `502` from this vhost usually means authelia has no users yet, not that the proxy is misconfigured.** Authelia treats an empty user store as a fatal startup error, so an enabled-but-unbootstrapped swarm crash-loops the container while the vhost in front of it works perfectly. Check `journalctl -M swarm-authelia -u authelia-swarm` before suspecting anything here; the bootstrap step is in [`swarm/sso.md`](../swarm/sso.md).
Per-agent UIs stay sub-path, forge and matrix get sub-domains — see
[Sub-domain shape (rationale)](#sub-domain-shape-rationale) below for why.
@ -108,7 +108,7 @@ now set unconditionally for every agent. The mechanism:
nginx reaches `web.sock` through `o=--x` (traverse) and the socket's
own `0666`. The gateway is one of three principals sharing that dir
and does not own its ownership rules — see
[`docs/boundary.md`](boundary.md#the-per-agent-socket-dir).
[`docs/trust-boundary/boundary.md`](../trust-boundary/boundary.md#the-per-agent-socket-dir).
3. **Marker gate**. After successful `bind_unix`, the harness drops
`<dir>/hyperhive-socket-bound` next to the socket. c0re's
`agent_sockets::write` filters its JSON map by marker presence —
@ -216,11 +216,11 @@ swarm-services fallback below is for.
**Why a CA, not a bare leaf**: a bare self-signed leaf is its own trust anchor, so every regeneration is a new anchor every consumer must re-trust — and a runtime-generated leaf can't be wired into an agent's build-time trust store at all. With a stable CA, agents and federation peers trust it *once*; leaf rotation never re-breaks them.
**What consumers trust**: `trust-bundle.pem` in the same state dir, not `ca.pem`. The hive CA is itself issued under the swarm root ([`swarm/ca.md`](swarm/ca.md) has the hierarchy), and an intermediate is not a chain a verifier can terminate at — so the bundle carries the hive CA plus whatever it is rooted at. nginx is handed the leaf with the hive CA appended for the same reason. Everything that trusts the hive's TLS reads the bundle: agents (via `security.pki.certificateFiles`), the CI and forge containers, and a federating peer.
**What consumers trust**: `trust-bundle.pem` in the same state dir, not `ca.pem`. The hive CA is itself issued under the swarm root ([`swarm/ca.md`](../swarm/ca.md) has the hierarchy), and an intermediate is not a chain a verifier can terminate at — so the bundle carries the hive CA plus whatever it is rooted at. nginx is handed the leaf with the hive CA appended for the same reason. Everything that trusts the hive's TLS reads the bundle: agents (via `security.pki.certificateFiles`), the CI and forge containers, and a federating peer.
**Why on by default**: matrix-dart-sdk (FluffyChat's SDK) hardcodes `https://<host>/.well-known/matrix/client` for homeserver discovery and refuses to fall back to plain http. Without TLS the browser client cannot bootstrap.
**Cert shape**: leaf subject CN = bare hive domain; subjectAltName is `<hive>` plus wildcard `*.<hive>`, so all current and future sub-domain vhosts validate under the same leaf + the hive CA. A swarm service whose name is *not* under this hive's domain cannot be added here — the hive CA is name-constrained to `<hive>`, and a violating SAN invalidates the whole leaf, not just that name. Those names get the swarm-services leaf instead ([`swarm/ca.md`](swarm/ca.md)).
**Cert shape**: leaf subject CN = bare hive domain; subjectAltName is `<hive>` plus wildcard `*.<hive>`, so all current and future sub-domain vhosts validate under the same leaf + the hive CA. A swarm service whose name is *not* under this hive's domain cannot be added here — the hive CA is name-constrained to `<hive>`, and a violating SAN invalidates the whole leaf, not just that name. Those names get the swarm-services leaf instead ([`swarm/ca.md`](../swarm/ca.md)).
**Rotation**: `hive-tls-ca.service` is idempotent — it re-signs the leaf when it is missing or within 30 days of expiry, always under the same CA (so consumer trust is undisturbed). The CA itself is regenerated only if missing or already expired. To force a leaf rotation, delete `gateway.pem` under the state dir and restart the unit, then reload `nginx`.

View file

@ -70,7 +70,7 @@ The flows, end to end:
the host forwards + masquerades out its uplink.
- **Swarm** — peer hives connect over the `wg-hive` WireGuard mesh
and reach each other's gateway/forge across it
([`docs/swarm/`](swarm/README.md)).
([`docs/swarm/`](../swarm/README.md)).
- **Control plane (no network)** — per-agent broker socket
`/run/hive/mcp.sock`, privileged helper `/run/hive/priv.sock`,
operator admin `/run/hyperhive/host.sock`, and the per-agent UI

View file

@ -35,7 +35,7 @@ services.hyperhive.swarm.wireguard = {
The store host is a swarm member like any other: it gets an entry in
`services.hyperhive.swarm.hives`, the same directory every host holds. See
[swarm/](swarm/README.md) for the mesh itself.
[swarm/](../swarm/README.md) for the mesh itself.
Note that the mesh is gated on `swarm.wireguard.enable`, **not** on
`c0re.enable` --- a store host runs no hive and would otherwise get no
@ -185,7 +185,7 @@ the access-review list.
The snapshot covers an agent's **state subvolume**, which is the parent
of `state/`, `claude/` and `harness/` (see
[`docs/persistence.md`'s btrfs subvolume
section](persistence.md#btrfs-subvolumes-for-varlibhyperhiveagentsname)
section](../agent-lifecycle/persistence.md#btrfs-subvolumes-for-varlibhyperhiveagentsname)
for how and when that subvolume is created). Consequences:
- The Claude session (`claude/`) travels, so a restored agent keeps its

View file

@ -178,7 +178,7 @@ durable knowledge here (`notes.md`, anything else) — the harness's own
internal files (`hyperhive-events.sqlite`, `hyperhive-turn-stats.sqlite`,
`hyperhive-model`) live in the separate `harness` dir instead, so they
don't clutter what claude sees as "my notes dir" (see
[`docs/persistence.md`](persistence.md)). Survives `destroy`/recreate
[`docs/agent-lifecycle/persistence.md`](../agent-lifecycle/persistence.md)). Survives `destroy`/recreate
alongside the claude dir.
## Networking & ports
@ -361,7 +361,7 @@ own self-consistent object store and is immune to the issue.
### `hive-forge`: prefer over raw curl pipelines
Full CLI reference: [`docs/tools/forge.md`](tools/forge.md).
Full CLI reference: [`docs/tools/forge.md`](../tools/forge.md).
Never use raw `curl` for forge access.
## GUI (weston/VNC)

View file

@ -32,7 +32,7 @@ using the same engine for its own unrelated queue.
## Watching it happen
Each **row** you see in a queue view (the **BU1LDS** page's R3BU1LD QU3U3
— see [`web-ui/dashboard.md`](web-ui/dashboard.md) — and swarm-ui's
— see [`web-ui/dashboard.md`](../web-ui/dashboard.md) — and swarm-ui's
`/jobs` page both render the same underlying graph) is one job; the rows
nested under it are that job's steps, in order (occasionally a couple run
side by side). A step shows one of:

View file

@ -20,13 +20,13 @@ services.hyperhive.otel = {
leaves the swarm — optional, because the swarm's own metrics store
(`deploy.victoriametrics`) is a destination in its own right. With both,
telemetry goes to both. See
[`swarm/services.md`](swarm/services.md#metrics-victoriametrics--grafana).
[`swarm/services.md`](../swarm/services.md#metrics-victoriametrics--grafana).
**There is exactly one way telemetry leaves a hive: through the collector that
`enable` starts on the host.** Agents never talk to `endpoint` themselves —
they export unauthenticated to a bridge address only their own containers can
reach. That collector forwards to the swarm's
([`swarm/services.md`](swarm/services.md#telemetry-collector-otel)), which is
([`swarm/services.md`](../swarm/services.md#telemetry-collector-otel)), which is
the single process holding the upstream credential and the only writer to the
swarm's store. No agent holds a copy, and neither does this hive.

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