nix: comments state current behaviour, not history

Rewrite comments and option descriptions under nix/ that narrate how the
code got here ("used to", "new name", "sat at the TOP", "no longer",
renamed/moved narration, attributions) to say what the code does now and
why. Comments and description strings only; no logic changes.

Files in open PR #4970's diff are left alone. Refs #3902

nix/agent-modules/default.nix

@@ -79,10 +79,10 @@ in
     #
     # Both spellings, for the same reason ../host-modules/deploy.nix lists both
     # of `swarm|deploy.matrix.registrationTokenFile`: an existing agent.nix may
-    # carry either the pre-rename `hyperhive.*` path or the current one, and only
-    # the one it actually carries will fire. The rename shim that used to bridge
-    # them is gone from ./renamed-options.nix — a rename pointing at an
-    # undeclared option breaks evaluation for everyone, removed or not.
+    # carry either the `hyperhive.*` path or the `services.hyperhive.agent.*`
+    # one, and only the one it actually carries will fire. Neither is an entry
+    # in ./renamed-options.nix — a rename pointing at an undeclared option
+    # breaks evaluation for everyone, removed or not.
     (lib.mkRemovedOptionModule [ "hyperhive" "matrix" "enable" ] matrixEnableRemoved)
     (lib.mkRemovedOptionModule [ "services" "hyperhive" "agent" "matrix" "enable" ] matrixEnableRemoved)
   ];

nix/agent-modules/forge.nix

@@ -10,8 +10,8 @@
 let
   userName = config.services.hyperhive.agent.user.name;
   # The token the agent fetched from the swarm secret store
-  # (./forge-token.nix), then the state-dir file the hive used to write,
-  # which is still the only copy for an agent without a store identity.
+  # (./forge-token.nix), then the state-dir file the hive writes, which is
+  # the only copy for an agent without a store identity.
   # Both are PATHS; each reader below takes the first that holds a token.
   fetchedTokenFile = config.services.hyperhive.agent.forge.tokenFile;
   stateTokenFile = "/agents/${userName}/state/forge-token";

nix/agent-modules/matrix.nix

@@ -37,7 +37,7 @@ let
   # per-agent "does this agent have a homeserver to reach" fact. So an agent the
   # hive handed no homeserver URL, whose operator declared no external account
   # either, has an empty set here and gets none of the units — the case the
-  # deleted `matrix.enable = false` used to express.
+  # "matrix off" case.
   #
   # No cycle: `matrixAccounts`'s own definition reads `matrix.url`, never this
   # binding, so the `mkIf`s below may read the merged option value freely.
@@ -75,9 +75,9 @@ in
       then talks to the wrong machine. An absent integration, never a
       misdirected one.
 
-      `null` is also this agent's **matrix off switch**, and the
-      replacement for the `services.hyperhive.agent.matrix.enable`
-      boolean that used to exist: the hive-internal `main` account in
+      `null` is also this agent's **matrix off switch** — there is no
+      separate `services.hyperhive.agent.matrix.enable` boolean: the
+      hive-internal `main` account in
       `services.hyperhive.agent.matrixAccounts` is declared from this
       URL, so `null` leaves that set empty and the whole integration —
       daemon unit, path watcher, injected MCP entry — is not generated
@@ -214,12 +214,11 @@ in
 
   config = {
     assertions = [
-      # The "extras require `matrix.enable`" assertion that used to head this
-      # list is gone with the option: a non-empty account set is now what
-      # enables matrix, so the condition it checked has become the definition
-      # of the thing it was checking. An operator declaring only an external
-      # account, with no hive homeserver, is a config this module now renders
-      # rather than rejects — matrix on, no `main`.
+      # There is no "extras require `matrix.enable`" assertion: a non-empty
+      # account set is what enables matrix, so that condition is the
+      # definition of the thing it would check. An operator declaring only an
+      # external account, with no hive homeserver, gets a rendered config —
+      # matrix on, no `main`.
       #
       # `main` is not a forbidden key --- this module declares it
       # itself (see the `matrixAccounts.main` definition below), so the

nix/agent-modules/renamed-options.nix

@@ -1,10 +1,9 @@
-# Deprecation shims for the agent tier's old option namespace.
+# Deprecation shims for the agent tier's top-level `hyperhive.*` spelling.
 #
-# Every per-agent option used to live at the top level, `hyperhive.<name>`,
-# while the host tier has always been under `services.hyperhive.*`. The agent
-# tier moved to `services.hyperhive.agent.<name>`; these entries keep an
-# existing `agent.nix` evaluating (with a deprecation warning) against the old
-# spelling.
+# Per-agent options live at `services.hyperhive.agent.<name>`, beside the host
+# tier's `services.hyperhive.*`. These entries keep an `agent.nix` that still
+# uses the top-level `hyperhive.<name>` spelling evaluating, with a
+# deprecation warning.
 #
 # ⚠️ One entry per LEAF, not per namespace. A single entry for a parent path
 # only covers its children when the parent is a submodule-typed option; every
@@ -119,9 +118,9 @@
       [ "hyperhive" "logs" "queryUrl" ]
       [ "services" "hyperhive" "agent" "logs" "queryUrl" ]
     )
-    # `matrix.enable` is deliberately absent from this list: the option it
-    # renamed to no longer exists, and a rename pointing at an undeclared
-    # option breaks evaluation for everyone. Both of its spellings are
+    # `matrix.enable` is deliberately absent from this list: it has no
+    # replacement option, and a rename pointing at an undeclared option
+    # breaks evaluation for everyone. Both of its spellings are
     # `mkRemovedOptionModule` in ./default.nix instead.
     (lib.mkRenamedOptionModule
       [ "hyperhive" "matrix" "url" ]