codex-usage-tracking 0.4.0__tar.gz → 0.5.0__tar.gz

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.5.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-usage-tracker",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Unofficial local tracker for aggregate Codex token usage from local session logs.",
   "author": {
     "name": "Douglas Monsky"

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.5.0}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.5.0 - 2026-06-10
+
+- Add the dashboard localization foundation, including starter locale catalogs, language metadata, local browser language selection, `--lang`, and `CODEX_USAGE_TRACKER_LANG`.
+- Add Vietnamese dashboard localization and focused validation coverage for translated dashboard labels.
+- Keep the README landing page focused on dashboard screenshots and companion usage workflows before detailed localization guidance.
+- Stabilize the CI synthetic benchmark smoke so coverage instrumentation does not create false release failures.
+- Pin the marketplace MCP runtime launcher to the exact `codex-usage-tracking==0.5.0` package.
+
+## 0.4.1 - 2026-06-09
+
+- Harden the production PyPI workflow so manual publishing must run from `main` or a tag ref before artifacts are downloaded and uploaded.
+- Skip TestPyPI/PyPI uploads when the exact distribution version already exists on the target index, allowing a GitHub Release to be reconciled after a workflow-dispatch publish.
+- Strengthen `scripts/check_release.py` so it validates the publish-ref preflight inside both the TestPyPI and PyPI jobs.
+- Check off completed 1.0 readiness items with evidence for migration coverage, localhost dashboard smoke testing, and the protected GitHub `pypi` environment.
+- Pin the marketplace MCP runtime launcher to the exact `codex-usage-tracking==0.4.1` package.
+
 ## 0.4.0 - 2026-06-09
 
 - Add official Python 3.14 support across CI, package classifiers, README/install docs, and installed-package Docker smoke coverage.

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.4.0
+Version: 0.5.0
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -190,6 +190,34 @@ The tracker cannot read your logged-in ChatGPT plan or live remaining usage auto
 - Companion Codex skills for operational setup and conversational usage analysis.
 - Optional local pricing, Codex credit, allowance, threshold, project alias, and privacy-mode configuration.
 
+## Dashboard Language
+
+The dashboard supports localized UI text. English is the canonical catalog, and the project includes starter locale catalogs for common dashboard languages.
+
+Set the initial dashboard language with `--lang`:
+
+```bash
+codex-usage-tracker --lang vi serve-dashboard --open
+```
+
+Or set a default with:
+
+```bash
+CODEX_USAGE_TRACKER_LANG=vi codex-usage-tracker serve-dashboard --open
+```
+
+The dashboard also includes a language selector. Browser selections are stored locally and can override the generated default for that browser.
+
+Supported starter locales include English, Vietnamese, Spanish, French, German, Portuguese, Japanese, Simplified Chinese, Korean, Russian, Italian, and Arabic. This localizes dashboard UI text, not the full CLI output or data exports.
+
+### Adding A Dashboard Language
+
+1. Add a locale JSON file named by language code under `src/codex_usage_tracker/plugin_data/dashboard/locales/`.
+2. Include every key from the English catalog.
+3. Preserve every placeholder from the English string.
+4. Add the language code, native name, English name, and text direction to the supported language metadata.
+5. Run the i18n validation tests.
+
 ## Common Commands
 
 ```bash
@@ -253,10 +281,13 @@ This is optional. The normal shell install above is the fastest trusted path for
 ## Current Limitations
 
 - This is a sidecar dashboard and plugin, not a native Codex chat overlay.
+- Codex upstream log formats can change, and parser compatibility may require tracker updates.
 - Token counts come from Codex's logged counters; the tracker does not re-tokenize prompts.
-- Pricing and Codex credit estimates depend on local rate data and confidence labels.
-- Remaining 5-hour and weekly allowance is not read automatically from the logged-in account.
+- Pricing and rate-card sources can change outside this project.
+- Pricing and Codex credit estimates depend on local rate data and confidence labels and are not guaranteed to match exact billing.
+- Live account allowance cannot be read automatically by this local tracker; remaining 5-hour and weekly allowance is only available when you configure copied values.
 - Local Codex logs may not include usage from other ChatGPT agentic surfaces that share the same allowance.
+- Plugin discovery limitations are separate from core Python CLI/dashboard support.
 - Parent-child thread relationships are only as good as the metadata Codex logs; inferred auto-review attachments are labeled as inferred.
 
 ## Roadmap

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.5.0}/README.md

@@ -153,6 +153,34 @@ The tracker cannot read your logged-in ChatGPT plan or live remaining usage auto
 - Companion Codex skills for operational setup and conversational usage analysis.
 - Optional local pricing, Codex credit, allowance, threshold, project alias, and privacy-mode configuration.
 
+## Dashboard Language
+
+The dashboard supports localized UI text. English is the canonical catalog, and the project includes starter locale catalogs for common dashboard languages.
+
+Set the initial dashboard language with `--lang`:
+
+```bash
+codex-usage-tracker --lang vi serve-dashboard --open
+```
+
+Or set a default with:
+
+```bash
+CODEX_USAGE_TRACKER_LANG=vi codex-usage-tracker serve-dashboard --open
+```
+
+The dashboard also includes a language selector. Browser selections are stored locally and can override the generated default for that browser.
+
+Supported starter locales include English, Vietnamese, Spanish, French, German, Portuguese, Japanese, Simplified Chinese, Korean, Russian, Italian, and Arabic. This localizes dashboard UI text, not the full CLI output or data exports.
+
+### Adding A Dashboard Language
+
+1. Add a locale JSON file named by language code under `src/codex_usage_tracker/plugin_data/dashboard/locales/`.
+2. Include every key from the English catalog.
+3. Preserve every placeholder from the English string.
+4. Add the language code, native name, English name, and text direction to the supported language metadata.
+5. Run the i18n validation tests.
+
 ## Common Commands
 
 ```bash
