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.

frontend/packages/swarm-ui/src/colors.css

@@ -2,5 +2,5 @@
    esbuild emits its own `dist/static/colors.css`, linked first by every
    swarm-ui page (before theme.css). This is the theme swap contract: a
    stylix-generated variant replaces only this file. See
-   @hive/shared/colors.css + docs/web-ui/css-vars.md. */
+   @hive/shared/colors.css + docs/4-implementation/web-ui/css-vars.md. */
 @import "@hive/shared/colors.css";

frontend/packages/swarm-ui/src/pages/review-runs/ReviewRuns.tsx

@@ -1,5 +1,5 @@
 // <ReviewRuns> — the review classifier's recent runs, newest first
-// (`docs/swarm/review-classifier.md`, "Recent runs"): which PRs it ran on,
+// (`docs/4-implementation/swarm/review-classifier.md`, "Recent runs"): which PRs it ran on,
 // what it answered, and which runs failed or were turned away. One card per
 // run; selecting a card expands it to the same result table the try-out
 // shows. Reads `GET /api/review-classifier/runs`. This section stores nothing and

frontend/packages/swarm-ui/src/pages/review-tryout/ReviewTryOut.tsx

@@ -1,6 +1,6 @@
 // <ReviewTryOut> — write a review classification and see how the model
 // answers it on a real PR, before it goes into a repo's config
-// (`docs/swarm/review-classifier.md`, "Try-out"). Pick a repo and a PR, write
+// (`docs/4-implementation/swarm/review-classifier.md`, "Try-out"). Pick a repo and a PR, write
 // one or more classifications, run: the page posts them to
 // swarm-controller's `POST /api/review-classifier/try-out`, which answers
 // `202 {id}`, and polls `GET .../try-out/{id}` until the run is `done` or

frontend/packages/swarm-ui/src/pages/review-tryout/TryOutResult.tsx

@@ -1,7 +1,7 @@
 // <TryOutResult> — a finished try-out: one row per classification, the
 // overall verdict under them, and the head commit the run read. One column per
 // field of a row, where the posted review folds them into four
-// (`docs/swarm/review-classifier.md`); no token
+// (`docs/4-implementation/swarm/review-classifier.md`); no token
 // counts, cache counts or cost, here or anywhere in the UI.
 import { Badge } from "@hive/shared/badge.js";
 import { Hint } from "../../ui/hint/Hint.js";

frontend/packages/swarm-ui/src/pages/review/ReviewPage.tsx

@@ -1,4 +1,4 @@
-// <ReviewPage> — the review classifier, one card of the jobs tab (`docs/swarm/ui.md`,
+// <ReviewPage> — the review classifier, one card of the jobs tab (`docs/2-handbook/swarm/ui.md`,
 // "Review"): the way to try a classification on a PR, the classifier's own
 // settings, and the runs it has done. The first two fold, since they are
 // used now and then and a folded header says what is in them; the runs are

frontend/packages/swarm-ui/src/theme.css

@@ -2,5 +2,5 @@
    esbuild emits it as its own `dist/static/theme.css`, linked by every
    swarm-ui page right after colors.css. The base16 slots it derives
    from live in colors.css (the swap contract); a theme swap replaces
-   only that file. See @hive/shared/theme.css + docs/web-ui/css-vars.md. */
+   only that file. See @hive/shared/theme.css + docs/4-implementation/web-ui/css-vars.md. */
 @import "@hive/shared/theme.css";