fixup! docs: sort the top-level directories into five sections by what the reader wants

docs/2-handbook/agent-lifecycle/config-changes.md

@@ -201,7 +201,7 @@ wraps it with identity + `HIVE_PORT` / `HIVE_LABEL`.
 ### Forge config repos
 
 The bundled `hive-forge` container runs on the swarm's forge host
-(`deploy.forgejo.enable`, see [`../swarm/services.md`](../swarm/services.md)).
+(`deploy.forgejo.enable`, see [`2-handbook/swarm/services.md`](../swarm/services.md)).
 Every agent created through the swarm has a repo in the private
 `agent-configs` Forgejo org, created and seeded by swarm-controller.
 hive-c0re pushes nothing to it, keeps no clone and reads nothing from it: forge

docs/2-handbook/agent-lifecycle/persistence.md

@@ -69,7 +69,7 @@ table, and the per-agent power-intent registry:
 On a host whose hive-c0re once kept scheduled prompts, the file also
 holds `scheduled_prompts` and `scheduled_prompt_targets`. Nothing opens
 them; scheduled prompts live at swarm level
-([`swarm/schedules.md`](../swarm/schedules.md)). They're safe to drop by
+([`2-handbook/swarm/schedules.md`](../swarm/schedules.md)). They're safe to drop by
 hand.
 
 Retention:

docs/2-handbook/integrations/matrix.md

@@ -351,7 +351,7 @@ federation at the protocol level from first boot (`allow_federation =
 true`) but trusts no remote homeserver until you list it 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/2-handbook/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

docs/2-handbook/swarm/README.md

@@ -583,7 +583,7 @@ mechanism.
    added to the public CAs; it holds the store's `pki` root, so a peer whose
    certificate chains to the same root validates. A peer outside this
    swarm's root needs a CA-issued certificate (ACME). Federation firewall
-   and TLS requirements: [`integrations/matrix.md`](../integrations/matrix.md).
+   and TLS requirements: [`2-handbook/integrations/matrix.md`](../integrations/matrix.md).
 
 3. **WireGuard mesh** (optional) — `deploy.wireguard.enable` reads each
    entry's `wireguardPublicKey`/`wireguardEndpoint`/`wireguardAddress`
