diff --git a/hive-c0re/src/forge/mod.rs b/hive-c0re/src/forge/mod.rs
index 5d5bb182..4da942b1 100644
--- a/hive-c0re/src/forge/mod.rs
+++ b/hive-c0re/src/forge/mod.rs
@@ -483,8 +483,7 @@ pub async fn ensure_all() {
 /// existing hooks first and skips creation when one is already targeting the
 /// correct URL.
 ///
-/// `hive_domain` is the public domain name of the hive (e.g.
-/// `pr1ma.darkest.space`); the webhook URL is
+/// `hive_domain` is the public domain name of the hive; the webhook URL is
 /// `https://<hive_domain>/webhook/config-pr` (routed through the gateway,
 /// avoiding the Forgejo SSRF guard that blocks loopback delivery).
 ///
@@ -495,8 +494,9 @@ pub async fn ensure_all() {
 /// An org-level hook covers every repo in `agent-configs` automatically,
 /// so no per-repo setup is needed as new agents are provisioned.
 ///
-/// Called at startup alongside `knowledge::ensure_webhook`. No-op when the
-/// core token is absent (forge not yet provisioned).
+/// Called at startup beside `knowledge::remove_webhook`, its opposite: that
+/// repo's one hook is the controller's now, this one has not moved yet. No-op
+/// when the core token is absent (forge not yet provisioned).
 ///
 /// # Errors
 ///
diff --git a/swarm-controller/src/webhook.rs b/swarm-controller/src/webhook.rs
index 5ad47f73..6a2435b6 100644
--- a/swarm-controller/src/webhook.rs
+++ b/swarm-controller/src/webhook.rs
@@ -170,13 +170,14 @@ pub(super) enum DeliveryKind {
 /// The route prefix a registered `target_url` must point at.
 ///
 /// ⚠️ Deliberately **not** `/webhook/knowledge` or `/webhook/config-pr`, the
-/// paths the per-hive receivers use. Both hive-side registrars delete any
-/// hook whose URL ends with *their* path but has a different base — see
-/// `hive-c0re`'s `forge::ensure_config_pr_webhook` and
-/// `workers::knowledge::ensure_webhook`. A swarm-level hook under those
-/// paths would therefore be deleted by every hive on every boot, and the
-/// symptom is a hook that silently stops existing. `webhook_urls_survive_the_hive_side_reapers`
-/// pins that.
+/// paths the per-hive receivers use. A hive-side registrar deletes any hook
+/// whose URL ends with *its* path but has a different base — see
+/// `hive-c0re`'s `forge::ensure_config_pr_webhook`. A swarm-level hook under
+/// such a path would therefore be deleted by every hive on every boot, and
+/// the symptom is a hook that silently stops existing.
+/// `webhook_urls_survive_the_hive_side_reapers` pins that, and its own doc
+/// records why `/webhook/knowledge` stays in the check even though the
+/// knowledge registrar no longer reaps.
 const ROUTE_PREFIX: &str = "/webhook/forge/";
 
 impl DeliveryKind {
@@ -632,17 +633,22 @@ mod tests {
         }
     }
 
-    /// A cross-daemon invariant with nothing else to enforce it: both
-    /// per-hive registrars in `hive-c0re` **delete** hooks whose URL ends
-    /// with their own path but carries a different base — see
-    /// `forge::ensure_config_pr_webhook` and `knowledge::ensure_webhook`.
+    /// A cross-daemon invariant with nothing else to enforce it: a per-hive
+    /// registrar in `hive-c0re` **deletes** hooks whose URL ends with its
+    /// own path but carries a different base. A controller URL matching such
+    /// a suffix would be deleted by every hive on every boot — the swarm hook
+    /// would simply cease to exist, with the cause in a different daemon's
+    /// startup sweep. Serving these under `/webhook/forge/` is what avoids
+    /// it, and this is the only place that says so in a form that fails.
     ///
-    /// While the swarm-level hooks live alongside the per-hive ones, a
-    /// controller URL matching either suffix would be deleted by every hive
-    /// on every boot: the swarm hook would simply cease to exist, with the
-    /// cause in a different daemon's startup sweep. Serving these under
-    /// `/webhook/forge/` is what avoids it, and this is the only place that
-    /// says so in a form that fails.
+    /// `forge::ensure_config_pr_webhook` still reaps that way. The knowledge
+    /// registrar no longer does — it was replaced by a removal that matches
+    /// the full URL, so it cannot touch another hive's hook. **The
+    /// `/webhook/knowledge` arm is kept anyway**, because the hazard is not
+    /// this repository's current code: it is whatever is *deployed*, and a
+    /// hive still running the previous version reaps by suffix until it is
+    /// upgraded. Drop that arm once no such hive can exist, not when the
+    /// source stops mentioning it.
     #[test]
     fn webhook_urls_survive_the_hive_side_reapers() {
         for suffix in ["/webhook/knowledge", "/webhook/config-pr"] {