@simonesiega/codex-limits 1.0.0 → 1.2.0

package/docs/readme/compatibility.md

@@ -16,22 +16,24 @@ This page describes the runtime, operating-system, Codex data, network, terminal
 
 Bun is used for dependency management, tests, development commands, and production builds. It is not required to run the published CLI. Runtime dependencies are bundled into `dist`, so the published package does not declare separate production dependencies.
 
-The root package module resolves to the agent-specific `dist/opencode.js` bundle for the OpenCode plugin loader. Its public module contract consists of a default plugin export and the named `tui` export; the internal core modules are not public package exports. Pi loads the separate `dist/pi.js` extension declared in the package's `pi.extensions` manifest. The GitHub Copilot CLI installer copies the separate `dist/copilot.mjs` bundle to a recognized user extension entry point.
+The root package module resolves to the agent-specific `dist/opencode.js` bundle for OpenCode plugin-loader compatibility. The explicit `@simonesiega/codex-limits/opencode` subpath and OpenCode's loader-reserved `@simonesiega/codex-limits/tui` subpath resolve to the same module; all three expose a default plugin and the named `tui` export. The host-only `@simonesiega/codex-limits/pi` subpath resolves to the separate `dist/pi.js` extension also declared in the package's `pi.extensions` manifest. The host-only `@simonesiega/codex-limits/copilot` subpath resolves to the executable `dist/copilot.mjs` extension, which the GitHub Copilot CLI installer also copies to its recognized user extension entry point.
+
+These agent-host exports are not a general-purpose JavaScript API and do not install an integration by themselves. The supported general interfaces are the CLI and its documented [JSON output](json-output.md). There is intentionally no `@simonesiega/codex-limits/core` export; internal core modules may change without a public API compatibility guarantee.
 
 ## Tested environments
 
-The following environments are covered by the repository's automated checks or current local validation. Other compatible environments may also work, but they are not tested for every release.
+The following environments are covered by the repository's automated checks or latest recorded local validation. Other compatible environments may also work, but they are not tested for every release.
 
-| Area                   | Tested environments                                                                                                |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| Automated packaged CLI | GitHub Actions on `ubuntu-latest` with Node.js 20, 22, and 24, plus `windows-latest` with Node.js 20               |
-| Current local checks   | Windows build `10.0.26200.8875` with Node.js 22.20.0 and Bun 1.3.14 (verified 2026-07-23)                          |
-| Terminal rendering     | Automated Ink rendering and layout tests; no named terminal application is included in the per-release test matrix |
-| OpenCode agent adapter | Mocked current keymap and legacy command API shapes; no exact OpenCode host release is tested end-to-end           |
-| pi agent adapter       | Mocked command/UI APIs with real TUI components; package discovery validated in pi 0.81.1 print mode               |
-| Copilot CLI adapter    | Mocked SDK command/timeline APIs and packed installation; typed against `@github/copilot-sdk` 1.0.8                |
+| Area                             | Tested environments                                                                                                                         |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Automated packaged CLI           | GitHub Actions on `ubuntu-latest` with Node.js 20 and 22, `windows-latest` with Node.js 20, and `macos-latest` with Node.js 22              |
+| Latest recorded local validation | Windows build `10.0.26200.8875` with Node.js 22.20.0 and Bun 1.3.14 (verified 2026-08-09)                                                   |
+| Terminal rendering               | Automated Ink rendering and layout tests; no named terminal application is included in the per-release test matrix                          |
+| OpenCode agent adapter           | Mocked API coverage plus packed install, plugin loading, `/codex-limits` dispatch, and removal in real OpenCode 1.18.14 and latest hosts    |
+| pi agent adapter                 | Mocked UI coverage plus packed install, command discovery, dispatch, removal, and post-removal discovery in real pi 0.81.1 and latest hosts |
+| Copilot CLI adapter              | Mocked SDK coverage plus packed install, extension loading, `/codex-limits` dispatch, and removal in the latest real Copilot CLI host       |
 
-The supported runtime and operating-system ranges are broader than this test matrix. In particular, macOS compatibility follows the cross-platform implementation but is not currently covered by the repository's automated workflow.
+The supported runtime and operating-system ranges are broader than this test matrix. Automated checks sample each supported operating system but do not test every supported Node.js version on every platform. The real-agent matrix runs for normal repository checks and on a weekly schedule so moving `latest` host releases are exercised even when the project has no new commits.
 
 ## Operating systems
 
