diff --git a/docs-site/src/content/docs/reference/codex-retry-diagnostics.md b/docs-site/src/content/docs/reference/codex-retry-diagnostics.md
index 532ada6ddfd..855ac4322bb 100644
--- a/docs-site/src/content/docs/reference/codex-retry-diagnostics.md
+++ b/docs-site/src/content/docs/reference/codex-retry-diagnostics.md
@@ -23,6 +23,24 @@ waiting visible: those items can contaminate history or imply work happened.
 Do not shorten the provider delay or provoke an extra request to advance the
 client's retry counter.
 
+## Triage: `exceeded retry limit, last status: 429 Too Many Requests`
+
+The message is the client's retry budget summary, not a diagnosis. One refusal
+that the client does not retransmit can end a turn in the same words as a
+fully exhausted budget, so treat the text as a question. Three cases look
+identical at this layer and are checked differently.
+
+| Check | Distinguishing evidence | If the check is positive |
+| --- | --- | --- |
+| Main-account hard lock (local admission policy) | The dashboard Settings or `GET /api/settings` reports the policy state, such as `mainAccountHardLock.state` being `blocked`, `ready`, or `off`, with `thresholds` and an optional `resetAt`. A non-streaming request may also carry an explicit main-policy body instead of a bare upstream 429. | Release it with a validated usage refresh such as `ocx account refresh openai`, or turn `codexMainAccountHardLock` off in Settings. Builds before [#6287](https://github.com/lidge-jun/opencodex/pull/6287) could keep an obsolete short-window block across restarts when no fresh observation ever replaced it; the release semantics are described in the [closing note on #6244](https://github.com/lidge-jun/opencodex/issues/6244). |
+| Upstream ChatGPT plan window | The account quota section shows a 5-hour or weekly window at or near its limit while the lock reports `ready` or `off`. | Wait for the window, spend an automatic or bought reset as ChatGPT offers it ([banked reset rules](https://help-lb.openai.com/en/articles/20001498-how-banked-codex-resets-work), [plan windows](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan)), or serve the request on another account with `ocx account use openai <id>`. Reset-credit spending after an exhausted weekly limit is tracked by [#6845](https://github.com/lidge-jun/opencodex/issues/6845). |
+| Provider incident or transport failure | Quota stays low, the lock stays released, and `ocx doctor` reports transport or ChatGPT reachability problems. | Retry after the incident clears or reroute through an existing combo. Changing lock or threshold policy is not a cure for a transport failure. |
+
+A locked main credential closes request admission; it does not reserve the
+account's remaining quota, and a predicted reset never releases the block on
+its own. The thresholds (by default `short` 90, `long` 98) are visible in the
+status payload and configurable through `codexMainAccountHardLockThresholds`.
+
 ## Why the first reconnect row can be absent
 
 The public Codex `rust-v0.158.0-alpha.2.1` source gates the ordinary stream-retry