diff --git a/.prettierignore b/.prettierignore
index 97df3845..3550935a 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -6,9 +6,9 @@
 # what made swarmctl's fail.
 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
+docs/4-implementation/agent-tools/forge-cli.md
+docs/4-implementation/agent-tools/swarm-logs-cli.md
+docs/4-implementation/agent-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
@@ -21,8 +21,8 @@ docs/4-implementation/networking/gateway.md
 docs/2-handbook/integrations/matrix.md
 docs/2-handbook/agent-lifecycle/persistence.md
 docs/4-implementation/web-ui/terminal-rendering.md
-docs/2-handbook/tools/forge.md
-docs/2-handbook/tools/matrix.md
+docs/4-implementation/agent-tools/forge.md
+docs/4-implementation/agent-tools/matrix.md
 docs/4-implementation/turn-loop/README.md
 docs/2-handbook/web-ui/agent.md
 docs/2-handbook/web-ui/dashboard.md
diff --git a/README.md b/README.md
index c7108624..160d71f0 100644
--- a/README.md
+++ b/README.md
@@ -84,10 +84,10 @@ box it gets:
   producers feed. → [schedules](docs/2-handbook/swarm/schedules.md)
 - **background bash** — long-running commands as tracked tasks
   (`run` / `status` / `kill`), so a build doesn't block the turn. →
-  [bash](docs/2-handbook/tools/bash.md)
+  [bash](docs/4-implementation/agent-tools/bash.md)
 - **subagents** — nested sessions on the agent's own runtime, optionally
   re-prompted toward a goal over several turns. →
-  [subagent](docs/2-handbook/tools/subagent.md)
+  [subagent](docs/4-implementation/agent-tools/subagent.md)
 - **forge** — its own Forgejo account, the `hive-forge` CLI, git
   credentials, and notifications turned into todos. Optional linked
   accounts on other forges, GitLab (`glab` + push), and GitHub (`gh` + push) via
@@ -95,7 +95,7 @@ box it gets:
   [forge](docs/2-handbook/integrations/forge.md) · [gitlab](docs/2-handbook/integrations/gitlab.md) ·
   [github](docs/2-handbook/integrations/github.md)
 - **matrix** — its own account(s) on the swarm homeserver, as MCP tools. →
-  [matrix](docs/2-handbook/tools/matrix.md)
+  [matrix](docs/4-implementation/agent-tools/matrix.md)
 - **knowledge** — the swarm's shared `internal/knowledge` repo, read-only
   at `/knowledge`, plus hyperhive's own docs in the container. →
   [knowledge](docs/2-handbook/integrations/knowledge.md)
