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.

AGENTS.md

@@ -10,20 +10,20 @@ when you need depth on a subsystem. This file is the index.
   the env var — inside an agent container `localhost` is the *agent*, not
   the forge, so a hardcoded loopback address fails to connect.
 - Operator/agent trust-boundary design:
-  **[docs/trust-boundary/boundary.md](docs/trust-boundary/boundary.md)** (`area/ops` issues
+  **[docs/2-handbook/trust-boundary/boundary.md](docs/2-handbook/trust-boundary/boundary.md)** (`area/ops` issues
   for the deployment/gateway/privsep work — the separator is a **slash**,
   and `--label area:ops` now fails with `did you mean "area/ops"?`).
 - Agent trust model (trust boundary, prompt-injection threat model,
   capability = accepted risk), credential isolation + sandbox threat model:
-  **[docs/trust-boundary/security.md](docs/trust-boundary/security.md)**.
+  **[docs/2-handbook/trust-boundary/security.md](docs/2-handbook/trust-boundary/security.md)**.
 - Odd-looking nspawn / container plumbing usually has a story:
-  **[docs/process/gotchas.md](docs/process/gotchas.md)**.
+  **[docs/5-project/process/gotchas.md](docs/5-project/process/gotchas.md)**.
 
 ## Build & check
 
 Always through the devshell — a bare `cargo` fails (`failed to find tool
 "cc"`, `cannot find -lsqlite3`). Details:
-[`docs/process/conventions.md`](docs/process/conventions.md#building--local-checks).
+[`docs/5-project/process/conventions.md`](docs/5-project/process/conventions.md#building--local-checks).
 
 ```sh
 nix develop -c cargo clippy --all-targets -- -D warnings
@@ -33,8 +33,8 @@ nix fmt        # treefmt is the CI gate, NOT bare cargo fmt
 
 Changed a `hivectl` / `swarmctl` verb or flag? Regenerate its doc — only
 CI's `nix flake check` catches the drift:
-`nix develop -c cargo run --bin hivectl -- markdown-docs > docs/tools/hivectl-cli.md`
-(same for `swarmctl` → `docs/tools/swarmctl-cli.md`). CI red but local
+`nix develop -c cargo run --bin hivectl -- markdown-docs > docs/2-handbook/reference/hivectl-cli.md`
+(same for `swarmctl` → `docs/2-handbook/reference/swarmctl-cli.md`). CI red but local
 green → build the suspect check (e.g. `nix build
 .#checks.x86_64-linux.hivectl-docs`) before blaming the builder.
 
@@ -58,10 +58,10 @@ Per-hive (host + in-container):
   crate.
 - **`hivectl/`** — operator CLI; talks to `hive-c0re` over the host admin
   socket, does NOT link it. Verb reference (CI-enforced):
-  [`docs/tools/hivectl-cli.md`](docs/tools/hivectl-cli.md).
+  [`docs/2-handbook/reference/hivectl-cli.md`](docs/2-handbook/reference/hivectl-cli.md).
 - **`hive-priv/`** — minimal root helper, socket-activated at
   `/run/hive/priv.sock`; the few root ops (bind-mount edits, nsenter)
-  `hive-c0re` delegates. See `docs/trust-boundary/boundary.md`.
+  `hive-c0re` delegates. See `docs/2-handbook/trust-boundary/boundary.md`.
 - **`hive-agent/`** — the in-container serve loop: turn-loop *policy*
   (`turn.rs`) over `hive-runtime`, per-agent web UI, event + turn-stats
   sinks, system-prompt renderer, claude launch config (`mcp_config.rs`).
@@ -130,7 +130,7 @@ Swarm-level:
   **`users.yml` in place**, shared with `swarm-authelia-bridge`; that
   crate's README says what both writers must uphold. Verb reference
   (CI-enforced):
-  [`docs/tools/swarmctl-cli.md`](docs/tools/swarmctl-cli.md).
+  [`docs/2-handbook/reference/swarmctl-cli.md`](docs/2-handbook/reference/swarmctl-cli.md).
 - **`swarm-authelia-bridge/`** (+ **`swarm-authelia-bridge-sock/`** wire
   types) — the other writer of authelia's users DB; runs inside
   `swarm-authelia`.
@@ -164,20 +164,20 @@ Swarm-level:
 - **`swarm-builder/`** — builds agent config PR heads for commit status,
   builds each agent from `internal/meta` before its deploy, and evaluates the
   agent archetypes the create form lists.
-  Design: [`docs/swarm/builder.md`](docs/swarm/builder.md).
+  Design: [`docs/4-implementation/swarm/builder.md`](docs/4-implementation/swarm/builder.md).
 - **`swarm-ci-metrics/`** — polls the forge's Actions runs and pushes each
   finished run's duration and queue wait to the metrics store. Design:
-  [`docs/swarm/ci-metrics.md`](docs/swarm/ci-metrics.md).
+  [`docs/4-implementation/swarm/ci-metrics.md`](docs/4-implementation/swarm/ci-metrics.md).
 - **`swarm-claude-login/`** — runs `claude auth login` for one agent and
   stores the credentials at `swarm/agents/<agent>/claude-credentials`.
-  Design: [`docs/swarm/claude-login.md`](docs/swarm/claude-login.md).
+  Design: [`docs/2-handbook/swarm/claude-login.md`](docs/2-handbook/swarm/claude-login.md).
 - **`swarm-notify-router/`** — forge events from swarm-controller's
   webhooks to todos on the agents they concern, through each agent's own
   consumer on the `ROUTER_TODOS` stream. Design:
-  [`docs/swarm/notify-router.md`](docs/swarm/notify-router.md).
+  [`docs/4-implementation/swarm/notify-router.md`](docs/4-implementation/swarm/notify-router.md).
 - **`swarm-review-classifier/`** — one `claude --print` per PR
   classification, no tools, no forge credential. Design:
-  [`docs/swarm/review-classifier.md`](docs/swarm/review-classifier.md).
+  [`docs/4-implementation/swarm/review-classifier.md`](docs/4-implementation/swarm/review-classifier.md).
 
 ### External dependencies with no directory here
 
@@ -213,7 +213,7 @@ in this file and drifted.
 
 - **Never add `#[allow(clippy::…)]`** — fix the lint instead (extract a
   helper, add backticks, etc.). Worked examples:
-  [`docs/process/conventions.md`](docs/process/conventions.md#building--local-checks).
+  [`docs/5-project/process/conventions.md`](docs/5-project/process/conventions.md#building--local-checks).
 - **Pre-push lint hook** (catches tracker-tag and comment-block failures
   before CI does — install once per clone):
   `ln -sf ../../scripts/pre-push .git/hooks/pre-push`
@@ -225,7 +225,7 @@ in this file and drifted.
 - **Operator-facing doc with real implementation detail mixed in**: wrap
   the implementation part in a `<details><summary>…</summary>` block
   (blank line after `<summary>` so the markdown inside renders) rather
-  than a sibling page — see `docs/integrations/github.md`'s
+  than a sibling page — see `docs/2-handbook/integrations/github.md`'s
   "Implementation" section. It only collapses in a rendered browser, and
   the `<summary>` line isn't markdown-processed, so keep it plain prose
   with no backticks.