@simonesiega/codex-limits 0.1.5 → 1.0.0

package/.env.example

@@ -16,3 +16,9 @@ CODEX_LIMITS_USAGE_ENDPOINT=
 
 # Optional: suppress global-install guidance from the non-interactive postinstall script.
 CODEX_LIMITS_SKIP_INIT=
+
+# Optional: override pi's global agent configuration directory for integration setup.
+PI_CODING_AGENT_DIR=
+
+# Optional: override GitHub Copilot CLI's user configuration and extension directory.
+COPILOT_HOME=

package/CHANGELOG.md

@@ -16,6 +16,48 @@ All notable changes to codex-limits are documented in this file.
 
 ### Security
 
+## [1.0.0] - 2026-07-23
+
+### Added
+
+- Added `codex-limits reset` for consuming a numbered or soonest-expiring reset coupon after an interactive recap and explicit `y` confirmation.
+- Added the GitHub Copilot CLI integration with `codex-limits agents install copilot` and a read-only `/codex-limits` extension command that does not send limit data to the LLM.
+- Added a task-oriented documentation hub and included the complete guides, JSON Schema, and sanitized example in published npm packages.
+- Added weekly Dependabot updates for the Bun dependency graph.
+
+### Changed
+
+- Changed the packaged OpenCode runtime entry point to the agent-specific `dist/opencode.js` bundle while preserving the package root plugin exports.
+- Changed `codex-limits doctor` text output to align every diagnostic value with the longest integration label.
+
+### Fixed
+
+- Fixed local session fallback to select the newest bounded event timestamp when file modification times are misleading.
+- Fixed combined dashboard loading to start independent usage and reset-coupon requests concurrently.
+
+### Security
+
+- Hardened bounded session and native HTTP reads against path-replacement races and unbounded error-body draining, and made `reset --soonest` fail closed when coupon expirations cannot be verified.
+- Prevented private Codex paths, free-form local reset text, and malformed coupon timestamp content from reaching public output.
+- Required manual npm publishing runs to use the version tag matching the package metadata.
+
+## [0.1.6] - 2026-07-22
+
+### Breaking Changes
+
+### Added
+
+- Added `codex-limits doctor` and `codex-limits doctor --json` for safe environment, connectivity, local usage, authentication, OpenCode, and pi integration diagnostics.
+- Added the pi agent integration with `codex-limits agents install pi` and a read-only `/codex-limits` overlay that does not send limit data to the LLM.
+
+### Changed
+
+### Fixed
+
+### Removed
+
+### Security
+
 ## [0.1.5] - 2026-07-22
 
 ### Breaking Changes

package/CONTRIBUTING.md

