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

Every docs directory moves under 1-getting-started, 2-handbook,
4-implementation or 5-project; the options reference (section 3) comes from
the website and has no directory here. trust-boundary stays whole under the
handbook for now. web-ui, swarm and tools split between handbook and
implementation, and the command-line references move to
2-handbook/reference. Links, path references in code and nix, and the docs
index follow the moves; no page content changes.

swarm-controller/README.md

@@ -44,24 +44,24 @@ The swarm's control plane. The swarm UI and `swarmctl` are its clients.
 - **Config PR status** — each agent's open config-repo PR, cached from forge
   webhooks (`GET /api/config-prs`, `/api/agents/{name}/config-pr`).
 - **Swarm-wide forge objects and webhooks** →
-  [`docs/swarm/README.md`](../docs/swarm/README.md#swarm-wide-forge-objects).
+  [`docs/2-handbook/swarm/README.md`](../docs/2-handbook/swarm/README.md#swarm-wide-forge-objects).
 - **Scheduled prompts** — named prompts for one or more agents, kept in
   the `schedule-definitions` KV bucket and written into each agent's key of
   `agent-schedules`, both of which this daemon alone writes
   (`GET`/`POST /api/schedules`, `PATCH`/`DELETE /api/schedules/{id}`); each
-  agent fires them itself → [`docs/swarm/schedules.md`](../docs/swarm/schedules.md).
+  agent fires them itself → [`docs/2-handbook/swarm/schedules.md`](../docs/2-handbook/swarm/schedules.md).
 - **Inference settings** — each agent's model, effort, subagent models and
   cap on concurrently running subagents, one key per agent in the
   `agent-inference` KV bucket, which this daemon
   alone writes (`GET`/`PUT`/`DELETE /api/agents/{name}/inference`); each
   agent applies them itself. `GET` also answers the model and effort the
   agent last reported in its turn-state header, kept in memory →
-  [`docs/swarm/inference.md`](../docs/swarm/inference.md).
+  [`docs/4-implementation/swarm/inference.md`](../docs/4-implementation/swarm/inference.md).
 - **Resource caps** — each agent's CPU and memory cap, one key per agent in
   the `agent-limits` KV bucket, which this daemon alone writes
   (`GET`/`PUT`/`DELETE /api/agents/{name}/limits`); the hive running the
   agent reads it, and each cap replaces the hive's own answer for that field →
-  [`docs/scheduler/coordinator.md`](../docs/scheduler/coordinator.md#container-resource-limits).
+  [`docs/4-implementation/scheduler/coordinator.md`](../docs/4-implementation/scheduler/coordinator.md#container-resource-limits).
 - **Egress allow-list** — the destinations agents may reach through their
   hive's egress proxy, each for every agent or for one, as one value in the
   `egress-allow` KV bucket, which this daemon alone writes
@@ -72,7 +72,7 @@ The swarm's control plane. The swarm UI and `swarmctl` are its clients.
   value of that bucket (`GET`/`POST`/`DELETE /api/egress/denied-domains`) with no
   derived entries; every hive renders it into an include the proxy checks before
   any allow, and reports the revision it rendered in its status snapshot →
-  [`docs/networking/network.md`](../docs/networking/network.md#egress-proxy-squid).
+  [`docs/4-implementation/networking/network.md`](../docs/4-implementation/networking/network.md#egress-proxy-squid).
 - **Agent instructions** — each agent's `AGENTS.md` as its harness last
   published it into the `agents-md` KV bucket
   (`GET /api/agents/{name}/agents-md`), and edits to it as git diffs, which
@@ -80,7 +80,7 @@ The swarm's control plane. The swarm UI and `swarmctl` are its clients.
   (`PUT /api/agents/{name}/agents-md`). `POST /api/agents` can set the text the
   file starts with (`agents_md`), stored in the `agents-md-initial` bucket for
   the harness to write when no file exists →
-  [`docs/swarm/README.md`](../docs/swarm/README.md#an-agents-agentsmd).
+  [`docs/2-handbook/swarm/README.md`](../docs/2-handbook/swarm/README.md#an-agents-agentsmd).
 - **Review classifier** — try-outs from the swarm UI and reviews on review
   requests, the requested reviews not yet finished, in the `review-requests`
   work-queue stream, and the newest 100 finished runs, one document in the
@@ -89,18 +89,18 @@ The swarm's control plane. The swarm UI and `swarmctl` are its clients.
   `GET /api/review-classifier/rules`, `GET /api/review-classifier/runs`), and
   the try-out page's branch for a PR, pushed as the classifier's forge account
   (`POST /api/review-classifier/open-pr`) →
-  [`docs/swarm/review-classifier.md`](../docs/swarm/review-classifier.md).
+  [`docs/4-implementation/swarm/review-classifier.md`](../docs/4-implementation/swarm/review-classifier.md).
 - **Review classifier settings** — the classifier's runtime, model, effort and how
   many requested reviews run at once, one document in the
   `review-classifier-settings` KV bucket, which this daemon alone reads and
   writes (`GET`/`PUT /api/review-classifier/settings`) →
-  [`docs/swarm/review-classifier.md`](../docs/swarm/review-classifier.md#swarm-level-settings).
+  [`docs/4-implementation/swarm/review-classifier.md`](../docs/4-implementation/swarm/review-classifier.md#swarm-level-settings).
 - **Notification flows** — which of the notification router's built-in flows are
   switched off, and the custom flows, as one document in the `notify-flows`
   KV bucket, which this daemon alone writes (`GET`/`PUT /api/notify/flows`);
   the router reads it. `GET /api/notify/deliveries` and `GET /api/notify/dry-run` ask
   the router for its deliveries log and a dry run of the saved flows →
-  [`docs/swarm/notify-router.md`](../docs/swarm/notify-router.md#flows).
+  [`docs/4-implementation/swarm/notify-router.md`](../docs/4-implementation/swarm/notify-router.md#flows).
 - **Operator profiles** — each operator's name and the pronouns on their
   forge profile, for every member of authelia's operator group, as one list
   under the one key of the `operator-profiles` KV bucket. This daemon alone
@@ -108,22 +108,22 @@ The swarm's control plane. The swarm UI and `swarmctl` are its clients.
   A forge read that fails keeps that operator's stored entry, and a name that
   leaves the group drops out of the list. Every agent reads the key into its
   system prompt →
-  [`docs/turn-loop/claude-invocation.md`](../docs/turn-loop/claude-invocation.md).
+  [`docs/4-implementation/turn-loop/claude-invocation.md`](../docs/4-implementation/turn-loop/claude-invocation.md).
 - **Builder runs** — the swarm builder's newest 100 finished builds of agent
   config PRs, with `nix`'s tail for a failed one, one document in the
   `builder-runs` KV bucket, which this daemon alone writes
   (`GET /api/builder/runs`, `GET /api/builder/runs/{id}`, the link on each
   `swarm-builder` commit status) →
-  [`docs/swarm/builder.md`](../docs/swarm/builder.md#build-records).
+  [`docs/4-implementation/swarm/builder.md`](../docs/4-implementation/swarm/builder.md#build-records).
 - **Meta fan-out** — the hyperhive pin of `internal/meta` that this daemon last
   sent the hives a deploy for, one key in the `meta-fanout` KV bucket, which
   this daemon alone reads and writes →
-  [`docs/swarm/builder.md`](../docs/swarm/builder.md).
+  [`docs/4-implementation/swarm/builder.md`](../docs/4-implementation/swarm/builder.md).
 - **Relays** — each agent's terminal and turn-state header as SSE, agent
   icons, the cross-repo issue report, and the UI's quick links.
 - **Alerts** — the swarm Grafana's current alerts (`GET /api/alerts`), read
   at request time with a Viewer service-account token from the secret store
-  → [`docs/swarm/credentials-reference.md`](../docs/swarm/credentials-reference.md).
+  → [`docs/2-handbook/swarm/credentials-reference.md`](../docs/2-handbook/swarm/credentials-reference.md).
 
 It reads its configuration once at startup, from the environment the nix module
 sets. It keeps the webhook HMAC secret in the secret store and

swarm-controller/src/matrix_account.rs

@@ -2,7 +2,7 @@
 //!
 //! **The internal one** — [`agent_token`] — is the agent's own `main` account on
 //! the swarm's homeserver, minted with the swarm's appservice token and stored
-//! where the agent's daemon reads it. See docs/swarm/credentials-reference.md for why
+//! where the agent's daemon reads it. See docs/2-handbook/swarm/credentials-reference.md for why
 //! `main` is the one name [`put_matrix_account`] refuses to write.
 //! [`hive_sender`] mints each **hive's** sender account the same way, sharing this module's helpers with [`agent_token`].
 //! [`operator_admin`] makes authelia's operators homeserver admins with the same

swarm-controller/src/routes/mod.rs

@@ -168,7 +168,7 @@ impl axum::response::IntoResponse for StatusUnavailable {
 /// Every error this daemon returns, in one shape.
 ///
 /// RFC 9457 `application/problem+json` is the hive-wide contract for HTTP
-/// error bodies (`docs/process/conventions.md`), and the operator UIs read `detail`
+/// error bodies (`docs/5-project/process/conventions.md`), and the operator UIs read `detail`
 /// for display. A bare string forces the reader to treat the entire body as
 /// the message, which is the difference between a UI that can offer "copy the
 /// cause" and one that can only dump a response.

swarm-controller/src/status.rs

@@ -16,7 +16,7 @@
 //! dashboard while the bucket says otherwise.
 //!
 //! **Absence is the case this is built around** — the freshness states
-//! and the reasoning behind each are in `docs/swarm/README.md`. The two
+//! and the reasoning behind each are in `docs/2-handbook/swarm/README.md`. The two
 //! properties that constrain the code rather than describe it:
 //! freshness is **derived at read time**, never stored (a stored
 //! `healthy: bool` goes stale silently the moment nothing arrives), and

swarm-controller/src/vcs_metrics.rs

@@ -1,6 +1,6 @@
 //! OTEL export of commit/push activity across every forge repo in the
 //! instance — the metric forgejo's own native `/metrics` endpoint (see
-//! `docs/integrations/forge.md`'s note on the survey that shipped it) does not carry.
+//! `docs/2-handbook/integrations/forge.md`'s note on the survey that shipped it) does not carry.
 //! That endpoint gives issue/comment/repo counts because Forgejo tracks
 //! those as durable rows it can `SELECT COUNT(*)` on demand; a commit or a
 //! push is not stored anywhere as a row to count, only observed in passing