codex-usage-tracking 0.3.2__tar.gz → 0.4.1__tar.gz

{codex_usage_tracking-0.3.2 → codex_usage_tracking-0.4.1}/.codex-plugin/plugin.json

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

{codex_usage_tracking-0.3.2 → codex_usage_tracking-0.4.1}/AGENTS.md

@@ -47,9 +47,94 @@ python -m pip install ".[dev]" twine
 codex-usage-tracker install-plugin --python .venv/bin/python
 ```
 
+## Branch And PR Workflow
+
+This project is now a published PyPI package with user-facing docs, JSON/MCP contracts, a release workflow, and privacy guarantees. Treat `main` as always releasable.
+
+- Do not commit directly to `main`.
+- Start each coherent task from current `main` with a short-lived branch.
+- Use branch prefixes `feature/`, `fix/`, `docs/`, `chore/`, `test/`, `release/`, or `hotfix/`.
+- Keep each branch focused on one issue, one reviewable task, or one release.
+- Do not create a long-lived `develop` branch.
+- Do not mix release prep with unrelated feature work.
+- Push task branches and open a PR for all changes headed to `main`.
+- Prefer squash merge for ordinary task PRs so `main` stays readable.
+- Use the PR as the review artifact even when there is only one maintainer.
+
+Recommended branch names:
+
+```text
+feature/<issue-number>-short-description
+fix/<issue-number>-short-description
+docs/<issue-number>-short-description
+chore/<issue-number>-short-description
+test/<issue-number>-short-description
+release/0.4.0
+hotfix/0.3.3
+```
+
+Before starting a task branch:
+
+```bash
+git switch main
+git pull --ff-only
+git switch -c docs/123-short-description
+```
+
+## Agent Boundaries
+
+Codex may create task branches, write tests, update docs, run local gates, prepare PR summaries, prepare release branches, and prepare changelog/version changes.
+
+Codex must not do these without explicit maintainer approval:
+
+- Push directly to `main`.
+- Create or push release tags.
+- Publish to TestPyPI or PyPI.
+- Add PyPI or TestPyPI API tokens.
+- Publish from a local machine.
+- Change privacy semantics.
+- Rename the PyPI distribution, import package, CLI command, plugin name, MCP tools, schema IDs, or stable JSON contracts.
+- Delete branches.
+- Force-push shared branches.
+
+Publishing must happen only through the approved GitHub Actions Trusted Publishing workflow and protected `testpypi`/`pypi` environments.
+
+## Issue And Milestone Workflow
+
+Use GitHub issues as the normal unit of work once the task is non-trivial. A branch should usually map to one issue and close it from the PR.
+
+Recommended labels:
+
+```text
+bug
+docs
+packaging
+release
+privacy
+security
+performance
+dashboard
+cli
+mcp
+parser-compat
+good-first-issue
+blocked
+1.0-blocker
+```
+
+Recommended milestones:
+
+```text
+0.4.0
+1.0-readiness
+1.0.0
+```
+
+Use patch releases for public blockers such as broken PyPI installs, missing package data, broken CLI entry points, privacy leaks, bad plugin installs, or bad runtime pins. Put planned stabilization work into the next minor release instead of bundling it into a patch.
+
 ## Validation
 
-Run the local CI gate before pushing to `main`:
+Run focused tests first, then broader checks. Run the full local CI gate before opening or updating PRs that touch release, packaging, CLI contracts, MCP behavior, dashboard behavior, privacy behavior, schemas, generated docs/assets, or bundled plugin/skill files.
 
 ```bash
 python -m ruff check .
@@ -79,6 +164,7 @@ node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard_state.js
 python -m build
 python scripts/check_release.py --dist
 git diff --check
+python scripts/smoke_installed_package.py
 codex-usage-tracker update-pricing --output /tmp/codex-usage-pricing.json
 codex-usage-tracker update-rate-card --output /tmp/codex-usage-rate-card.json
 codex-usage-tracker doctor