@@ -216,10 +244,13 @@ This is optional. The normal shell install above is the fastest trusted path for
 ## Current Limitations
 
 - This is a sidecar dashboard and plugin, not a native Codex chat overlay.
+- Codex upstream log formats can change, and parser compatibility may require tracker updates.
 - Token counts come from Codex's logged counters; the tracker does not re-tokenize prompts.
-- Pricing and Codex credit estimates depend on local rate data and confidence labels.
-- Remaining 5-hour and weekly allowance is not read automatically from the logged-in account.
+- Pricing and rate-card sources can change outside this project.
+- Pricing and Codex credit estimates depend on local rate data and confidence labels and are not guaranteed to match exact billing.
+- Live account allowance cannot be read automatically by this local tracker; remaining 5-hour and weekly allowance is only available when you configure copied values.
 - Local Codex logs may not include usage from other ChatGPT agentic surfaces that share the same allowance.
+- Plugin discovery limitations are separate from core Python CLI/dashboard support.
 - Parent-child thread relationships are only as good as the metadata Codex logs; inferred auto-review attachments are labeled as inferred.
 
 ## Roadmap

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.5.0}/docs/cli-reference.md

@@ -4,6 +4,14 @@ This page lists the common command-line workflows. For tested JSON contract ids,
 
 ## Index And Setup
 
+Run first-time setup:
+
+```bash
+codex-usage-tracker setup
+```
+
+`setup` installs or refreshes the local plugin wrapper, initializes local config templates when needed, refreshes the aggregate index, runs `doctor`, and prints whether Codex needs a restart for plugin discovery.
+
 Refresh the local aggregate index:
 
 ```bash
@@ -27,6 +35,36 @@ codex-usage-tracker inspect-log ~/.codex/sessions/YYYY/MM/DD/rollout-...jsonl --
 
 `inspect-log` reports parser adapter, aggregate token-count events, session ids, models, and parser diagnostics. It does not store raw prompts, assistant messages, tool output, or transcript snippets.
 
+Check setup without writing files:
+
+```bash
+codex-usage-tracker doctor
+codex-usage-tracker doctor --suggest-repair
+```
+
+`doctor` validates local paths, database state, parser diagnostics, pricing and allowance config, dashboard output, plugin files, and MCP importability. `--suggest-repair` adds likely next commands without making changes.
+
+Reset only the local aggregate database:
+
+```bash
+codex-usage-tracker reset-db --yes
+```
+
+`reset-db` deletes tracker-owned aggregate SQLite rows. It does not delete raw Codex logs and requires `--yes`.
+
+## Plugin Lifecycle
+
+```bash
+codex-usage-tracker install-plugin
+codex-usage-tracker install-plugin --python .venv/bin/python
+codex-usage-tracker upgrade-plugin
+codex-usage-tracker uninstall-plugin
+```
+
+`install-plugin` writes the package-owned local Codex plugin wrapper, companion skills, and MCP config. Use the `--python` form for source checkouts that should use a repo-local virtual environment.
+
+`upgrade-plugin` refreshes an existing wrapper in place. `uninstall-plugin` removes only the tracker-owned plugin wrapper and marketplace entry.
+
 ## Dashboard
 
 ```bash
@@ -45,6 +83,8 @@ codex-usage-tracker serve-dashboard --no-context-api --open
 
 Dashboards default to active sessions only. Use `--include-archived` for an all-history static/opened dashboard, or switch the served dashboard's `History` control from `Active sessions only` to `All history` when you intentionally want archived logs scanned and included.
 
+Use global `--lang <code>` before the dashboard command, or set `CODEX_USAGE_TRACKER_LANG`, to choose the dashboard's initial UI language. The dashboard language selector can then override that default in the browser. Localization applies to dashboard UI text, not JSON fields, CSV columns, model names, thread names, paths, or full CLI output.
+
 The localhost `/api/usage` endpoint accepts `limit` and `offset` query parameters, so automation can page aggregate rows without asking the server to load an entire large history at once.
 
 ## Summaries
@@ -110,6 +150,14 @@ codex-usage-tracker export --output usage.csv --limit 0
 
 Use `--privacy-mode redacted` or `--privacy-mode strict` before sharing CSV output.
 