@@ -0,0 +1,226 @@
+<p align="center">
+  <img src="docs/photos/logo/logo.png" alt="codex-limits logo" width="180" />
+</p>
+
+<h1 align="center">
+  Contributing to Codex Limits
+</h1>
+
+<p align="center">
+    Guidelines for contributing to <strong>codex-limits</strong>.
+</p>
+
+<p align="center">
+    <img src="https://img.shields.io/badge/TypeScript-5-blue?logo=typescript" alt="TypeScript" />
+    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs welcome" />
+    <img src="https://img.shields.io/github/license/simonesiega/codex-limits" alt="License" />
+    <img src="https://img.shields.io/github/issues-pr/simonesiega/codex-limits" alt="Open pull requests" />
+    <img src="https://img.shields.io/github/issues/simonesiega/codex-limits" alt="Open issues" />
+</p>
+
+Read [`README.md`](README.md) first, then use the [documentation hub](docs/README.md) to find the canonical guide for the area you plan to change.
+
+## Contents
+
+- [Quick start](#quick-start)
+- [Branch naming](#branch-naming)
+- [Issues](#issues)
+- [Local development](#local-development)
+- [Code guidelines](#code-guidelines)
+- [Safety rules](#safety-rules)
+- [Adding a new agent](#adding-a-new-agent)
+- [Documentation changes](#documentation-changes)
+- [Pull request checklist](#pull-request-checklist)
+- [Security policy](#security-policy)
+- [Community guidelines](#community-guidelines)
+- [Contact](#contact)
+
+## Quick start
+
+If you are new to the project, read [`README.md`](README.md) and the [documentation hub](docs/README.md), then choose one focused issue or improvement.
+
+| Step | Action                                          |
+| ---- | ----------------------------------------------- |
+| 1    | Fork the repository.                            |
+| 2    | Create a branch from `main`.                    |
+| 3    | Make one focused change.                        |
+| 4    | Run the local checks.                           |
+| 5    | Open a Pull Request with context and rationale. |
+
+## Branch naming
+
+| Type        | Pattern  | Example                     |
+| ----------- | -------- | --------------------------- |
+| Feature     | `feat/`  | `feat/add-agent-adapter`    |
+| Bug fix     | `fix/`   | `fix/usage-window-reset`    |
+| Docs        | `docs/`  | `docs/update-agent-guide`   |
+| Maintenance | `chore/` | `chore/update-build-config` |
+| Tests       | `test/`  | `test/add-coupon-coverage`  |
+
+## Issues
+
+Before opening a new issue, check existing [Issues](https://github.com/simonesiega/codex-limits/issues) to avoid duplicates.
+
+Please include:
+
+| Field               | Why it matters                                           |
+| ------------------- | -------------------------------------------------------- |
+| Expected behavior   | Explains what should happen.                             |
+| Actual behavior     | Shows what currently happens.                            |
+| Reproduction steps  | Makes the issue easier to verify.                        |
+| Environment         | Helps isolate OS, Node, Bun, or Codex-specific behavior. |
+| Logs or screenshots | Clarifies terminal, CLI, or agent output.                |
+
+For architecture-level changes, open an issue first so the design can be discussed before implementation.
+
+## Local development
+
+### Requirements
+
+Before starting development, read the project [Requirements](README.md#requirements) and make sure your environment meets them. Development also requires [Bun](https://bun.sh/) using the version declared in `package.json`, because this repository uses Bun for dependency management, scripts, builds, and tests.
+
+Install dependencies:
+
+```bash
+bun install
+```
+
+Run the CLI locally:
+
+```bash
+bun run dev
+```
+
+Run the full validation pipeline (format verification, documentation checks, types, tests, production builds, and packed-artifact smoke checks):
+
+```bash
+bun run check
+```
+
+Run all documentation checks:
+
+```bash
+bun run docs:check
+```
+
+Run the documentation checks individually:
+
+```bash
+bun run docs:link
+bun run docs:schema
+```
+
+Run tests only:
+
+```bash
+bun test
+```
+
+Build the package:
+
+```bash
+bun run build
+```
+
+## Code guidelines
+
+Keep changes small, readable, and easy to review.
+
+| Area               | Guideline                                                                                         |
+| ------------------ | ------------------------------------------------------------------------------------------------- |
+| Core logic         | Keep usage detection, normalization, and safety rules inside `src/package/core`.                  |
+| CLI commands       | Add commands through the shared registry and parser; keep handlers focused and capability-scoped. |
+| Terminal UI        | Keep Ink rendering inside `src/package/tui`; components should receive display-ready data.        |
+| Agent integrations | Keep adapters thin and reuse the shared core instead of reimplementing Codex limit parsing.       |
+| Tests              | Add or update tests when behavior, safety rules, or output formatting changes.                    |
+
+When adding a CLI command, create a focused command module and register it in `src/package/commands/command-registry.ts`. Put names, descriptions, usage, options, positional arguments, conflicts, and safety classification in that command definition so the shared parser and help generator stay synchronized. Command factories should accept only the runtime capabilities their handlers use.
+
+## Safety rules
+
+`codex-limits` treats local Codex data as read-only and should remain safe by default.
+
+Do not print, log, snapshot, or commit:
+
+- access tokens;
+- account IDs;
+- auth headers;
+- cookies;
+- raw local Codex files;
+- private environment values.
+
+If a change touches local data discovery, live coupon data, warnings, output formatting, or agent integrations, make sure sensitive values are redacted before they can reach the CLI, TUI, JSON output, tests, or screenshots.
+
+Command handlers should let the router replace unexpected exceptions with their fixed command failure message. Use `AgentInstallError` only for bounded, deliberately user-safe adapter messages; never pass through a raw filesystem, network, or credential error.
+
+## Adding a new agent
+
+New agents should use the same small adapter shape as [`src/agents/opencode`](src/agents/opencode), [`src/agents/pi`](src/agents/pi), and [`src/agents/copilot`](src/agents/copilot): `format.ts`, `install.ts`, `integration.ts`, and `plugin.ts`. Put reusable presentation and safe configuration behavior in `src/agents/shared`.
+
+| Step | Action                                                                                                                          |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | Create `src/agents/<agent-name>` with the standard four-file adapter layout.                                                    |
+| 2    | Define metadata, optional environment help, `install`, and `inspect` in `integration.ts`.                                       |
+| 3    | Keep `plugin.ts` focused on the target host API and load Codex data only through the shared package core.                       |
+| 4    | Register the integration descriptor once in `src/agents/index.ts`; shared install and doctor commands consume it automatically. |
+| 5    | Add installer, formatter, and host-behavior tests. When end-to-end automation is impractical, document the manual validation.   |
+| 6    | Add `docs/readme/agents/<agent-name>.md`.                                                                                       |
+| 7    | Add the integration to [Agent Integrations](docs/readme/agent-integrations.md).                                                 |
+| 8    | Update the README supported-agent summary and any target-specific package/build metadata.                                       |
+| 9    | Add or update screenshots when the visual output changes.                                                                       |
+| 10   | Run the documentation link and schema checks.                                                                                   |
+
+The goal of every integration is the same: show Codex limit information quickly, safely, and without sending unnecessary work to the LLM.
+
+## Documentation changes
+
+Task-oriented guides live under [`docs/`](docs/README.md), and visual assets live under [`docs/photos/`](docs/photos/). Update the canonical guide whenever behavior, setup, compatibility, output, or safety guarantees change; avoid copying complete procedures into multiple files.
+
+Keep documentation changes consistent with these rules:
+
+- use relative links for files in this repository;
+- keep commands executable from their documented working directory;
+- keep heading anchors stable when another file links to them;
+- synchronize JSON examples with `docs/schema/codex-limits.schema.json`;
+- use descriptive image alt text and sanitized screenshots;
+- never include tokens, account IDs, cookies, authorization headers, private paths, environment contents, or raw Codex files.
+
+Run:
+
+```bash
+bun run docs:check
+git diff --check
+```
+
+Documentation-only changes do not require unrelated runtime changes, but the complete `bun run check` remains the final repository gate before release.
+
+## Pull request checklist
+
+Before requesting review, verify:
+
+- [ ] The PR title and description explain what changed and why.
+- [ ] The change is focused and does not include unrelated cleanup.
+- [ ] `bun run format` was run and `bun run check` passes locally.
+- [ ] Tests were added or updated for behavior changes.
+- [ ] Documentation was updated if commands, setup, output, or agent support changed.
+- [ ] No secrets, account data, tokens, cookies, or raw local files were committed.
+- [ ] Screenshots were updated only when the visual output changed.
+
+## Security policy
+
+If you discover a vulnerability or a way to expose private Codex data, do not open a public issue.
+
+Please follow the private reporting process in [`SECURITY.md`](./SECURITY.md).
+
+## Community guidelines
+
+Be clear, respectful, and constructive in issues, Pull Requests, and reviews. Good contributions are focused, tested, documented, and easy to understand.
+
+## Contact
+
+For direct contact:
+
+- Email: [simonesiega1@gmail.com](mailto:simonesiega1@gmail.com)
+- GitHub: [@simonesiega](https://github.com/simonesiega)
+
+Thanks for contributing to **`codex-limits`**.

package/README.md

@@ -16,13 +16,13 @@
 
 <p align="center">
   <img src="https://img.shields.io/npm/v/@simonesiega/codex-limits?label=npm" alt="npm version" />
-  <img src="https://img.shields.io/badge/TypeScript-5-blue?logo=typescript" alt="TypeScript" />
-  <img src="https://img.shields.io/badge/Bun-toolchain-black?logo=bun" alt="Bun toolchain" />
+  <img src="https://img.shields.io/badge/test_coverage-96.2%25_lines-brightgreen" alt="Test coverage: 96.2% lines" />
 </p>
 
 <p align="center">
   <a href="#local-development">
-    <img src="https://img.shields.io/badge/test_coverage-95.9%25_lines-brightgreen" alt="Test coverage: 95.9% lines" />
+    <img src="https://img.shields.io/badge/TypeScript-5-blue?logo=typescript" alt="TypeScript" />
+    <img src="https://img.shields.io/badge/Bun-toolchain-black?logo=bun" alt="Bun toolchain" />
   </a>
 </p>
 
@@ -46,6 +46,7 @@ The screenshots show the **`codex-limits`** terminal dashboards: clean, read-onl
 - [Usage](#usage)
 - [Troubleshooting](#troubleshooting)
 - [Documentation](#documentation)
+  - [Documentation hub](docs/README.md)
   - [JSON output](docs/readme/json-output.md)
   - [Agent integrations](docs/readme/agent-integrations.md)
   - [Compatibility](docs/readme/compatibility.md)
@@ -54,9 +55,6 @@ The screenshots show the **`codex-limits`** terminal dashboards: clean, read-onl
 - [License](#license)
 - [Contributors](#contributors)
 
-> Last verified against: `@simonesiega/codex-limits` v0.1.5
-> Verification date: 2026-07-22
-
 ## Quick start
 
 The package is available on npm as [`@simonesiega/codex-limits`](https://www.npmjs.com/package/@simonesiega/codex-limits) and supports Node.js 20 or newer.
@@ -83,10 +81,12 @@ Install an optional agent integration by name:
 codex-limits agents install <agent-name>
 ```
 
-For example, install the OpenCode integration:
+For example, install the OpenCode, pi, or GitHub Copilot CLI integration:
 
 ```bash
 codex-limits agents install opencode
+codex-limits agents install pi
+codex-limits agents install copilot
 ```
 
 The existing `codex-limits init --<agent-name>` syntax remains supported as a compatibility command.
@@ -100,25 +100,29 @@ The existing `codex-limits init --<agent-name>` syntax remains supported as a co
 | Operating systems   | Windows, macOS, and Linux are supported through their standard Codex data locations. Use `CODEX_LIMITS_HOME` or `CODEX_HOME` if your data is stored elsewhere.                                                    |
 | Internet connection | Local usage fallback can work offline. An internet connection is required for current live usage and reset-credit coupon information; unavailable network data is reported safely without breaking the dashboard. |
 
+The standalone CLI supports Node.js 20 and newer. The optional pi integration runs inside the pi host; pi 0.81.x requires Node.js 22.19 or newer. The GitHub Copilot CLI integration uses Copilot's experimental extension host and its CLI-provided SDK.
+
 ## Overview
 
 When you are working with Codex or agent-based coding tools, usage limits can interrupt your flow if you do not know what is left or when the next reset happens.
 
 **`codex-limits`** gives you that information in one clean terminal view. It shows the usage windows currently supplied by Codex, including weekly usage and the 5-hour window when available, together with remaining percentages, progress bars, reset times, and reset-credit coupons, so you can quickly check your status and continue coding without leaving the terminal.
 
-It also includes plain-text commands for quick checks, JSON output for scripts and automation, optional agent integrations through `codex-limits agents`, and safe output that never prints tokens, account IDs, auth headers, cookies, or raw local files.
+It also includes plain-text commands for quick checks, an explicitly confirmed `codex-limits reset` action for using one reset coupon, a safe `codex-limits doctor` diagnostic report, JSON output for scripts and automation, optional agent integrations through `codex-limits agents`, and safe output that never prints tokens, account IDs, auth headers, cookies, private paths, or raw local files.
 
 ## Agent integrations
 
-Optional integrations make Codex limit information available directly inside supported coding agents while reusing the same read-only core and safety model as the CLI.
+Optional integrations make Codex limit information available directly inside supported coding agents while reusing the same normalized read paths and safety model as the CLI. Agent integrations do not receive the reset command's mutation capability.
 
 For installation details, adapter behavior, architecture, and contribution guidance, see the detailed [Agent integrations guide](docs/readme/agent-integrations.md).
 
 ### Supported agents
 
-| Agent    | Status    | Agent command   | Guide                                                    | Description                                                                                                     |
-| -------- | --------- | --------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| OpenCode | Supported | `/codex-limits` | [Installation and usage](docs/readme/agents/opencode.md) | Opens a fast, read-only Codex limits dashboard directly inside OpenCode without sending the request to the LLM. |
+| Agent              | Status    | Agent command   | Guide                                                    | Description                                                                                                         |
+| ------------------ | --------- | --------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| OpenCode           | Supported | `/codex-limits` | [Installation and usage](docs/readme/agents/opencode.md) | Opens a fast, read-only Codex limits dashboard directly inside OpenCode without sending the request to the LLM.     |
+| pi                 | Supported | `/codex-limits` | [Installation and usage](docs/readme/agents/pi.md)       | Opens a themed, read-only Codex limits overlay directly inside pi without sending the request to the LLM.           |
+| GitHub Copilot CLI | Supported | `/codex-limits` | [Installation and usage](docs/readme/agents/copilot.md)  | Logs a compact, read-only Codex limits summary through a local Copilot CLI extension without sending it to the LLM. |
 
 Agent integrations are not enabled automatically during package installation. They must be installed with `codex-limits agents install` (or the compatible `codex-limits init` syntax) and are only available in the agent terminal after a restart. See [Adding new agents](#adding-new-agents) if you want to add support for another agent.
 
@@ -132,9 +136,25 @@ The OpenCode integration adds a `/codex-limits` command that opens a compact mod
   <img src="docs/photos/agents/opencode/opencode_result.png" alt="OpenCode codex-limits integration screenshot" width="740" />
 </p>
 
+#### pi
+
+The pi integration adds a `/codex-limits` command that opens a themed overlay inside the agent interface. It shows the same read-only usage windows and reset-credit summary without sending the request or limit data to the LLM.
+
+<p align="center">
+  <img src="docs/photos/agents/pi/pi_result.png" alt="pi codex-limits integration screenshot" width="740" />
+</p>
+
+#### GitHub Copilot CLI
+
+The GitHub Copilot CLI integration adds a `/codex-limits` command that displays a compact, read-only limits summary in the session timeline. It loads the shared core locally without sending the request or limit data to the LLM.
+
+<p align="center">
+  <img src="docs/photos/agents/copilot/copilot_result.png" alt="GitHub Copilot CLI codex-limits integration screenshot" width="740" />
+</p>
+
 ### Adding new agents
 
-New agents can be added by creating a dedicated adapter under `src/agents/<agent-name>` and registering it in `src/agents/index.ts`. Each integration should keep the same goal: show Codex limit information quickly, safely, and without exposing tokens, account IDs, cookies, auth headers, or raw local files.
+New agents use the same four-file adapter layout under `src/agents/<agent-name>`: `format.ts`, `install.ts`, `integration.ts`, and `plugin.ts`. The integration descriptor owns its metadata, environment help, installer, and read-only diagnostic check; registering that descriptor in `src/agents/index.ts` automatically connects shared installation, compatibility help, and doctor diagnostics. Each integration should show Codex limit information quickly and safely without exposing tokens, account IDs, cookies, auth headers, or raw local files.
 
 See the [Contributing](./CONTRIBUTING.md) guide if you want to add support for another agent.
 
@@ -142,16 +162,16 @@ See the [Contributing](./CONTRIBUTING.md) guide if you want to add support for a
 
 **`codex-limits`** is built around a shared core with different output surfaces on top of it.
 
-| Area               | Path                   | Purpose                                                                                                                                           |
-| ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| CLI entry          | `src/package/cli.ts`   | Starts the `codex-limits` command and delegates to the shared command registry.                                                                   |
-| Core logic         | `src/package/core`     | Detects Codex data, reads local usage, fetches optional live information, normalizes usage windows, and keeps sensitive values out of the output. |
-| CLI commands       | `src/package/commands` | Defines command metadata, shared parsing and help, scoped runtime services, and focused command handlers.                                         |
-| Terminal UI        | `src/package/tui`      | Renders the clean Ink-based dashboard from normalized usage data.                                                                                 |
-| Agent integrations | `src/agents`           | Contains optional coding-agent adapters used by the `codex-limits agents` command group.                                                          |
-| Tests              | `tests`                | Contains the test suite used to validate core behavior, CLI output, safety rules, and integration logic.                                          |
+| Area               | Path                   | Purpose                                                                                                                                    |
+| ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| CLI entry          | `src/package/cli.ts`   | Starts the `codex-limits` command and delegates to the shared command registry.                                                            |
+| Core logic         | `src/package/core`     | Detects Codex data, normalizes live and local information, performs confirmed coupon redemption, and keeps sensitive values out of output. |
+| CLI commands       | `src/package/commands` | Defines command metadata, shared parsing and help, scoped runtime services, and focused command handlers.                                  |
+| Terminal UI        | `src/package/tui`      | Renders the clean Ink-based dashboard from normalized usage data.                                                                          |
+| Agent integrations | `src/agents`           | Contains optional coding-agent adapters used by the `codex-limits agents` command group.                                                   |
+| Tests              | `tests`                | Contains the test suite used to validate core behavior, CLI output, safety rules, and integration logic.                                   |
 
-This structure keeps the project easy to extend: the core decides what the data means, while the CLI, TUI, and agents only decide how that information is shown.
+This structure keeps the project easy to extend: the core owns data meaning and authenticated network operations, while commands control when capabilities are used and the TUI and agents remain rendering-only surfaces.
 
 ## Environment
 
@@ -167,10 +187,12 @@ Environment variables are only used as a fallback when automatic discovery is no
 | `CODEX_LIMITS_ACCOUNT_ID`     | Provides the account ID paired with `CODEX_LIMITS_ACCESS_TOKEN`.                         |
 | `CODEX_LIMITS_USAGE_ENDPOINT` | Overrides the live usage endpoint with HTTPS or loopback HTTP for advanced setups/tests. |
 | `CODEX_LIMITS_SKIP_INIT`      | Suppresses optional global-install setup guidance from the non-interactive postinstall.  |
+| `PI_CODING_AGENT_DIR`         | Overrides pi's global agent configuration directory for integration setup and checks.    |
+| `COPILOT_HOME`                | Overrides GitHub Copilot CLI's user configuration and extension directory.               |
 
 ### Data access and safety
 
-Local Codex data is inspected read-only with bounded file, directory, JSONL, and response limits. Credentials, raw files, and private paths are excluded from public output. Live requests require HTTPS, except for loopback HTTP during local testing. See [`SECURITY.md`](./SECURITY.md#local-data-and-network-behavior) for the complete data-access and network-safety model.
+Local Codex data is always inspected read-only with bounded file, directory, JSONL, and response limits. Credentials, raw files, and private paths are excluded from public output. Live requests require HTTPS, except for loopback HTTP during local testing. Only `codex-limits reset` mutates the remote account, and it requires an interactive recap followed by an explicit `y` or `yes` confirmation. See [`SECURITY.md`](./SECURITY.md#local-data-and-network-behavior) for the complete data-access and network-safety model.
 
 ## Usage
 
@@ -180,12 +202,56 @@ Local Codex data is inspected read-only with bounded file, directory, JSONL, and
 | `codex-limits status`                    | Prints a plain usage summary.                          |
 | `codex-limits coupons`                   | Prints reset-credit coupon information.                |
 | `codex-limits coupons --json`            | Prints machine-readable reset-credit coupon data only. |
+| `codex-limits reset <coupon-index>`      | Reviews and uses the numbered available reset coupon.  |
+| `codex-limits reset --soonest`           | Reviews and uses the coupon that expires first.        |
 | `codex-limits --json`                    | Prints machine-readable usage and coupon data.         |
+| `codex-limits doctor`                    | Prints safe environment and connectivity diagnostics.  |
+| `codex-limits doctor --json`             | Prints machine-readable diagnostics only.              |
 | `codex-limits agents`                    | Lists the available agent-management subcommands.      |
 | `codex-limits agents install <agent...>` | Installs one or more named agent integrations.         |
 | `codex-limits agents install --all`      | Installs every supported agent integration.            |
 | `codex-limits init`                      | Runs the compatible interactive installation flow.     |
 
+### Resetting usage
+
+Use one available reset coupon by the number shown in `codex-limits coupons`, or let the command select the available coupon that expires first:
+
+```bash
+codex-limits reset <coupon-index>
+codex-limits reset --soonest
+```
+
+Reset is an irreversible remote mutation and works only in an interactive terminal. The command refreshes the coupon list, rejects missing or unavailable indexes, prints a recap with the selected coupon and expiration, and asks `Type y to confirm [y/N]`. Only `y` or `yes` sends the consume request; every other answer cancels without using a coupon. The request carries the coupon's internal service ID and a fresh idempotency key so an internal retry cannot consume a second coupon.
+
+If no coupon is available, the command reports that nothing was used. If the selected index is absent, coupon details cannot be verified, or the final service result is ambiguous, it exits without claiming success.
+
+### Diagnostics
+
+Run the read-only doctor command when Codex data, live usage, or an agent integration is unavailable:
+
+```bash
+codex-limits doctor
+```
+
+```text
+Codex Limits diagnostics
+
+Package version:                1.0.0
+Node.js version:                22.0.0
+Operating system:               Windows
+Codex home detected:            Yes
+Authentication found:           Yes
+Local usage found:              Yes
+Live endpoint:                  Reachable
+OpenCode integration:           Installed
+pi integration:                 Installed
+GitHub Copilot CLI integration: Installed
+
+No sensitive values were displayed.
+```
+
+The doctor checks only whether recognized resources are available, including the OpenCode, pi, and GitHub Copilot CLI integrations. It never prints credential values, private paths, endpoint URLs, configuration contents, or raw Codex data. The live check makes the same bounded authenticated read-only usage request as the dashboard; it is reported as `Not checked` when complete authentication is unavailable. Use `codex-limits doctor --json` for the stable machine-readable form documented in [JSON output](docs/readme/json-output.md#doctor-document).
+
 ### Agent management
 
 Use `codex-limits agents install` to install optional integrations. Installation only updates the selected agent configuration; it does not send a prompt to an LLM or modify Codex data.
@@ -209,7 +275,7 @@ Make sure Codex has been run and authenticated at least once. If its data is sto
 
 ### Usage information unavailable
 
-Run `codex-limits status` to view the safe warning summary. Confirm that Codex authentication is current and that the machine can reach the ChatGPT Codex service. Local session data may still provide a fallback when live usage is unavailable; coupon information requires an internet connection.
+Run `codex-limits doctor` to check Codex home discovery, authentication presence, local usage, and live endpoint reachability without exposing sensitive values. Run `codex-limits status` to view the safe warning summary. Confirm that Codex authentication is current and that the machine can reach the ChatGPT Codex service. Local session data may still provide a fallback when live usage is unavailable; coupon information requires an internet connection.
 
 ### Permission errors
 
@@ -217,15 +283,19 @@ Confirm that your user can read the selected Codex directory and its session fil
 
 ### Agent command not appearing after installation
 
-Run the named installer again, for example `codex-limits agents install opencode`, and confirm that it reports the integration as installed or already installed. Restart the target agent terminal so it reloads its configuration. If the command is still missing, verify that the displayed configuration paths belong to the agent installation you are using.
+Run the named installer again, for example `codex-limits agents install opencode`, `codex-limits agents install pi`, or `codex-limits agents install copilot`, and confirm that it reports the integration as installed or already installed. Restart the target agent terminal so it reloads its configuration. If the command is still missing, verify that the displayed configuration paths belong to the agent installation you are using.
 
 ## Documentation
 
-The README provides an overview of the main features, commands, and configuration options. For more detailed technical information, see the following guides:
+The [documentation hub](docs/README.md) routes CLI users, automation authors, agent users, and contributors to the appropriate canonical guide.
 
-- [JSON output](docs/readme/json-output.md) — Learn about the machine-readable output format, available fields, warnings, examples, and scripting behavior.
-- [Agent integrations](docs/readme/agent-integrations.md) — Learn how agent integrations work, how they are installed, and how to develop and contribute new agent adapters.
-- [Compatibility](docs/readme/compatibility.md) — View the supported operating systems, Node.js versions, terminals, Codex environments, and agent versions.
+| Area                   | Canonical guide                                                                                                                                                                   |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CLI setup and commands | [Quick start](#quick-start) · [Usage](#usage) · [Troubleshooting](#troubleshooting)                                                                                               |
+| Automation             | [JSON output](docs/readme/json-output.md) · [JSON Schema](docs/schema/codex-limits.schema.json) · [Example document](docs/examples/codex-limits-output.example.json)              |
+| Agent integrations     | [Overview](docs/readme/agent-integrations.md) · [OpenCode](docs/readme/agents/opencode.md) · [pi](docs/readme/agents/pi.md) · [GitHub Copilot CLI](docs/readme/agents/copilot.md) |
+| Runtime support        | [Compatibility](docs/readme/compatibility.md)                                                                                                                                     |
+| Development and safety | [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md)                                                                                             |
 
 ## Local development
 
@@ -254,11 +324,13 @@ Useful development commands:
 
 ## Security
 
-| Operation                 | Reads                                           | Writes                            | Network                         |
-| ------------------------- | ----------------------------------------------- | --------------------------------- | ------------------------------- |
-| `codex-limits`            | Recognized Codex state and bounded session data | Nothing                           | Live usage and coupon endpoints |
-| `status` / `coupons`      | Shared read-only core                           | Nothing                           | When live data is requested     |
-| `agents install` / `init` | Selected agent configuration                    | Adds the integration registration | Does not send an LLM prompt     |
+| Operation                 | Reads                                           | Writes                            | Network                                |
+| ------------------------- | ----------------------------------------------- | --------------------------------- | -------------------------------------- |
+| `codex-limits`            | Recognized Codex state and bounded session data | Nothing                           | Live usage and coupon endpoints        |
+| `status` / `coupons`      | Shared read-only core                           | Nothing                           | When live data is requested            |
+| `reset`                   | Current reset coupon list and Codex credentials | One selected remote coupon        | Confirmed reset-credit consume request |
+| `doctor`                  | Bounded Codex and agent configuration checks    | Nothing                           | Live usage endpoint when authenticated |
+| `agents install` / `init` | Selected agent configuration                    | Adds the integration registration | Does not send an LLM prompt            |
 
 For vulnerability reports and local data safety details, see [`SECURITY.md`](./SECURITY.md).