diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md
index dd7f4791..86866108 100644
--- a/docs/getting-started/setup.md
+++ b/docs/getting-started/setup.md
@@ -99,6 +99,11 @@ swarmctl agent create ruth --hive <hive>   # on the swarm-controller's host
 hivectl agent ruth rebuild          # on ruth's hive: hands her the identity
 ```
 
+`agent create` declares an agent the swarm has no declaration for as
+`paused`, so without a further step ruth keeps running but drives no turns.
+`swarmctl` has no verb for wanted state: open `/agents` in the swarm UI and set
+her `up` from her card.
+
 Within about ten minutes the controller creates her forge user and matrix
 account and mints their tokens into the store, where she fetches them.
 `swarmctl agent mint-forge-token ruth` skips the wait for the forge token.
diff --git a/docs/swarm/credentials.md b/docs/swarm/credentials.md
index 7dfeb09e..c285080e 100644
--- a/docs/swarm/credentials.md
+++ b/docs/swarm/credentials.md
@@ -113,7 +113,15 @@ swarmctl agent mint-forge-token <agent>
 
 An agent without a store identity gets no swarm token and keeps using the
 `forge-token` file in its state dir, if it has one; re-create it with
-`swarmctl agent create` to give it one.
+`swarmctl agent create` to give it one. The swarm leaves an agent it already
+declares as it is. For an agent with no declaration, such as one only its hive
+knows about, `agent create` declares it `paused`; set it `up` from its card in
+the swarm UI.
+
+⚠️ **Re-create existing agents before deploying a hive-side change that makes a
+container require a credential it may not have.** A container whose store
+identity is absent doesn't start (`nix/agent-modules/bao.nix` exits 1), so
+create the identities first, setting any newly paused agent `up` as above.
 
 **Revoking an agent's queue credential.** Declaring an agent `destroyed` —
 `PUT /api/hives/{hive}/agents/{agent}/state` — deletes