diff --git a/swarm-controller/src/webhook.rs b/swarm-controller/src/webhook.rs
index 03efd5a5..5af18ad1 100644
--- a/swarm-controller/src/webhook.rs
+++ b/swarm-controller/src/webhook.rs
@@ -6,22 +6,26 @@
 //! deliveries. One owner is the only non-racing shape, and the only
 //! swarm-wide thing in the deployment is this daemon.
 //!
-//! **This relays; it does not interpret.** The payload stays opaque bytes,
-//! keyed by a [`DeliveryKind`] from the URL path. The hives already know
-//! what a delivery *means* — which repo is the knowledge repo, which config
-//! PR action queues an approval — so parsing it here would be a second place
-//! deciding that, and the two would drift.
+//! **Receipt only, for now — the interpretation lands here next.** The
+//! payload is currently opaque bytes keyed by a [`DeliveryKind`] from the URL
+//! path, because nothing consumes it yet.
 //!
-//! **The HMAC code is not shared with `hive-c0re` because c0re's copy is
-//! leaving, not staying.** Once registration moves here, hives stop
-//! registering *and* receiving, and c0re's routes and secret go with it. A
-//! shared crate is right when a second consumer *arrives*; here it is
-//! departing. The two verifiers meanwhile check different hooks with
-//! different secrets and never need to agree.
+//! ⚠️ This used to say *"this relays; it does not interpret"*, and that is no
+//! longer the direction: this daemon is to **parse a delivery and emit a
+//! semantic message** — *knowledge repo changed*, *deploy agent X at rev Y* —
+//! addressed to whoever needs it, rather than forwarding forge bytes for each
+//! hive to re-derive. The earlier reasoning ("parsing here would be a second
+//! place deciding what a delivery means") counted this daemon as a *second*
+//! interpreter while assuming the hives stay interpreters. They do not: the
+//! parsing **moves** rather than duplicating, so one place decides.
+//!
+//! The HMAC code is deliberately **not** shared with `hive-c0re`: that copy
+//! is leaving, not staying, and a shared crate is right only when a second
+//! consumer *arrives*. Same arriving-or-leaving question as the paragraph
+//! above, asked about code instead of about meaning.
 //!
 //! **These hooks are registered ALONGSIDE the per-hive ones** — see
-//! [`crate::forge::Client::ensure_swarm_webhooks`], which carries why, and
-//! why moving them cannot come before fan-out.
+//! [`crate::forge::Client::ensure_swarm_webhooks`].
 
 use anyhow::{Context as _, Result};
 use axum::{