diff --git a/docs/integrations/matrix.md b/docs/integrations/matrix.md
index 05fb932f..524f5e05 100644
--- a/docs/integrations/matrix.md
+++ b/docs/integrations/matrix.md
@@ -217,18 +217,29 @@ Nothing to do, and no window where the hive is without an account.
   stays in the store, unread, until an operator deletes it. Delete it or
   leave it; the accounts it authenticates as keep their own standing either
   way, since an access token lives on the device that minted it.
-- **The hive re-mints, per hive, on the next boot.** `ensure_hive_user` runs
-  from the startup sweep. It short-circuits on the token file it already has
-  — so the first boot after the upgrade keeps running on the shared token
-  until that file goes — and on a hive with no such file it reads the new
-  per-hive store path, finds nothing on a store that has never held one, and
-  falls through to the register-or-appservice-login ladder against
-  `@hive-<hive>:`. That ladder needs only the `as_token`, which is per hive
-  and on local disk, so it works with or without a reachable store.
-- **To move a hive onto its own account now**, delete its sender-token file
-  (`hivectl matrix sync-admin` re-provisions, or the next sweep does) — the
-  ladder then registers `@hive-<hive>:` and persists that account's token.
-  Only then does the hive stop presenting the shared one.
+- **The hive re-mints, per hive, on the next sweep.** `ensure_hive_user`
+  reads the new per-hive store path **first, on every sweep**, not just when
+  the file is missing (`sender_source`'s decision). If a per-hive token is
+  already there — `swarm-controller` mints one for every hive — the sweep
+  takes it and overwrites the file, so the shared token stops being served
+  as soon as one exists in the store, no boot required. If the store has
+  nothing yet, the file is left untouched (still the shared token, right
+  after the upgrade), so nothing breaks mid-sweep. Only when neither the
+  store nor the file holds anything does the sweep fall through to the
+  register-or-appservice-login ladder against `@hive-<hive>:`, using only
+  the `as_token`, which is per hive and on local disk, so that step works
+  with or without a reachable store.
+- **To move a hive onto its own account now**, clear both copies: the
+  sender-token file, and the store's `swarm/hives/<hive>/matrix/sender-token`
+  if `swarm-controller` or `swarm-matrix-ctl` has already published one for
+  it (otherwise the next sweep just re-adopts that value instead of minting
+  a new one). With both empty, the next sweep — or `hivectl matrix
+  sync-admin` — runs the ladder, registers `@hive-<hive>:`, and persists
+  that account's token to the file. The ladder never writes the store — on
+  a swarm that runs `swarm-controller`, its own mint pass will reach the
+  same account on its next tick and write a token there too, on the same
+  pinned device, which replaces whichever token was minted last. Only once
+  both copies agree does the hive stop presenting the shared one.
 - **The rooms the shared account created don't follow the new account, and
   this is the one step that needs a decision.** Membership is per account.
   `ensure_hive_space` takes the stored room id first, so the sweep hands the