diff --git a/docs/tools/swarmctl-cli.md b/docs/tools/swarmctl-cli.md
index a769ec59..dd6d4c1f 100644
--- a/docs/tools/swarmctl-cli.md
+++ b/docs/tools/swarmctl-cli.md
@@ -65,7 +65,7 @@ Manage agents across the swarm
 
 * `create` — Queue creation of a new agent on a hive in this swarm
 * `mint-forge-token` — Check one agent's forge token, and mint it if it's missing or stale
-* `inference` — Show or change the model, effort and subagent models the swarm sets for an agent
+* `inference` — Show the model, effort, subagent models and subagent cap the swarm sets for an agent, or change the model, effort and subagent models
 
 
 
@@ -122,7 +122,9 @@ Queues and returns, the same way `agent create` does — watch the swarm UI's jo
 
 ## `swarmctl agent inference`
 
-Show or change the model, effort and subagent models the swarm sets for an agent.
+Show the model, effort, subagent models and subagent cap the swarm sets for an agent, or change the model, effort and subagent models.
+
+`get` prints the subagent cap (`max_subagents`); `set` has no flag for it and keeps a stored one. Only swarm-ui sets it.
 
 A field the swarm sets wins over the agent's own value (its agent.nix or a `hyperhive-model`/`hyperhive-effort` file) from its next turn on; the agent reads its settings every ten seconds. A field the swarm doesn't set, or clears, leaves the agent on its own value.
 
diff --git a/hive-agent/src/swarm_inference.rs b/hive-agent/src/swarm_inference.rs
index 5d4dd6fa..b899d3fc 100644
--- a/hive-agent/src/swarm_inference.rs
+++ b/hive-agent/src/swarm_inference.rs
@@ -20,7 +20,7 @@
 //! A failed read changes nothing. Until the first successful read after a
 //! start, the agent runs on its local values.
 //!
-//! `subagent_models` is not read here.
+//! `subagent_models` and `max_subagents` are not read here.
 
 use std::time::Duration;
 
diff --git a/swarm-controller/README.md b/swarm-controller/README.md
index dd8bf723..16b9b4f8 100644
--- a/swarm-controller/README.md
+++ b/swarm-controller/README.md
@@ -46,8 +46,9 @@ The swarm's control plane. The swarm UI and `swarmctl` are its clients.
   `agent-schedules`, both of which this daemon alone writes
   (`GET`/`POST /api/schedules`, `PATCH`/`DELETE /api/schedules/{id}`); each
   agent fires them itself → [`docs/swarm/schedules.md`](../docs/swarm/schedules.md).
-- **Inference settings** — each agent's model, effort and subagent models,
-  one key per agent in the `agent-inference` KV bucket, which this daemon
+- **Inference settings** — each agent's model, effort, subagent models and
+  cap on concurrently running subagents, one key per agent in the
+  `agent-inference` KV bucket, which this daemon
   alone writes (`GET`/`PUT`/`DELETE /api/agents/{name}/inference`); each
   agent applies them itself. `GET` also answers the model and effort the
   agent last reported in its turn-state header, kept in memory →
diff --git a/swarmctl/src/main.rs b/swarmctl/src/main.rs
index b2836536..e6276b16 100644
--- a/swarmctl/src/main.rs
+++ b/swarmctl/src/main.rs
@@ -246,8 +246,11 @@ enum AgentVerb {
     /// Queues and returns, the same way `agent create` does — watch the
     /// swarm UI's job view for the outcome.
     MintForgeToken(AgentMintForgeTokenArgs),
-    /// Show or change the model, effort and subagent models the swarm sets
-    /// for an agent.
+    /// Show the model, effort, subagent models and subagent cap the swarm sets
+    /// for an agent, or change the model, effort and subagent models.
+    ///
+    /// `get` prints the subagent cap (`max_subagents`); `set` has no flag for
+    /// it and keeps a stored one. Only swarm-ui sets it.
     ///
     /// A field the swarm sets wins over the agent's own value (its agent.nix
     /// or a `hyperhive-model`/`hyperhive-effort` file) from its next turn on;