+## Support Bundle
+
+```bash
+codex-usage-tracker --privacy-mode strict support-bundle --output ~/.codex-usage-tracker/support-bundle.json
+```
+
+Support bundles are diagnostic summaries for issues. They include package, platform, doctor, schema, parser, pricing, allowance, threshold, project-config, and privacy metadata. They exclude raw logs, aggregate rows, prompts, assistant messages, tool output, and context text.
+
 ## Local Config
 
 ```bash
@@ -125,6 +173,16 @@ codex-usage-tracker init-projects
 
 Local config files live under `~/.codex-usage-tracker/` and are never committed by this project.
 
+Stable local config files:
+
+- `pricing.json`: schema `_schema: codex-usage-tracker-pricing-v1`, optional `_source`, `models`, `aliases`, and `_estimated_models`. `models` maps model labels to USD-per-million-token rates such as `input`, `cached_input`, and `output`.
+- `rate-card.json`: schema `codex-usage-tracker-codex-rate-card-v1`, optional `_source`, `credit_rates`, and `aliases`. `credit_rates` maps Codex model labels to credit rates for aggregate token counters.
+- `allowance.json`: schema `codex-usage-tracker-allowance-v1`, `windows`, optional `credit_rates`, and `aliases`. `windows` stores copied 5-hour, weekly, or other allowance snapshots such as `remaining_percent`, `reset_at`, `remaining_credits`, and `total_credits`.
+- `thresholds.json`: JSON object keyed by recommendation threshold names such as `low_cache_ratio`, `high_context_percent`, and `high_cost_usd`. Unknown keys are ignored.
+- `projects.json`: JSON object with `aliases`, `ignored_paths`, and `tags` for local project attribution.
+
+These config schemas are part of the 1.0 compatibility surface. New optional fields may be added, but existing meanings should not change without documentation and a compatibility plan.
+
 ## Privacy Mode
 
 `--privacy-mode` is a global option, so place it before the subcommand:

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.5.0}/docs/dashboard-guide.md

@@ -22,9 +22,9 @@ codex-usage-tracker init-allowance
 codex-usage-tracker parse-allowance "5h 79% 6:50 PM Weekly 33% Jun 7"
 ```
 
-To tune review thresholds locally, run `codex-usage-tracker init-thresholds` and edit `~/.codex-usage-tracker/thresholds.json`. These thresholds control low-cache, high-context, high-uncached-input, large-thread, reasoning-spike, low-output, and high-cost recommendations.
+To tune review thresholds locally, run `codex-usage-tracker init-thresholds` and edit `~/.codex-usage-tracker/thresholds.json`. This file is a JSON object keyed by recommendation threshold names such as `low_cache_ratio`, `high_context_percent`, and `high_cost_usd`; unknown keys are ignored. These thresholds control low-cache, high-context, high-uncached-input, large-thread, reasoning-spike, low-output, and high-cost recommendations.
 
-To tune project attribution locally, run `codex-usage-tracker init-projects` and edit `~/.codex-usage-tracker/projects.json`. The dashboard derives project name, relative cwd, branch, tags, and a hashed remote origin from aggregate `cwd` and local Git metadata when available.
+To tune project attribution locally, run `codex-usage-tracker init-projects` and edit `~/.codex-usage-tracker/projects.json`. This file supports `aliases`, `ignored_paths`, and `tags`. The dashboard derives project name, relative cwd, branch, tags, and a hashed remote origin from aggregate `cwd` and local Git metadata when available.
 
 Before sharing screenshots or generated artifacts, use `--privacy-mode redacted` or `--privacy-mode strict` before the subcommand:
 
@@ -37,6 +37,15 @@ Redacted mode hides raw cwd/source paths, hides Git remote labels, and hashes un
 
 `serve-dashboard` refreshes active-session logs before opening by default. Use `--no-refresh` only when you intentionally want a cached view of the existing local index.
 
+Set the initial dashboard language with the global `--lang` option before the command, or use `CODEX_USAGE_TRACKER_LANG`:
+
+```bash
+codex-usage-tracker --lang vi serve-dashboard --open
+CODEX_USAGE_TRACKER_LANG=vi codex-usage-tracker serve-dashboard --open
+```
+
+The dashboard language selector stores your browser preference locally. It localizes dashboard UI labels, captions, badges, empty states, detail-panel labels, context controls, and recommendation text; it does not translate raw data values, JSON fields, CSV columns, model names, thread names, project names, paths, or full CLI output.
+
 The server keeps the HTML aggregate-only and enables two live features:
 
 - `Refresh` rescans local Codex logs and updates the dashboard rows.

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.5.0}/docs/development.md

@@ -38,7 +38,7 @@ fix/<issue-number>-short-description
 docs/<issue-number>-short-description
 chore/<issue-number>-short-description
 test/<issue-number>-short-description
-release/0.4.0
+release/0.5.0
 hotfix/0.3.3
 ```
 
@@ -91,7 +91,7 @@ blocked
 Recommended milestones:
 
 ```text
-0.4.0
+0.5.0
 1.0-readiness
 1.0.0
 ```
@@ -147,10 +147,12 @@ python scripts/smoke_installed_package.py --docker
 To verify the public PyPI package instead of the local checkout:
 
 ```bash
