diff --git a/docs/operator-capabilities.md b/docs/operator-capabilities.md
index c1776d5399..718a9eeb3a 100644
--- a/docs/operator-capabilities.md
+++ b/docs/operator-capabilities.md
@@ -21,8 +21,8 @@ Two things are worth knowing before reading the rest:
 | Storage | `usr.operator` (per workspace, per user) |
 | Resolved into | `Authed.is_operator` (`windmill-common/src/auth.rs:245`) |
 | Instance groups | best matching role wins, `"operator"` → `is_operator` (`windmill-common/src/users.rs:277-311`) |
-| Superadmins | `is_admin = true`, `is_operator = false` — on the workspace-scoped paths (`windmill-common/src/auth.rs:391`, `windmill-api-auth/src/auth.rs:463`, `:525`), not on the global ones below |
-| **Non-workspace-scoped routes** | `is_operator = true` for *every* caller, workspace admins included, with empty groups and folders — there is no `usr` row to read when the path carries no workspace (`windmill-api-auth/src/auth.rs:403-497`). So `is_operator` implies `usr.operator = true` only on `/api/w/{workspace}/…` routes; on global routes it is not a discriminator at all |
+| Superadmins | `is_admin = true`, `is_operator = false` on the workspace-scoped paths (`windmill-common/src/auth.rs:391`, `windmill-api-auth/src/auth.rs:463`) — not on the global ones below. The `superadmin_secret` token is its own arm and stays `false` everywhere (`windmill-api-auth/src/auth.rs:515-525`) |
+| **Non-workspace-scoped routes** | `is_operator = true`, with empty groups and folders, for every caller resolved through the `usr` lookup — workspace admins and superadmins included — because there is no `usr` row to read when the path carries no workspace (`windmill-api-auth/src/auth.rs:403-497`). The two token kinds that never reach that branch are the `superadmin_secret` token (above) and `jwt_` tokens, which carry `claims.is_operator` verbatim (`auth.rs:208`). So `is_operator` implies `usr.operator = true` only on `/api/w/{workspace}/…` routes; on global routes it is close to meaningless |
 | Job tokens | the flag is persisted in `job_perms` and rebuilt from it, so a `$WM_TOKEN` minted for an operator's job is itself operator-flagged (`windmill-queue/src/jobs.rs:6769`, `auth.rs:514`) |
 | Token scopes | orthogonal — scopes only ever *narrow*. An operator may mint themselves API tokens (`POST /users/tokens/create`, verified `201`) but never a token more privileged than they are (`ensure_scopes_within_caller`) |