diff --git a/docs/2-handbook/integrations/forge.md b/docs/2-handbook/integrations/forge.md
index e8a46b4a..b0680aac 100644
--- a/docs/2-handbook/integrations/forge.md
+++ b/docs/2-handbook/integrations/forge.md
@@ -398,4 +398,4 @@ delivers every unread notification it's handed. A hive-forge CLI
 subscription verb bounds the firehose explicitly (dropping broad repo
 watches an agent doesn't need) — the poller never guesses which
 watches to drop. See the `subscription` verb in
-[`docs/2-handbook/tools/forge.md`](../tools/forge.md).
+[`docs/4-implementation/agent-tools/forge.md`](../../4-implementation/agent-tools/forge.md).
diff --git a/docs/2-handbook/tools/README.md b/docs/2-handbook/tools/README.md
index 1de51218..7492994f 100644
--- a/docs/2-handbook/tools/README.md
+++ b/docs/2-handbook/tools/README.md
@@ -1,11 +1,8 @@
 # Tools
 
-`hivectl` is _your_ tool — the operator's own host CLI. Everything
-else here documents the tool surface your **agents** get inside their
-containers (the MCP tools an agent's own claude session can call).
-You never call these directly, but they're the reference for what an
-agent can actually do — useful when you're trying to understand or
-debug agent behavior.
+`hivectl` and `swarmctl` are _your_ tools — the operator's own CLIs. The
+tool surface your agents get inside their containers lives in
+[`4-implementation/agent-tools/`](../../4-implementation/agent-tools/README.md).
 
 ## For the operator
 
@@ -25,27 +22,3 @@ 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
-
-- **[bash](bash.md)** — background shell execution (`mcp__bash__*`),
-  available on every agent unconditionally.
-- **[subagent](subagent.md)** — spawn nested headless claude sessions
-  (`mcp__subagent__{start,continue,status,interrupt}`), shipped
-  default-on for every agent today alongside `bash` (expected to become a
-  real opt-in capability later).
-- **[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](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
-  (`mcp__matrix__*`) for agents with a matrix account, multiple
-  accounts per agent, and declaring extra MCP servers generally.
diff --git a/docs/4-implementation/agent-tools/README.md b/docs/4-implementation/agent-tools/README.md
new file mode 100644
index 00000000..63516866
--- /dev/null
+++ b/docs/4-implementation/agent-tools/README.md
@@ -0,0 +1,32 @@
+# Agent tools
+
+The tool surface your **agents** get inside their containers (the MCP tools
+an agent's own claude session can call, plus the CLIs it shells out to).
+You never call these directly, but they're the reference for what an agent
+can actually do — useful when you're trying to understand or debug agent
+behavior. The operator's own tools are in
+[`2-handbook/tools/`](../../2-handbook/tools/README.md).
+
+## What your agents can do
+
+- **[bash](bash.md)** — background shell execution (`mcp__bash__*`),
+  available on every agent unconditionally.
+- **[subagent](subagent.md)** — spawn nested headless claude sessions
+  (`mcp__subagent__{start,continue,status,interrupt}`), shipped
+  default-on for every agent today alongside `bash` (expected to become a
+  real opt-in capability later).
+- **[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](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.
+- **[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.
+- **[matrix](matrix.md)** — the matrix MCP tool surface
+  (`mcp__matrix__*`) for agents with a matrix account, multiple
+  accounts per agent, and declaring extra MCP servers generally.
diff --git a/docs/2-handbook/tools/bash.md b/docs/4-implementation/agent-tools/bash.md
similarity index 100%
rename from docs/2-handbook/tools/bash.md
rename to docs/4-implementation/agent-tools/bash.md
diff --git a/docs/2-handbook/tools/forge-cli.md b/docs/4-implementation/agent-tools/forge-cli.md
similarity index 100%
rename from docs/2-handbook/tools/forge-cli.md
rename to docs/4-implementation/agent-tools/forge-cli.md
diff --git a/docs/2-handbook/tools/forge.md b/docs/4-implementation/agent-tools/forge.md
similarity index 99%
rename from docs/2-handbook/tools/forge.md
rename to docs/4-implementation/agent-tools/forge.md
index 64abcc79..19aed65e 100644
--- a/docs/2-handbook/tools/forge.md
+++ b/docs/4-implementation/agent-tools/forge.md
@@ -10,7 +10,7 @@ autogenerated from the binary's own command tree, see
 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/tools/forge-cli.md`.
+markdown-docs > docs/4-implementation/agent-tools/forge-cli.md`.
 
 ## Credentials and repo defaults
 
diff --git a/docs/2-handbook/tools/matrix.md b/docs/4-implementation/agent-tools/matrix.md
similarity index 98%
rename from docs/2-handbook/tools/matrix.md
rename to docs/4-implementation/agent-tools/matrix.md
index 4ef3f834..816bce9d 100644
--- a/docs/2-handbook/tools/matrix.md
+++ b/docs/4-implementation/agent-tools/matrix.md
@@ -149,7 +149,7 @@ pending invites, resolve_invite to accept or reject`. The daemon clears
 the keyed todo when a `resolve_invite` (or `join_room`) call resolves
 the invite.
 
-See [`docs/2-handbook/integrations/matrix.md`](../integrations/matrix.md) for the homeserver setup,
+See [`docs/2-handbook/integrations/matrix.md`](../../2-handbook/integrations/matrix.md) for the homeserver setup,
 provisioning flow, and federation config.
 
 ## Extra MCP servers (per-agent)
diff --git a/docs/2-handbook/tools/subagent.md b/docs/4-implementation/agent-tools/subagent.md
similarity index 98%
rename from docs/2-handbook/tools/subagent.md
rename to docs/4-implementation/agent-tools/subagent.md
index 02f876d4..35ccbe6f 100644
--- a/docs/2-handbook/tools/subagent.md
+++ b/docs/4-implementation/agent-tools/subagent.md
@@ -325,7 +325,7 @@ it came from. One without a `model` runs on claude's own default, which the
 daemon doesn't check. The list is:
 
 - the swarm's `subagent_models` for this agent, when it sets one
-  ([`inference.md`](../../4-implementation/swarm/inference.md)). It replaces the agent's own
+  ([`inference.md`](../swarm/inference.md)). It replaces the agent's own
   list, so it can name models that list leaves out.
 - otherwise `services.hyperhive.agent.availableModels`, which reaches the
   daemon as `HIVE_AVAILABLE_MODELS`. An empty list restricts nothing.
@@ -340,7 +340,7 @@ as `<provider>/<model>` on `opencode`.
 ## How many subagents may run at once
 
 When the swarm sets `max_subagents` for the agent
-([`inference.md`](../../4-implementation/swarm/inference.md)), the daemon refuses a `start`, or a
+([`inference.md`](../swarm/inference.md)), the daemon refuses a `start`, or a
 `continue` of a session that isn't running, once that many subagents are
 running, before anything spawns:
 
@@ -405,7 +405,7 @@ daemon reads from the swarm on each `start`/`continue`:
 `Edit`, `Glob`, `Grep`, `Read`, `Skill`, `Write`, plus `WebFetch`/
 `WebSearch` for an agent granted `web_tools` and not otherwise. A running
 subagent keeps the tools it started with. See
-[the harness's own allowlist](../../4-implementation/turn-loop/mcp.md#tool-allowlist-hive_sh4repermissionsallowed_builtin_tools)
+[the harness's own allowlist](../turn-loop/mcp.md#tool-allowlist-hive_sh4repermissionsallowed_builtin_tools)
 for what that list contains and why.
 
 The exception: **a subagent gets Claude's built-in `Bash` iff its parent
diff --git a/docs/2-handbook/tools/swarm-logs-cli.md b/docs/4-implementation/agent-tools/swarm-logs-cli.md
similarity index 100%
rename from docs/2-handbook/tools/swarm-logs-cli.md
rename to docs/4-implementation/agent-tools/swarm-logs-cli.md
diff --git a/docs/2-handbook/tools/swarm-metrics-cli.md b/docs/4-implementation/agent-tools/swarm-metrics-cli.md
similarity index 100%
rename from docs/2-handbook/tools/swarm-metrics-cli.md
rename to docs/4-implementation/agent-tools/swarm-metrics-cli.md
diff --git a/docs/4-implementation/swarm/inference.md b/docs/4-implementation/swarm/inference.md
index 8eba7a5a..7bf14bee 100644
--- a/docs/4-implementation/swarm/inference.md
+++ b/docs/4-implementation/swarm/inference.md
@@ -20,11 +20,11 @@ swarmctl agent inference clear iris
 - `--subagent-models` takes a comma-separated list. It replaces the
   agent's `availableModels` as the models its subagent `start` and
   `continue` calls may name, read on each call
-  ([`subagent.md`](../../2-handbook/tools/subagent.md#which-models-a-subagent-may-run-on)).
+  ([`subagent.md`](../agent-tools/subagent.md#which-models-a-subagent-may-run-on)).
 - You set the subagent cap, `max_subagents`, in the swarm UI's inference
   dialog; `set` has no flag for it and keeps the stored one. It's a whole
   number from 0 to 32, where 0 allows no subagents; unset means no cap
-  ([`subagent.md`](../../2-handbook/tools/subagent.md#how-many-subagents-may-run-at-once)).
+  ([`subagent.md`](../agent-tools/subagent.md#how-many-subagents-may-run-at-once)).
 - `get` shows each field, naming the unset ones (or says the swarm sets
   nothing for the agent), and then the model and effort the agent reports
   running on, each with where it comes from.
diff --git a/docs/4-implementation/turn-loop/mcp.md b/docs/4-implementation/turn-loop/mcp.md
index 9fbc6e49..543bd86a 100644
--- a/docs/4-implementation/turn-loop/mcp.md
+++ b/docs/4-implementation/turn-loop/mcp.md
@@ -20,7 +20,7 @@ entry on the schema's stdio default — it spawns
 the tools land in claude as
 `mcp__hyperhive__<tool>`. Each entry also has an `availableToSubagents`
 toggle (default `false`) — see
-[`docs/2-handbook/tools/subagent.md`](../../2-handbook/tools/subagent.md#mcp-servers-available-to-a-subagent)
+[`docs/4-implementation/agent-tools/subagent.md`](../agent-tools/subagent.md#mcp-servers-available-to-a-subagent)
 for what reaches a subagent's own `--mcp-config` and what doesn't.
 An `"http"` entry that needs request headers (a bearer-authenticated remote
 server) sets `headersFile` to an absolute path: a file holding a JSON object
@@ -48,7 +48,7 @@ runs on the change.
   (default: empty = unrestricted) limits which names `send` accepts —
   useful for sandboxing. The broker refuses `to: "operator"`. The error
   points an agent that has the matrix MCP tools at matrix
-  ([matrix](../../2-handbook/tools/matrix.md)), and tells one without them that the
+  ([matrix](../agent-tools/matrix.md)), and tells one without them that the
   operator reads its `set_status` line, its turn output on the dashboard,
   and its logs.
 - `recv` — drain inbox. Always an immediate peek, never blocks. `max`
@@ -139,11 +139,11 @@ hive_name?, swarm_name?, matrix_accounts? }`. `matrix_accounts` is a
 ## Privileged tools (by permission)
 
 - **Bash execution** (`execution`) — background shell tasks. See
-  [`docs/2-handbook/tools/bash.md`](../../2-handbook/tools/bash.md).
+  [`docs/4-implementation/agent-tools/bash.md`](../agent-tools/bash.md).
 - **Subagent spawning** — nested sessions on the agent's own runtime
   (claude or ACP, via `hive-runtime`) as background tasks, shipped
   default-on like bash execution; no permission gates it. See
-  [`docs/2-handbook/tools/subagent.md`](../../2-handbook/tools/subagent.md).
+  [`docs/4-implementation/agent-tools/subagent.md`](../agent-tools/subagent.md).
 - **Config changes** — no permission: they go through a forge PR on
   `agent-configs/<name>` — see
   [`docs/2-handbook/agent-lifecycle/config-changes.md`](../../2-handbook/agent-lifecycle/config-changes.md).
@@ -155,14 +155,14 @@ hive_name?, swarm_name?, matrix_accounts? }`. `matrix_accounts` is a
   [`docs/5-project/process/conventions.md#permissions`](../../5-project/process/conventions.md).
 - **Matrix MCP + extra servers** — `mcp__matrix__*` tools and
   per-agent extra MCP config. See
-  [`docs/2-handbook/tools/matrix.md`](../../2-handbook/tools/matrix.md).
+  [`docs/4-implementation/agent-tools/matrix.md`](../agent-tools/matrix.md).
 
 ## Waking the agent from inside the container
 
 The built-in producers (matrix, bash, forge) upsert a todo on the
 harness's in-agent socket (`HIVE_AGENT_SOCKET`, `UpsertTodo` — see
-[`docs/2-handbook/tools/bash.md` § Completion as a todo
-(loose-ends v2)](../../2-handbook/tools/bash.md#completion-as-a-todo-loose-ends-v2)
+[`docs/4-implementation/agent-tools/bash.md` § Completion as a todo
+(loose-ends v2)](../agent-tools/bash.md#completion-as-a-todo-loose-ends-v2)
 for the full upsert/signal/clear mechanism): a new or changed summary
 makes the harness signal its own turn loop, with no hive-c0re
 round-trip. An external MCP server (or any other in-container process)
@@ -205,7 +205,7 @@ The built-in list and the `--tools` value it resolves to live in
 `hive-sh4re` (the `Permission` enum itself is in `hive-types`), not in the
 harness, because the
 subagent daemon spawns its own `claude` and must resolve the same set —
-see [`docs/2-handbook/tools/subagent.md`](../../2-handbook/tools/subagent.md).
+see [`docs/4-implementation/agent-tools/subagent.md`](../agent-tools/subagent.md).
 
 - Allowed built-ins: `Edit`, `Glob`, `Grep`, `Read`, `Skill`, `Write`.
   `Skill` is what makes an installed plugin's `SKILL.md` invokable —
diff --git a/docs/5-project/process/conventions.md b/docs/5-project/process/conventions.md
index 0a5c736f..10d3e8ca 100644
--- a/docs/5-project/process/conventions.md
+++ b/docs/5-project/process/conventions.md
@@ -286,7 +286,7 @@ host access it has.
 | `messaging` | `send`, `recv`, `ack_until` |
 | `meta` | `get_agent_meta` (`set_status` is always-on, see below) |
 | `inbox` | `get_loose_ends`, `cancel_loose_end`, `remind` |
-| `execution` | the `bash` MCP server (`mcp__bash__run`/`status`/`kill`), rendered into the agent's MCP config only with it; a subagent gets Claude's own `Bash` instead. See `docs/2-handbook/tools/bash.md`. |
+| `execution` | the `bash` MCP server (`mcp__bash__run`/`status`/`kill`), rendered into the agent's MCP config only with it; a subagent gets Claude's own `Bash` instead. See `docs/4-implementation/agent-tools/bash.md`. |
 | `web_tools` | the Claude built-ins `WebFetch`/`WebSearch` |
 | `manage_root_agent` | every agent's state (rw) bind-mounted into the holder's container, plus `/meta` (ro) |
 | `logs` | the log store: `swarm-logs` queries. Checked by `swarm-logs-auth` at the gateway, not by a tool list. Off by default. |
diff --git a/docs/5-project/process/gotchas.md b/docs/5-project/process/gotchas.md
index 04118363..89521fdd 100644
--- a/docs/5-project/process/gotchas.md
+++ b/docs/5-project/process/gotchas.md
@@ -392,7 +392,7 @@ own self-consistent object store and is immune to the issue.
 
 ### `hive-forge`: prefer over raw curl pipelines
 
-Full CLI reference: [`docs/2-handbook/tools/forge.md`](../../2-handbook/tools/forge.md).
+Full CLI reference: [`docs/4-implementation/agent-tools/forge.md`](../../4-implementation/agent-tools/forge.md).
 Never use raw `curl` for forge access.
 
 ## GUI (weston/VNC)
diff --git a/docs/README.md b/docs/README.md
index 88af925e..88a2ac18 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -29,13 +29,13 @@ later work.
 - **What does the dashboard look like, and how to use it?** →
   [`2-handbook/web-ui/`](2-handbook/web-ui/README.md) — the operator-facing starting point,
   with [`dashboard`](2-handbook/web-ui/dashboard.md) and [`agent`](2-handbook/web-ui/agent.md).
-- **What tools does an agent (or the operator) have available?** →
-  [`2-handbook/tools/`](2-handbook/tools/README.md) — `hivectl` (yours) plus every agent's MCP
-  tool surface (bash, forge, lifecycle, matrix).
+- **What tools does the operator have?** →
+  [`2-handbook/tools/`](2-handbook/tools/README.md) — `hivectl` and `swarmctl`. The agents' own tool
+  surface is in [`4-implementation/agent-tools/`](4-implementation/agent-tools/README.md).
 - **What does `hivectl` do? Provisioning, gateway users, container
   shells?** → [`2-handbook/tools/hivectl.md`](2-handbook/tools/hivectl.md) (the curated guide);
   [`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
+  autogenerated flag reference. The `swarmctl` reference sits beside it in
   [`2-handbook/tools/`](2-handbook/tools/README.md).
 
 ### Agent lifecycle
@@ -59,11 +59,11 @@ later work.
 
 - **How do per-agent forge accounts work? What does `forge_notify` poll,
   and how does it format wake messages?** → [`2-handbook/integrations/forge.md`](2-handbook/integrations/forge.md)
-  (the swarm's Forgejo); [`2-handbook/tools/forge.md`](2-handbook/tools/forge.md) for the
+  (the swarm's Forgejo); [`4-implementation/agent-tools/forge.md`](4-implementation/agent-tools/forge.md) for the
   `hive-forge` CLI verbs agents actually call.
 - **How does the matrix-tuwunel container work? Multiple accounts per
   agent?** → [`2-handbook/integrations/matrix.md`](2-handbook/integrations/matrix.md) (the homeserver);
-  [`2-handbook/tools/matrix.md`](2-handbook/tools/matrix.md) for the MCP tool surface and
+  [`4-implementation/agent-tools/matrix.md`](4-implementation/agent-tools/matrix.md) for the MCP tool surface and
   `services.hyperhive.agent.matrixAccounts`.
 - **How to give an agent a GitHub account (`gh` + `git push`)? how's
   the PAT injected?** → [`2-handbook/integrations/github.md`](2-handbook/integrations/github.md)
@@ -101,6 +101,12 @@ Nothing of it sits in this tree.
 
 ## 4. Implementation
 
+### Agent tools
+
+- **What can an agent do inside its container? bash, subagent, forge, matrix, and the
+  `hive-forge`, `swarm-logs` and `swarm-metrics` CLI references?** →
+  [`4-implementation/agent-tools/`](4-implementation/agent-tools/README.md).
+
 ### Turn loop, scheduler, CI, observability
 
 - **How does claude get its prompt, and what tools does it have?** →
diff --git a/hive-forge/README.md b/hive-forge/README.md
index 1c3707a8..6dc9a6a8 100644
--- a/hive-forge/README.md
+++ b/hive-forge/README.md
@@ -32,4 +32,4 @@ here.
   own notification read-state (no local mirror to drift).
 - **`body.rs`** — shared `--body`/`--body-file`/stdin resolution.
 
-Full verb reference: `docs/2-handbook/tools/forge.md`.
+Full verb reference: `docs/4-implementation/agent-tools/forge.md`.
diff --git a/hive-forge/src/main.rs b/hive-forge/src/main.rs
index 1e0dcbf7..810c1d10 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/tools/forge-cli.md`.
+    // pipes into `docs/4-implementation/agent-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/hive-sh4re/src/permissions.rs b/hive-sh4re/src/permissions.rs
index 55a7f7e2..2f0c0551 100644
--- a/hive-sh4re/src/permissions.rs
+++ b/hive-sh4re/src/permissions.rs
@@ -73,7 +73,7 @@ pub fn builtin_tools_for(perms: &[Permission]) -> Vec<&'static str> {
 /// `Execution` already grants shell execution to the parent agent, via the
 /// out-of-process `bash` MCP server (`mcp__bash__run`/`status`/`kill` —
 /// see the variant's own doc comment). A subagent has no MCP server at all
-/// by default (`docs/2-handbook/tools/subagent.md`), so there is no `mcp__bash__*` for
+/// by default (`docs/4-implementation/agent-tools/subagent.md`), so there is no `mcp__bash__*` for
 /// it to inherit that permission through; it gets Claude's own `Bash`
 /// instead.
 ///
diff --git a/hive-subagent-mcp/src/role.rs b/hive-subagent-mcp/src/role.rs
index d6fff24a..96f800ab 100644
--- a/hive-subagent-mcp/src/role.rs
+++ b/hive-subagent-mcp/src/role.rs
@@ -9,7 +9,7 @@
 //! agent ships roles yet, so "named but missing" is the ordinary first-run
 //! state, and quietly spawning without the file would hand a subagent a
 //! prompt missing every clause the role was there to carry. See
-//! `docs/2-handbook/tools/subagent.md`.
+//! `docs/4-implementation/agent-tools/subagent.md`.
 
 use std::path::{Path, PathBuf};
 
diff --git a/hive-subagent-mcp/src/session.rs b/hive-subagent-mcp/src/session.rs
index ff3671f4..44a24699 100644
--- a/hive-subagent-mcp/src/session.rs
+++ b/hive-subagent-mcp/src/session.rs
@@ -27,7 +27,7 @@
 //! (`resume_target`), and waits for the driver's answer on the rest.** A
 //! turn that still misses is the call's own error, naming the directory
 //! searched (`classify_end`), within `RESUME_GRACE`. See
-//! `docs/2-handbook/tools/subagent.md`.
+//! `docs/4-implementation/agent-tools/subagent.md`.
 
 //! **One `start` can be more than one turn.** With a `goal` set, a turn that
 //! ends without a stop signal is followed by another re-prompting the
@@ -43,7 +43,7 @@
 //! exactly the incentive to claim it — the same failure class as a build
 //! report asserting "done, tests pass". Everything here treats it as a claim
 //! about the work, never as the work, and says so. See
-//! `docs/2-handbook/tools/subagent.md`.
+//! `docs/4-implementation/agent-tools/subagent.md`.
 
 //! **A subagent cannot say who it is.** Neither signal tool takes a session
 //! name. Each run is minted an unguessable token at spawn
@@ -61,7 +61,7 @@
 //! `State::finish_turn` remembers it against the name, which is what lets
 //! `status`, the end-of-turn todo and `continue`'s own reply all say the
 //! session was killed rather than let it read as finished. See
-//! `docs/2-handbook/tools/subagent.md`.
+//! `docs/4-implementation/agent-tools/subagent.md`.
 //!
 //! **No mid-turn compaction.** Building on `hive_claude::Claude::spawn` +
 //! `RunningClaude::wait` directly (not `InfiniteSession::run`) is what makes
@@ -1193,7 +1193,7 @@ fn subagent_otel_attrs(name: &str) -> String {
 /// ones, via [`hive_sh4re::permissions::subagent_builtin_tools_for`] over the
 /// agent's permissions ([`crate::swarm_models::permissions_now`]), which
 /// documents its one `Bash` exception. `--tools` does not filter `mcp__*`,
-/// so the signal tools are unnamed in it (`docs/2-handbook/tools/subagent.md`).
+/// so the signal tools are unnamed in it (`docs/4-implementation/agent-tools/subagent.md`).
 ///
 /// `signal_url` is what makes `goal_reached`/`need_help` callable at all: a
 /// subagent reaches them over the same streamable-http listener its parent
@@ -1273,7 +1273,7 @@ fn build_config(
 ///
 /// Unreadable task instructions, or (with a role) a harness dir that
 /// cannot be written. Both refuse the spawn rather than dropping either
-/// half — see `docs/2-handbook/tools/subagent.md`.
+/// half — see `docs/4-implementation/agent-tools/subagent.md`.
 fn system_prompt_and_trigger(
     name: &str,
     role: Option<&str>,
@@ -2339,7 +2339,7 @@ pub fn status(state: &State, name: &str, dir: Option<&str>) -> anyhow::Result<St
 /// Deliberately just the number now — the full "seconds means working,
 /// minutes means wedged, resets each turn" explanation used to repeat here
 /// on every single call. It already lives in the `status` tool description
-/// and in `docs/2-handbook/tools/subagent.md`'s "Telling working from wedged"
+/// and in `docs/4-implementation/agent-tools/subagent.md`'s "Telling working from wedged"
 /// section, so restating it in a line meant to be skimmed, possibly several
 /// times a minute, was pure repetition.
 ///
diff --git a/nix/checks.nix b/nix/checks.nix
index e07bab96..b9e8d482 100644
--- a/nix/checks.nix
+++ b/nix/checks.nix
@@ -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/tools/swarm-logs-cli.md} generated.md; then
+        if ! diff -u ${../docs/4-implementation/agent-tools/swarm-logs-cli.md} generated.md; then
           echo "" >&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
+          echo "ERROR: docs/4-implementation/agent-tools/swarm-logs-cli.md is out of date — regenerate it:" >&2
+          echo "  nix build .#swarm-logs && ./result/bin/swarm-logs markdown-docs > docs/4-implementation/agent-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/tools/swarm-metrics-cli.md} generated.md; then
+        if ! diff -u ${../docs/4-implementation/agent-tools/swarm-metrics-cli.md} generated.md; then
           echo "" >&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
+          echo "ERROR: docs/4-implementation/agent-tools/swarm-metrics-cli.md is out of date — regenerate it:" >&2
+          echo "  nix build .#swarm-metrics && ./result/bin/swarm-metrics markdown-docs > docs/4-implementation/agent-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/tools/forge-cli.md} generated.md; then
+        if ! diff -u ${../docs/4-implementation/agent-tools/forge-cli.md} generated.md; then
           echo "" >&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
+          echo "ERROR: docs/4-implementation/agent-tools/forge-cli.md is out of date — regenerate it:" >&2
+          echo "  nix build .#hive-forge && ./result/bin/hive-forge markdown-docs > docs/4-implementation/agent-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 5e81625d..ff616804 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/tools/swarm-logs-cli.md`).
+    /// Print this CLI's reference as markdown (source of `docs/4-implementation/agent-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 2da47b32..dd46ca31 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/tools/swarm-metrics-cli.md`).
+    /// Print this CLI's reference as markdown (source of `docs/4-implementation/agent-tools/swarm-metrics-cli.md`).
     #[command(hide = true)]
     MarkdownDocs,
 }