-python scripts/smoke_installed_package.py --from-pypi --version 0.4.0
-python scripts/smoke_installed_package.py --docker --from-pypi --version 0.4.0
+python scripts/smoke_installed_package.py --from-pypi --version 0.5.0
+python scripts/smoke_installed_package.py --docker --from-pypi --version 0.5.0
 ```
 
+`scripts/check_release.py` treats these public-package smoke commands as release-state claims. Keep their `--version` and `codex-usage-tracking==...` values aligned with `pyproject.toml`; the release gate fails when the docs claim a different public version. It also checks that install docs point at the real PyPI distribution, `codex-usage-tracking`, and keep the warning that `codex-usage-tracker` is a different PyPI package.
+
 Docker avoids local toolchain side effects during install testing. Keep one local `pipx` smoke for platform-specific PATH and plugin-discovery behavior, but use Docker for repeatable Linux package verification.
 
 For documentation-only branches, at minimum run:
@@ -222,7 +224,7 @@ Tracked timings:
 | `pricing_coverage_seconds` | Pricing coverage report |
 | `project_summary_seconds` | Project summary report |
 
-The normal CI smoke uses a tiny synthetic history with `--enforce-thresholds` so regressions in the benchmark contract are visible on pull requests. The 10k/100k runs are a practical local gate for performance-sensitive changes; the 500k run is the release-sized gate and can take about a minute on a modern laptop because recommendations and project summary intentionally scan all aggregate rows.
+The normal CI smoke uses a tiny synthetic history with `--enforce-thresholds` and a small `--threshold-scale` allowance so coverage instrumentation and shared runner noise do not create false failures. The 10k/100k runs are a practical local gate for performance-sensitive changes; the 500k run is the release-sized gate and can take about a minute on a modern laptop because recommendations and project summary intentionally scan all aggregate rows.
 
 ## Release Checklist
 
@@ -264,8 +266,8 @@ After the release branch merges, tag from updated `main`, not from an unreviewed
 ```bash
 git switch main
 git pull --ff-only
-git tag -a v0.4.0 -m "codex-usage-tracker 0.4.0"
-git push origin v0.4.0
+git tag -a v0.5.0 -m "codex-usage-tracker 0.5.0"
+git push origin v0.5.0
 ```
 
 Do not create or push release tags without maintainer approval.
@@ -274,7 +276,7 @@ Do not create or push release tags without maintainer approval.
 
 Publishing uses GitHub Actions Trusted Publishing through `.github/workflows/publish.yml`; do not upload from a local machine and do not add PyPI or TestPyPI API tokens.
 
-The first public package release, `0.3.0`, was published on June 8, 2026. Patch release `0.3.1` followed the same day to ship the live-dashboard skill launch fix. Patch release `0.3.2` made dashboard launch refresh the default and added runtime enablement for context loading. Minor release `0.4.0` added Python 3.14 support, release recovery docs, stricter privacy/support-bundle regression coverage, and large-history benchmark thresholds:
+The first public package release, `0.3.0`, was published on June 8, 2026. Patch release `0.3.1` followed the same day to ship the live-dashboard skill launch fix. Patch release `0.3.2` made dashboard launch refresh the default and added runtime enablement for context loading. Minor release `0.4.0` added Python 3.14 support, release recovery docs, stricter privacy/support-bundle regression coverage, and large-history benchmark thresholds. Patch release `0.4.1` was published by workflow dispatch from `main`; it hardened the PyPI publish workflow and checked off completed 1.0 readiness gates. Minor release `0.5.0` added dashboard localization support and starter language catalogs.
 
 - GitHub Release: `https://github.com/douglasmonsky/codex-usage-tracker/releases/tag/v0.3.0`
 - GitHub Release: `https://github.com/douglasmonsky/codex-usage-tracker/releases/tag/v0.3.1`

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.5.0}/docs/install.md

@@ -38,6 +38,8 @@ By default the tracker looks for Codex JSONL logs under `~/.codex`, stores its o
 
 Windows support should work for the core dashboard/CLI when Codex writes readable JSONL logs, but plugin discovery is tied to Codex's local plugin directory behavior. Run `codex-usage-tracker doctor --suggest-repair` after setup if Codex does not show the plugin.
 
