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.

nix/agent-modules/agent-service.nix

@@ -189,7 +189,7 @@ in
       not `state/` — `harness/` survives container rebuilds exactly like
       `state/` does, but is never bind-mounted into another agent's
       container (unlike `state/`, which a `ManageRootAgent` holder gets
-      read-write for recovery — see `docs/2-handbook/agent-lifecycle/persistence.md`'s "Cross-agent access to
+      read-write for recovery — see `docs/2-handbook/agents/persistence.md`'s "Cross-agent access to
       state"), so this credential is reachable by nothing but this agent
       and the host. Permissions should be `0600`, owned by the agent's
       unix user. Whatever owner it was installed with, the file becomes

nix/agent-modules/forge.nix

@@ -201,7 +201,7 @@ in
     # agent deployment the container can boot before the swarm has minted
     # the token, so the service fires too early and exits with "no
     # forge-token found". Without this path unit, nothing would ever
-    # re-run it. See docs/2-handbook/agent-lifecycle/persistence.md::forge-avatar-sync.
+    # re-run it. See docs/2-handbook/agents/persistence.md::forge-avatar-sync.
     #
     # PathChanged=, not PathExists=: a PathExists= condition that already
     # holds re-activates the unit immediately every time the path unit

nix/agent-modules/matrix.nix

@@ -302,7 +302,7 @@ in
     # Long-running matrix-sdk client + sync per agent. Serves the MCP
     # tools directly over streamable-http + emits hyperhive wake
     # signals on incoming room events via `/run/hive/mcp.sock`. See
-    # `docs/2-handbook/agent-lifecycle/persistence.md::Matrix per-agent daemon + token-arrival
+    # `docs/2-handbook/agents/persistence.md::Matrix per-agent daemon + token-arrival
     # trigger` for the first-boot-ordering rationale.
     systemd.services.hive-matrix-daemon = lib.mkIf matrixEnabled {
       description = "long-running matrix-sdk Client + MCP daemon";
@@ -434,7 +434,7 @@ in
     # `tokenFile`, or a `main` from before the swarm minted it). Without this
     # the daemon would exit 0 silently on first boot and the MCP
     # would have no backend until next restart. See
-    # `docs/2-handbook/agent-lifecycle/persistence.md` (same section as above).
+    # `docs/2-handbook/agents/persistence.md` (same section as above).
     systemd.paths.hive-matrix-daemon = lib.mkIf matrixEnabled {
       description = "trigger hive-matrix-daemon when a matrix token appears";
       wantedBy = [ "multi-user.target" ];

nix/agent-modules/user.nix

@@ -229,7 +229,7 @@ in
     # home dir, chowns the bind-mounted state + `~/.claude/`, and
     # (marker-guarded) moves any leftover `/root/.claude` content
     # from the previous root-run shape. See
-    # `docs/2-handbook/agent-lifecycle/persistence.md::First-boot agent-user migration` for the
+    # `docs/2-handbook/agents/persistence.md::First-boot agent-user migration` for the
     # step-by-step rationale; this script implements it.
     system.activationScripts.hive-agent-user-migrate = lib.stringAfter [ "users" "specialfs" ] ''
       homeDir=${lib.escapeShellArg homeDir}

nix/agent-modules/weston-vnc.nix

@@ -38,7 +38,7 @@ in
   # Port allocation, weston bind-address quirk, PAM service name, the
   # Type=simple choice, idle-time=0: all in
   # docs/5-project/process/gotchas.md::Weston VNC compositor.
-  # Harness-side WebSocket relay shape: docs/2-handbook/web-ui/agent.md::Per-agent
+  # Harness-side WebSocket relay shape: docs/2-handbook/agents/web-page.md::Per-agent
   # endpoints (`/screen` + `/screen/ws`).
 
   options.services.hyperhive.agent.gui.enable = lib.mkOption {