diff --git a/docs/tools/forge.md b/docs/tools/forge.md
index f0029e1e..cbd4d254 100644
--- a/docs/tools/forge.md
+++ b/docs/tools/forge.md
@@ -31,9 +31,18 @@ refuses an issue number, which the old generic `close` couldn't). Run
 list (show/create/edit/status/merge/reviews/commits/diff/view/comment/
 comments/close/reopen/labels/assign/dependency/reaction/timeline as applicable).
 
-The flat forms below (`close 42`, `pr-create …`, `pr-status …`, …) still work
-as **hidden back-compat aliases** during the transition and are dropped from
-`--help`; prefer the namespaced form. They'll be removed in a later sweep.
+The flat forms are two different groups, and `--help` hides both, so the
+difference cannot be seen from the CLI and is stated here instead:
+
+- **Renamed — these no longer run.** `issue-create` `issue-edit` `pr-create`
+  `pr-status` `pr-merge` `pr-reviews` `pr-commits` `pr-assign-reviewer` `diff`
+  parse only far enough to print the namespaced form that replaced them, and
+  are removed outright in a later release.
+- **Kind-agnostic — these stay.** `view` `comment` `comments` `close` `assign`
+  `labels` `timeline` are the only way to act on a number without already
+  knowing whether it is an issue or a PR, which no namespaced form offers.
+  Hidden, but supported; prefer `issue <verb>` / `pr <verb>` when the kind is
+  known, since those validate it.
 
 ```bash
 hive-forge pr close 42                      # close a PR (kind-validated)
diff --git a/hive-forge/src/main.rs b/hive-forge/src/main.rs
index 7f59afa5..ff5e0aa6 100644
--- a/hive-forge/src/main.rs
+++ b/hive-forge/src/main.rs
@@ -71,10 +71,15 @@ enum Verb {
     //   no `issue <verb>` form, so a caller holding just a number can be
     //   sent somewhere unambiguous.
     // - **Kind-agnostic** (`view`, `comment`, `comments`, `close`,
-    //   `assign`, `labels`, `timeline`, …) still work. Each exists as both
-    //   `issue <verb>` and `pr <verb>`, so there is no single replacement
-    //   to send a caller to when all they hold is a number — refusing
-    //   these would remove a capability rather than rename one.
+    //   `assign`, `labels`, `timeline`) **stay** — hidden, not deprecated.
+    //   Each exists as both `issue <verb>` and `pr <verb>`, so there is no
+    //   single replacement to send a caller to when all they hold is a
+    //   number: refusing these would remove a capability rather than
+    //   rename one.
+    //
+    // `credential-helper` is hidden for a third reason and is in neither
+    // group — git invokes it, no human does. A sweep that reads
+    // `hide = true` as "deprecated" would take out checkout auth.
     /// Dump title + body + all comments for an issue or PR.
     #[command(hide = true)]
     View(verbs::view::Args),