diff --git a/.changeset/28614-connection-reconnect-required-docblock.md b/.changeset/28614-connection-reconnect-required-docblock.md
new file mode 100644
index 00000000000..17408a9c84a
--- /dev/null
+++ b/.changeset/28614-connection-reconnect-required-docblock.md
@@ -0,0 +1,8 @@
+---
+'@objectstack/spec': patch
+---
+
+Clause-②: no
+Metadata-protocol: none
+
+`ConnectorConnectionState.status`'s docblock no longer says `reconnect_required` means only that the authorization server refused the grant. It now names every way the grant stops working: the authorization server refused it on refresh, the connection keeps nothing to renew an expired access token with (no refresh token was issued, or no client to refresh with), or the upstream refused the connection's token while an `mcp` instance discovered its tools; `statusReason` says which. Comment only; no behaviour change.
diff --git a/packages/spec/src/contracts/automation-service.ts b/packages/spec/src/contracts/automation-service.ts
index f97289473e8..f79021da2d3 100644
--- a/packages/spec/src/contracts/automation-service.ts
+++ b/packages/spec/src/contracts/automation-service.ts
@@ -1134,7 +1134,11 @@ export interface ConnectorConnectionState {
     /**
      * `not_connected` — no administrator connected it here yet (the instance
      * dispatches nothing for this organization); `connected`; or
-     * `reconnect_required` — the authorization server refused the grant.
+     * `reconnect_required` — the grant stopped working: the authorization
+     * server refused it on refresh, the connection keeps nothing to renew an
+     * expired access token with (no refresh token was issued, or no client to
+     * refresh with), or the upstream refused the connection's token while an
+     * `mcp` instance discovered its tools. `statusReason` says which.
      */
     status: 'not_connected' | 'connected' | 'reconnect_required';
     /** Why the grant stopped working, when `status` is `reconnect_required`. */