diff --git a/docs/cron-guide.md b/docs/cron-guide.md
index b5c37fc3..461b5cb7 100644
--- a/docs/cron-guide.md
+++ b/docs/cron-guide.md
@@ -284,7 +284,7 @@ automatically after **Run Now**.
 > ⚠️ **Session-cap math if you disable auto-close.** With
 > `autoClosePreviousSession: false`, nothing ever closes the sessions a
 > recurring job creates — an interval job every 30 min creates 48 tabs/day and
-> hits the global 50-session cap in ~25 hours (sooner with existing tabs), after
+> hits the global session cap (50 by default, `CODEMAN_MAX_SESSIONS`) in ~25 hours (sooner with existing tabs), after
 > which **every** fire of **every** job fails with "Maximum concurrent sessions
 > reached" until you delete tabs by hand. Leave auto-close on for unattended
 > recurring jobs, or clean up sessions yourself.
diff --git a/docs/wiki/Settings-Reference.md b/docs/wiki/Settings-Reference.md
index 3db462e6..13b71aeb 100644
--- a/docs/wiki/Settings-Reference.md
+++ b/docs/wiki/Settings-Reference.md
@@ -221,7 +221,7 @@ Some things are configured before the server starts, not in the UI:
 | `CODEMAN_FILE_PICKER_ROOTS`         | Extra roots for the path picker.                                        |
 | `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK` | Acknowledges exposing the server with no password.                  |
 | `CODEMAN_BASE_URL`                  | Mounts Codeman under a sub-path behind a reverse proxy that forwards the prefix unchanged. See [Remote Access](Remote-Access). |
-| `CODEMAN_MAX_SESSIONS`              | Cap on concurrent sessions. 50 by default, 1 to 462 (a larger value is clamped to 462, anything that is not a positive integer falls back to 50). Read at startup. In multi-user mode the per-user cap defaults to half of it unless `CODEMAN_MAX_SESSIONS_PER_USER` is set. |
+| `CODEMAN_MAX_SESSIONS`              | Cap on concurrent sessions. 50 by default, 1 to 462 (a larger value is clamped to 462, anything that is not a positive integer falls back to 50). Read at startup. The 462 assumes the default `CODEMAN_MAX_WEBVIEWS` and no pinned closed sessions, which share the same 512-entry tab layout. In multi-user mode the per-user cap defaults to half of it unless `CODEMAN_MAX_SESSIONS_PER_USER` is set. |
 | `CODEMAN_MAX_DOWNLOAD_BYTES`        | Cap on raw file bodies and downloads. 2 GB by default, `0` for none.    |
 | `CODEMAN_MAX_PASTE_IMAGE_BYTES`     | Cap on one pasted, dropped or attached image or document. 50 MB by default. |
 | `CODEMAN_MAX_PASTE_VIDEO_BYTES`     | Cap on one attached video (phone Attach, drop). 1 GB by default; videos stream to disk, so this bounds disk use, not memory. |
