diff --git a/nix/host-modules/swarm-bao.nix b/nix/host-modules/swarm-bao.nix
index 37802f39..54e182b8 100644
--- a/nix/host-modules/swarm-bao.nix
+++ b/nix/host-modules/swarm-bao.nix
@@ -23,8 +23,8 @@
 # distribute: reach the store to get the CA material, need a cert from that CA
 # to reach the store. Service↔store mTLS is therefore its own trust domain,
 # separate from the gateway's HTTPS certificates and from both CAs in this
-# tree. The cert paths are inputs with no defaults and nothing here fills them
-# in; whatever comes to mint that identity is what they will point at.
+# tree. The cert paths are inputs this module declares no default for and never
+# fills in; a glue module mints that identity and points them at it.
 {
   pkgs,
   lib,
@@ -199,10 +199,13 @@ in
         Certificate the store serves, covering
         {option}`services.hyperhive.swarm.bao.domain`.
 
-        No default, and this module deliberately does not know what could
-        provide one — for the same reason
-        {option}`services.hyperhive.deploy.bao.clientCaFile` doesn't. The
-        deployment names the file; the store never reaches for an authority.
+        This module declares no default and deliberately does not know
+        what could provide one — for the same reason
+        {option}`services.hyperhive.deploy.bao.clientCaFile` doesn't: the
+        store never reaches for an authority.
+
+        On a hive that runs the store, a glue module supplies a path as a
+        `mkDefault`, so naming your own here wins over it.
 
         A path, never a value.
       '';
@@ -226,11 +229,14 @@ in
       description = ''
         Authority the store validates hive **client** certificates against.
 
-        Deliberately has no default, and does not reach for the hive CA:
-        the hive CA is a future *consumer* of the store, so a store that
-        authenticated against it could not come up before the thing it
-        issues. It is a value someone points at — the swarm root for a
-        swarm that runs one, an operator's own CA otherwise.
+        This module declares no default and does not reach for the hive
+        CA: the hive CA is a future *consumer* of the store, so a store
+        that authenticated against it could not come up before the thing
+        it issues.
+
+        On a hive that runs the store, a glue module supplies the CA it
+        minted for exactly this, as a `mkDefault`. Point this at something
+        else — the swarm root, an operator's own CA — and yours wins.
 
         `null` leaves client-certificate verification off, which is only
         appropriate where something else authenticates the connection.
@@ -328,10 +334,14 @@ in
             The swarm secret store has no server certificate: set both
             services.hyperhive.deploy.bao.serverCertFile and .serverKeyFile.
 
-            Nothing defaults them, on purpose — a store must not take its
-            identity from an authority it will itself distribute, and
-            service-to-store mTLS is a separate trust domain from the
+            This module defaults neither, on purpose — a store must not
+            take its identity from an authority it will itself distribute,
+            and service-to-store mTLS is a separate trust domain from the
             gateway's certificates and from either CA in this tree.
+
+            A hive that runs the store normally gets both from a glue
+            module, so reaching this means that glue is absent or
+            something set these back to null.
           '';
         }
       ];