diff --git a/docs/swarm/builder.md b/docs/swarm/builder.md
index 506657f3..ab7fff0b 100644
--- a/docs/swarm/builder.md
+++ b/docs/swarm/builder.md
@@ -150,10 +150,22 @@ pins the agent's current config (see
 [Config changes](../agent-lifecycle/config-changes.md#the-swarms-meta-flake)). A render
 equal to the committed `flake.nix` sends no lock.
 
-When a commit moves the pin from one rev to another, the controller sends a
-deploy to every agent a hive places, so they rebuild on the new hyperhive. A
-restart that moves nothing deploys nothing, and the first commit deploys
-nothing.
+The controller sends a deploy to every agent a hive places whenever the pin in
+`internal/meta` differs from the pin it last sent, so they rebuild on the new
+hyperhive. It keeps that pin as the key `pin` in the `meta-fanout` KV bucket,
+which only the controller reads or writes, and a `RecordFanout` job writes the
+key after every deploy of the fan-out succeeds. The check runs after each update
+and once when the controller starts.
+
+- The first commit sends a deploy, because the key holds no pin yet.
+- A controller that starts with no key, as after the upgrade that added it,
+  sends one round. A deploy is idempotent per pin, so the round is harmless.
+- A controller that dies after the commit, or a deploy that fails, leaves the
+  key behind. The next update or start sends the deploys again.
+- A restart that finds the key equal to the pin sends nothing.
+- When the bucket won't open, or its key won't read, the controller logs a
+  warning and sends deploys only when its own update moved the pin. That case
+  writes no key.
 
 ## Credentials
 
diff --git a/swarm-controller/README.md b/swarm-controller/README.md
index 93cd8ddd..10a8ec55 100644
--- a/swarm-controller/README.md
+++ b/swarm-controller/README.md
@@ -102,6 +102,10 @@ The swarm's control plane. The swarm UI and `swarmctl` are its clients.
   (`GET /api/builder/runs`, `GET /api/builder/runs/{id}`, the link on each
   `swarm-builder` commit status) →
   [`docs/swarm/builder.md`](../docs/swarm/builder.md#build-records).
+- **Meta fan-out** — the hyperhive pin of `internal/meta` that this daemon last
+  sent the hives a deploy for, one key in the `meta-fanout` KV bucket, which
+  this daemon alone reads and writes →
+  [`docs/swarm/builder.md`](../docs/swarm/builder.md).
 - **Relays** — each agent's terminal and turn-state header as SSE, agent
   icons, the cross-repo issue report, and the UI's quick links.
 - **Alerts** — the swarm Grafana's current alerts (`GET /api/alerts`), read