+Plugin discovery limitations are separate from core Python CLI/dashboard support. If Codex cannot discover the local plugin wrapper, the installed command, SQLite index, generated dashboard, localhost server, and CLI JSON reports can still work.
+
 ## Upgrade
 
 ```bash

codex_usage_tracking-0.5.0/docs/one-dot-oh-readiness.md

@@ -0,0 +1,228 @@
+# 1.0 Readiness
+
+This checklist tracks the work needed to move from the first public PyPI releases toward a stable 1.0 contract. Keep all verification data synthetic or aggregate-only.
+
+Each completed checkbox names the primary verification command inline. The evidence reference section at the end maps those commands to the concrete tests, scripts, workflow checks, or public-install smokes that prove the completed items.
+
+## Compatibility Promise
+
+- CLI command names documented in `docs/cli-reference.md` are stable after 1.0.
+- JSON schema IDs documented in `docs/cli-json-schemas.md` are stable after 1.0.
+- New JSON fields may be added in minor releases, but existing required fields should not be removed or change type without a new schema version.
+- MCP tool names and response schemas are stable after 1.0.
+- CSV export columns are stable after 1.0 unless a new export schema or version flag is introduced.
+- Config file schemas for pricing, allowance, thresholds, projects, and rate cards are stable after 1.0.
+- Privacy-mode semantics are stable after 1.0.
+- SQLite migrations must support upgrade from the last pre-1.0 release to 1.0.
+
+Not guaranteed:
+
+- Codex upstream log format stability.
+- OpenAI pricing or rate-card source stability.
+- Automatic access to live account allowance.
+- Exact billing equivalence.
+
+## 1. Public Install And Package Metadata
+
+- [x] Verify the current public PyPI version is visible as `0.5.0`: `python -c "import json, urllib.request; print(json.load(urllib.request.urlopen('https://pypi.org/pypi/codex-usage-tracking/json'))['info']['version'])"`.
+- [x] Verify public venv install for `0.5.0`: `python -m venv /tmp/codex-usage-pypi-smoke && . /tmp/codex-usage-pypi-smoke/bin/activate && python -m pip install codex-usage-tracking==0.5.0 && codex-usage-tracker --version`.
+- [x] Verify public pipx install path for `0.5.0`: `PIPX_HOME=/tmp/codex-usage-pipx-home PIPX_BIN_DIR=/tmp/codex-usage-pipx-bin pipx install codex-usage-tracking==0.5.0 && /tmp/codex-usage-pipx-bin/codex-usage-tracker --version`.
+- [x] Verify installed package resources from a built wheel: `python scripts/smoke_installed_package.py`.
+- [x] Verify installed package resources in Linux Docker: `python scripts/smoke_installed_package.py --docker`.
+- [x] Verify public PyPI package in Docker: `python scripts/smoke_installed_package.py --docker --from-pypi --version 0.5.0`.
+- [x] Verify PyPI metadata names remain unchanged: `python scripts/check_release.py`.
+- [x] Add Python 3.14 as an official support target after CI, package classifiers, docs, and installed-package smoke coverage were added. Docker smoke coverage uses `python:3.14-slim` by default. Track this in issue #12.
+
+## 2. Upgrade And Migration
+
+- [x] Add synthetic legacy SQLite fixture test proving `init_db` upgrades without data loss: `python -m pytest tests/test_store_migrations.py`.
+- [x] Reassess whether a synthetic v0.3-style SQLite fixture is required; the current legacy migration fixture covers active schema drift, so no separate v0.3 fixture is currently needed: `python -m pytest tests/test_store_migrations.py`.
+- [x] Verify `schema_state` reports expected version and checksum after migration: `python -m pytest tests/test_store_migrations.py`.
+- [x] Verify `rebuild-index` clears only tracker-owned aggregate tables: `python -m pytest tests/test_store_dashboard_mcp.py`.
+- [x] Verify `reset-db` does not touch raw Codex logs: `python -m pytest tests/test_cli_lifecycle.py`.
+- [x] Verify refresh metadata and parser diagnostics survive migration: `python -m pytest tests/test_store_migrations.py tests/test_parser.py`.
+- [x] Verify CSV export columns after migration: `python -m pytest tests/test_store_migrations.py`.
+
+## 3. CLI Compatibility
+
+- [x] Confirm every documented command in `docs/cli-reference.md` exists: `python -m pytest tests/test_cli_release.py`.
+- [x] Confirm no documented command is removed without a deprecation plan: manual diff review plus `python -m pytest tests/test_cli_release.py`.
+- [x] Verify command help works from an installed wheel: `python scripts/smoke_installed_package.py`.
+- [x] Verify lifecycle commands still return actionable errors without real logs: `python -m pytest tests/test_cli_lifecycle.py`.
+
+## 4. MCP Compatibility
+
+- [x] Verify MCP tool names remain documented in `docs/mcp.md`: `python -m pytest tests/test_cli_release.py`.
+- [x] Verify MCP JSON responses use tracked schema IDs where applicable: `python -m pytest tests/test_store_dashboard_mcp.py`.
+- [x] Verify companion skill packaged copy matches source skill: `python scripts/check_release.py`.
+- [x] Verify plugin installer writes MCP config from an installed wheel: `python scripts/smoke_installed_package.py`.
+
+## 5. JSON Contract Stability
+
+- [x] Verify every documented `--json` command has a tracked schema: `python -m pytest tests/test_json_contracts.py`.
+- [x] Verify every schema in `docs/cli-json-schemas.md` exists in `src/codex_usage_tracker/json_contracts.py`: `python -m pytest tests/test_json_contracts.py`.
+- [x] Verify every schema in `json_contracts.py` is documented: `python -m pytest tests/test_json_contracts.py`.
+- [x] Verify known payload examples pass `validate_json_payload_contract`: `python -m pytest tests/test_json_contracts.py`.
+- [x] Verify invalid or missing required fields fail contract validation: `python -m pytest tests/test_json_contracts.py`.
+- [x] Cover query, recommendations, summary, session, doctor, pricing-coverage, dashboard, export, support-bundle, and plugin lifecycle JSON payload contracts: `python -m pytest tests/test_json_contracts.py`.
+
+## 6. CSV Export Stability
+
+- [x] Verify expected CSV columns for aggregate exports: `python -m pytest tests/test_cli_lifecycle.py`.
+- [x] Verify redacted and strict privacy CSV exports omit private metadata: `python -m pytest tests/test_privacy.py`.
+- [x] Verify migration fixtures still export the expected CSV shape: `python -m pytest tests/test_store_migrations.py`.
+
+## 7. Config File Stability
+
+- [x] Verify pricing config initialization and parsing: `python -m pytest tests/test_pricing.py`.
+- [x] Verify allowance and rate-card config initialization and parsing: `python -m pytest tests/test_allowance.py`.
+- [x] Verify threshold config initialization and parsing: `python -m pytest tests/test_recommendations.py`.
+- [x] Verify project alias/tag config initialization and parsing: `python -m pytest tests/test_projects.py`.
+- [x] Document config schema changes before release: manual review of `docs/pricing-and-credits.md`, `docs/dashboard-guide.md`, and `docs/cli-reference.md`; enforced by `python -m pytest tests/test_cli_release.py`.
+
+## 8. Dashboard Behavior
+
+- [x] Verify dashboard aggregate payload remains raw-context-free: `python -m pytest tests/test_store_dashboard_mcp.py`.
+- [x] Verify dashboard URL state round trips: `python -m pytest tests/test_dashboard_state.py`.
+- [x] Verify dashboard formatting helpers: `node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard_format.js`.
+- [x] Verify dashboard data helpers: `node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard_data.js`.
+- [x] Verify active-history and all-history state labels: `python -m pytest tests/test_cli_release.py tests/test_store_dashboard_mcp.py`.
+- [x] Run a manual localhost dashboard smoke before release with temporary aggregate-only paths: `codex-usage-tracker serve-dashboard --open` plus `curl -fsS http://127.0.0.1:8897/dashboard.html`.
+
+## 9. Privacy And Sharing Safety
+
+- [x] Verify dashboard payloads in normal, redacted, and strict modes: `python -m pytest tests/test_privacy.py`.
+- [x] Verify query JSON in normal, redacted, and strict modes: `python -m pytest tests/test_privacy.py`.
+- [x] Verify session JSON in normal, redacted, and strict modes: `python -m pytest tests/test_privacy.py`.
+- [x] Verify CSV export in redacted and strict modes: `python -m pytest tests/test_privacy.py`.
+- [x] Verify strict mode does not leak raw cwd, source paths, branch, remote labels, project tags, or synthetic private project names: `python -m pytest tests/test_privacy.py`.
+- [x] Verify raw context fields never appear in SQLite, CSV, dashboard payloads, support bundles, generated static HTML, docs, or screenshots: `python -m pytest tests/test_privacy.py scripts/check_release.py`.
+
+## 10. Support-Bundle Safety
+
+- [x] Verify support bundles include package version, Python version, OS/platform, doctor status, schema state, parser diagnostics, pricing status, allowance status, threshold status, project config status, and privacy metadata: `python -m pytest tests/test_support.py`.
+- [x] Verify support bundles exclude raw logs, prompt text, assistant text, tool output, context text, and raw source paths in strict mode: `python -m pytest tests/test_support.py`.
+- [x] Update issue templates to request only strict-mode support bundles: `python scripts/check_release.py`.
+
+## 11. Large-History Performance
+
+- [x] Run synthetic 10k benchmark: `python scripts/benchmark_synthetic_history.py --rows 10000 --json --enforce-thresholds`.
+- [x] Run synthetic 100k benchmark: `python scripts/benchmark_synthetic_history.py --rows 100000 --json --enforce-thresholds`.
+- [x] Run synthetic 500k benchmark as a release gate when practical: `python scripts/benchmark_synthetic_history.py --rows 500000 --json --enforce-thresholds`.
+- [x] Define thresholds for active-only dashboard query, all-history dashboard query, since/until, model/effort, min_tokens, recommendations, pricing coverage, and project summary.
+- [x] Add a smaller CI-safe benchmark if it can stay fast and deterministic.
+
+## 12. Release Process
+
+- [x] Verify publish workflow publishes `codex-usage-tracking`, not `codex-usage-tracker`: `python scripts/check_release.py`.
+- [x] Verify publish workflow uses Trusted Publishing, not API tokens: `python scripts/check_release.py`.
+- [x] Verify TestPyPI and PyPI jobs exist and publish only on workflow dispatch or release events: `python scripts/check_release.py`.
+- [x] Verify manual PyPI workflow dispatch is restricted to `main` or tag refs: `python scripts/check_release.py`.
+- [x] Verify PyPI job is gated by environment `pypi`: `gh api repos/douglasmonsky/codex-usage-tracker/environments/pypi`.
+- [x] Verify dist filenames match `codex_usage_tracking`: `python -m build && python scripts/check_release.py --dist`.
+- [x] Verify TestPyPI process: run `Publish Python package` with `target=testpypi` only when intentionally testing release publication.
+- [x] Verify PyPI process: publish a GitHub Release or run workflow dispatch with `target=pypi` only when intentionally publishing a reviewed release.
+- [x] Document release recovery by cutting a new patch version when an uploaded artifact is wrong: see `docs/development.md`.
+
+## 13. Known Limitations
+
+- [x] Document that Codex upstream log formats can change and parser compatibility may require updates.
+- [x] Document that pricing and rate-card sources can change outside this project.
+- [x] Document that live account allowance cannot be read automatically by this local tracker.
+- [x] Document that cost and credit estimates are not guaranteed to match exact billing.
+- [x] Document platform/plugin discovery limitations separately from the core Python CLI/dashboard support.
+
+## Evidence References
+
+These references are the concrete proof behind completed checklist items. Public package smoke commands are version-specific to `0.5.0`; all repo tests use synthetic or aggregate-only data.
+
+### Public Install And Package Metadata
+
+- Public PyPI version, public venv install, and public pipx install are proven by the exact public-install commands in section 1.
+- Built-wheel and installed-resource coverage is proven by `scripts/smoke_installed_package.py` and `tests/test_cli_release.py::test_installed_package_smoke_checks_help_for_stable_commands`.
+- Linux package-resource coverage is proven by `scripts/smoke_installed_package.py --docker`.
+- Public PyPI Docker coverage is proven by `scripts/smoke_installed_package.py --docker --from-pypi --version 0.5.0`.
+- PyPI metadata, package/distribution names, package resources, source/wheel member names, Python 3.10-3.14 support metadata, CI workflow requirements, publish workflow safety text, and tracked secret patterns are proven by `scripts/check_release.py`, `scripts/check_release.py --dist`, and `tests/test_cli_release.py::test_release_check_script_passes`.
+
+### Upgrade And Migration
+
+- Legacy SQLite migration, schema state, migration idempotence, malformed legacy schema handling, and migration CSV shape are proven by `tests/test_store_migrations.py`.
+- The v0.3 fixture decision is covered by `tests/test_store_migrations.py`; no additional v0.3-specific fixture is currently required because the active pre-1.0 migration path is already represented by the legacy fixture.
+- `rebuild-index` clearing only tracker-owned aggregate rows is proven by `tests/test_store_dashboard_mcp.py::test_rebuild_index_clears_aggregate_rows_before_rescan`.
+- `reset-db` preserving raw Codex logs is proven by `tests/test_cli_lifecycle.py::test_setup_support_bundle_and_reset_db_cli`.
+- Refresh metadata and parser diagnostics are proven by `tests/test_store_migrations.py`, `tests/test_parser.py`, and `tests/test_store_dashboard_mcp.py::test_refresh_reports_skipped_corrupt_token_events`.
+
+### CLI Compatibility
+
+- Documented CLI command existence and stable command coverage are proven by `tests/test_cli_release.py::test_cli_reference_documents_only_existing_stable_commands` and `tests/test_cli_release.py::test_stable_cli_commands_are_not_removed_without_a_deprecation_plan`.
+- Installed-wheel subcommand help coverage is proven by `scripts/smoke_installed_package.py` and guarded by `tests/test_cli_release.py::test_installed_package_smoke_checks_help_for_stable_commands`.
+- Lifecycle actionable errors without real logs are proven by `tests/test_cli_lifecycle.py::test_lifecycle_commands_return_actionable_errors_without_real_logs`.
+
+### MCP Compatibility
+
+- MCP tool documentation parity is proven by `tests/test_cli_release.py::test_mcp_tool_names_remain_documented`.
+- MCP JSON response schema IDs and wrapper payload contracts are proven by `tests/test_store_dashboard_mcp.py::test_mcp_wrappers_smoke`.
+- Companion skill source/package parity is proven by `scripts/check_release.py`.
+- Installed-wheel plugin MCP config is proven by `scripts/smoke_installed_package.py`.
+
+### JSON Contract Stability
+
+- Documented schema table parity, runtime schema ID tracking, example validation, invalid-payload rejection, and minimal payload validation are proven by `tests/test_json_contracts.py`.
+- README and CLI schema doc references are additionally guarded by `tests/test_cli_release.py::test_cli_json_schema_doc_lists_tracked_contracts`.
+
+### CSV Export Stability
+
+- Aggregate CSV columns are proven by `tests/test_cli_lifecycle.py::test_report_json_and_query_cli`.
+- Redacted and strict privacy CSV behavior is proven by `tests/test_privacy.py::test_privacy_modes_cover_dashboard_query_session_and_csv` and `tests/test_privacy.py::test_aggregate_outputs_exclude_raw_transcript_content`.
+- Migration CSV shape is proven by `tests/test_store_migrations.py::test_csv_export_keeps_current_columns_after_legacy_migration`.
+
+### Config File Stability
+
+- Pricing config initialization and parsing are proven by `tests/test_pricing.py` and `tests/test_cli_lifecycle.py::test_rate_card_allowance_and_pricing_snapshot_cli`.
+- Allowance and Codex rate-card config initialization/parsing are proven by `tests/test_allowance.py` and `tests/test_cli_lifecycle.py::test_rate_card_allowance_and_pricing_snapshot_cli`.
+- Threshold config initialization/parsing is proven by `tests/test_recommendations.py::test_threshold_template_and_overrides`.
+- Project alias, ignored-path, tag, and privacy behavior is proven by `tests/test_projects.py`.
+- Config schema documentation coverage is proven by `tests/test_cli_release.py::test_local_config_schema_docs_reference_stable_fields`.
+
+### Dashboard Behavior
+
+- Aggregate-only dashboard payloads and CSV are proven by `tests/test_store_dashboard_mcp.py::test_dashboard_and_csv_are_aggregate_only` and `tests/test_privacy.py::test_aggregate_outputs_exclude_raw_transcript_content`.
+- URL-state round trips are proven by `tests/test_dashboard_state.py::test_dashboard_url_state_round_trips`.
+- Dashboard helper syntax is proven by the `node --check` commands in section 8 and the CI dashboard JavaScript syntax job.
+- Active/all-history payload behavior is proven by `tests/test_store_dashboard_mcp.py::test_dashboard_history_scope_excludes_archived_rows_by_default` and `tests/test_store_dashboard_mcp.py::test_dashboard_server_usage_api_switches_history_scope`.
+- Active/all-history user-facing labels are proven by `tests/test_cli_release.py::test_dashboard_history_scope_labels_remain_user_facing`.
+- No-context startup and runtime context enablement are proven by `tests/test_store_dashboard_mcp.py::test_dashboard_server_can_enable_context_api_at_runtime` and `tests/test_privacy.py::test_context_server_requires_loopback_origin_token_and_enablement`.
+- Manual localhost smoke is proven by running `codex-usage-tracker serve-dashboard --open` against temporary database, config, output, and Codex-home paths on `127.0.0.1:8897`, then probing `/dashboard.html` with `curl -fsS`.
+
+### Privacy And Sharing Safety
+
+- Dashboard, query, session, CSV, support-bundle, and generated-static-HTML privacy behavior is proven by `tests/test_privacy.py`.
+- Strict project metadata redaction is proven by `tests/test_privacy.py::test_privacy_modes_cover_dashboard_query_session_and_csv` and `tests/test_projects.py::test_project_privacy_modes_redact_sensitive_metadata`.
+- Raw context exclusion and explicit context loading are proven by `tests/test_privacy.py::test_context_loading_is_explicit_redacted_and_not_static_html`, `tests/test_privacy.py::test_context_server_requires_loopback_origin_token_and_enablement`, and `tests/test_store_dashboard_mcp.py::test_context_loads_raw_log_only_on_demand`.
+- Tracked-file secret scanning is proven by `scripts/check_release.py`.
+
+### Support-Bundle Safety
+
+- Support-bundle payload shape and secret safety are proven by `tests/test_support.py::test_support_bundle_default_mode_contract_and_secret_safety`.
+- Strict support-bundle path and doctor-text redaction is proven by `tests/test_support.py::test_support_bundle_strict_mode_redacts_local_paths_and_doctor_text`.
+- Safe issue-template requests are proven by `scripts/check_release.py`.
+
+### Large-History Performance
+
+- Benchmark command behavior and threshold contract are smoke-tested by `tests/test_cli_release.py::test_synthetic_history_benchmark_script_smoke`.
+- Release-size 10k, 100k, and 500k benchmark claims are proven by running `python scripts/benchmark_synthetic_history.py --rows 10000 100000 500000 --json --enforce-thresholds` before release work when practical.
+- CI-safe benchmark coverage is proven by the CI `Release readiness` job through `tests/test_cli_release.py::test_synthetic_history_benchmark_script_smoke`, using a small `--threshold-scale` allowance for coverage instrumentation and shared runner noise.
+
+### Release Process
+
+- Normal CI package build plus `twine check` and dist verification are proven by `.github/workflows/ci.yml` and enforced by `scripts/check_release.py::_check_ci_workflow`.
+- Publish workflow package name, Trusted Publishing, TestPyPI/PyPI job presence, event guards, no push/PR publishing, no token/password publishing, and manual PyPI main/tag preflight are proven by `scripts/check_release.py::_check_publish_workflow`.
+- The GitHub `pypi` environment gate is proven by `gh api repos/douglasmonsky/codex-usage-tracker/environments/pypi`, which reports a `required_reviewers` protection rule and `can_admins_bypass=false`.
+- Dist filename and wheel/sdist member checks are proven by `python -m build`, `python -m twine check dist/*`, and `python scripts/check_release.py --dist`.
+- TestPyPI publish process is proven by a workflow-dispatch run on `main`, followed by TestPyPI metadata and clean virtualenv install checks for `codex-usage-tracking==0.5.0`.
+- PyPI publish process is proven by a workflow-dispatch run on `main`, protected `pypi` environment approval, PyPI metadata visibility, clean virtualenv install, temporary pipx install, and Docker public-package smoke for `codex-usage-tracking==0.5.0`.
+- Release recovery documentation is proven by `scripts/check_release.py` required-file and docs checks.
+
+### Known Limitations
+
+- Parser-format drift, pricing/rate-card drift, live allowance, non-billing-equivalence, and plugin-discovery boundary documentation are proven by `tests/test_cli_release.py::test_known_limitations_are_documented`.

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.5.0}/docs/pricing-and-credits.md