@@ -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`](../../4-implementation/networking/snapshot-store.md) — the
+- [`4-implementation/networking/snapshot-store.md`](../../4-implementation/networking/snapshot-store.md) — the
   swarm's `btrfs receive` endpoint and the `swarm.snapshotStore` option
-- [`../process/conventions.md`](../../5-project/process/conventions.md) § Hive identity —
+- [`5-project/process/conventions.md`](../../5-project/process/conventions.md) § Hive identity —
   env vars, qualified labels
-- [`../integrations/matrix.md`](../integrations/matrix.md) — matrix
+- [`2-handbook/integrations/matrix.md`](../integrations/matrix.md) — matrix
   federation, TLS cert autogeneration, firewall posture
-- [`../networking/gateway.md`](../../4-implementation/networking/gateway.md) — nginx vhosts and
+- [`4-implementation/networking/gateway.md`](../../4-implementation/networking/gateway.md) — nginx vhosts and
   the `.well-known/matrix/` autodiscovery scheme

docs/2-handbook/swarm/services.md

@@ -439,7 +439,7 @@ doesn't gate them: that option says this host _runs_ the store, while the swarm
 has one either way, reached by its swarm name through the gateway.
 
 Agent-side configuration, and what a hive's own collector does, are in
-[`../scheduler/observability.md`](../../4-implementation/scheduler/observability.md).
+[`4-implementation/scheduler/observability.md`](../../4-implementation/scheduler/observability.md).
 
 ### CI runner
 
@@ -452,7 +452,7 @@ It needs neither the forge nor a hive on its host. It reaches the forge at
 publishes to the secret store, which it reads under its own `ci-runner` leaf.
 On a host without the store, that leaf is the one file to copy. Registration,
 the container and the threat model are in
-[`../scheduler/ci.md`](../../4-implementation/scheduler/ci.md).
+[`4-implementation/scheduler/ci.md`](../../4-implementation/scheduler/ci.md).
 
 The runner's built-in Prometheus endpoint is on, bound to `127.0.0.1:9101` in
 the container's own network namespace. The container's journal forwarder

docs/2-handbook/swarm/sso.md

@@ -16,7 +16,7 @@ authelia binds no TCP port: its listeners are unix sockets only the gateway can
 publishes it as `auth.<swarm.domain>` — vhost, dnsmasq record and TLS
 name all follow `deploy.authelia`, so there is nothing to turn on
 separately. (Details, including why a client hive must not declare that
-vhost: [`../networking/gateway.md`](../../4-implementation/networking/gateway.md).)
+vhost: [`4-implementation/networking/gateway.md`](../../4-implementation/networking/gateway.md).)
 
 **Nobody can log in until the first user exists.** authelia exits at
 startup on an empty user set:
@@ -50,7 +50,7 @@ this password is stored nowhere — record it now
 the hash. It reads and writes authelia's `users.yml` directly — it's
 the one user store, shared with `swarm-authelia-bridge`, which creates
 agent identities in the same file. No restart: authelia watches it. Full
-reference: [`../tools/swarmctl-cli.md`](../reference/swarmctl-cli.md).
+reference: [`2-handbook/reference/swarmctl-cli.md`](../reference/swarmctl-cli.md).
 
 You can edit `users.yml` by hand, and `swarmctl` will read what you
 wrote. ⚠️ It rewrites the whole file on every change, so **comments and
@@ -208,7 +208,7 @@ Four consequences worth stating plainly:
 - **A member of `admins` becomes a matrix homeserver admin** once their
   first matrix login has created the account: `swarm-controller` promotes
   them within five minutes, and never demotes. See
-  [`../integrations/matrix.md`](../integrations/matrix.md#operators-are-homeserver-admins).
+  [`2-handbook/integrations/matrix.md`](../integrations/matrix.md#operators-are-homeserver-admins).
 
 - **tuwunel re-reads its secret file on every OAuth exchange**, not only
   at startup, and its own sandboxing hides most paths from it. It gets the

docs/2-handbook/swarm/ui.md

@@ -1089,4 +1089,4 @@ swarm's front page opens with a name mismatch.
 ## Cross-references
 
 - [`sso.md`](sso.md) — the authelia instance itself, and the user store.
-- [`../networking/gateway.md`](../../4-implementation/networking/gateway.md) — the full vhost map and TLS modes.
+- [`4-implementation/networking/gateway.md`](../../4-implementation/networking/gateway.md) — the full vhost map and TLS modes.

docs/2-handbook/web-ui/README.md

@@ -55,16 +55,16 @@ merging a config change or bumping a flake input.
 **Grant or revoke a permission.** Not on the hive dashboard: an agent's
 permissions live in the swarm. Set them with `swarmctl agent permissions`,
 or on the swarm UI's create-agent screen when creating the agent; see
-[`process/conventions.md`](../../5-project/process/conventions.md#permissions).
+[`5-project/process/conventions.md`](../../5-project/process/conventions.md#permissions).
 
 **Read an agent's logs.** Logs aren't in the hive dashboard. Every
 hive ships its agents', daemons' and infra containers' journals to the
 swarm's VictoriaLogs; read them in Grafana's **Explore** — see
-[`swarm/services.md`](../swarm/services.md#logs-victorialogs).
+[`2-handbook/swarm/services.md`](../swarm/services.md#logs-victorialogs).
 
 **Set up a schedule.** Scheduled prompts are swarm-level: set them with
-`swarmctl schedule` ([`swarm/schedules.md`](../swarm/schedules.md)) or
-in the schedules card on the swarm UI's messages tab ([`swarm/ui.md`](../swarm/ui.md)).
+`swarmctl schedule` ([`2-handbook/swarm/schedules.md`](../swarm/schedules.md)) or
+in the schedules card on the swarm UI's messages tab ([`2-handbook/swarm/ui.md`](../swarm/ui.md)).
 
 ## More depth