diff --git a/nix/host-modules/hive-gateway/vhosts.nix b/nix/host-modules/hive-gateway/vhosts.nix
index ee855739..e54dddda 100644
--- a/nix/host-modules/hive-gateway/vhosts.nix
+++ b/nix/host-modules/hive-gateway/vhosts.nix
@@ -1,9 +1,17 @@
-# nginx virtual-host tree for the gateway: the `_` default server
-# (dashboard, per-agent routing, matrix discovery), the forge, matrix
-# and authelia sub-domain vhosts, and the Accept-header SPA map for the
-# matrix GUI. Pure function — called from ./default.nix with the
-# outer-scope config values as arguments; returns
-# `{ virtualHosts }`.
+# nginx virtual-host tree for the **hive's own** gateway surface: the `_`
+# default server, which answers unmatched `Host` with a bare 444, and the
+# vhost named for the hive domain, which carries the dashboard, per-agent
+# routing, matrix discovery, the swagger UI and the legacy
+# `<hive>/matrix/*` redirect.
+#
+# Scope: a swarm service declares its own vhost and dns name in its own
+# module, built from the kit this file also consumes
+# (`services.hyperhive.gateway.lib`, ./vhost-lib.nix). That keeps a
+# service's gateway surface next to the service, and keeps this file to
+# the surface the hive itself serves.
+#
+# Pure function — called from ./default.nix with the outer-scope config
+# values as arguments; returns `{ virtualHosts }`.
 {
   lib,
   cfg, # services.hyperhive.gateway