@@ -95,6 +181,65 @@ codex-usage-tracker summary --preset by-subagent-role
 codex-usage-tracker expensive --limit 5
 ```
 
+For documentation-only branches, at minimum run:
+
+```bash
+python scripts/check_release.py
+git diff --check
+```
+
+## Release Branches
+
+Use release branches only for version/changelog/pinning/publish prep, for example `release/0.4.0` or `hotfix/0.3.3`.
+
+Release branches may include:
+
+- Version bumps.
+- `CHANGELOG.md` updates.
+- Install/version wording updates.
+- Runtime package pins.
+- Publish workflow tweaks.
+- Release notes.
+- Final smoke-test fixes directly tied to release readiness.
+
+Release branches must not include unrelated features.
+
+Recommended release sequence:
+
+```bash
+git switch main
+git pull --ff-only
+git switch -c release/0.4.0
+# version/changelog/release edits
+python -m ruff check .
+python -m mypy
+python -m pytest
+python -m pytest --cov=codex_usage_tracker --cov-report=term-missing
+python -m compileall src
+node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard_format.js
+node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard_data.js
+node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard.js
+node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard_state.js
+python scripts/check_release.py
+git diff --check
+rm -rf dist build src/codex_usage_tracker.egg-info src/codex_usage_tracking.egg-info
+python -m build
+python -m twine check dist/*
+python scripts/check_release.py --dist
+git add .
+git commit -m "Prepare 0.4.0 release"
+git push -u origin release/0.4.0
+```
+
+Open a PR to `main` and merge only after CI passes. After merge, tag from updated `main`, not from an unreviewed release branch, and only after explicit maintainer approval:
+
+```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
+```
+
 ## Privacy Rules
 
 - Never commit real Codex session logs.

{codex_usage_tracking-0.3.2 → codex_usage_tracking-0.4.1}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 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.
+- 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.
+- Add a release recovery runbook for failed publish workflows, stale PyPI/TestPyPI pages, Trusted Publishing issues, bad artifacts, and patch-forward recovery.
+- Add synthetic large-history benchmark thresholds for active/all-history dashboard queries, date filtering, model/effort filtering, recommendations, pricing coverage, and project summaries.
+- Add stricter privacy regression coverage for generated dashboards, CSV exports, API payloads, and support bundles.
+- Redact sensitive strings and local diagnostic paths in support bundles, including nested doctor output in redacted and strict privacy modes.
+- Add aggregate schema migration, JSON contract parity, installed-package smoke, and protected-main workflow readiness coverage.
+- Pin the marketplace MCP runtime launcher to the exact `codex-usage-tracking==0.4.0` package.
+
 ## 0.3.2 - 2026-06-08
 
 - Make `open-dashboard` and `serve-dashboard` refresh active-session logs by default, with `--no-refresh` as the explicit cached-index mode.

{codex_usage_tracking-0.3.2 → codex_usage_tracking-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.3.2
+Version: 0.4.1
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Monitoring
 Requires-Python: >=3.10
@@ -45,7 +46,7 @@ Local-first dashboard, Codex plugin, and companion skill for understanding where
 
 [![CI](https://github.com/douglasmonsky/codex-usage-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/douglasmonsky/codex-usage-tracker/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/codex-usage-tracking.svg)](https://pypi.org/project/codex-usage-tracking/)
-![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-blue)
+![Python 3.10-3.14](https://img.shields.io/badge/python-3.10--3.14-blue)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 > **Unofficial project:** Codex Usage Tracker is an independent open-source project. It is not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. OpenAI and Codex are trademarks of OpenAI; this project only reads local log files from your machine.
@@ -67,6 +68,7 @@ codex-usage-tracker serve-dashboard --open
 ```
 
 Use your normal Python launcher for your platform: `python3` is common on macOS/Linux, and `py` may be preferable on Windows. On macOS with Homebrew, `brew install pipx` is also fine.
+If `codex-usage-tracker` is not found after installing with pipx, open a new terminal or add the binary directory printed by `pipx ensurepath` to your `PATH`.
 
 `serve-dashboard` refreshes active-session usage before opening by default. Use `--no-refresh` only when you intentionally want to inspect the cached local index.
 
@@ -98,7 +100,7 @@ More install paths: [Install Guide](docs/install.md).
 
 ## Platform Support
 
-The core app is not macOS-only. The CLI, SQLite index, dashboard generator, and localhost server are Python-based and CI-tested on Ubuntu for Python 3.10-3.13. It defaults to `~/.codex` for local Codex logs and `~/.codex-usage-tracker` for tracker data; pass `--codex-home` or `--db` when your local layout differs. Codex plugin discovery depends on Codex's local plugin directories on your machine, so run `codex-usage-tracker doctor` after setup if plugin registration does not appear in Codex.
+The core app is not macOS-only. The CLI, SQLite index, dashboard generator, and localhost server are Python-based and CI-tested on Ubuntu for Python 3.10-3.14. The installed-package Docker smoke path uses `python:3.14-slim` by default so packaged resources and CLI entry points are exercised on the newest supported runtime. It defaults to `~/.codex` for local Codex logs and `~/.codex-usage-tracker` for tracker data; pass `--codex-home` or `--db` when your local layout differs. Codex plugin discovery depends on Codex's local plugin directories on your machine, so run `codex-usage-tracker doctor` after setup if plugin registration does not appear in Codex.
 
 ## Dashboard Preview
 
@@ -251,14 +253,18 @@ 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
 
+- Keep Python runtime support validated with CI matrix coverage, package classifiers, release docs, and installed-package smoke tests.
 - Improve the `Set limits` flow with a paste/import experience for 5-hour and weekly allowance snapshots.
 - Track allowance snapshot history so local Codex credits can be compared against visible remaining-usage changes over time.
 - Clarify top-card token accounting by showing output tokens and reasoning output as a subset instead of implying all token cards add together.

{codex_usage_tracking-0.3.2 → codex_usage_tracking-0.4.1}/README.md

@@ -9,7 +9,7 @@ Local-first dashboard, Codex plugin, and companion skill for understanding where
 
 [![CI](https://github.com/douglasmonsky/codex-usage-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/douglasmonsky/codex-usage-tracker/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/codex-usage-tracking.svg)](https://pypi.org/project/codex-usage-tracking/)
-![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-blue)
+![Python 3.10-3.14](https://img.shields.io/badge/python-3.10--3.14-blue)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 > **Unofficial project:** Codex Usage Tracker is an independent open-source project. It is not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. OpenAI and Codex are trademarks of OpenAI; this project only reads local log files from your machine.
@@ -31,6 +31,7 @@ codex-usage-tracker serve-dashboard --open
 ```
 
 Use your normal Python launcher for your platform: `python3` is common on macOS/Linux, and `py` may be preferable on Windows. On macOS with Homebrew, `brew install pipx` is also fine.
+If `codex-usage-tracker` is not found after installing with pipx, open a new terminal or add the binary directory printed by `pipx ensurepath` to your `PATH`.
 
 `serve-dashboard` refreshes active-session usage before opening by default. Use `--no-refresh` only when you intentionally want to inspect the cached local index.
 
@@ -62,7 +63,7 @@ More install paths: [Install Guide](docs/install.md).
 
 ## Platform Support
 
-The core app is not macOS-only. The CLI, SQLite index, dashboard generator, and localhost server are Python-based and CI-tested on Ubuntu for Python 3.10-3.13. It defaults to `~/.codex` for local Codex logs and `~/.codex-usage-tracker` for tracker data; pass `--codex-home` or `--db` when your local layout differs. Codex plugin discovery depends on Codex's local plugin directories on your machine, so run `codex-usage-tracker doctor` after setup if plugin registration does not appear in Codex.
+The core app is not macOS-only. The CLI, SQLite index, dashboard generator, and localhost server are Python-based and CI-tested on Ubuntu for Python 3.10-3.14. The installed-package Docker smoke path uses `python:3.14-slim` by default so packaged resources and CLI entry points are exercised on the newest supported runtime. It defaults to `~/.codex` for local Codex logs and `~/.codex-usage-tracker` for tracker data; pass `--codex-home` or `--db` when your local layout differs. Codex plugin discovery depends on Codex's local plugin directories on your machine, so run `codex-usage-tracker doctor` after setup if plugin registration does not appear in Codex.
 
 ## Dashboard Preview
 
@@ -215,14 +216,18 @@ 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
 
+- Keep Python runtime support validated with CI matrix coverage, package classifiers, release docs, and installed-package smoke tests.
 - Improve the `Set limits` flow with a paste/import experience for 5-hour and weekly allowance snapshots.
 - Track allowance snapshot history so local Codex credits can be compared against visible remaining-usage changes over time.
 - Clarify top-card token accounting by showing output tokens and reasoning output as a subset instead of implying all token cards add together.

{codex_usage_tracking-0.3.2 → codex_usage_tracking-0.4.1}/docs/architecture.md

@@ -15,7 +15,7 @@ Codex Usage Tracker is a local sidecar app. It reads aggregate token counters fr
 - `plugin_data/dashboard/dashboard_format.js` owns dashboard formatting primitives. `dashboard_data.js` owns row payload and thread relationship helpers. `dashboard_state.js` owns URL, CSV, and download state utilities. `dashboard.js` owns DOM rendering, event handling, API refresh, and detail-panel behavior.
 - `context.py` is the only normal path that reads raw log context, and it does so only for one selected record on demand with redaction and size limits.
 - `plugin_installer.py`, `.mcp.json`, `skills/`, and `scripts/check_release.py` own install and packaging behavior.
-- `scripts/benchmark_synthetic_history.py` owns generated large-history query timing for 10k, 100k, and 500k aggregate-row fixtures. It must stay synthetic-only and must not read real Codex logs.
+- `scripts/benchmark_synthetic_history.py` owns generated large-history query timing and threshold enforcement for 10k, 100k, and 500k aggregate-row fixtures. It must stay synthetic-only and must not read real Codex logs.
 - `skills/codex-usage-tracker/` is the source copy for the operational Codex skill. It should stay focused on setup, dashboard, export, doctor, and direct MCP workflows.
 - `skills/codex-usage-api/` is the source copy for the conversational analyst skill. It should stay focused on aggregate-only API routing, interpretation, and limitations.
 - `src/codex_usage_tracker/plugin_data/skills/` contains the wheel-bundled copies installed by `codex-usage-tracker install-plugin`.
@@ -50,4 +50,4 @@ git diff --check
 
 Dashboard UI changes should also be opened in a browser and checked on desktop and mobile widths for overlap, stale state, and aggregate-only output.
 
-Run `python scripts/benchmark_synthetic_history.py --rows 10000 100000 500000` after changing SQLite filters, dashboard payload loading, or indexes.
+Run `python scripts/benchmark_synthetic_history.py --rows 10000 100000 --json --enforce-thresholds` after changing SQLite filters, dashboard payload loading, or indexes. Run the 500k benchmark before release work when practical.

{codex_usage_tracking-0.3.2 → codex_usage_tracking-0.4.1}/docs/cli-json-schemas.md

@@ -1,6 +1,6 @@
-# CLI and MCP JSON Schemas
+# CLI, MCP, and Dashboard JSON Schemas
 
-Codex Usage Tracker exposes aggregate-only JSON for automation through CLI `--json` flags and MCP tools. These payloads do not include prompts, assistant messages, tool output, or raw transcript snippets.
+Codex Usage Tracker exposes aggregate-only JSON for automation through CLI `--json` flags, MCP tools, and the local dashboard server API. These payloads do not include prompts, assistant messages, tool output, or raw transcript snippets.
 
 ## Companion Skill Usage
 
@@ -24,6 +24,13 @@ Use the global `--privacy-mode redacted` or `--privacy-mode strict` option, or t
 
 Stable payload contracts are tracked in `codex_usage_tracker.json_contracts` and covered by tests. Every stable payload includes a top-level `schema` string so agents can distinguish compatible responses from markdown, disabled-context responses, or future versions.
 
+Compatibility rules before 1.0:
+
+- Additive fields are allowed when they do not change documented field types or privacy semantics.
+- Removing a documented schema, removing a required field, changing a required field type, or changing privacy behavior requires either a new schema id or an explicit pre-1.0 migration note.
+- After 1.0, breaking payload changes require a new schema id.
+- Config-file schemas such as pricing, allowance, and rate-card JSON are tracked separately from runtime CLI/MCP/dashboard payload schemas.
+
 Tracked schema ids:
 
 | Schema | Surface |
@@ -42,6 +49,7 @@ Tracked schema ids:
 | `codex-usage-tracker-session-v1` | CLI `session --json`, MCP `session_usage(response_format="json")` |
 | `codex-usage-tracker-context-v1` | CLI `context`, MCP `usage_call_context` when raw context is explicitly enabled |
 | `codex-usage-tracker-context-disabled-v1` | MCP `usage_call_context` when raw context is disabled |
+| `codex-usage-tracker-context-settings-v1` | Dashboard server `/api/context-settings` response |
 | `codex-usage-tracker-dashboard-v1` | CLI `dashboard --json`, MCP `generate_usage_dashboard()` |
 | `codex-usage-tracker-open-dashboard-v1` | CLI `open-dashboard --json` |
 | `codex-usage-tracker-serve-dashboard-v1` | CLI `serve-dashboard --json` startup payload |

{codex_usage_tracking-0.3.2 → codex_usage_tracking-0.4.1}/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
@@ -110,6 +148,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 +171,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.3.2 → codex_usage_tracking-0.4.1}/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: