diff --git a/CLAUDE.md b/CLAUDE.md
index 2bd17f51..35ff3ebc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -363,7 +363,7 @@ docs/
                        inbox, live view, per-agent endpoints, stats)
   turn-loop.md         claude invocation, wake prompt, MCP tool surface
   tools/               per-group tool docs (bash.md, lifecycle.md,
-                         scheduling.md, matrix.md, forge.md)
+                         scheduling.md, matrix.md)
   approvals.md         approval flow, manager policy, helper events
   persistence.md       sqlite dbs, retention, state dir layout
   terminal-rendering.md  per-agent terminal row taxonomy (as built)
@@ -417,9 +417,6 @@ read them à la carte.
 - **"How do per-agent forge accounts work? What does forge_notify
   poll + how does it format wake messages?"** →
   [`docs/forge.md`](docs/forge.md).
-- **"What verbs does `hive-forge` support? How do I post a comment,
-  upload an attachment, manage subscriptions?"** →
-  [`docs/tools/forge.md`](docs/tools/forge.md).
 - **"How does the matrix-tuwunel container work? What about
   fluffychat-web and per-agent matrix accounts?"** →
   [`docs/matrix.md`](docs/matrix.md).
diff --git a/docs/gotchas.md b/docs/gotchas.md
index bf483e2a..32facc46 100644
--- a/docs/gotchas.md
+++ b/docs/gotchas.md
@@ -195,8 +195,37 @@ instead of `meta#nixosConfigurations.argus.config…`. The fix:
 
 ## `hive-forge`: prefer over raw curl pipelines
 
-Full CLI reference: [`docs/tools/forge.md`](tools/forge.md).
-Never use raw `curl` for forge access.
+Every agent container has `hive-forge` in PATH (installed via
+`harness-base.nix`; lives in `/hive-forge` as a proper Rust binary).
+Use it instead of ad-hoc curl pipelines:
+
+```bash
+hive-forge view 42                          # title + body + comments
+hive-forge comments 42                      # list all comments (human-readable)
+hive-forge --json comments 42               # same as above, JSON array (global flag)
+hive-forge comment 42 --body "..."          # post comment (inline body)
+hive-forge comment 42 --body-file - <<EOF   # ...or pipe a HEREDOC
+multi-line body
+EOF
+hive-forge assign 42 damocles
+hive-forge close 42
+hive-forge labels 42 add feature
+hive-forge pr 42                            # PR metadata as JSON
+hive-forge pr-create --title "..." --head my-branch --push    # also `git push forge my-branch`, suppressing the post-push "Create a pull request" hint
+hive-forge diff 42                          # unified diff (lockfile hunks collapsed by default)
+hive-forge diff 42 --full                   # include unfiltered lockfile hunks
+hive-forge branches deployed/               # filter branches by pattern
+hive-forge -r other-org/other-repo pr 7     # target a different repo
+hive-forge lint unassigned                  # open issues/PRs with no assignee
+hive-forge lint no-reviewer --reviewer argus  # PRs missing a reviewer comment from argus
+hive-forge lint stale-branches --days 14    # branches with no recent activity
+hive-forge lint assignments                 # per-assignee open item count
+```
+
+`hive-forge <verb> --help` prints the full signature for any verb.
+Credentials come from `$HYPERHIVE_STATE_DIR/forge-token`; default
+repo from `$HIVE_FORGE_REPO`, overridden per-invocation by the
+global `-r/--repo` flag.
 
 ## Containerized nix-daemon needs `sandbox-fallback = true`
 
diff --git a/docs/tools/forge.md b/docs/tools/forge.md
deleted file mode 100644
index c7112863..00000000
--- a/docs/tools/forge.md
+++ /dev/null
@@ -1,64 +0,0 @@
-# hive-forge CLI
-
-`hive-forge` is the Forgejo API wrapper available in every agent
-container (installed via `harness-base.nix`; lives in `/hive-forge`
-as a proper Rust binary). Use it instead of ad-hoc curl pipelines.
-
-## Credentials and repo defaults
-
-- Credentials: `$HYPERHIVE_STATE_DIR/forge-token`
-- Default repo: `$HIVE_FORGE_REPO`
-- Per-invocation override: global `-r/--repo` flag
-
-## Verbs
-
-```bash
-hive-forge view 42                          # title + body + comments
-hive-forge comments 42                      # list all comments (human-readable)
-hive-forge --json comments 42               # same as above, JSON array (global flag)
-hive-forge comment 42 --body "..."          # post comment (inline body)
-hive-forge comment 42 --body-file - <<EOF   # ...or pipe a HEREDOC
-multi-line body
-EOF
-hive-forge comment-show 18042               # fetch one comment by id
-hive-forge comment-edit 18042 --body "..."  # edit a comment
-hive-forge assign 42 damocles
-hive-forge close 42
-hive-forge labels 42 add feature
-hive-forge issue-create --title "..." --body "..."
-hive-forge issue-edit 42 --title "new title"
-hive-forge pr 42                            # PR metadata as JSON
-hive-forge pr-create --title "..." --head my-branch --push    # also `git push forge my-branch`
-hive-forge pr-reviews 42                    # list reviews on a PR
-hive-forge diff 42                          # unified diff (lockfile hunks collapsed by default)
-hive-forge diff 42 --full                   # include unfiltered lockfile hunks
-hive-forge list                             # open issues/PRs
-hive-forge milestone                        # list milestones
-hive-forge branches deployed/               # filter branches by pattern
-hive-forge tree-sha main                    # git tree SHA for a ref
-hive-forge -r other-org/other-repo pr 7     # target a different repo
-hive-forge lint unassigned                  # open issues/PRs with no assignee
-hive-forge lint no-reviewer --reviewer argus  # PRs missing a reviewer comment from argus
-hive-forge lint stale-branches --days 14    # branches with no recent activity
-hive-forge lint assignments                 # per-assignee open item count
-hive-forge timeline 42                      # audit trail: closes, label changes, assignments, commit refs
-hive-forge attach-issue 42 /path/to/file    # upload a file attachment to an issue; prints download URL
-hive-forge attach-comment 18042 /path/to/file  # upload a file attachment to a comment; prints download URL
-hive-forge attachment-get <uuid>            # download an attachment; prints resolved path to stdout
-hive-forge subscription --watch             # subscribe to repo notifications
-hive-forge subscription --unwatch           # unsubscribe
-```
-
-`hive-forge <verb> --help` prints the full signature for any verb.
-
-## Notes
-
-- `comment --body "..."` with backticks in the body: always use
-  `--body-file -` with a HEREDOC to avoid shell escaping issues.
-- `pr-create --push` also runs `git push forge <head>` and suppresses
-  the post-push "Create a pull request" hint (we print the canonical
-  URL ourselves).
-- `attachment-get` saves to `/tmp/forge-attachment-{uuid}` by default
-  and prints the resolved path. Pass `-o -` to stream to stdout.
-- Do NOT use raw `curl` for forge access -- the CLI handles auth,
-  error checking, and output formatting.