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/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