From df8a82bc33d8d0af85173b6c246fd504e0b35620 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Fri, 6 Nov 2026 22:59:11 +0100
Subject: [PATCH] docs: move the cli references under 2-handbook/tools

Closes #6157
---
 .prettierignore                               | 10 +++---
 AGENTS.md                                     |  8 ++---
 README.md                                     |  2 +-
 docs/2-handbook/swarm/schedules.md            |  2 +-
 docs/2-handbook/swarm/sso.md                  |  2 +-
 docs/2-handbook/tools/README.md               | 12 +++++--
 .../{reference => tools}/forge-cli.md         |  0
 docs/2-handbook/tools/forge.md                |  4 +--
 .../{reference => tools}/hivectl-cli.md       |  0
 docs/2-handbook/tools/hivectl.md              |  4 +--
 .../{reference => tools}/swarm-logs-cli.md    |  0
 .../{reference => tools}/swarm-metrics-cli.md |  0
 .../{reference => tools}/swarmctl-cli.md      |  0
 docs/4-implementation/swarm/inference.md      |  2 +-
 docs/5-project/process/conventions.md         |  8 ++---
 docs/5-project/process/gotchas.md             |  2 +-
 docs/README.md                                |  4 +--
 hive-forge/src/main.rs                        |  2 +-
 nix/checks.nix                                | 34 +++++++++----------
 swarm-logs/src/main.rs                        |  2 +-
 swarm-metrics/src/main.rs                     |  2 +-
 swarmctl/README.md                            |  2 +-
 22 files changed, 54 insertions(+), 48 deletions(-)
 rename docs/2-handbook/{reference => tools}/forge-cli.md (100%)
 rename docs/2-handbook/{reference => tools}/hivectl-cli.md (100%)
 rename docs/2-handbook/{reference => tools}/swarm-logs-cli.md (100%)
 rename docs/2-handbook/{reference => tools}/swarm-metrics-cli.md (100%)
 rename docs/2-handbook/{reference => tools}/swarmctl-cli.md (100%)

diff --git a/.prettierignore b/.prettierignore
index eed7adfa..97df3845 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -4,11 +4,11 @@
 # generator, not the formatter, owns these files' layout. Every CLI
 # reference doc belongs here — adding one and forgetting this line is
 # what made swarmctl's fail.
-docs/2-handbook/reference/hivectl-cli.md
-docs/2-handbook/reference/swarmctl-cli.md
-docs/2-handbook/reference/forge-cli.md
-docs/2-handbook/reference/swarm-logs-cli.md
-docs/2-handbook/reference/swarm-metrics-cli.md
+docs/2-handbook/tools/hivectl-cli.md
+docs/2-handbook/tools/swarmctl-cli.md
+docs/2-handbook/tools/forge-cli.md
+docs/2-handbook/tools/swarm-logs-cli.md
+docs/2-handbook/tools/swarm-metrics-cli.md
 
 # Files with multi-line list-item continuations that prettier strips to col 0.
 # prettier's `proseWrap: "preserve"` prevents prose reflow but not list-item
