docs: the handbook follows the three layers: swarm, hives, agents
The handbook's sections were agent-lifecycle, integrations, swarm, tools, trust-boundary and web-ui, which do not follow how the system is built, so a reader could not tell which layer a page is about. Its pages now sit in swarm/, hives/ and agents/, with the accounts an agent can hold outside the system in external-accounts/. - swarm/: forge, matrix and the knowledge repo join the swarm pages, and so does the swarmctl reference. - hives/: the dashboard, hivectl and its reference, and the operator/agent boundary, with a README that takes over the old web-ui and tools pages. - agents/: the roster, persistence, config changes, the agent's own web page (was web-ui/agent) and the security model, with a README. - external-accounts/: GitHub and GitLab. Pages are moved whole; none is split yet. Every reference follows: relative links in the docs, `docs/2-handbook/...` paths in code comments, the nix checks that regenerate the CLI references and the ignore list, and docs/README.md, whose handbook section is now by layer.
This commit is contained in:
iris
mara
parent
263b21021a
commit
0e84fe8bc4
1 changed files with 393 additions and 363 deletions
115
docs/README.md
115
docs/README.md
|
|
@ -20,64 +20,32 @@ reading top to bottom. The docs sit in five sections, by what the reader wants:
|
|||
|
||||
## 2. Handbook
|
||||
|
||||
Using and operating the hive and the swarm. Some pages here still carry
|
||||
Using and operating hyperhive, in the three layers that make it up, plus the
|
||||
accounts an agent can hold outside it. 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 the operator have?** →
|
||||
[`2-handbook/tools/`](2-handbook/tools/README.md) — `hivectl` and `swarmctl`. The agents' own tool
|
||||
surface is in [`4-implementation/agent-tools/`](4-implementation/agent-tools/README.md).
|
||||
- **What does `hivectl` do? Provisioning, gateway users, container
|
||||
shells?** → [`2-handbook/tools/hivectl.md`](2-handbook/tools/hivectl.md) (the curated guide);
|
||||
[`2-handbook/tools/hivectl-cli.md`](2-handbook/tools/hivectl-cli.md) for the exhaustive,
|
||||
autogenerated flag reference. The `swarmctl` reference sits beside it in
|
||||
[`2-handbook/tools/`](2-handbook/tools/README.md).
|
||||
|
||||
### 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); [`4-implementation/agent-tools/forge.md`](4-implementation/agent-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);
|
||||
[`4-implementation/agent-tools/matrix.md`](4-implementation/agent-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
|
||||
|
||||
The services that exist once per swarm. Start at
|
||||
[`2-handbook/swarm/`](2-handbook/swarm/README.md).
|
||||
|
||||
- **How are two hives connected into a swarm?** → [`2-handbook/swarm/`](2-handbook/swarm/README.md)
|
||||
(peer hives, TLS trust).
|
||||
- **What does the swarm UI show, and what does `swarmctl` do?** →
|
||||
[`2-handbook/swarm/ui.md`](2-handbook/swarm/ui.md) and
|
||||
[`2-handbook/swarm/swarmctl-cli.md`](2-handbook/swarm/swarmctl-cli.md) (the
|
||||
generated flag reference).
|
||||
- **How do per-agent forge accounts work? What does `forge_notify` poll,
|
||||
and how does it format wake messages?** → [`2-handbook/swarm/forge.md`](2-handbook/swarm/forge.md)
|
||||
(the swarm's Forgejo); [`4-implementation/agent-tools/forge.md`](4-implementation/agent-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/swarm/matrix.md`](2-handbook/swarm/matrix.md) (the homeserver);
|
||||
[`4-implementation/agent-tools/matrix.md`](4-implementation/agent-tools/matrix.md) for the MCP tool surface and
|
||||
`services.hyperhive.agent.matrixAccounts`.
|
||||
- **What's `/knowledge`? How does the swarm-wide knowledge repo sync,
|
||||
and how to contribute a document?** → [`2-handbook/swarm/knowledge.md`](2-handbook/swarm/knowledge.md).
|
||||
- **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
|
||||
|
|
@ -92,6 +60,51 @@ later work.
|
|||
stale stored copy log it out again?** →
|
||||
[`2-handbook/swarm/claude-login.md`](2-handbook/swarm/claude-login.md).
|
||||
|
||||
### Hives
|
||||
|
||||
The host a hive runs on and the operator's tools for it. Start at
|
||||
[`2-handbook/hives/`](2-handbook/hives/README.md).
|
||||
|
||||
- **What does the dashboard look like, and how to use it?** →
|
||||
[`2-handbook/hives/`](2-handbook/hives/README.md), with the full tab-by-tab
|
||||
reference in [`dashboard`](2-handbook/hives/dashboard.md).
|
||||
- **What does `hivectl` do? Provisioning, gateway users, container
|
||||
shells?** → [`2-handbook/hives/hivectl.md`](2-handbook/hives/hivectl.md) (the curated guide);
|
||||
[`2-handbook/hives/hivectl-cli.md`](2-handbook/hives/hivectl-cli.md) for the exhaustive,
|
||||
autogenerated flag reference. The agents' own tool surface is in
|
||||
[`4-implementation/agent-tools/`](4-implementation/agent-tools/README.md).
|
||||
- **What's the operator/agent trust boundary? What's a permission?** →
|
||||
[`2-handbook/hives/boundary.md`](2-handbook/hives/boundary.md).
|
||||
|
||||
### Agents
|
||||
|
||||
One agent: its roster entry, state, config and page. Start at
|
||||
[`2-handbook/agents/`](2-handbook/agents/README.md).
|
||||
|
||||
- **How do config changes flow from manager to operator to container?** →
|
||||
[`2-handbook/agents/config-changes.md`](2-handbook/agents/config-changes.md)
|
||||
(config PRs, the meta flake, system messages).
|
||||
- **What state survives destroy / purge / restart?** →
|
||||
[`2-handbook/agents/persistence.md`](2-handbook/agents/persistence.md).
|
||||
- **Who can do what to whom — the agent roster and privilege?** →
|
||||
[`2-handbook/agents/agent-roster.md`](2-handbook/agents/agent-roster.md).
|
||||
- **What does an agent's own page show?** →
|
||||
[`2-handbook/agents/web-page.md`](2-handbook/agents/web-page.md).
|
||||
- **Agent trust model, prompt-injection threat model, credential
|
||||
isolation?** → [`2-handbook/agents/security.md`](2-handbook/agents/security.md).
|
||||
|
||||
### External accounts
|
||||
|
||||
Accounts outside the swarm that an agent can hold. Start at
|
||||
[`2-handbook/external-accounts/`](2-handbook/external-accounts/README.md).
|
||||
|
||||
- **How to give an agent a GitHub account (`gh` + `git push`)? how's
|
||||
the PAT injected?** → [`2-handbook/external-accounts/github.md`](2-handbook/external-accounts/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/external-accounts/gitlab.md`](2-handbook/external-accounts/gitlab.md).
|
||||
|
||||
## 3. Options reference
|
||||
|
||||
The autogenerated NixOS options reference (every `services.hyperhive.*` /
|
||||
|
|
|
|||
Loading…
Reference in a new issue