docs(#3162): point the serverName pin section at the new rebuild warning

argus's optional note. Nothing in the doc was inaccurate, but an operator
who sees the activation-time warning has no thread back to the page that
explains why pinning matters -- and this section is the explanation.

States the one property they need from it: it never fails the rebuild, so
acting on it is theirs to do before the ids are minted.

docs/matrix.md

@@ -67,6 +67,12 @@ services.hyperhive.swarm.matrix = {
 };
 ```
 
+A rebuild on a host that already has a homeserver prints a
+`hive-matrix: WARNING — … serverName is unset` line when this is missing,
+naming the value it is about to default to. That warning is why this
+section exists; it never fails the rebuild, so it is on you to act on it
+before the ids are minted.
+
 ## Default-closed firewall
 
 `openFirewall` defaults to `false` (secure-by-default): the host

nix/host-modules/hive-matrix.nix

@@ -758,6 +758,51 @@ in
     # would hand tuwunel an empty file on first boot and break every
     # registration until restart. Idempotent;
     # docs/matrix.md::Provisioning flow.
+    # Tell an operator whose homeserver already exists that `serverName` is
+    # unpinned, at the one moment they are looking: the rebuild.
+    #
+    # ⚠️ An activation script and NOT `warnings`, which is where this
+    # obviously belongs and does not work. The condition needs the host
+    # filesystem — does a homeserver already exist here? — and
+    # `nixos-rebuild switch --flake` evaluates PURELY, where
+    # `builtins.pathExists "/var/lib/…"` answers **false** rather than
+    # throwing. A `warnings` entry gated on it would evaluate, deploy, and
+    # print nothing, on every real deployment. Same shape as an option whose
+    # consumer is disabled: renders perfectly, does nothing.
+    #
+    # Only rendered when `serverName` is null, so a hive that pinned it
+    # cannot be nagged — the script does not exist there rather than
+    # existing and choosing to stay quiet. A guard that cries wolf at a
+    # correctly-configured deployment is worse than no guard, because the
+    # next real one is read as noise too.
+    #
+    # Never fails. This warns about a choice that cannot be undone; refusing
+    # the activation would break the rebuild of a hive that had already made
+    # that choice deliberately, which is the opposite of helping.
+    system.activationScripts.hive-matrix-servername-pin = lib.mkIf (cfg.serverName == null) (
+      lib.stringAfter [ "var" ] ''
+        # The homeserver's own database, asked of the container's evaluated
+        # config rather than hardcoded: a guessed path resolves cleanly and
+        # silently never matches, which is exactly the failure this guard
+        # exists to avoid one level up.
+        dbDir=${
+          lib.escapeShellArg (
+            # Same host-side container-root prefix this module already writes
+            # by hand for the SSO secret copy above — not a second convention.
+            "/var/lib/nixos-containers/hive-matrix"
+            + config.containers.hive-matrix.config.services.matrix-tuwunel.settings.global.database_path
+          )
+        }
+        if [ -d "$dbDir" ]; then
+          echo "hive-matrix: WARNING — services.hyperhive.swarm.matrix.serverName is unset, and this host already has a homeserver at $dbDir."
+          echo "hive-matrix: it is defaulting to ${effectiveServerName}, which is baked into every NEW user and room id."
+          echo "hive-matrix: if ids here were minted under a different name, existing accounts and rooms are stranded — reverting the config does NOT undo it."
+          echo "hive-matrix: pin whichever name this homeserver already uses, e.g.:"
+          echo "hive-matrix:   services.hyperhive.swarm.matrix.serverName = \"''${HIVE_MATRIX_EXISTING_SERVER_NAME:-<the name already in use>}\";"
+        fi
+      ''
+    );
+
     system.activationScripts.hive-matrix-register-token = lib.stringAfter [ "var" ] ''
       tokenFile=${lib.escapeShellArg (toString cfg.registrationTokenFile)}
       if [ ! -s "$tokenFile" ]; then