diff --git a/AGENTS.md b/AGENTS.md
index a14a9879..a51d7973 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -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/2-handbook/reference/hivectl-cli.md`
-(same for `swarmctl` → `docs/2-handbook/reference/swarmctl-cli.md`). CI red but local
+`nix develop -c cargo run --bin hivectl -- markdown-docs > docs/2-handbook/tools/hivectl-cli.md`
+(same for `swarmctl` → `docs/2-handbook/tools/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,7 +58,7 @@ 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/2-handbook/reference/hivectl-cli.md`](docs/2-handbook/reference/hivectl-cli.md).
+  [`docs/2-handbook/tools/hivectl-cli.md`](docs/2-handbook/tools/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/2-handbook/trust-boundary/boundary.md`.
@@ -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/2-handbook/reference/swarmctl-cli.md`](docs/2-handbook/reference/swarmctl-cli.md).
+  [`docs/2-handbook/tools/swarmctl-cli.md`](docs/2-handbook/tools/swarmctl-cli.md).
 - **`swarm-authelia-bridge/`** (+ **`swarm-authelia-bridge-sock/`** wire
   types) — the other writer of authelia's users DB; runs inside
   `swarm-authelia`.
diff --git a/README.md b/README.md
index c59dd42e..c7108624 100644
--- a/README.md
+++ b/README.md
@@ -175,7 +175,7 @@ once, top to bottom.
   [`docs/2-handbook/swarm/ui.md`](docs/2-handbook/swarm/ui.md)
 - **`swarmctl`** — the swarm's CLI, on the swarm-controller host: create
   agents and mint their identities, manage SSO users, make forge admins.
-  → [reference](docs/2-handbook/reference/swarmctl-cli.md)
+  → [reference](docs/2-handbook/tools/swarmctl-cli.md)
 - **per-hive** — each hive's dashboard (container state,
   rebuild queue) and `hivectl` for host-level administration and
   container shells. → [`docs/2-handbook/web-ui/`](docs/2-handbook/web-ui/README.md) ·
diff --git a/docs/2-handbook/swarm/schedules.md b/docs/2-handbook/swarm/schedules.md
index 526a3628..a9dc7a0e 100644
--- a/docs/2-handbook/swarm/schedules.md
+++ b/docs/2-handbook/swarm/schedules.md
@@ -41,7 +41,7 @@ kqzpmwab  "standup"  every 1d  from 2026-10-05T07:00:00Z  next 2026-10-05T07:00:
 - `schedule list` shows one row per prompt: id, name, cadence, start, next
   fire time, agents, and the first line of the body.
 
-The full flag reference is [`swarmctl-cli.md`](../reference/swarmctl-cli.md).
+The full flag reference is [`swarmctl-cli.md`](../tools/swarmctl-cli.md).
 
 ## When a prompt fires
 
diff --git a/docs/2-handbook/swarm/sso.md b/docs/2-handbook/swarm/sso.md
index d3681e17..795f45e3 100644
--- a/docs/2-handbook/swarm/sso.md
+++ b/docs/2-handbook/swarm/sso.md
@@ -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: [`2-handbook/reference/swarmctl-cli.md`](../reference/swarmctl-cli.md).
+reference: [`2-handbook/tools/swarmctl-cli.md`](../tools/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
diff --git a/docs/2-handbook/tools/README.md b/docs/2-handbook/tools/README.md
index 9de2186d..1de51218 100644
--- a/docs/2-handbook/tools/README.md
+++ b/docs/2-handbook/tools/README.md
@@ -12,12 +12,12 @@ debug agent behavior.
 - **[hivectl](hivectl.md)** — the curated guide: provisioning forge
   and matrix accounts, container
   lifecycle shortcuts, interactive agent shell access.
-- **[hivectl-cli](../reference/hivectl-cli.md)** — the exhaustive, autogenerated
+- **[hivectl-cli](hivectl-cli.md)** — the exhaustive, autogenerated
   flag-by-flag reference, kept in lockstep with the binary by CI.
 
 ## For the swarm operator
 
-- **[swarmctl-cli](../reference/swarmctl-cli.md)** — the exhaustive, autogenerated
+- **[swarmctl-cli](swarmctl-cli.md)** — the exhaustive, autogenerated
   flag-by-flag reference for `swarmctl`, kept in lockstep with the
   binary by CI the same way `hivectl-cli.md` is. `swarmctl` itself
   runs as root on the swarm-controller host, not through `hivectl` —
@@ -25,6 +25,12 @@ debug agent behavior.
   (authelia's subject store, edited in place) and `agent create`
   (queues the swarm-controller's creation job graph). No curated guide
   yet; add one here if/when that grows.
+- **[swarm-logs-cli](swarm-logs-cli.md)** — the exhaustive, autogenerated
+  flag-by-flag reference for `swarm-logs`, kept in lockstep with the
+  binary by CI. No curated guide.
+- **[swarm-metrics-cli](swarm-metrics-cli.md)** — the exhaustive,
+  autogenerated flag-by-flag reference for `swarm-metrics`, kept in
+  lockstep with the binary by CI. No curated guide.
 
 ## What your agents can do
 
@@ -37,7 +43,7 @@ debug agent behavior.
 - **[forge](forge.md)** — the `hive-forge` Forgejo CLI every agent has
   for issues, PRs, and comments. Not an MCP tool — a binary agents
   shell out to instead of ad-hoc curl.
-- **[forge-cli](../reference/forge-cli.md)** — the exhaustive, autogenerated
+- **[forge-cli](forge-cli.md)** — the exhaustive, autogenerated
   flag-by-flag reference for `hive-forge`, kept in lockstep with the
   binary by CI the same way `hivectl-cli.md` is.
 - **[matrix](matrix.md)** — the matrix MCP tool surface
diff --git a/docs/2-handbook/reference/forge-cli.md b/docs/2-handbook/tools/forge-cli.md
similarity index 100%
rename from docs/2-handbook/reference/forge-cli.md
rename to docs/2-handbook/tools/forge-cli.md
diff --git a/docs/2-handbook/tools/forge.md b/docs/2-handbook/tools/forge.md
index b2d997ef..64abcc79 100644
--- a/docs/2-handbook/tools/forge.md
+++ b/docs/2-handbook/tools/forge.md
@@ -6,11 +6,11 @@ proper Rust binary). Use it instead of ad-hoc curl pipelines.
 
 This page is the curated guide. For the exhaustive flag-by-flag reference
 autogenerated from the binary's own command tree, see
-[`forge-cli.md`](../reference/forge-cli.md) — emitted by the hidden `hive-forge
+[`forge-cli.md`](forge-cli.md) — emitted by the hidden `hive-forge
 markdown-docs` subcommand and kept in lockstep with the code by the
 `hive-forge-docs` flake check (CI fails if the committed copy drifts).
 Regenerate with `nix build .#hive-forge && ./result/bin/hive-forge
-markdown-docs > docs/2-handbook/reference/forge-cli.md`.
+markdown-docs > docs/2-handbook/tools/forge-cli.md`.
 
 ## Credentials and repo defaults
 
diff --git a/docs/2-handbook/reference/hivectl-cli.md b/docs/2-handbook/tools/hivectl-cli.md
similarity index 100%
rename from docs/2-handbook/reference/hivectl-cli.md
rename to docs/2-handbook/tools/hivectl-cli.md
diff --git a/docs/2-handbook/tools/hivectl.md b/docs/2-handbook/tools/hivectl.md
index d4313f8e..f668555e 100644
--- a/docs/2-handbook/tools/hivectl.md
+++ b/docs/2-handbook/tools/hivectl.md
@@ -15,11 +15,11 @@ shortcuts and interactive agent shell access.
 
 This page is the curated guide. For the exhaustive flag-by-flag
 reference autogenerated from the binary's own command tree, see
-[`hivectl-cli.md`](../reference/hivectl-cli.md) — emitted by the hidden `hivectl
+[`hivectl-cli.md`](hivectl-cli.md) — emitted by the hidden `hivectl
 markdown-docs` subcommand and kept in lockstep with the code by the
 `hivectl-docs` flake check (CI fails if the committed copy drifts).
 Regenerate with `nix build .#default && ./result/bin/hivectl
-markdown-docs > docs/2-handbook/reference/hivectl-cli.md`.
+markdown-docs > docs/2-handbook/tools/hivectl-cli.md`.
 
 ## Agents
 
diff --git a/docs/2-handbook/reference/swarm-logs-cli.md b/docs/2-handbook/tools/swarm-logs-cli.md
similarity index 100%
rename from docs/2-handbook/reference/swarm-logs-cli.md
rename to docs/2-handbook/tools/swarm-logs-cli.md
diff --git a/docs/2-handbook/reference/swarm-metrics-cli.md b/docs/2-handbook/tools/swarm-metrics-cli.md
similarity index 100%
rename from docs/2-handbook/reference/swarm-metrics-cli.md
rename to docs/2-handbook/tools/swarm-metrics-cli.md
diff --git a/docs/2-handbook/reference/swarmctl-cli.md b/docs/2-handbook/tools/swarmctl-cli.md
similarity index 100%
rename from docs/2-handbook/reference/swarmctl-cli.md
rename to docs/2-handbook/tools/swarmctl-cli.md
diff --git a/docs/4-implementation/swarm/inference.md b/docs/4-implementation/swarm/inference.md
index 33454297..8eba7a5a 100644
--- a/docs/4-implementation/swarm/inference.md
+++ b/docs/4-implementation/swarm/inference.md
@@ -30,7 +30,7 @@ swarmctl agent inference clear iris
   running on, each with where it comes from.
 - `clear` removes every field; the agent goes back to its own values.
 
-The full flag reference is [`swarmctl-cli.md`](../../2-handbook/reference/swarmctl-cli.md). The
+The full flag reference is [`swarmctl-cli.md`](../../2-handbook/tools/swarmctl-cli.md). The
 swarm UI's agents page edits the same settings; see [UI](../../2-handbook/swarm/ui.md). The
 swarm is the only place to change an agent's model or effort at runtime:
 its web UI shows both but has no picker and no `/model` or `/effort`
diff --git a/docs/5-project/process/conventions.md b/docs/5-project/process/conventions.md
index 76d454e9..0a5c736f 100644
--- a/docs/5-project/process/conventions.md
+++ b/docs/5-project/process/conventions.md
@@ -497,20 +497,20 @@ mara — don't add `#[allow]` speculatively. The gate is intentional.
 fmt / `cargo test` cover most gates, but `nix flake check` runs extra
 check derivations they don't:
 
-- **`hivectl-docs`** regenerates `docs/2-handbook/reference/hivectl-cli.md` from
+- **`hivectl-docs`** regenerates `docs/2-handbook/tools/hivectl-cli.md` from
   hivectl's clap tree and **fails if the committed copy is stale**.
   **After any change to a hivectl verb or flag, regenerate it**:
   ```sh
-  nix develop -c cargo run --bin hivectl -- markdown-docs > docs/2-handbook/reference/hivectl-cli.md
+  nix develop -c cargo run --bin hivectl -- markdown-docs > docs/2-handbook/tools/hivectl-cli.md
   ```
   clippy / fmt / `cargo test` all pass *without* this — only the
   flake check catches the drift, and `ci-log` often can't show you
   why (it 500s on a fast failure), so you're left guessing "builder
   flake" when it's a stale doc.
 - **`swarmctl-docs`** is the same check for `swarmctl` /
-  `docs/2-handbook/reference/swarmctl-cli.md`:
+  `docs/2-handbook/tools/swarmctl-cli.md`:
   ```sh
-  nix develop -c cargo run --bin swarmctl -- markdown-docs > docs/2-handbook/reference/swarmctl-cli.md
+  nix develop -c cargo run --bin swarmctl -- markdown-docs > docs/2-handbook/tools/swarmctl-cli.md
   ```
 - there's also a flake `cargo-test` check and NixOS module
   evaluation in the set.
diff --git a/docs/5-project/process/gotchas.md b/docs/5-project/process/gotchas.md
index 1fe5d943..04118363 100644
--- a/docs/5-project/process/gotchas.md
+++ b/docs/5-project/process/gotchas.md
@@ -336,7 +336,7 @@ nix develop -c cargo run -p hive-c0re --bin hivectl -- <args>
 ```
 
 This is also how you regenerate committed generated docs locally —
-for example `docs/2-handbook/reference/hivectl-cli.md` via the `hivectl markdown-docs`
+for example `docs/2-handbook/tools/hivectl-cli.md` via the `hivectl markdown-docs`
 subcommand (its `hivectl-docs` flake check otherwise only fails in
 CI on drift).
 
diff --git a/docs/README.md b/docs/README.md
index 8adc4c11..88af925e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -34,9 +34,9 @@ later work.
   tool surface (bash, forge, lifecycle, matrix).
 - **What does `hivectl` do? Provisioning, gateway users, container
   shells?** → [`2-handbook/tools/hivectl.md`](2-handbook/tools/hivectl.md) (the curated guide);
-  [`2-handbook/reference/hivectl-cli.md`](2-handbook/reference/hivectl-cli.md) for the exhaustive,
+  [`2-handbook/tools/hivectl-cli.md`](2-handbook/tools/hivectl-cli.md) for the exhaustive,
   autogenerated flag reference. The other command-line references sit beside it in
-  [`2-handbook/reference/`](2-handbook/reference/).
+  [`2-handbook/tools/`](2-handbook/tools/README.md).
 
 ### Agent lifecycle
 
diff --git a/hive-forge/src/main.rs b/hive-forge/src/main.rs
index f173e886..1e0dcbf7 100644
--- a/hive-forge/src/main.rs
+++ b/hive-forge/src/main.rs
@@ -229,7 +229,7 @@ fn run() -> Result<()> {
     }
     // Same reasoning as `credential-helper` above: no repo, no forge
     // credentials — just a pure render of the clap tree the docs build
-    // pipes into `docs/2-handbook/reference/forge-cli.md`.
+    // pipes into `docs/2-handbook/tools/forge-cli.md`.
     if let Verb::MarkdownDocs = verb {
         // `show_footer(false)`: the default footer's wording ("This
         // document was generated automatically by...") is clap-markdown's
diff --git a/nix/checks.nix b/nix/checks.nix
index 7b661676..e07bab96 100644
--- a/nix/checks.nix
+++ b/nix/checks.nix
@@ -473,7 +473,7 @@ in
   };
 
   # `hivectl` CLI reference freshness check. The committed
-  # markdown at `docs/2-handbook/reference/hivectl-cli.md` is the rendered
+  # markdown at `docs/2-handbook/tools/hivectl-cli.md` is the rendered
   # output of the hidden `hivectl markdown-docs` subcommand
   # (clap-markdown walks the binary's own command tree). This
   # check regenerates it from the built binary and fails if the
@@ -485,13 +485,13 @@ in
   # makes this check unsatisfiable rather than merely stale.
   # Regenerate locally with:
   #   nix build .#default
-  #   ./result/bin/hivectl markdown-docs > docs/2-handbook/reference/hivectl-cli.md
+  #   ./result/bin/hivectl markdown-docs > docs/2-handbook/tools/hivectl-cli.md
   hivectl-docs = pkgs.runCommand "hivectl-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; } ''
     ${self.packages.${system}.default}/bin/hivectl markdown-docs > generated.md
-    if ! diff -u ${../docs/2-handbook/reference/hivectl-cli.md} generated.md; then
+    if ! diff -u ${../docs/2-handbook/tools/hivectl-cli.md} generated.md; then
       echo "" >&2
-      echo "ERROR: docs/2-handbook/reference/hivectl-cli.md is out of date — regenerate it:" >&2
-      echo "  nix build .#default && ./result/bin/hivectl markdown-docs > docs/2-handbook/reference/hivectl-cli.md" >&2
+      echo "ERROR: docs/2-handbook/tools/hivectl-cli.md is out of date — regenerate it:" >&2
+      echo "  nix build .#default && ./result/bin/hivectl markdown-docs > docs/2-handbook/tools/hivectl-cli.md" >&2
       exit 1
     fi
     touch "$out"
@@ -504,10 +504,10 @@ in
   # nix/packages/default.nix's comment on it).
   swarmctl-docs = pkgs.runCommand "swarmctl-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; } ''
     ${self.packages.${system}.swarmctl}/bin/swarmctl markdown-docs > generated.md
-    if ! diff -u ${../docs/2-handbook/reference/swarmctl-cli.md} generated.md; then
+    if ! diff -u ${../docs/2-handbook/tools/swarmctl-cli.md} generated.md; then
       echo "" >&2
-      echo "ERROR: docs/2-handbook/reference/swarmctl-cli.md is out of date — regenerate it:" >&2
-      echo "  nix build .#swarmctl && ./result/bin/swarmctl markdown-docs > docs/2-handbook/reference/swarmctl-cli.md" >&2
+      echo "ERROR: docs/2-handbook/tools/swarmctl-cli.md is out of date — regenerate it:" >&2
+      echo "  nix build .#swarmctl && ./result/bin/swarmctl markdown-docs > docs/2-handbook/tools/swarmctl-cli.md" >&2
       exit 1
     fi
     touch "$out"
@@ -521,10 +521,10 @@ in
     pkgs.runCommand "swarm-logs-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; }
       ''
         ${self.packages.${system}.swarm-logs}/bin/swarm-logs markdown-docs > generated.md
-        if ! diff -u ${../docs/2-handbook/reference/swarm-logs-cli.md} generated.md; then
+        if ! diff -u ${../docs/2-handbook/tools/swarm-logs-cli.md} generated.md; then
           echo "" >&2
-          echo "ERROR: docs/2-handbook/reference/swarm-logs-cli.md is out of date — regenerate it:" >&2
-          echo "  nix build .#swarm-logs && ./result/bin/swarm-logs markdown-docs > docs/2-handbook/reference/swarm-logs-cli.md" >&2
+          echo "ERROR: docs/2-handbook/tools/swarm-logs-cli.md is out of date — regenerate it:" >&2
+          echo "  nix build .#swarm-logs && ./result/bin/swarm-logs markdown-docs > docs/2-handbook/tools/swarm-logs-cli.md" >&2
           exit 1
         fi
         touch "$out"
@@ -536,10 +536,10 @@ in
     pkgs.runCommand "swarm-metrics-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; }
       ''
         ${self.packages.${system}.swarm-metrics}/bin/swarm-metrics markdown-docs > generated.md
-        if ! diff -u ${../docs/2-handbook/reference/swarm-metrics-cli.md} generated.md; then
+        if ! diff -u ${../docs/2-handbook/tools/swarm-metrics-cli.md} generated.md; then
           echo "" >&2
-          echo "ERROR: docs/2-handbook/reference/swarm-metrics-cli.md is out of date — regenerate it:" >&2
-          echo "  nix build .#swarm-metrics && ./result/bin/swarm-metrics markdown-docs > docs/2-handbook/reference/swarm-metrics-cli.md" >&2
+          echo "ERROR: docs/2-handbook/tools/swarm-metrics-cli.md is out of date — regenerate it:" >&2
+          echo "  nix build .#swarm-metrics && ./result/bin/swarm-metrics markdown-docs > docs/2-handbook/tools/swarm-metrics-cli.md" >&2
           exit 1
         fi
         touch "$out"
@@ -554,10 +554,10 @@ in
     pkgs.runCommand "hive-forge-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; }
       ''
         ${self.packages.${system}.hive-forge}/bin/hive-forge markdown-docs > generated.md
-        if ! diff -u ${../docs/2-handbook/reference/forge-cli.md} generated.md; then
+        if ! diff -u ${../docs/2-handbook/tools/forge-cli.md} generated.md; then
           echo "" >&2
-          echo "ERROR: docs/2-handbook/reference/forge-cli.md is out of date — regenerate it:" >&2
-          echo "  nix build .#hive-forge && ./result/bin/hive-forge markdown-docs > docs/2-handbook/reference/forge-cli.md" >&2
+          echo "ERROR: docs/2-handbook/tools/forge-cli.md is out of date — regenerate it:" >&2
+          echo "  nix build .#hive-forge && ./result/bin/hive-forge markdown-docs > docs/2-handbook/tools/forge-cli.md" >&2
           exit 1
         fi
         touch "$out"
diff --git a/swarm-logs/src/main.rs b/swarm-logs/src/main.rs
index 3211dcf7..5e81625d 100644
--- a/swarm-logs/src/main.rs
+++ b/swarm-logs/src/main.rs
@@ -62,7 +62,7 @@ enum Verb {
         format: query::Format,
     },
 
-    /// Print this CLI's reference as markdown (source of `docs/2-handbook/reference/swarm-logs-cli.md`).
+    /// Print this CLI's reference as markdown (source of `docs/2-handbook/tools/swarm-logs-cli.md`).
     ///
     /// No `completions` sibling, unlike `hivectl` and `swarmctl`: those are
     /// installed on an operator's interactive host, where a completion script
diff --git a/swarm-metrics/src/main.rs b/swarm-metrics/src/main.rs
index fb71b99a..2da47b32 100644
--- a/swarm-metrics/src/main.rs
+++ b/swarm-metrics/src/main.rs
@@ -117,7 +117,7 @@ enum Verb {
         span: SpanArgs,
     },
 
-    /// Print this CLI's reference as markdown (source of `docs/2-handbook/reference/swarm-metrics-cli.md`).
+    /// Print this CLI's reference as markdown (source of `docs/2-handbook/tools/swarm-metrics-cli.md`).
     #[command(hide = true)]
     MarkdownDocs,
 }
diff --git a/swarmctl/README.md b/swarmctl/README.md
index 56315b74..07f9d585 100644
--- a/swarmctl/README.md
+++ b/swarmctl/README.md
@@ -61,7 +61,7 @@ an error.
 | `SWARMCTL_SWARM`               | the swarm's domain, bare or `https://`: reach the controller there   |
 | `SWARMCTL_CA_FILE`             | a PEM CA to trust beside the system roots, for `SWARMCTL_SWARM`      |
 
-Every verb and flag: [`docs/2-handbook/reference/swarmctl-cli.md`](../docs/2-handbook/reference/swarmctl-cli.md).
+Every verb and flag: [`docs/2-handbook/tools/swarmctl-cli.md`](../docs/2-handbook/tools/swarmctl-cli.md).
 The sections below cover why each verb behaves as it does.
 
 ## `user add`