@@ -83,8 +83,11 @@ Configure the usage component:
 
 ## Accuracy Notes
 
+- Codex upstream log formats can change, and parser compatibility may require tracker updates before new event shapes are fully understood.
+- Pricing and rate-card sources can change outside this project. Refresh or pin local files when reports need a known source snapshot.
 - Local Codex logs may not include usage from other ChatGPT agentic surfaces that share the same allowance.
-- The dashboard does not infer live remaining allowance from the logged-in account plan.
+- Live account allowance cannot be read automatically by this local tracker, and the dashboard does not infer live remaining allowance from the logged-in account plan.
 - Pricing can change after a report is generated. Use `pin-pricing` when you need reproducible historical cost estimates.
 - Rows with direct model/rate-card matches are more trustworthy than inferred aliases or local overrides.
 - Cost and credit calculations use aggregate counters; the tracker does not re-tokenize prompts or reconstruct usage from raw text.
+- Cost and credit estimates are not guaranteed to match exact billing.

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-usage-tracking"
-version = "0.4.0"
+version = "0.5.0"
 description = "Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -62,6 +62,7 @@ where = ["src"]
 "codex_usage_tracker.plugin_data" = [
   "assets/*",
   "dashboard/*",
+  "dashboard/locales/*",
   "docs/*",
   "docs/assets/*",
   "rate_cards/*",