diff --git a/nix/host-modules/swarm-controller.nix b/nix/host-modules/swarm-controller.nix
index c249d3ad..fcc5fbfd 100644
--- a/nix/host-modules/swarm-controller.nix
+++ b/nix/host-modules/swarm-controller.nix
@@ -95,6 +95,20 @@ let
   # when this is set, and a hook whose `target_url` nothing answers is worse
   # than no hook at all — forgejo keeps the registration, marks every
   # delivery failed, and the hook still reads as configured.
+  #
+  # ⚠️ Correct ONLY while the vhost and this daemon share a host, and they do
+  # by construction: the UI's `/api/` location proxies
+  # `http://unix:<socketPath>`, a path that resolves nowhere else, and this
+  # daemon binds no TCP address at all (see the header). `swarm.ui.enable`
+  # therefore is not a guess about *some* host publishing the endpoint — it is
+  # the flag that declares that vhost, on the box holding the socket.
+  #
+  # ⇒ The day this daemon grows a TCP listener so another host can front it,
+  # THIS LINE SILENTLY STOPS BEING RIGHT: the env goes unset on the controller
+  # host, registration quietly does not happen, and nothing errors. That is
+  # the moment to add an explicit `publicUrl` option — not before, because
+  # until then there is exactly one derivable answer and an option would only
+  # be a second place to get it wrong.
   webhookEnv = lib.optionalAttrs uiCfg.enable {
     SWARM_CONTROLLER_PUBLIC_URL = "https://${uiCfg.domain}";
   };