@@ -48,8 +50,6 @@ Codex home candidates are checked in this order, skipping missing or unreadable
 7. `%APPDATA%/Codex`, when `APPDATA` is available
 8. `%LOCALAPPDATA%/Codex`, when `LOCALAPPDATA` is available
 
-The `Parall` spelling in candidate 6 matches the constant in `src/package/core/codex/paths.ts` and is covered by the path-generation test. This verifies that the documentation matches the current implementation; it does not claim that every macOS Codex installation uses that directory.
-
 `CODEX_LIMITS_HOME` has the highest priority. `CODEX_HOME` is Codex's native override and is used next. Override values must identify readable directories; files and unreadable paths are ignored.
 
 The default home directory is resolved from `HOME`, then `USERPROFILE`, then the operating system's home-directory API.
@@ -66,7 +66,7 @@ For normal use, Codex must have been installed, run, and authenticated at least
 
 Both credential environment variables are required together. Supplying only one produces an incomplete-authentication warning and does not initiate an authenticated request.
 
-Local Codex data is inspected read-only. File traversal, file counts, file sizes, JSONL line sizes, search depth, and response sizes are bounded. Nested symbolic links are skipped. Filesystem warnings do not include relative or absolute Codex paths, and fallback reset-duration strings must use compact duration units before they are normalized. Raw local files, tokens, account IDs, authorization headers, and private paths are excluded from public output.
+Local Codex data is inspected read-only. See the [Security policy](../../SECURITY.md#local-data-and-network-behavior) for the canonical traversal, redaction, and file-handling safeguards.
 
 Local state layouts can vary between Codex versions. The parser recognizes common primary/five-hour and secondary/weekly window names and can return partial data when only some fields are understood. For live responses, declared window durations such as `limit_window_seconds` take precedence over legacy primary/secondary slot names, because the usage service can now return weekly usage in `primary_window` without a 5-hour window.
 
@@ -82,53 +82,46 @@ Live data uses these defaults:
 
 These endpoints are implementation details rather than a public API contract and may change when Codex changes its service behavior. A response containing only a recognized weekly window is treated as valid live usage; local discovery is used only when the live response contains no recognized usage window.
 
-Requests are authenticated from Codex credentials, reject redirects, time out after 10 seconds by default, and limit JSON responses to 1 MB. Independent usage and coupon lookups start concurrently. The transport uses the runtime's `fetch` implementation and can fall back to native Node HTTP/HTTPS transport for supported failures. Coupon timestamps must be bounded RFC 3339 values. Coupon redemption accepts only an exact coupon ID with the recognized `codex_rate_limits` type. `--soonest` refuses partial or count-inconsistent coupon data and any available coupon whose expiration cannot be verified. Its bounded JSON `POST` uses a fresh idempotency key for each confirmed redemption and reuses that key for any transport fallback.
+Requests require complete Codex credentials and use a 10-second timeout by default. The runtime's `fetch` implementation and native Node HTTP/HTTPS transport are both supported. See the [Security policy](../../SECURITY.md#local-data-and-network-behavior) for canonical request, response, endpoint, timestamp, and redemption safeguards.
 
-`CODEX_LIMITS_USAGE_ENDPOINT` can override only the live usage endpoint. Overrides must use HTTPS. Plain HTTP is accepted only for loopback testing on `localhost`, `127.0.0.1`, or `::1`. URLs containing embedded usernames or passwords and all other protocols are rejected.
+`CODEX_LIMITS_USAGE_ENDPOINT` can override only the live usage endpoint. Supported overrides use HTTPS, with plain HTTP limited to loopback testing on `localhost`, `127.0.0.1`, or `::1`.
 
 An internet connection is therefore recommended for current usage and required for coupon data. The CLI remains usable offline when compatible local usage snapshots exist.
 
 ## Terminal and automation compatibility
 
-| Surface                        | Requirement                                                |
-| ------------------------------ | ---------------------------------------------------------- |
-| Interactive dashboard          | A terminal capable of running the Ink UI                   |
-| `status` and `coupons`         | Any environment that can capture standard output           |
-| JSON output                    | Any environment that can capture and parse standard output |
-| Reset coupon redemption        | Both standard input and standard output must be TTYs       |
-| Interactive agent installation | Both standard input and standard output must be TTYs       |
-| Explicit agent installation    | Works non-interactively with an agent name or `--all`      |
+| Surface                     | Requirement                                                |
+| --------------------------- | ---------------------------------------------------------- |
+| Interactive dashboard       | A terminal capable of running the Ink UI                   |
+| `status` and `coupons`      | Any environment that can capture standard output           |
+| JSON output                 | Any environment that can capture and parse standard output |
+| Reset coupon redemption     | Both standard input and standard output must be TTYs       |
+| Interactive agent lifecycle | Both standard input and standard output must be TTYs       |
+| Explicit agent lifecycle    | Install and uninstall work with agent names or `--all`     |
 
-Use [`codex-limits --json`](json-output.md) or `codex-limits coupons --json` in scripts. Errors use a non-zero exit code and are written to standard error; successful machine-readable output is written to standard output. `codex-limits reset` is intentionally interactive and has no JSON or unattended confirmation mode.
+Use [`codex-limits --json`](json-output.md), `codex-limits coupons --json`, or `codex-limits doctor --json` in scripts. Errors use a non-zero exit code and are written to standard error; successful machine-readable output is written to standard output. `codex-limits reset` is intentionally interactive and has no JSON or unattended confirmation mode.
 
 ## OpenCode compatibility
 
-Install the OpenCode integration with `codex-limits agents install opencode` (or the compatible `codex-limits init --opencode` form). The integration writes to both `~/.config/opencode/opencode.json` and `~/.config/opencode/tui.json`. It supports OpenCode hosts that expose either:
-
-- the current keymap layer registration API; or
-- the legacy command registration API.
+The integration supports OpenCode hosts that expose either the current keymap layer registration API or the legacy command registration API. Compatibility is detected from the runtime API shape rather than an exact version list. Automated adapter tests cover both shapes, while the real-host compatibility matrix installs the packed package, dispatches `/codex-limits`, and verifies safe removal in OpenCode 1.18.14 and the latest npm release.
 
-Compatibility is determined from the API shape available at runtime rather than from a list of exact OpenCode versions. Automated adapter tests use host mocks for both supported API shapes; the repository does not currently claim end-to-end validation against named OpenCode releases.
-
-The command is `/codex-limits`. It loads the shared core locally and does not send an LLM prompt. See [Agent integrations](agent-integrations.md) for installation and troubleshooting.
+See the [OpenCode integration guide](agents/opencode.md) for canonical installation, configuration, removal, and troubleshooting instructions.
 
 ## pi compatibility
 
-Install the pi integration with `codex-limits agents install pi` (or the compatible `codex-limits init --pi` form). The installer registers the current package root in `~/.pi/agent/settings.json`, or in the directory selected by `PI_CODING_AGENT_DIR`. The npm package also supports pi's native `pi install npm:@simonesiega/codex-limits` flow through its extension manifest.
+The extension is developed against `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` 0.81.x, which require Node.js 22.19 or newer. Those optional peers are supplied by the pi host and do not change the standalone CLI's Node.js 20 requirement.
 
-The extension uses pi's command registration and custom overlay APIs. It is developed against `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` 0.81.x, which require Node.js 22.19 or newer. These packages are optional peers and are supplied by the pi host rather than bundled into the extension. This does not change the standalone CLI's Node.js 20 requirement. Local validation confirmed that pi 0.81.1 discovers the installed package and handles `/codex-limits` without invoking the model in print mode; the interactive overlay is covered with host mocks and real TUI components rather than a terminal-level end-to-end test.
+Automated real-host checks install the packed package into pi 0.81.1 and the latest npm release, verify that the host discovers `/codex-limits` as an extension command, dispatch it through pi's RPC command path without creating a model-conversation message, uninstall it, and verify that a fresh pi host no longer discovers the command. Mocked tests continue to cover the interactive overlay with real TUI components; the overlay itself is not terminal-tested against every pi release.
 
-The `/codex-limits` command loads the shared core locally, opens a themed read-only overlay, and never sends a prompt or limit data to the LLM. Outside pi's interactive TUI it skips loading and sends no message to the model. See the dedicated [pi integration guide](agents/pi.md) for installation, removal, and troubleshooting.
+See the [pi integration guide](agents/pi.md) for canonical installation, configuration, removal, and troubleshooting instructions.
 
 ## GitHub Copilot CLI compatibility
 
-Install the GitHub Copilot CLI integration with `codex-limits agents install copilot` (or the compatible `codex-limits init --copilot` form). The installer copies the bundled ESM extension to `~/.copilot/extensions/codex-limits/extension.mjs`, or beneath the directory selected by `COPILOT_HOME`.
-
-The integration uses Copilot CLI's experimental extension mechanism. Copilot starts the extension in a separate Node.js process, supplies `@github/copilot-sdk/extension` through its module resolver, and communicates over JSON-RPC on standard input and output. The bundle calls `joinSession()`, registers `/codex-limits` through session commands, and uses `session.log()` for the compact timeline output. It does not call `session.send()` or add the request or result to the model conversation.
+The integration depends on Copilot CLI's experimental extension mechanism, which may change. npm installations of the current Copilot CLI require Node.js 22 or newer; other official installation methods package the host separately. The host must provide `@github/copilot-sdk/extension` to the extension process.
 
-The adapter is type-checked against `@github/copilot-sdk` 1.0.8. Automated tests use host mocks for registration, timeline output, static safe failures, and installer behavior. Package validation confirms that `dist/copilot.mjs` retains only the CLI-provided SDK as an external host import and is copied to the expected user extension path. No exact Copilot CLI release is currently tested end-to-end, and the experimental API may change. The current npm installation of Copilot CLI requires Node.js 22 or newer; other official installation methods package the host separately.
+The adapter is type-checked against `@github/copilot-sdk` 1.0.8. Automated tests cover registration, timeline output, and safe failures. The real-host compatibility matrix additionally installs the packed extension into the latest Copilot CLI npm release, dispatches `/codex-limits`, requires its local timeline summary to appear without model authentication, and verifies safe removal through packed diagnostics.
 
-See the dedicated [GitHub Copilot CLI integration guide](agents/copilot.md) for installation, removal, host details, and troubleshooting.
+See the [GitHub Copilot CLI integration guide](agents/copilot.md) for canonical installation, configuration, removal, and troubleshooting instructions.
 
 ## Support policy
 
@@ -137,7 +130,8 @@ The latest npm release is supported. The current `main` branch is supported for
 ## Related documentation
 
 - [JSON output](json-output.md) — Machine-readable output, fields, warnings, and scripting behavior.
-- [Agent integrations](agent-integrations.md) — Installation, architecture, compatibility, and troubleshooting for agent adapters.
+- [Agent integrations](agent-integrations.md) — Supported-agent index, shared lifecycle modes, and adapter architecture.
 - [Security policy](../../SECURITY.md) — Data-access safeguards, network behavior, and vulnerability reporting.
+- [Troubleshooting](troubleshooting.md) — Diagnosis for Codex data, network, terminal, reset, and agent problems.
 - [Documentation hub](../README.md) — Task-oriented index for CLI, automation, agent, development, and security guides.
-- [Project README](../../README.md) — Product overview, installation, commands, configuration, and troubleshooting.
+- [Project README](../../README.md) — Product overview, installation, commands, and configuration.

package/docs/readme/json-output.md

@@ -48,52 +48,73 @@ interface UsageWindowJson {
 }
 ```
 
-This example represents one snapshot captured at `2026-07-13T16:00:07.000Z` on a system configured for UTC:
+This example represents a sanitized snapshot:
+
+<!-- validated-example: codex-limits-output.example.json -->
 
 ```json
 {
   "windows": {
     "fiveHour": {
       "label": "5-hour usage limit",
-      "remainingPercent": 93,
-      "usedPercent": 7,
-      "resetsAt": "2026-07-13T19:55:07.000Z",
+      "remainingPercent": 80,
+      "usedPercent": 20,
+      "resetsAt": "2026-07-14T01:30:15.000Z",
       "resetsIn": "3h 55m"
     },
     "weekly": {
       "label": "Weekly usage limit",
-      "remainingPercent": 11,
-      "usedPercent": 89,
-      "resetsAt": "2026-07-15T17:40:07.000Z",
-      "resetsIn": "2d 1h 40m"
+      "remainingPercent": 31,
+      "usedPercent": 69,
+      "resetsAt": "2026-07-18T11:15:15.000Z",
+      "resetsIn": "4d 13h 40m"
     }
   },
   "coupons": {
-    "available": 2,
-    "earnedThisPeriod": 4,
-    "nextExpirationDate": "Monday 20 July 2026",
-    "nextExpirationIn": "7d 4h 38m",
+    "available": 4,
+    "earnedThisPeriod": 0,
+    "nextExpirationDate": "Saturday 18 July 2026",
+    "nextExpirationIn": "4d 2h 42m",
     "items": [
       {
         "index": 1,
         "status": "available",
-        "grantedAt": "2026-06-20T20:38:07Z",
-        "expiresAt": "2026-07-20T20:38:07Z",
-        "expirationDate": "Monday 20 July 2026",
-        "expiresIn": "7d 4h 38m"
+        "grantedAt": "2026-06-18T00:17:20.252556Z",
+        "expiresAt": "2026-07-18T00:17:20.252556Z",
+        "expirationDate": "Saturday 18 July 2026",
+        "expiresIn": "4d 2h 42m"
       },
       {
         "index": 2,
         "status": "available",
-        "grantedAt": "2026-06-27T20:38:07Z",
-        "expiresAt": "2026-07-27T20:38:07Z",
+        "grantedAt": "2026-06-26T23:48:13.132409Z",
+        "expiresAt": "2026-07-26T23:48:13.132409Z",
         "expirationDate": "Monday 27 July 2026",
-        "expiresIn": "14d 4h 38m"
+        "expiresIn": "13d 2h 12m"
+      },
+      {
+        "index": 3,
+        "status": "available",
+        "grantedAt": "2026-07-01T19:59:47.228684Z",
+        "expiresAt": "2026-07-31T19:59:47.228684Z",
+        "expirationDate": "Friday 31 July 2026",
+        "expiresIn": "17d 22h 24m"
+      },
+      {
+        "index": 4,
+        "status": "available",
+        "grantedAt": "2026-07-13T17:48:41.527506Z",
+        "expiresAt": "2026-08-12T17:48:41.527506Z",
+        "expirationDate": "Wednesday 12 August 2026",
+        "expiresIn": "29d 20h 13m"
       }
     ],
     "warnings": []
   },
-  "warnings": []
+  "warnings": [
+    "Skipped a sensitive-looking local file.",
+    "Skipped a local cache file because it is too large to inspect safely."
+  ]
 }
 ```
 
@@ -121,11 +142,13 @@ interface CouponItemJson {
 }
 ```
 
-Using the same reference time and timezone as the complete example:
+Sanitized example ([see the sanitized coupon example](../examples/codex-limits-coupons-output.example.json)):
+
+<!-- validated-example: codex-limits-coupons-output.example.json -->
 
 ```json
 {
-  "available": 1,
+  "available": 2,
   "earnedThisPeriod": 4,
   "nextExpirationDate": "Monday 20 July 2026",
   "nextExpirationIn": "7d 4h 38m",
@@ -137,6 +160,14 @@ Using the same reference time and timezone as the complete example:
       "expiresAt": "2026-07-20T20:38:07Z",
       "expirationDate": "Monday 20 July 2026",
       "expiresIn": "7d 4h 38m"
+    },
+    {
+      "index": 2,
+      "status": "available",
+      "grantedAt": "2026-06-27T20:38:07Z",
+      "expiresAt": "2026-07-27T20:38:07Z",
+      "expirationDate": "Monday 27 July 2026",
+      "expiresIn": "14d 4h 38m"
     }
   ],
   "warnings": []
@@ -162,11 +193,13 @@ interface DoctorJson {
 }
 ```
 
-Example:
+Sanitized example ([see the JSON example](../examples/codex-limits-doctor-output.example.json)):
+
+<!-- validated-example: codex-limits-doctor-output.example.json -->
 
 ```json
 {
-  "packageVersion": "1.0.0",
+  "packageVersion": "1.2.0",
   "nodeVersion": "22.0.0",
   "operatingSystem": "Windows",
   "codexHomeDetected": true,
@@ -201,14 +234,14 @@ For comparisons and stored data, prefer canonical fields such as `resetsAt` and
 
 ### Coupon summary
 
-| Field                | Meaning                                                                              |
-| -------------------- | ------------------------------------------------------------------------------------ |
-| `available`          | Available reset-credit count as a non-negative integer, or `null` when not returned. |
-| `earnedThisPeriod`   | Total earned reset credits as a non-negative integer, or `null`.                     |
-| `nextExpirationDate` | Local calendar date for the next available coupon, or otherwise the soonest coupon.  |
-| `nextExpirationIn`   | Compact non-negative duration until that expiration.                                 |
-| `items`              | Valid coupon entries sorted by expiration time.                                      |
-| `warnings`           | Safe coupon-specific availability or payload warnings.                               |
+| Field                | Meaning                                                                                        |
+| -------------------- | ---------------------------------------------------------------------------------------------- |
+| `available`          | Available reset-credit count as a non-negative safe integer, or `null` when invalid or absent. |
+| `earnedThisPeriod`   | Total earned reset credits as a non-negative safe integer, or `null`.                          |
+| `nextExpirationDate` | Local calendar date for the next available coupon, or otherwise the soonest coupon.            |
+| `nextExpirationIn`   | Compact non-negative duration until that expiration.                                           |
+| `items`              | Valid coupon entries sorted by expiration time.                                                |
+| `warnings`           | Safe coupon-specific availability or payload warnings.                                         |
 
 Coupon `index` values are one-based and assigned after sorting. `grantedAt` and `expiresAt` preserve bounded RFC 3339 timestamp strings from the service. `expirationDate` is rendered in the machine's local timezone as `Weekday D Month YYYY`; `expiresIn` is calculated at command execution time. Coupon entries with malformed or extra timestamp text are omitted and produce a warning.
 
@@ -287,9 +320,11 @@ Consumers should tolerate `null` values and warning entries. Parse fields as JSO
 
 ## Related documentation
 
-- [Example JSON output](../examples/codex-limits-output.example.json) — Complete example response produced by `codex-limits --json`.
-- [JSON Schema](../schema/codex-limits.schema.json) — Machine-readable schema for validating the complete JSON response.
+- [Complete limits example](../examples/codex-limits-output.example.json) and [schema](../schema/codex-limits.schema.json) — Resources for `codex-limits --json`.
+- [Coupon example](../examples/codex-limits-coupons-output.example.json) and [schema](../schema/codex-limits-coupons.schema.json) — Resources for `codex-limits coupons --json`.
+- [Doctor example](../examples/codex-limits-doctor-output.example.json) and [schema](../schema/codex-limits-doctor.schema.json) — Resources for `codex-limits doctor --json`.
 - [Compatibility](compatibility.md) — Runtime, operating system, local-data, terminal, and network requirements.
 - [Agent integrations](agent-integrations.md) — Installation, architecture, behavior, and development of supported agent integrations.
+- [Troubleshooting](troubleshooting.md) — Diagnosis for JSON output, automation, and data availability problems.
 - [Documentation hub](../README.md) — Task-oriented index for CLI, automation, agent, development, and security guides.
-- [Project README](../../README.md) — Product overview, installation, commands, configuration, and troubleshooting.
+- [Project README](../../README.md) — Product overview, installation, commands, and configuration.

package/docs/readme/troubleshooting.md

@@ -0,0 +1,160 @@
+# Troubleshooting
+
+[← Documentation hub](../README.md) · [Project README](../../README.md)
+
+Use this guide when Codex data, live usage, reset-credit coupons, JSON output, the terminal dashboard, reset redemption, or an agent integration is unavailable.
+
+## Contents
+
+- [Start with diagnostics](#start-with-diagnostics)
+- [No Codex data found](#no-codex-data-found)
+- [Usage information is unavailable](#usage-information-is-unavailable)
+- [Reset-credit coupons are unavailable](#reset-credit-coupons-are-unavailable)
+- [Authentication overrides are incomplete](#authentication-overrides-are-incomplete)
+- [Permission errors](#permission-errors)
+- [The dashboard does not render correctly](#the-dashboard-does-not-render-correctly)
+- [JSON output or automation fails](#json-output-or-automation-fails)
+- [Reset redemption does not proceed](#reset-redemption-does-not-proceed)
+- [An agent command does not appear](#an-agent-command-does-not-appear)
+- [Agent installation reports invalid or conflicting configuration](#agent-installation-reports-invalid-or-conflicting-configuration)
+- [Agent uninstallation refuses a target](#agent-uninstallation-refuses-a-target)
+- [The problem persists](#the-problem-persists)
+- [Related documentation](#related-documentation)
+
+## Start with diagnostics
+
+Run the read-only diagnostic command first:
+
+```bash
+codex-limits doctor
+```
+
+For machine-readable diagnostics:
+
+```bash
+codex-limits doctor --json
+```
+
+Then run `codex-limits status` to see safe usage warnings and `codex-limits coupons` to check coupon availability independently. Diagnostic and warning output intentionally omits credentials, private paths, endpoint URLs, and raw Codex files.
+
+## No Codex data found
+
+1. Run Codex and authenticate at least once.
+2. Run `codex-limits doctor` and check **Codex home detected**, **Authentication found**, and **Local usage found**.
+3. If Codex stores data outside its standard location, set `CODEX_LIMITS_HOME` or `CODEX_HOME` to the correct directory.
+4. Confirm that the selected location is a readable directory rather than a file.
+5. Review [Codex data compatibility](compatibility.md#codex-data-compatibility) for recognized data and credential sources.
+
+## Usage information is unavailable
+
+Current usage normally comes from the live Codex endpoint, with compatible local state used as a fallback.
+
+- Confirm that Codex authentication is current.
+- Check **Live endpoint** with `codex-limits doctor`.
+- Confirm that the machine can reach the ChatGPT Codex service.
+- Run Codex again to create a recent local usage snapshot when working offline.
+- Check [network compatibility](compatibility.md#network-compatibility) if a proxy, firewall, endpoint override, or offline environment is involved.
+
+A missing 5-hour window is not necessarily an error. Codex may provide only a weekly usage window.
+
+## Reset-credit coupons are unavailable
+
+Coupon information requires complete credentials and network access; it has no local-data fallback.
+
+- Confirm that `authenticationFound` is `true` in `doctor --json`, or that **Authentication found** is **Yes** in text output.
+- If using environment credentials, provide both `CODEX_LIMITS_ACCESS_TOKEN` and `CODEX_LIMITS_ACCOUNT_ID`.
+- Use the live usage endpoint status as a general connectivity signal, but inspect coupon warnings separately because `doctor` does not call the coupon endpoint.
+- Inspect safe warnings from `codex-limits coupons`.
+
+Do not print credential values while troubleshooting.
+
+## Authentication overrides are incomplete
+
+`CODEX_LIMITS_ACCESS_TOKEN` and `CODEX_LIMITS_ACCOUNT_ID` must be supplied together. Providing only one disables authenticated live requests and produces a safe warning. Either provide both values or remove the partial override so the CLI can use a readable Codex `auth.json` file.
+
+## Permission errors
+
+Confirm that your user can read the selected Codex directory and recognized files. Prefer correcting ownership or permissions, or selecting the correct directory with `CODEX_LIMITS_HOME`, instead of running the CLI with elevated privileges.
+
+The CLI intentionally skips unsafe, unreadable, oversized, or symbolic-link entries. See the [Security policy](../../SECURITY.md#local-data-and-network-behavior) for canonical file-handling behavior.
+
+## The dashboard does not render correctly
+
+- Confirm that the command is running in an interactive terminal.
+- Resize very narrow or short terminals; the dashboard switches to compact layouts automatically.
+- Use `codex-limits status`, `codex-limits coupons`, or JSON output when Ink rendering is unavailable.
+- Check [terminal compatibility](compatibility.md#terminal-and-automation-compatibility).
+
+## JSON output or automation fails
+
+Use one of the documented JSON forms:
+
+```bash
+codex-limits --json
+codex-limits coupons --json
+codex-limits doctor --json
+```
+
+`status --json` is not supported. Successful JSON is written to standard output; command failures are written to standard error and return a non-zero exit code. Warnings and unavailable nullable fields can still appear in a successful document.
+
+Validate consumers against the schemas and examples linked from [JSON output](json-output.md). Parse JSON fields rather than terminal text or pretty-print whitespace.
+
+## Reset redemption does not proceed
+
+`codex-limits reset` requires both standard input and standard output to be interactive TTYs. It has no unattended or JSON confirmation mode.
+
+- Run `codex-limits coupons` first and confirm that an available coupon is listed.
+- Use a displayed coupon index, or `codex-limits reset --soonest` when expiration data is complete.
+- Confirm only after reviewing the recap.
+- If coupon details are incomplete, availability is inconsistent, or the final response is ambiguous, the command fails closed and does not claim success.
+
+See [Reset redemption](../../SECURITY.md#reset-redemption) for the canonical safety behavior.
+
+## An agent command does not appear
+
+Use the troubleshooting section for the installed agent:
+
+- [OpenCode command troubleshooting](agents/opencode.md#the-command-does-not-appear)
+- [pi command troubleshooting](agents/pi.md#the-command-does-not-appear)
+- [GitHub Copilot CLI command troubleshooting](agents/copilot.md#the-command-does-not-appear)
+
+In general, rerun the named installer, confirm that it reports **installed** or **already installed**, and restart the agent so it reloads configuration. Agent-specific configuration paths, reload behavior, host requirements, and removal steps remain canonical in each dedicated guide.
+
+## Agent installation reports invalid or conflicting configuration
+
+Installers intentionally refuse malformed, oversized, symbolic-link, or conflicting targets rather than overwriting them. Review the relevant dedicated guide before changing agent configuration:
+
+- [OpenCode setup troubleshooting](agents/opencode.md#setup-reports-invalid-json)
+- [pi setup troubleshooting](agents/pi.md#setup-reports-invalid-json)
+- [GitHub Copilot CLI extension conflicts](agents/copilot.md#the-extension-path-is-already-in-use)
+
+Do not remove unrelated plugins, packages, extensions, or configuration fields.
+
+## Agent uninstallation refuses a target
+
+Uninstallers intentionally fail closed on malformed, oversized, symbolic-link, unreadable, or unrecognized targets. They do not rewrite or delete the target merely because it occupies an expected path.
+
+1. Run `codex-limits doctor` to review the bounded installed status.
+2. Read the removal section for [OpenCode](agents/opencode.md#re-running-or-removing-the-integration), [pi](agents/pi.md#re-running-or-removing-the-integration), or [GitHub Copilot CLI](agents/copilot.md#re-running-or-removing-the-integration).
+3. Correct malformed host configuration before retrying.
+4. For an unrecognized Copilot entry point, inspect the dedicated extension directory and remove it manually only if you can independently verify its ownership.
+
+With multiple named targets or `--all`, review every per-agent result: one failure does not prevent other adapters from attempting safe removal.
+
+## The problem persists
+
+1. Run `codex-limits doctor` and the affected read-only command again.
+2. Record the command, expected behavior, safe status labels, and warning text.
+3. Include the operating system and Node.js version, but redact private paths and environment values.
+4. Check existing [GitHub issues](https://github.com/simonesiega/codex-limits/issues) before opening a focused report.
+
+For a suspected credential, data-exposure, unsafe-write, or reset-redemption vulnerability, follow the private process in the [Security policy](../../SECURITY.md#reporting-a-vulnerability) instead of opening a public issue.
+
+## Related documentation
+
+- [Compatibility](compatibility.md) — Canonical runtime, operating-system, Codex-data, network, terminal, and agent-host requirements.
+- [JSON output](json-output.md) — Machine-readable contracts, schemas, examples, and scripting behavior.
+- [Agent integrations](agent-integrations.md) — Supported-agent index and shared lifecycle modes.
+- [Security policy](../../SECURITY.md) — Canonical safety behavior and private vulnerability reporting.
+- [Documentation hub](../README.md) — Task-oriented documentation index.
+- [Project README](../../README.md) — Product overview, installation, and command reference.

package/docs/schema/codex-limits-coupons.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/simonesiega/codex-limits/main/docs/schema/codex-limits-coupons.schema.json",
+  "title": "Codex Limits Coupons JSON Output",
+  "description": "Schema for the output of `codex-limits coupons --json`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "available",
+    "earnedThisPeriod",
+    "nextExpirationDate",
+    "nextExpirationIn",
+    "items",
+    "warnings"
+  ],
+  "properties": {
+    "available": {
+      "$ref": "#/$defs/nullableNonNegativeInteger"
+    },
+    "earnedThisPeriod": {
+      "$ref": "#/$defs/nullableNonNegativeInteger"
+    },
+    "nextExpirationDate": {
+      "$ref": "#/$defs/nullableString"
+    },
+    "nextExpirationIn": {
+      "$ref": "#/$defs/nullableString"
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/couponItem"
+      }
+    },
+    "warnings": {
+      "$ref": "#/$defs/warnings"
+    }
+  },
+  "$defs": {
+    "couponItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["index", "status", "grantedAt", "expiresAt", "expirationDate", "expiresIn"],
+      "properties": {
+        "index": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "status": {
+          "anyOf": [
+            {
+              "type": "string",
+              "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "grantedAt": {
+          "$ref": "#/$defs/nullableDateTime"
+        },
+        "expiresAt": {
+          "$ref": "#/$defs/nullableDateTime"
+        },
+        "expirationDate": {
+          "$ref": "#/$defs/nullableString"
+        },
+        "expiresIn": {
+          "$ref": "#/$defs/nullableString"
+        }
+      }
+    },
+    "nullableDateTime": {
+      "anyOf": [
+        {
+          "type": "string",
+          "format": "date-time"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "nullableNonNegativeInteger": {
+      "anyOf": [
+        {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "nullableString": {
+      "type": ["string", "null"]
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}