docs: the index's handbook section links only handbook pages

The implementation pages it pointed at are listed under the implementation section instead, in a new agent-state group and under swarm services and web UI internals.
2026-11-12 12:24:48 +01:00 · 2026-11-12 12:24:48 +01:00 · 19357bca2d
commit 19357bca2d
parent 724675ad58
1 changed files with 39 additions and 32 deletions
--- a/docs/README.md
+++ b/docs/README.md
@ -36,35 +36,26 @@ The services that exist once per swarm. Start at
  matrix and SSO login answering the internet?** → [`2-handbook/swarm/semi-spread-deploy.md`](2-handbook/swarm/semi-spread-deploy.md)
  (worked example: machines, WireGuard, DNS).
 - **What does the swarm UI show, and what does `swarmctl` do?** →
-  [`2-handbook/swarm/ui.md`](2-handbook/swarm/ui.md) (the full page reference is
-  [`4-implementation/web-ui/swarm-ui.md`](4-implementation/web-ui/swarm-ui.md)) and
+  [`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.
+  (the swarm's Forgejo).
 - **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`.
+  agent?** → [`2-handbook/swarm/matrix.md`](2-handbook/swarm/matrix.md) (the homeserver and the
+  accounts an agent holds on it).
 - **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?** →
  [`2-handbook/swarm/credentials.md`](2-handbook/swarm/credentials.md) (the
-  rules, where each secret goes and why, adding a secret) and
-  [`4-implementation/swarm/credentials-reference.md`](4-implementation/swarm/credentials-reference.md) (the
-  tables: each credential and where each file lives). The store's identities,
-  keys and login:
-  [`4-implementation/swarm/credentials.md`](4-implementation/swarm/credentials.md).
+  rules, where each secret goes and why, adding a secret).
 - **How does an agent get a prompt at set times, and why doesn't it fire
  twice after downtime?** → [`2-handbook/swarm/schedules.md`](2-handbook/swarm/schedules.md).
 - **How to create an agent from a ready-made set of permissions and
  settings?** → [`2-handbook/swarm/archetypes.md`](2-handbook/swarm/archetypes.md).
 - **How to log an agent in to claude from the swarm UI?** →
-  [`2-handbook/swarm/claude-login.md`](2-handbook/swarm/claude-login.md). Why a
-  stale stored copy doesn't log the agent out again, and the minter's grants:
-  [`4-implementation/swarm/claude-login.md`](4-implementation/swarm/claude-login.md).
+  [`2-handbook/swarm/claude-login.md`](2-handbook/swarm/claude-login.md).
 - **Where do the hives back up each agent's state, how long does it stay, and how to
  check it?** → [`2-handbook/swarm/archive.md`](2-handbook/swarm/archive.md).

@ -74,13 +65,11 @@ 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`](4-implementation/web-ui/dashboard.md).
+  [`2-handbook/hives/`](2-handbook/hives/README.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).
+  autogenerated flag reference.
 - **What's the operator/agent trust boundary? What's a permission?** →
  [`2-handbook/hives/boundary.md`](2-handbook/hives/boundary.md).

@ -91,19 +80,12 @@ One agent: its entry in the agent list, state, config and page. Start at

 - **How do config changes flow from agent to operator to container?** →
  [`2-handbook/agents/persistence.md`](2-handbook/agents/persistence.md#config-changes).
-  The meta flake and system messages:
-  [`4-implementation/agent-state/config-changes.md`](4-implementation/agent-state/config-changes.md).
 - **What state survives destroy / purge / restart?** →
-  [`2-handbook/agents/persistence.md`](2-handbook/agents/persistence.md); the
-  tables and directory layout:
-  [`4-implementation/agent-state/persistence.md`](4-implementation/agent-state/persistence.md).
+  [`2-handbook/agents/persistence.md`](2-handbook/agents/persistence.md).
 - **Who can do what to whom — the agent list and privilege?** →
-  [`2-handbook/agents/agent-permissions.md`](2-handbook/agents/agent-permissions.md); how
-  `topology.json` is rebuilt and what's special about the manager:
-  [`4-implementation/agent-state/roster.md`](4-implementation/agent-state/roster.md).
+  [`2-handbook/agents/agent-permissions.md`](2-handbook/agents/agent-permissions.md).
 - **What does an agent's own page show?** →
-  [`2-handbook/agents/web-page.md`](2-handbook/agents/web-page.md); the full
-  reference is [`agent-page`](4-implementation/web-ui/agent-page.md).
+  [`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).

@ -113,9 +95,7 @@ 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);
-  the `gh`/git-push and notification-poller mechanics are in
-  [`4-implementation/agent-tools/github.md`](4-implementation/agent-tools/github.md).
+  the PAT injected?** → [`2-handbook/external-accounts/github.md`](2-handbook/external-accounts/github.md).
 - **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).

@ -136,9 +116,23 @@ Nothing of it sits in this tree.
 - **How does the forge notification poller wake an agent, and how does it
  format and de-duplicate what it delivers?** →
  [`4-implementation/agent-tools/forge-notify.md`](4-implementation/agent-tools/forge-notify.md).
+- **Which `hive-forge` verbs do agents call, and what does the swarm's forge give each
+  agent?** → [`4-implementation/agent-tools/forge.md`](4-implementation/agent-tools/forge.md).
+- **What's the matrix MCP tool surface, and what's `services.hyperhive.agent.matrixAccounts`?** →
+  [`4-implementation/agent-tools/matrix.md`](4-implementation/agent-tools/matrix.md).
 - **How do an agent's `gh` and `git push` authenticate to GitHub?** →
  [`4-implementation/agent-tools/github.md`](4-implementation/agent-tools/github.md).

+### Agent state
+
+- **How does the meta flake carry a config change, and what are the system messages?** →
+  [`4-implementation/agent-state/config-changes.md`](4-implementation/agent-state/config-changes.md).
+- **What are the tables and the directory layout behind what survives a destroy, purge
+  or restart?** →
+  [`4-implementation/agent-state/persistence.md`](4-implementation/agent-state/persistence.md).
+- **How's `topology.json` rebuilt, and what's special about the manager?** →
+  [`4-implementation/agent-state/roster.md`](4-implementation/agent-state/roster.md).
+
 ### Turn loop, scheduler, CI, observability

 - **How does claude get its prompt, and what tools does it have?** →
@ -184,6 +178,13 @@ Nothing of it sits in this tree.
 - **How are the metrics store, Grafana, log store and OTEL collector wired, and
  who may reach each?** →
  [`4-implementation/swarm/telemetry.md`](4-implementation/swarm/telemetry.md).
+- **Which credential lives where, and what are the store's identities, keys and login?** →
+  [`4-implementation/swarm/credentials-reference.md`](4-implementation/swarm/credentials-reference.md) (the
+  tables: each credential and where each file lives) and
+  [`4-implementation/swarm/credentials.md`](4-implementation/swarm/credentials.md).
+- **Why doesn't a stale stored claude login log the agent out again, and what does the
+  minter's policy grant?** →
+  [`4-implementation/swarm/claude-login.md`](4-implementation/swarm/claude-login.md).

 ### Trust boundary mechanics

@ -200,6 +201,12 @@ Nothing of it sits in this tree.
  [`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).
+- **What does each swarm UI page show, down to its endpoints?** →
+  [`swarm-ui`](4-implementation/web-ui/swarm-ui.md).
+- **What's on each tab of the hive dashboard?** →
+  [`dashboard`](4-implementation/web-ui/dashboard.md).
+- **What does an agent's own page show, in full?** →
+  [`agent-page`](4-implementation/web-ui/agent-page.md).

 ### Crate reference