docs: refresh device token scope refs

docs/cli/devices.md

@@ -72,6 +72,9 @@ openclaw devices reject <requestId>
 Rotate a device token for a specific role (optionally updating scopes).
 The target role must already exist in that device's approved pairing contract;
 rotation cannot mint a new unapproved role.
+If you omit `--scope`, later reconnects with the stored rotated token reuse that
+token's cached approved scopes. If you pass explicit `--scope` values, those
+become the stored scope set for future cached-token reconnects.
 
 ```
 openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write

docs/gateway/protocol.md

@@ -273,9 +273,16 @@ The Gateway treats these as **claims** and enforces server-side allowlists.
   persisted by the client for future connects.
 - Clients should persist the primary `hello-ok.auth.deviceToken` after any
   successful connect.
+- Reconnecting with that **stored** device token should also reuse the stored
+  approved scope set for that token. This preserves read/probe/status access
+  that was already granted and avoids silently collapsing reconnects to a
+  narrower implicit admin-only scope.
 - Additional `hello-ok.auth.deviceTokens` entries are bootstrap handoff tokens.
   Persist them only when the connect used bootstrap auth on a trusted transport
   such as `wss://` or loopback/local pairing.
+- If a client supplies an **explicit** `deviceToken` or explicit `scopes`, that
+  caller-requested scope set remains authoritative; cached scopes are only
+  reused when the client is reusing the stored per-device token.
 - Device tokens can be rotated/revoked via `device.token.rotate` and
   `device.token.revoke` (requires `operator.pairing` scope).
 - Token issuance/rotation stays bounded to the approved role set recorded in

docs/gateway/troubleshooting.md

@@ -117,6 +117,9 @@ Common signatures:
 - `device signature invalid` / `device signature expired` → client signed the wrong
   payload (or stale timestamp) for the current handshake.
 - `AUTH_TOKEN_MISMATCH` with `canRetryWithDeviceToken=true` → client can do one trusted retry with cached device token.
+- That cached-token retry reuses the cached scope set stored with the paired
+  device token. Explicit `deviceToken` / explicit `scopes` callers keep their
+  requested scope set instead.
 - `too many failed authentication attempts (retry later)` from a browser-origin
   loopback client → repeated failures from that same normalized `Origin` are
   locked out temporarily; another localhost origin uses a separate bucket.

docs/help/faq.md

@@ -2552,6 +2552,7 @@ Related: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-a
 
     - The Control UI keeps the token in `sessionStorage` for the current browser tab session and selected gateway URL, so same-tab refreshes keep working without restoring long-lived localStorage token persistence.
     - On `AUTH_TOKEN_MISMATCH`, trusted clients can attempt one bounded retry with a cached device token when the gateway returns retry hints (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`).
+    - That cached-token retry now reuses the cached approved scopes stored with the device token. Explicit `deviceToken` / explicit `scopes` callers still keep their requested scope set instead of inheriting cached scopes.
 
     Fix:
 

docs/help/troubleshooting.md

@@ -139,6 +139,9 @@ flowchart TD
     - `origin not allowed` → browser `Origin` is not allowed for the Control UI
       gateway target.
     - `AUTH_TOKEN_MISMATCH` with retry hints (`canRetryWithDeviceToken=true`) → one trusted device-token retry may occur automatically.
+    - That cached-token retry reuses the cached scope set stored with the paired
+      device token. Explicit `deviceToken` / explicit `scopes` callers keep
+      their requested scope set instead.
     - `too many failed authentication attempts (retry later)` from a localhost
       browser origin → repeated failures from that same `Origin` are temporarily
       locked out; another localhost origin uses a separate bucket.