diff --git a/plugins/codeman/skills/codeman/SKILL.md b/plugins/codeman/skills/codeman/SKILL.md
index a9772f77..d1376225 100644
--- a/plugins/codeman/skills/codeman/SKILL.md
+++ b/plugins/codeman/skills/codeman/SKILL.md
@@ -666,8 +666,9 @@ You are yourself a session on this server, and the API has **no undo**.
   user's repository state, so say that you did; **removing** one discards any
   uncommitted work inside it, so ask first ([§5.1](reference/verbs.md#51-where-to-spawn)).
 - Never `tmux kill-session`, `pkill tmux`, `pkill claude`. The API is the only interface.
-- Sessions count against a **global cap of 50** (and, in multi-user mode, a per-user
-  cap of 25 that fires the same 409). Case creation is uncapped and writes real
+- Sessions count against a **global cap, 50 by default** (`CODEMAN_MAX_SESSIONS`), and,
+  in multi-user mode, a per-user cap (half the global cap, 25 by default) that fires
+  the same 409. Case creation is uncapped and writes real
   directories. Clean up every session you start, and never retry `quick-start` in a
   loop.
 
diff --git a/plugins/codeman/skills/codeman/reference/verbs.md b/plugins/codeman/skills/codeman/reference/verbs.md
index 2dfe8bb0..c0020676 100644
--- a/plugins/codeman/skills/codeman/reference/verbs.md
+++ b/plugins/codeman/skills/codeman/reference/verbs.md
@@ -101,8 +101,9 @@ Differences from `quick-start` worth knowing before you debug one:
 - hitting the session cap here is `OPERATION_FAILED`, where `quick-start` returns
   `SESSION_BUSY` for the identical condition.
 
-`quick-start` failure codes are `SESSION_BUSY` (the global 50-session cap, or the
-per-user cap of 25 in multi-user mode), `FORBIDDEN`, `CONFLICT`, `NOT_FOUND` (a
+`quick-start` failure codes are `SESSION_BUSY` (the global session cap, 50 by default via
+`CODEMAN_MAX_SESSIONS`, or the per-user cap in multi-user mode, half the global cap,
+25 by default), `FORBIDDEN`, `CONFLICT`, `NOT_FOUND` (a
 remote or docker host named by the case no longer exists), `OPERATION_FAILED` and
 `INVALID_INPUT`. **None of them are retryable in a loop.** Always branch on
 `.success` before reading `.data.sessionId`: on failure the field is absent, `jq -r`
diff --git a/skills/codeman/SKILL.md b/skills/codeman/SKILL.md
index a9772f77..d1376225 100644
--- a/skills/codeman/SKILL.md
+++ b/skills/codeman/SKILL.md
@@ -666,8 +666,9 @@ You are yourself a session on this server, and the API has **no undo**.
   user's repository state, so say that you did; **removing** one discards any
   uncommitted work inside it, so ask first ([§5.1](reference/verbs.md#51-where-to-spawn)).
 - Never `tmux kill-session`, `pkill tmux`, `pkill claude`. The API is the only interface.
-- Sessions count against a **global cap of 50** (and, in multi-user mode, a per-user
-  cap of 25 that fires the same 409). Case creation is uncapped and writes real
+- Sessions count against a **global cap, 50 by default** (`CODEMAN_MAX_SESSIONS`), and,
+  in multi-user mode, a per-user cap (half the global cap, 25 by default) that fires
+  the same 409. Case creation is uncapped and writes real
   directories. Clean up every session you start, and never retry `quick-start` in a
   loop.
 
diff --git a/skills/codeman/reference/verbs.md b/skills/codeman/reference/verbs.md
index 2dfe8bb0..c0020676 100644
--- a/skills/codeman/reference/verbs.md
+++ b/skills/codeman/reference/verbs.md
@@ -101,8 +101,9 @@ Differences from `quick-start` worth knowing before you debug one:
 - hitting the session cap here is `OPERATION_FAILED`, where `quick-start` returns
   `SESSION_BUSY` for the identical condition.
 
-`quick-start` failure codes are `SESSION_BUSY` (the global 50-session cap, or the
-per-user cap of 25 in multi-user mode), `FORBIDDEN`, `CONFLICT`, `NOT_FOUND` (a
+`quick-start` failure codes are `SESSION_BUSY` (the global session cap, 50 by default via
+`CODEMAN_MAX_SESSIONS`, or the per-user cap in multi-user mode, half the global cap,
+25 by default), `FORBIDDEN`, `CONFLICT`, `NOT_FOUND` (a
 remote or docker host named by the case no longer exists), `OPERATION_FAILED` and
 `INVALID_INPUT`. **None of them are retryable in a loop.** Always branch on
 `.success` before reading `.data.sessionId`: on failure the field is absent, `jq -r`
diff --git a/src/config/map-limits.ts b/src/config/map-limits.ts
index ee8c7965..f7b0f010 100644
--- a/src/config/map-limits.ts
+++ b/src/config/map-limits.ts
@@ -26,8 +26,10 @@ const DEFAULT_MAX_CONCURRENT_SESSIONS = 50;
  * holds at most `MAX_TAB_REFS` (512) refs, and those count saved web tabs as well
  * as sessions; an owner can save up to `MAX_WEBVIEWS` (50 by default) web tabs.
  * 512 - 50 = 462 keeps session creation answering with the capacity message
- * instead of failing with a 500 on the layout limit. (`PUT /api/session-order`
- * accepts up to 500 ids, which stays above this.)
+ * instead of failing with a 500 on the layout limit, at the default `MAX_WEBVIEWS`
+ * and with no pinned closed sessions: a pinned session stays in the layout as a
+ * stopped record after it is closed, and it shares the same 512-ref budget.
+ * (`PUT /api/session-order` accepts up to 500 ids, which stays above this.)
  */
 export const MAX_CONCURRENT_SESSIONS_CEILING = 462;