diff --git a/docs/swarm/ui.md b/docs/swarm/ui.md
index a747718d..1b5b1d5f 100644
--- a/docs/swarm/ui.md
+++ b/docs/swarm/ui.md
@@ -232,8 +232,12 @@ decides that field again. **clear the swarm's caps** sends the `DELETE`. The
 controller checks each value against systemd's own syntax, because systemd
 ignores a value it can't parse and the agent would run uncapped, and it
 refuses, for example, a percentage with a leading zero. The dialog shows the
-refusal's reason under the fields and leaves them as you typed them. The panel
-reads `GET /api/agents/{agent}/limits`. [hivectl](../tools/hivectl.md#per-agent-resource-limits)
+refusal's reason under the fields and leaves them as you typed them.
+
+A saved change isn't instant. The hive reads the caps about every 30 seconds,
+and a running agent takes a changed cap at its next spawn or rebuild, so the
+row shows the new value before the agent runs under it. The panel reads
+`GET /api/agents/{agent}/limits`. [hivectl](../tools/hivectl.md#per-agent-resource-limits)
 sets the hive's own limits.
 
 ### Linking external accounts
diff --git a/frontend/packages/swarm-ui/src/agent/detail/AgentLimits.tsx b/frontend/packages/swarm-ui/src/agent/detail/AgentLimits.tsx
index ee96c3a5..2482d66e 100644
--- a/frontend/packages/swarm-ui/src/agent/detail/AgentLimits.tsx
+++ b/frontend/packages/swarm-ui/src/agent/detail/AgentLimits.tsx
@@ -167,7 +167,8 @@ function LimitsForm({
       <p>
         Caps what {agent} may use, wherever it runs. A cap here replaces the
         hive's own answer for that field; an empty box leaves the field to the
-        hive. The hive applies a change within seconds.
+        hive. The hive reads a change within about 30 seconds, and a running
+        agent takes it at its next spawn or rebuild.
       </p>
       <form class="ui-agent-limits-form" onSubmit={save}>
         <TextField