codex-usage-analyzer 0.1.0 → 0.2.0

package/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+Contributions to `codex-usage-analyzer` should be small, reviewable, and tied to a concrete user or integration need.
+
+## Before you start
+
+1. Search the [issue tracker](https://github.com/postmelee/codex-usage-analyzer/issues) for an existing task.
+2. Open an issue for a bug, feature, public contract change, or structural change before editing source.
+3. Wait for a maintainer to confirm the scope. This repository uses an issue-first Hyper-Waterfall workflow, so implementation stages cross explicit approval boundaries.
+
+Security reports do not belong in public issues. Follow [SECURITY.md](SECURITY.md).
+
+## Development requirements
+
+- Node.js 20 or newer
+- No runtime dependency additions without prior scope approval
+- Synthetic fixtures and fake transports for automated tests
+
+Run the local checks:
+
+```bash
+npm test
+npm pack --dry-run
+```
+
+Automated tests must not require a real account, network access, a local Codex installation, or private credentials. Never commit or paste raw account usage, tokens, account identifiers, prompts, responses, app-server stderr, or machine-specific paths.
+
+## Change guidelines
+
+- Keep the default path on the official app-server `account/usage/read` method.
+- Preserve the identity-free output boundary.
+- Keep fields allowlisted and validate all upstream values before returning them.
+- Update implementation, tests, TypeScript declarations, JSON Schema, and public documentation together when a public surface changes.
+- Treat contract shape, meaning, or nullability changes as compatibility work requiring consumer-impact review.
+- Keep private or undocumented endpoint experiments out of the default command and package contract.
+- Avoid unrelated formatting, dependency, or repository metadata changes.
+
+External contributors normally do not need to edit `mydocs/`; it contains the maintainer's workflow records and manuals. A maintainer will coordinate any required internal documentation.
+
+## Pull requests
+
+A pull request should include:
+
+- the linked issue and approved scope
+- a concise behavior summary
+- focused tests for success, failure, and privacy boundaries
+- commands used for verification
+- compatibility or downstream impact, when applicable
+
+Before requesting review, confirm that tests pass, the package dry-run contains only intended artifacts, generated output is absent, and the diff contains no secrets or private data.
+
+## Collaboration
+
+Keep discussion technical and specific. Explain tradeoffs, respond to review findings with code or evidence, and split work when a change becomes broader than its approved issue.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 postmelee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,255 +1,195 @@
 # codex-usage-analyzer
 
-`codex-usage-analyzer` is the local usage analysis package that emits `UsageSnapshot v2` JSON.
+[![npm package](https://img.shields.io/npm/v/codex-usage-analyzer)](https://www.npmjs.com/package/codex-usage-analyzer)
+[![CI](https://github.com/postmelee/codex-usage-analyzer/actions/workflows/ci.yml/badge.svg)](https://github.com/postmelee/codex-usage-analyzer/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-The package is designed to be reused by product-specific CLIs and web services. It analyzes local usage sources and returns a validated snapshot; account identity, submit tokens, public profile URLs, and rendered cards belong to the product that wraps it.
+Read the account usage shown by Codex through the official app-server protocol, from one small CLI.
 
-## CLI
+`codex-usage-analyzer` starts your installed Codex CLI, calls `account/usage/read`, and emits a stable, identity-free contract. It does not scan local sessions or directly read authentication files, tokens, keychains, prompts, or responses.
 
-The published CLI entry point is:
+## Quick start
 
 ```bash
-npx codex-usage-analyzer@latest analyze --json
+npx --yes codex-usage-analyzer@latest
 ```
 
-The `--json` mode writes a single `UsageSnapshot v2` object to stdout. Errors and usage text are written to stderr.
+Human-readable output:
 
-The production `analyze --json` path reads local Codex session JSONL files from the Codex home directory. It uses `--codex-home <path>` when provided, otherwise `CODEX_HOME`, otherwise the default Codex home. When the session source is missing or unreadable, the command still emits a valid snapshot: required numeric totals are zero, unavailable usage details are `null` or empty arrays, and `extensions["codexUsageAnalyzer.diagnostics"]` explains the unavailable source. The production path does not return the sample fixture.
+```text
+Codex account usage
 
-The parser currently derives token totals, daily token buckets, model ranking, skill/plugin ranking, longest task duration, streaks, reasoning effort, and total thread count from allowlisted session event fields. Skill/plugin rankings are counted only from actual invocation events that can be classified by session tool catalog metadata; catalog or enabled-tool lists alone do not increment usage. Custom/local skill and plugin names may appear in `topSkills` and `topPlugins`, but the analyzer does not emit raw local file paths, raw JSONL lines, session ids, prompts, responses, tool input, or tool output.
+Lifetime tokens    1.23B
+Peak daily tokens  45.6M
+Longest turn       12m 34s
+Current streak     3 days
+Longest streak     21 days
+Daily buckets      30 days
 
-Streak fields are local-only analyzer results. The current parser treats a UTC date as active when local session JSONL contains positive `last_token_usage` for that date.
-
-Codex Desktop's profile screen is backed by its remote profile data and may include account-level usage that is no longer present in local session files, usage from another device, or data retained after local cleanup. For that reason, `activity.currentStreakDays` and `activity.longestStreakDays` are not guaranteed to match the Codex Desktop profile. The diagnostic extension includes `profileComparison.parity: "not_guaranteed"` when the analyzer has not compared against a remote profile baseline.
-
-The analyzer does not call Codex Desktop remote profile APIs or plugin-store APIs. `skills` and `plugins` are local session-derived fields, so they are unavailable when actual invocation source events are absent.
-
-`codexAssets.pet` is a safe logical reference, not an image export. The analyzer can report the Codex Desktop built-in pet catalog and the selected pet id when that setting is available. If no selected pet setting is persisted, it follows Codex Desktop's default and reports the built-in `codex` pet as `codex-built-in:pet:codex`. When a selected custom pet is found under `pets/<id>/pet.json` with an allowlisted spritesheet extension, the analyzer reports `codex-local:pet:custom-selected`.
-
-The default analyzer output does not include local file paths, custom pet directory names, image bytes, data URLs, or generated image artifacts. Files under `generated_images/` are treated as private generated artifacts and are not promoted to `codexAssets`. A wrapper that wants to render custom pet images in a web application must provide its own opt-in asset export, upload, or local serving layer.
-
-Local repository smoke command:
-
-```bash
-node bin/codex-usage-analyzer.js analyze --json
+Captured at 2026-07-11T00:00:00.000Z
 ```
 
-Parser fixture smoke command:
-
-```bash
-node bin/codex-usage-analyzer.js analyze --json --codex-home src/__tests__/fixtures/parser
-```
+The values above are synthetic. Your command reads the usage available to the currently signed-in Codex account.
 
-Asset fixture smoke command:
+For machine-readable output:
 
 ```bash
-node bin/codex-usage-analyzer.js analyze --json --codex-home src/__tests__/fixtures/assets
+npx --yes codex-usage-analyzer@latest --json
 ```
 
-Development fixture command:
-
-```bash
-node bin/codex-usage-analyzer.js analyze --json --fixture-sample
+```json
+{
+  "contractVersion": 1,
+  "capturedAt": "2026-07-11T00:00:00.000Z",
+  "summary": {
+    "lifetimeTokens": 1234567890,
+    "peakDailyTokens": 45600000,
+    "longestRunningTurnSec": 754,
+    "currentStreakDays": 3,
+    "longestStreakDays": 21
+  },
+  "dailyUsageBuckets": [
+    {
+      "startDate": "2026-07-10",
+      "tokens": 123456
+    }
+  ]
+}
 ```
 
-The `--fixture-sample` mode is for tests, examples, and contract inspection only. It returns the packaged sample snapshot and must not be treated as real local Codex usage.
+## Why this CLI
 
-## Profile Parity Smoke (Repository Only)
+- **Account-level source:** use the same app-server method intended for Codex account usage instead of estimating from retained local files.
+- **Privacy-first boundary:** receive usage metrics without adding names, usernames, avatars, emails, account identifiers, or credentials to the output.
+- **Stable integration:** consume a versioned JSON contract with allowlisted fields and explicit `null` semantics.
+- **Small runtime:** use Node.js built-ins and the Codex CLI already installed on your machine; there are no runtime package dependencies.
 
-Use the profile smoke helper from a repository checkout when you want to compare
-a local analyzer result with values manually copied from Codex Desktop's profile
-UI. The comparison uses a redacted baseline file; do not commit a baseline copied
-from a real account.
+## Supported metrics
 
-The helper is not published as an npm package binary. It is a maintainer QA
-tool for release and parser parity checks.
+| Field | Meaning |
+|---|---|
+| `summary.lifetimeTokens` | Lifetime token usage |
+| `summary.peakDailyTokens` | Highest token usage reported for one day |
+| `summary.longestRunningTurnSec` | Longest-running turn, in seconds |
+| `summary.currentStreakDays` | Current activity streak, in days |
+| `summary.longestStreakDays` | Longest activity streak, in days |
+| `dailyUsageBuckets` | Source-dated daily token buckets, when available |
 
-Create a production snapshot:
+Every summary field is present. A value of `null` means the upstream method did not provide that metric; it does not mean zero. Daily buckets can likewise be `null`, an empty array, or an array of dated values.
 
-```bash
-node bin/codex-usage-analyzer.js analyze --json > <local-snapshot.json>
-```
+## Requirements
 
-Create a redacted baseline using
-`src/__tests__/fixtures/profile-baseline/redacted-baseline.json` as the shape
-reference, then compare:
+- Node.js 20 or newer
+- A recent Codex CLI available as `codex` on `PATH`
+- A ChatGPT-backed Codex sign-in that supports `account/usage/read`
 
-```bash
-node scripts/profile-smoke.js --baseline <redacted-baseline.json> --snapshot <local-snapshot.json>
-```
-
-The smoke output is a field-level summary. Result statuses mean:
-
-- `match`: expected and actual values are equal.
-- `within_tolerance`: numeric values differ only within the baseline tolerance.
-- `mismatch`: the field is comparable and differs outside tolerance.
-- `not_comparable`: the baseline intentionally marks the field as visible in
-  profile UI but not comparable to local analyzer data.
-- `skipped`: the baseline did not include that expected field.
+API-key-only and Bedrock authentication do not provide this account usage method. Sign in through the installed Codex CLI before running the analyzer. The package delegates authentication to Codex and never asks you to paste a token.
 
-Mismatch reasons distinguish parser-bug candidates from expected source
-differences:
+## CLI reference
 
-- `numeric_mismatch`, `value_mismatch`, `actual_field_absent`, and ranking
-  shape reasons mean a comparable field differed.
-- `source_mismatch` means the baseline author marked that field as comparing
-  different sources, such as remote profile data versus local analyzer data.
-- `profile_parity_not_guaranteed` means the local snapshot itself reports that
-  remote profile parity is not guaranteed, and the field is source-sensitive.
-- `remote_profile_source_differs` is used with `not_comparable` fields that
-  should be visible in the profile baseline but intentionally not compared.
+```text
+codex-usage-analyzer - Read your Codex account usage
 
-Use optional baseline `sourcePolicy` metadata to keep a field comparable while
-labeling source-driven differences:
-
-```json
-{
-  "sourcePolicy": {
-    "activity.totalThreads": "source_mismatch",
-    "skills.topSkills": "source_mismatch",
-    "plugins.topPlugins": "source_mismatch"
-  }
-}
+Usage:
+  codex-usage-analyzer [usage] [--json]
+  codex-usage-analyzer [usage] --help
+  codex-usage-analyzer --version
 ```
 
-`sourcePolicy` belongs only to the redacted smoke baseline. It is not part of
-`UsageSnapshot v2`, and the analyzer output schema does not change. A
-source-aware mismatch still makes the smoke command exit nonzero; the field
-reason is what separates source differences from likely parser regressions.
-
-Known mismatch reasons:
-
-- Codex Desktop profile values can come from a remote account-level source,
-  while this analyzer reads local session files and local Codex metadata.
-- Local cleanup, migration, archiving, deletion, or another device can make the
-  profile UI and local analyzer cover different source ranges.
-- Streaks use the analyzer's UTC date buckets from local token events; profile
-  UI can use remote activity data.
-- Activity insights and thread counts can differ when the profile UI aggregates
-  remote account-level data and the analyzer reads retained local sessions.
-- Top skills/plugins require actual local invocation events. Catalog, enabled
-  tool lists, or remote profile rankings alone are not counted.
-- `--fixture-sample` snapshots are rejected by the profile smoke helper, so a
-  packaged example cannot pass as a real profile parity check.
-
-Redaction rules for real local baselines:
-
-- Keep only profile-visible numbers, model ids, ranking ids, and explicit
-  tolerance values needed for comparison.
-- Do not include real account handles, emails, local private paths, credential
-  material, conversation identifiers, conversation titles, prompts, responses,
-  tool input/output bodies, image captures, or unredacted session JSONL.
+| Command | Output |
+|---|---|
+| `codex-usage-analyzer` | Human-readable account usage |
+| `codex-usage-analyzer usage` | Same human-readable output |
+| `codex-usage-analyzer --json` | Account Usage Contract JSON |
+| `codex-usage-analyzer usage --json` | Same JSON output |
+| `codex-usage-analyzer --help` | Help without starting app-server |
+| `codex-usage-analyzer --version` | Package version without starting app-server |
+
+Successful output is written to stdout. Failures are written to stderr as a stable error code and a safe message, without raw RPC data or app-server stderr.
 
 ## SDK
 
 ```js
 import {
-  analyzeUsage,
-  assertUsageSnapshotV2,
-  createSampleUsageSnapshotV2,
-  validateUsageSnapshotV2
+  ACCOUNT_USAGE_CONTRACT_VERSION,
+  CodexUsageError,
+  readAccountUsage
 } from "codex-usage-analyzer";
 
-const snapshot = await analyzeUsage();
-assertUsageSnapshotV2(snapshot);
-```
-
-`analyzeUsage()` returns the production analyzer result. You can pass `codexHome` for deterministic tests or custom Codex home discovery:
-
-```js
-const snapshot = await analyzeUsage({
-  codexHome: "/path/to/codex-home"
-});
+try {
+  const usage = await readAccountUsage({ timeoutMs: 15_000 });
+  console.log(usage.contractVersion === ACCOUNT_USAGE_CONTRACT_VERSION);
+} catch (error) {
+  if (error instanceof CodexUsageError) {
+    console.error(error.code);
+  }
+}
 ```
 
-When a local source is unavailable, fields use zero, `null`, empty arrays, and a namespaced diagnostic extension rather than sample values.
-
-Use `createSampleUsageSnapshotV2()` only for examples, tests, and contract inspection.
+The SDK returns the same document as CLI `--json`. See the [Account Usage Contract](docs/account-usage-contract.md) and [JSON Schema](docs/account-usage.schema.json) for field and compatibility rules.
 
-Public exports:
+## How it works
 
-- `analyzeUsage(options?)`
-- `createSampleUsageSnapshotV2(overrides?)`
-- `validateUsageSnapshotV2(value)`
-- `assertUsageSnapshotV2(value)`
-- `isUsageSnapshotV2(value)`
-- `USAGE_SNAPSHOT_V2_SCHEMA_VERSION`
-- `sampleUsageSnapshotV2`
+1. Spawn `codex app-server` without a shell.
+2. Complete the stable app-server initialization handshake.
+3. Call `account/usage/read`.
+4. Allowlist and validate the supported fields.
+5. Stop the child process and return the normalized document.
 
-## Package Contents
+The package has no direct credential reader and no private profile endpoint fallback. Authentication and service communication remain inside the installed Codex process.
 
-The npm package includes the CLI entry point, runtime analyzer source, parser
-modules, snapshot validators, type declarations, and the sample snapshot fixture
-used by the SDK. It excludes repository tests, parser fixtures, working docs,
-and repository-only smoke helper scripts.
+## Downstream integrations
 
-## Ownership Boundary
+Profile sites, README cards, and other services can accept the identity-free JSON contract and combine it with identity they manage separately. The [Downstream Integration Guide](docs/downstream-integration.md) defines recommended field names, ownership, submit-token, validation, rendering, caching, and deletion boundaries.
 
-The analyzer owns local usage fields such as token totals, token breakdown, model usage, skill usage, plugin usage, activity statistics, and safe Codex pet logical references.
+Do not add identity fields to the account usage document. A downstream service should resolve GitHub identity from its own authenticated account binding, not trust a display name or avatar submitted by this CLI.
 
-Web products own GitHub login, display name, avatar URL, bio, profile visibility, submit tokens, devices, public URLs, rendered cards, and any uploaded or web-served pet image assets.
+## Privacy and Security
 
-Product-specific wrappers can call this SDK and submit the resulting snapshot to their own service:
+The default CLI does not directly read or emit:
 
-```js
-import {
-  analyzeUsage,
-  assertUsageSnapshotV2
-} from "codex-usage-analyzer";
+- access tokens, refresh tokens, cookies, or keychain entries
+- names, usernames, avatars, emails, or account identifiers
+- prompts, responses, tool input, tool output, or local session files
+- local filesystem paths, raw RPC responses, or raw app-server stderr
 
-const snapshot = assertUsageSnapshotV2(await analyzeUsage());
-await submitToProductService({ snapshot });
-```
+Treat account usage as private data even though the contract excludes identity. Review a downstream service's retention and visibility policy before submitting output anywhere.
 
-Wrapper metadata such as bearer tokens, device ids, account handles, visibility, GitHub bio, GitHub avatar URLs, custom pet upload URLs, and card-only rendering hints must stay outside the analyzer snapshot.
+For vulnerability reporting and supported versions, see [SECURITY.md](SECURITY.md).
 
-## Tests
+## Troubleshooting
 
-```bash
-npm test
-node bin/codex-usage-analyzer.js analyze --json
-node bin/codex-usage-analyzer.js analyze --json --codex-home src/__tests__/fixtures/parser
-node bin/codex-usage-analyzer.js analyze --json --codex-home src/__tests__/fixtures/assets
-node bin/codex-usage-analyzer.js analyze --json --fixture-sample
-```
-
-The test suite validates the SDK exports, production parser behavior, asset safe output behavior, fixture-only CLI behavior, and `UsageSnapshot v2` schema rules.
+| Error code | What to check |
+|---|---|
+| `CODEX_NOT_FOUND` | Install or update Codex and confirm `codex` is on `PATH`. |
+| `APP_SERVER_START_FAILED` or `APP_SERVER_EXITED` | Confirm the installed Codex CLI can start and that your environment permits child processes. |
+| `APP_SERVER_TIMEOUT` | Retry after checking connectivity; SDK callers can set `timeoutMs` up to 120000. |
+| `APP_SERVER_RPC_ERROR` | Update Codex and confirm a compatible ChatGPT-backed sign-in. |
+| `APP_SERVER_PROTOCOL_ERROR` or `INVALID_ACCOUNT_USAGE_RESPONSE` | Update both Codex and this package; the upstream response was not safe to normalize. |
 
-## Release Checklist
+The CLI intentionally suppresses raw upstream details. When reporting a bug, include the package version, Codex version, Node.js version, platform, command shape, and error code only.
 
-Before publishing:
+## Development
 
 ```bash
 npm test
 npm pack --dry-run
-node bin/codex-usage-analyzer.js analyze --json
-npx --yes github:postmelee/codex-usage-analyzer analyze --json
 ```
 
-After the package is published:
+Maintainers should use the repository's [npm release guide](mydocs/manual/npm_release_guide.md) for release operations; those steps are intentionally kept out of the user guide.
 
-```bash
-npx --yes codex-usage-analyzer@latest analyze --json
-```
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Changes to the public contract need an issue and explicit consumer-impact review.
 
-Do not paste raw production snapshot output into release notes, PR bodies, or
-issue comments. Record only structural pass/fail results, exit codes, and
-package metadata needed for release verification.
+## Support
 
-## Non-Goals
+Use [GitHub Issues](https://github.com/postmelee/codex-usage-analyzer/issues) for reproducible bugs and focused feature requests. Use GitHub's private vulnerability reporting path for security-sensitive reports.
 
-This package does not:
+## License
 
-- perform GitHub OAuth
-- use private Codex Desktop profile endpoints
-- export custom pet image files by default
-- issue or store submit tokens
-- own public profile handles
-- render cards or images
-- update GitHub README files
-- upload raw credential files
-- expose local private paths
+Copyright (c) postmelee. Released under the [MIT License](LICENSE).
 
-## Status
+This license covers only this repository's code and documentation. It does not grant rights to OpenAI services, Codex assets, user data, model outputs, trademarks, or third-party content.
 
-This repository is the standalone home for the analyzer package. The production analyzer path is separated from the packaged sample fixture, and the release checklist above is the maintainer path for npm publishing and npx verification. Broader parity work against Codex Desktop profile data remains outside the npm release flow.
+This independent project is not affiliated with, endorsed by, or sponsored by OpenAI. OpenAI and Codex names and trademarks belong to their respective owners.

package/SECURITY.md

@@ -0,0 +1,44 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+|---|---|
+| Latest published npm release | Yes |
+| `main` | Development branch; not a supported release |
+| Older npm releases | No |
+
+Security fixes are released on the latest package line. Users should update to the newest published version before reporting an issue that may already be fixed.
+
+## Reporting a vulnerability
+
+Use [GitHub private vulnerability reporting](https://github.com/postmelee/codex-usage-analyzer/security/advisories/new) so maintainers can investigate without exposing users.
+
+If private reporting is unavailable, open a minimal public issue asking for a secure contact channel. Do not include exploit details or sensitive data in that issue.
+
+Include only the information needed to reproduce the security boundary:
+
+- affected package and Codex CLI versions
+- Node.js version and operating system
+- command shape and safe error code
+- impact and minimal reproduction using synthetic data
+- whether the issue affects command execution, response validation, logging, persistence, or package integrity
+
+Never submit authentication tokens, cookies, account identifiers, raw account usage, raw app-server responses or stderr, prompts, responses, local filesystem paths, private repository links, or private keys.
+
+## Security scope
+
+Reports are especially useful when they involve:
+
+- unexpected command or shell execution
+- credential, account identifier, or private data exposure
+- unsafe handling of app-server protocol messages
+- validation bypass in the public contract
+- sensitive information written to stdout, stderr, logs, or package artifacts
+- npm package, dependency, workflow, or trusted-publishing supply-chain risk
+
+The CLI intentionally delegates sign-in to the installed Codex process. It does not directly read authentication files or keychains and does not accept pasted OpenAI credentials. A downstream service that accepts this package's output has its own authentication, storage, rendering, visibility, retention, and deletion responsibilities.
+
+## Disclosure
+
+Please allow maintainers to confirm the issue and prepare a fix before public disclosure. The project will credit reporters when requested and appropriate, but it does not promise a fixed response or remediation timeline.

package/bin/codex-usage-analyzer.js

@@ -4,7 +4,9 @@ import { runCli } from "../src/cli.js";
 try {
   const exitCode = await runCli(process.argv.slice(2));
   process.exitCode = exitCode;
-} catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
+} catch {
+  process.stderr.write(
+    "codex-usage-analyzer: Unexpected failure. [UNEXPECTED_ERROR]\n"
+  );
   process.exitCode = 1;
 }

package/docs/account-usage-contract.md

@@ -0,0 +1,85 @@
+# Account Usage Contract
+
+`codex-usage-analyzer --json` and the JavaScript `readAccountUsage()` API return the same Account Usage Contract. The current contract version is `1`.
+
+The contract is a minimal, stable projection of the official Codex app-server `account/usage/read` result. It never includes a name, username, avatar, email, account identifier, or authentication material.
+
+The machine-readable source of truth is [`account-usage.schema.json`](account-usage.schema.json).
+
+## Shape
+
+```json
+{
+  "contractVersion": 1,
+  "capturedAt": "2026-07-11T00:00:00.000Z",
+  "summary": {
+    "lifetimeTokens": 1234567890,
+    "peakDailyTokens": 45600000,
+    "longestRunningTurnSec": 754,
+    "currentStreakDays": 3,
+    "longestStreakDays": 21
+  },
+  "dailyUsageBuckets": [
+    {
+      "startDate": "2026-07-10",
+      "tokens": 123456
+    }
+  ]
+}
+```
+
+All example values are synthetic and do not represent a real account.
+
+## Root fields
+
+| Field | Type | Meaning |
+|---|---|---|
+| `contractVersion` | integer, constant `1` | Version of this downstream contract |
+| `capturedAt` | ISO 8601 UTC string | Time at which the app-server response was received |
+| `summary` | object | Account-level token and activity summary |
+| `dailyUsageBuckets` | array or `null` | Daily token buckets; `null` means unavailable upstream |
+
+## Summary fields
+
+Every summary field is always present. Each value is either a non-negative safe integer or `null`.
+
+| Field | Meaning |
+|---|---|
+| `lifetimeTokens` | Lifetime token usage |
+| `peakDailyTokens` | Highest token usage reported for one day |
+| `longestRunningTurnSec` | Longest-running turn duration, in seconds |
+| `currentStreakDays` | Current activity streak, in days |
+| `longestStreakDays` | Longest activity streak, in days |
+
+When the upstream method omits a metric or returns `null`, the wrapper preserves `null`. Downstream consumers must treat `null` as unavailable, not zero.
+
+## Daily buckets
+
+- `dailyUsageBuckets: null` means the upstream method did not provide buckets.
+- `dailyUsageBuckets: []` means the bucket source was present but contained no rows.
+- Each row contains only `startDate` and `tokens`.
+- `startDate` is a `YYYY-MM-DD` date-only string. Consumers must preserve it as the source date instead of applying timezone rebucketing.
+- `tokens` is a non-negative safe integer.
+
+## Forward compatibility
+
+The wrapper emits allowlisted fields only. New fields added by app-server do not automatically enter contract version 1. Changing an existing field's meaning, nullability, or root shape requires a new contract version and a consumer-impact review.
+
+Version 1 objects reject unknown fields because `additionalProperties` is false throughout the schema. Validate `contractVersion` before accepting a document and reject unsupported versions explicitly.
+
+## Privacy boundary
+
+The contract excludes:
+
+- display name, username, avatar, email, and account identifier
+- access or refresh tokens, cookies, and credential paths
+- local Codex session content and local filesystem paths
+- raw app-server responses, stderr, and RPC error messages
+
+Identity, submit tokens, storage, card rendering, cache policy, and deletion belong to the downstream service. See the [Downstream Integration Guide](downstream-integration.md).
+
+## Upstream
+
+- [OpenAI Codex App Server](https://developers.openai.com/codex/app-server)
+- Method: `account/usage/read`
+- API-key-only and Bedrock authentication are not supported by this method.