codex-usage-tracking 0.15.0__tar.gz → 0.16.0__tar.gz

{codex_usage_tracking-0.15.0 → codex_usage_tracking-0.16.0}/.codex-plugin/plugin.json

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

{codex_usage_tracking-0.15.0 → codex_usage_tracking-0.16.0}/AGENTS.md

@@ -242,9 +242,9 @@ git push origin v0.4.0
 ## Privacy Rules
 
 - Never commit real Codex session logs.
-- Never store raw prompts, assistant text, tool outputs, pasted secrets, or message snippets.
-- Raw context may be read only on demand from original local JSONL files; never persist it to SQLite, CSV, generated HTML, fixtures based on real logs, or commits.
-- Store only selected aggregate session metadata for subagents, including parent thread labels; do not persist raw session instructions or source JSON.
+- Never commit real prompts, assistant text, tool outputs, pasted secrets, message snippets, or raw Codex logs.
+- The local content index may store bounded snippets in the user-owned SQLite database by approved design. Do not expose indexed/raw content through default CSV, generated HTML, support bundles, screenshots, aggregate JSON, fixtures based on real logs, or commits.
+- Raw context may be read during refresh/content indexing or explicit selected-call context loading. Keep shareable outputs aggregate-first unless a command is explicitly documented as a local raw/content export.
 - Keep fixture data synthetic.
 - Keep local SQLite databases, CSV exports, HTML dashboards, caches, and virtualenvs out of git.
 - Do not hard-code real current USD model pricing in source; refresh the local config from OpenAI's published pricing docs or use manual local overrides. Internal Codex model estimates must be explicitly marked as estimates with source and rationale metadata.
@@ -252,10 +252,10 @@ git push origin v0.4.0
 
 ## Definition Of Done
 
-- Parser handles synthetic session logs without reading raw message content.
+- Parser and content-index handling are covered by synthetic session logs.
 - SQLite refresh is idempotent.
-- MCP tool functions return concise aggregate data.
-- Dashboard is generated from aggregate-only JSON.
+- MCP tool functions return concise aggregate data by default; content-aware tools must be explicit local investigation surfaces.
+- Dashboard generated HTML is aggregate-first and does not embed indexed/raw content.
 - Doctor, summary presets, dashboard, and expensive-call views work from CLI and MCP wrappers.
 - `codex-usage-tracker install-plugin` can register the installed package without relying on a source-checkout symlink.
 - `python -m codex_usage_tracker` and `codex-usage-tracker --version` both work.
@@ -263,8 +263,8 @@ git push origin v0.4.0
 - `scripts/check_release.py --dist` passes before any public release.
 - Pricing coverage clearly separates configured, estimated, and unpriced model usage.
 - Codex credit coverage clearly separates exact rate-card matches, inferred aliases, and missing credit rates.
-- Dashboard Calls and Threads views share filters, totals, and aggregate-only hover details.
+- Dashboard Calls and Threads views share filters, totals, and aggregate-first hover details.
 - Dashboard usage docs are updated when the visible dashboard workflow changes, and screenshots must be generated from synthetic data only.
-- Dashboard aggregate refresh is localhost-only and keeps generated HTML aggregate-only; context loading is lazy, localhost-only, explicit, redacted, and not embedded in the static HTML payload.
+- Dashboard refresh is localhost-only, generated HTML stays aggregate-first, and context loading is lazy, localhost-only, explicit, redacted, and not embedded in the static HTML payload.
 - Subagent calls preserve logged parent-session metadata, latch to parent thread labels when available, and auto-review attachment is clearly marked when inferred.
 - Tests and compile checks pass.

{codex_usage_tracking-0.15.0 → codex_usage_tracking-0.16.0}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.16.0 - 2026-07-07
+
+- Add allowance intelligence foundation with normalized allowance history, evidence-graded change diagnostics, local evidence exports, and API/MCP report surfaces for weekly-vs-5-hour usage analysis.
+- Add local content-indexed MCP/API exploration surfaces, including content search, thread trace, pattern scans, investigation walks, and strict local evidence exports.
+- Add roadmap for default local content indexing, SQLite FTS5 search, parser drift handling, and future diagnostics for repeated file rediscovery, shell churn, and large low-output calls.
+- Fix schema initialization so already-applied migrations are not rerun during read/report calls on migrated local databases.
+
+## 0.15.1 - 2026-07-05
+
+- Fix the PyPI wheel package resources by tracking the React dashboard `index.html` entrypoint used by `serve-dashboard` and installed-package smoke tests.
+
 ## 0.15.0 - 2026-07-05
 
 - Make the companion plugin/skills remediation-aware for token-waste investigations, including Headroom suggestions when available, dashboard verification paths, and custom local automation ideas.

{codex_usage_tracking-0.15.0 → codex_usage_tracking-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.15.0
+Version: 0.16.0
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -59,11 +59,11 @@ Local-first dashboard, Codex plugin, and companion skill for understanding where
 
 > **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.
 
-Codex Usage Tracker reads the JSONL logs already written by Codex, indexes aggregate usage counters into SQLite, and gives you a dashboard, CLI, and MCP tools for investigating real usage patterns. It keeps prompts, assistant messages, tool output, pasted secrets, and raw transcript content out of SQLite, CSV exports, and generated dashboard HTML.
+Codex Usage Tracker reads the JSONL logs already written by Codex, indexes aggregate usage counters plus local content/tool/command/file-event evidence into SQLite, and gives you a dashboard, CLI, and MCP tools for investigating real usage patterns. The content index stays on your machine; CSV exports, generated dashboard HTML, support bundles, and shareable reports omit indexed content by default. Use `refresh --aggregate-only` or `rebuild-index --aggregate-only` when you want the older aggregate-only SQLite posture.
 
 Built for developers using Codex locally who want to know which threads, models, subagents, and long chats are driving usage without uploading logs anywhere. The public PyPI package is [`codex-usage-tracking`](https://pypi.org/project/codex-usage-tracking/), and it installs the `codex-usage-tracker` command.
 
-After install, you get a localhost dashboard, a local SQLite aggregate index, CLI reports, MCP tools, and a companion Codex skill for asking questions like "what drove my usage this week?"
+After install, you get a localhost dashboard, a local SQLite usage index, CLI reports, MCP tools, and a companion Codex skill for asking questions like "what drove my usage this week?"
 
 ## Quick Install
 
@@ -90,13 +90,13 @@ Source install for development or branch testing:
 pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
 ```
 
-`setup` installs or refreshes the local Codex plugin wrapper, initializes local config templates when needed, refreshes the aggregate index, runs `codex-usage-tracker doctor`, and tells you whether Codex needs a restart for plugin discovery.
+`setup` installs or refreshes the local Codex plugin wrapper, initializes local config templates when needed, refreshes the local usage index, runs `codex-usage-tracker doctor`, and tells you whether Codex needs a restart for plugin discovery.
 
 Want Codex to do it for you? Paste: `Install codex-usage-tracking with pipx, run codex-usage-tracker setup, and open the Codex Usage Tracker dashboard.`
 
 ## Talk To Your Usage Data
 
-The dashboard shows the evidence; the companion plugin and skills make it conversational. After `setup` and a Codex restart, ask Codex to refresh the local aggregate index, call MCP tools, and explain what is driving usage without exposing prompts or tool output.
+The dashboard shows the evidence; the companion plugin and skills make it conversational. After `setup` and a Codex restart, ask Codex to refresh the local usage index, call MCP tools, and explain what is driving usage. Shareable reports stay aggregate-first and omit indexed content unless an explicit local content tool/export is added for that purpose.
 
 Good starter prompts:
 
@@ -108,7 +108,7 @@ Compare model and effort usage, then suggest safer defaults.
 Open the dashboard and filter Calls to the rows behind your recommendation.
 ```
 
-The companion skill treats waste discovery as diagnosis plus remediation: it can point to Calls, Threads, Call Investigator, Diagnostics Notebook, Headroom when available, or a custom local command/skill/report preset Codex can build to stop repeating the same waste pattern.
+The companion skill treats waste discovery as diagnosis plus remediation: it can point to Calls, Threads, Call Investigator, Diagnostics Notebook, Allowance Intelligence, Headroom when available, or a custom local command/skill/report preset Codex can build to stop repeating the same waste pattern.
 
 Example conversation docs:
 
@@ -307,6 +307,7 @@ Full model: [Privacy Guide](docs/privacy.md).
 - [Dashboard Guide](docs/dashboard-guide.md)
 - [CLI Reference](docs/cli-reference.md)
 - [Pricing, Credits, And Allowance](docs/pricing-and-credits.md)
+- [Allowance Intelligence](docs/allowance-intelligence.md)
 - [MCP And Codex Skills](docs/mcp.md)
 - [Privacy Guide](docs/privacy.md)
 - [Architecture](docs/architecture.md)

{codex_usage_tracking-0.15.0 → codex_usage_tracking-0.16.0}/README.md

@@ -14,11 +14,11 @@ Local-first dashboard, Codex plugin, and companion skill for understanding where
 
 > **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.
 
-Codex Usage Tracker reads the JSONL logs already written by Codex, indexes aggregate usage counters into SQLite, and gives you a dashboard, CLI, and MCP tools for investigating real usage patterns. It keeps prompts, assistant messages, tool output, pasted secrets, and raw transcript content out of SQLite, CSV exports, and generated dashboard HTML.
+Codex Usage Tracker reads the JSONL logs already written by Codex, indexes aggregate usage counters plus local content/tool/command/file-event evidence into SQLite, and gives you a dashboard, CLI, and MCP tools for investigating real usage patterns. The content index stays on your machine; CSV exports, generated dashboard HTML, support bundles, and shareable reports omit indexed content by default. Use `refresh --aggregate-only` or `rebuild-index --aggregate-only` when you want the older aggregate-only SQLite posture.
 
 Built for developers using Codex locally who want to know which threads, models, subagents, and long chats are driving usage without uploading logs anywhere. The public PyPI package is [`codex-usage-tracking`](https://pypi.org/project/codex-usage-tracking/), and it installs the `codex-usage-tracker` command.
 
-After install, you get a localhost dashboard, a local SQLite aggregate index, CLI reports, MCP tools, and a companion Codex skill for asking questions like "what drove my usage this week?"
+After install, you get a localhost dashboard, a local SQLite usage index, CLI reports, MCP tools, and a companion Codex skill for asking questions like "what drove my usage this week?"
 
 ## Quick Install
 
@@ -45,13 +45,13 @@ Source install for development or branch testing:
 pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
 ```
 
-`setup` installs or refreshes the local Codex plugin wrapper, initializes local config templates when needed, refreshes the aggregate index, runs `codex-usage-tracker doctor`, and tells you whether Codex needs a restart for plugin discovery.
+`setup` installs or refreshes the local Codex plugin wrapper, initializes local config templates when needed, refreshes the local usage index, runs `codex-usage-tracker doctor`, and tells you whether Codex needs a restart for plugin discovery.
 
 Want Codex to do it for you? Paste: `Install codex-usage-tracking with pipx, run codex-usage-tracker setup, and open the Codex Usage Tracker dashboard.`
 
 ## Talk To Your Usage Data
 
-The dashboard shows the evidence; the companion plugin and skills make it conversational. After `setup` and a Codex restart, ask Codex to refresh the local aggregate index, call MCP tools, and explain what is driving usage without exposing prompts or tool output.
+The dashboard shows the evidence; the companion plugin and skills make it conversational. After `setup` and a Codex restart, ask Codex to refresh the local usage index, call MCP tools, and explain what is driving usage. Shareable reports stay aggregate-first and omit indexed content unless an explicit local content tool/export is added for that purpose.
 
 Good starter prompts:
 
@@ -63,7 +63,7 @@ Compare model and effort usage, then suggest safer defaults.
 Open the dashboard and filter Calls to the rows behind your recommendation.
 ```
 
-The companion skill treats waste discovery as diagnosis plus remediation: it can point to Calls, Threads, Call Investigator, Diagnostics Notebook, Headroom when available, or a custom local command/skill/report preset Codex can build to stop repeating the same waste pattern.
+The companion skill treats waste discovery as diagnosis plus remediation: it can point to Calls, Threads, Call Investigator, Diagnostics Notebook, Allowance Intelligence, Headroom when available, or a custom local command/skill/report preset Codex can build to stop repeating the same waste pattern.
 
 Example conversation docs:
 
@@ -262,6 +262,7 @@ Full model: [Privacy Guide](docs/privacy.md).
 - [Dashboard Guide](docs/dashboard-guide.md)
 - [CLI Reference](docs/cli-reference.md)
 - [Pricing, Credits, And Allowance](docs/pricing-and-credits.md)
+- [Allowance Intelligence](docs/allowance-intelligence.md)
 - [MCP And Codex Skills](docs/mcp.md)
 - [Privacy Guide](docs/privacy.md)
 - [Architecture](docs/architecture.md)

codex_usage_tracking-0.16.0/docs/allowance-intelligence.md

@@ -0,0 +1,64 @@
+# Allowance Intelligence
+
+Allowance intelligence is an aggregate-only workflow for asking: did visible Codex allowance behavior change, or is the counter just noisy?
+
+It uses observed `token_count.rate_limits` snapshots already present in local Codex logs. It does not read prompts, assistant text, tool output, raw command output, or OpenAI account internals.
+
+## What It Can Say
+
+- Normalize observed 5-hour and weekly usage snapshots into `allowance_observations`.
+- Compare visible usage-percent movement with locally estimated Codex credits.
+- Separate weekly evidence from 5-hour rolling-window behavior.
+- Flag candidate allowance regime shifts when recent weekly credits-per-visible-percent drops sharply.
+- Preserve the possibility that other Codex or ChatGPT usage outside local logs explains movement.
+
+## Evidence Grades
+
+- `insufficient_data`: not enough observations or positive usage spans.
+- `counter_noise_likely`: usually used for 5-hour windows because rolling-window behavior is noisy.
+- `no_change_detected`: enough weekly evidence exists, but no candidate shift was found.
+- `possible_regime_change`: weekly evidence suggests a visible capacity change, but evidence is limited.
+- `strong_local_evidence`: multiple weekly spans show a consistent drop in credits-per-visible-percent.
+- `inconclusive_other_usage_possible`: observed movement could plausibly be explained by usage outside these local logs.
+
+## Statistical Detector Direction
+
+The detector now includes a `nonparametric-v1` evidence block for weekly candidate shifts. It adds:
+
+- exact permutation p-values for mean credits-per-percent shifts when the split is small enough to enumerate locally;
+- Cliff's delta effect size, where negative values mean recent spans bought less visible allowance movement per estimated credit;
+- a stricter `research_readiness.ready_for_public_claim` flag that requires repeated weekly spans on both sides of the split, strong effect size, and p-value support.
+
+This intentionally separates local diagnostics from public claims. Candidate shifts require at least six positive weekly spans before the split, which keeps a tiny early baseline from becoming the headline result when later data is much denser. Public-claim readiness stays stricter still: it requires repeated weekly spans on both sides, strong effect size, and p-value support.
+
+## Commands
+
+```bash
+codex-usage-tracker allowance-history --window-kind weekly --json
+codex-usage-tracker allowance-diagnostics --window-kind weekly --json
+codex-usage-tracker allowance-export --output /tmp/codex-allowance-evidence.json
+```
+
+Use `--limit 0` to inspect all normalized observations. The export command always produces strict-privacy payloads.
+
+## MCP Tools
+
+- `usage_allowance_history(...)`
+- `usage_allowance_diagnostics(...)`
+- `usage_allowance_export(...)`
+
+The MCP tools default to strict privacy for allowance work because these reports are likely to be copied into issues or community discussions.
+
+## Local API
+
+- `/api/allowance/history`
+- `/api/allowance/diagnostics`
+- `/api/allowance/export`
+
+The dashboard can build an Allowance / Limit Intelligence surface from these payloads later without inventing a separate data contract.
+
+## Privacy
+
+Strict export omits prompts, assistant messages, tool output, file paths, thread names, session IDs, and record IDs. It includes anonymized observation dates, window kinds, visible usage movement, estimated credits, confidence labels, evidence grades, and caveats.
+
+This project remains unofficial and local-first. The diagnostics are evidence for local investigation, not an official OpenAI usage ledger.

codex_usage_tracking-0.16.0/docs/architecture.md

@@ -0,0 +1,62 @@
+# Architecture
+
+Codex Usage Tracker is a local sidecar app. It reads Codex session JSONL logs, stores tracker-owned indexes in SQLite, and exposes usage data through CLI commands, MCP tools, CSV export, generated dashboards, and the localhost React dashboard.
+
+The current storage model has two layers:
+
+- Aggregate usage index: token counters, model/effort metadata, call origins, diagnostic labels, thread summaries, pricing/credit estimates, allowance snapshots, and safe report payloads.
+- Local content index: normalized conversation turns, bounded content fragments, tool calls, command runs, file events, persisted investigation run summaries, and source provenance for explicit local MCP/API investigation.
+
+Shareable outputs remain aggregate-first and must omit indexed/raw content unless an export is explicitly documented as a local raw/content export.
+
+## Boundaries
+
+- `parser.py` converts local JSONL events into aggregate `UsageEvent` records. It also attaches metadata-only call-origin categories, diagnostic facts from `diagnostic_facts.py`, archived-session flags, conservative thread keys, source cursors, and parser diagnostics.
+- `store/content_index.py` owns normalized local content-index population and cleanup. It may persist bounded local snippets, tool-call metadata, command roots/labels, file path hashes/basenames, parser adapter metadata, source provenance, parse warnings, and FTS5 search rows. Investigation/report builders may persist bounded run summaries in `investigation_runs`. These surfaces must not feed raw/indexed content into default CSV, dashboard HTML, support bundle, or aggregate report payloads.
+- `call_origin.py` owns the pure call-origin classifier and migrated-row fallback. It must not open source JSONL files; source-log reads belong in refresh/indexing or explicit context loading.
+- `schema.py` owns persisted SQLite columns and migrations. Add columns or tables there before changing refresh, export, or MCP behavior.
+- `store.py` and `store/api.py` own SQLite setup, refresh, rebuild, query access, previous/next call links, materialized thread summaries, source-file refresh cursors, SQL-backed live dashboard API slices, and cleanup ordering.
+- `source_records.py` owns source-file provenance, parser coverage, incremental cursors, and replacement on source-file changes.
+- `reports.py` is the application-service layer for summaries, expensive-call reports, recommendations, pricing coverage, source coverage, allowance reports, and filtered query payloads. CLI and MCP wrappers should call this layer instead of duplicating report assembly.
+- `api_payloads.py` owns stable JSON payload helpers shared by CLI and MCP. `json_contracts.py` owns lightweight contract checks for schema-versioned CLI/MCP payloads and localhost live API payloads.
+- `costing.py`, `pricing_config.py`, `pricing_openai.py`, `pricing_estimates.py`, and `allowance.py` own cost, credit, rate-card, and allowance annotation. Keep estimate confidence and source metadata attached to rows.
+- `projects.py`, `threads.py`, and `recommendations.py` annotate aggregate rows with project identity, thread relationships, and actionable signals. Project privacy redaction belongs in `projects.py` so CLI, MCP, dashboard, CSV, and support-bundle surfaces share behavior.
+- `context.py` is the normal path for explicit selected-call raw context. It reads one selected source file on demand, applies redaction and size limits, omits tool output by default, and keeps full serialized group analysis explicit.
+- `diagnostic_snapshots.py` owns persisted diagnostic snapshot refresh/load orchestration. Snapshot modules should stay synthetic-testable and avoid raw transcript persistence in aggregate diagnostic facts.
+- `dashboard.py` builds aggregate-first static dashboard payloads and writes HTML/assets. `server.py` adds localhost refresh, compatibility `/api/usage`, SQL-backed live API slices, and explicit lazy context loading.
+- `frontend/dashboard/` owns the React dashboard. It should render server/API payloads rather than becoming an independent source of usage calculations.
+- `plugin_installer.py`, `.mcp.json`, `skills/`, `src/codex_usage_tracker/plugin_data/skills/`, and `scripts/check_release.py` own install and packaging behavior.
+- `scripts/benchmark_synthetic_history.py` owns generated large-history query timing checks. It must stay synthetic-only and must not read real Codex logs.
+
+## Extension Rules
+
+1. Add new aggregate usage-event metrics through `UsageEvent`, `schema.py`, migrations, store writers, privacy behavior, export behavior, and focused migration/privacy tests.
+2. Add new content-index records through `schema.py`, `store/content_index.py`, source provenance tests, cleanup tests, and shareable-output tests proving indexed content does not leak through default exports.
+3. Add new report views through `reports.py` first, then wire CLI and MCP wrappers to the shared service.
+4. Add new machine-readable outputs through `api_payloads.py`, a `schema` value, `json_contracts.py`, and focused contract tests when the output is stable.
+5. Add dashboard-only interactions in the narrowest dashboard module and keep URL state in dashboard state helpers.
+6. Keep examples, screenshots, mocks, and fixtures synthetic. Never derive committed fixtures from real logs.
+7. When editing skill instructions, update both the source `skills/...` file and the bundled `src/codex_usage_tracker/plugin_data/skills/...` copy. `scripts/check_release.py` verifies installable plugin assets stay complete and synced.
+8. When adding fields derived from `cwd`, Git metadata, source paths, log-event metadata, or indexed content, decide how they behave in `normal`, `redacted`, and `strict` privacy modes before exposing them in dashboard, JSON, CSV, MCP, support-bundle, or shareable export output.
+9. Diagnostic snapshot refresh must remain explicit on demand. Normal usage refresh paths may load stored snapshots, but must not rescan source logs for diagnostic sections unless the user calls diagnostics `--refresh` or a `/api/diagnostics/<section>/refresh` endpoint.
+
+## Validation
+
+Use the narrowest useful check first, then the release suite before committing shared parser, schema, MCP, dashboard, packaging, or privacy changes:
+
+```bash
+python -m pytest
+python -m compileall src
+python -m mypy
+for file in src/codex_usage_tracker/plugin_data/dashboard/dashboard*.js; do
+  node --check "$file"
+done
+python scripts/check_release.py
+python -m build
+python scripts/check_release.py --dist
+git diff --check
+```
+
+Dashboard UI changes should also be opened in a browser and checked at desktop and mobile widths for overflow, overlap, stale state, and shareable-output behavior.
+
+Run `python scripts/benchmark_synthetic_history.py --rows 10000 100000 --json --enforce-thresholds` after changing SQLite filters, dashboard payload loading, or indexes. Run `python scripts/benchmark_synthetic_history.py --rows 1000 --with-source-logs --json --enforce-thresholds` after changing source-log refresh, content indexing, explicit context loading, or source-log diagnostics. Run the 500k benchmark before release work when practical.

{codex_usage_tracking-0.15.0 → codex_usage_tracking-0.16.0}/docs/cli-json-schemas.md

@@ -1,6 +1,6 @@
 # CLI, MCP, and Dashboard JSON Schemas
 
-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.
+Codex Usage Tracker exposes JSON for automation through CLI `--json` flags, MCP tools, and the local dashboard server API. Default shareable payloads are aggregate-first and do not include prompts, assistant messages, tool output, or raw transcript snippets. `usage_content_search` is the explicit local content-index exception and marks that it can include indexed snippets.
 
 ## Companion Skill Usage
 
@@ -47,6 +47,9 @@ Tracked schema ids:
 | `codex-usage-tracker-summary-v1` | CLI `summary --json`, CLI `expensive --json`, MCP summary/expensive JSON |
 | `codex-usage-tracker-query-v1` | CLI `query`, MCP `usage_query(...)` |
 | `codex-usage-tracker-recommendations-v1` | CLI `recommendations --json`, MCP `usage_recommendations(response_format="json")`, MCP `usage_dashboard_recommendations(...)` |
+| `codex-usage-tracker-allowance-history-v1` | CLI `allowance-history --json`, MCP `usage_allowance_history(...)`, dashboard server `/api/allowance/history` |
+| `codex-usage-tracker-allowance-diagnostics-v1` | CLI `allowance-diagnostics --json`, MCP `usage_allowance_diagnostics(...)`, dashboard server `/api/allowance/diagnostics` |
+| `codex-usage-tracker-allowance-evidence-export-v1` | CLI `allowance-export --json`, MCP `usage_allowance_export(...)`, dashboard server `/api/allowance/export` |
 | `codex-usage-tracker-reports-pack-v1` | Dashboard server `/api/reports/pack` response, MCP `usage_report_pack(...)` |
 | `codex-usage-tracker-diagnostics-v1` | CLI `diagnostics ... --json`, dashboard server `/api/diagnostics/*` |
 | `codex-usage-tracker-diagnostic-overview-v1` | CLI `diagnostics overview --json`, dashboard server `/api/diagnostics/overview` |
@@ -74,6 +77,12 @@ Tracked schema ids:
 | `codex-usage-tracker-open-dashboard-v1` | CLI `open-dashboard --json` |
 | `codex-usage-tracker-serve-dashboard-v1` | CLI `serve-dashboard --json` startup payload, including preferred React `dashboard_url` and legacy `legacy_dashboard_url` fallback |
 | `codex-usage-tracker-pricing-coverage-v1` | CLI `pricing-coverage --json`, MCP `usage_pricing_coverage(response_format="json")` |
+| `codex-usage-tracker-source-coverage-v1` | CLI `source-coverage --json`, MCP `usage_source_coverage(response_format="json")` |
+| `codex-usage-tracker-content-search-v1` | MCP `usage_content_search(...)`; explicit local content-index search, may include indexed snippets |
+| `codex-usage-tracker-thread-trace-v1` | MCP `usage_thread_trace(...)`; explicit local content-index thread/session timeline |
+| `codex-usage-tracker-pattern-scan-v1` | MCP `usage_repetition_scan(...)`, `usage_command_loop_scan(...)`, `usage_file_churn_scan(...)`, `usage_context_bloat_scan(...)`; explicit local content/event-index pattern diagnostics |
+| `codex-usage-tracker-investigation-walk-v1` | MCP `usage_investigation_walk(question=...)`; bounded local hypothesis walk over normalized pattern evidence |
+| `codex-usage-tracker-local-evidence-export-v1` | MCP `usage_local_evidence_export(question=...)`; strict shareable local evidence summary without raw/indexed content |
 | `codex-usage-tracker-export-v1` | CLI `export --json`, MCP `export_usage_csv(...)` |
 | `codex-usage-tracker-init-pricing-v1` | CLI `init-pricing --json`, MCP `init_usage_pricing_config()` |
 | `codex-usage-tracker-update-pricing-v1` | CLI `update-pricing --json`, MCP `update_usage_pricing_config()` |
@@ -214,6 +223,76 @@ Schema: `codex-usage-tracker-recommendations-v1`
 
 Rows include `recommendation_score`, `primary_recommendation`, `secondary_recommendations`, `primary_signal`, `secondary_signals`, `recommended_action`, and `flag_explanations`. Thread rollups summarize the highest-priority threads using the same aggregate-only signals.
 
+## Allowance Intelligence
+
+Commands:
+
+```bash
+codex-usage-tracker allowance-history --window-kind weekly --json
+codex-usage-tracker allowance-diagnostics --window-kind weekly --json
+codex-usage-tracker allowance-export --output /tmp/codex-allowance-evidence.json
+```
+
+MCP:
+
+- `usage_allowance_history(...)`
+- `usage_allowance_diagnostics(...)`
+- `usage_allowance_export(...)`
+
+Server API:
+
+- `/api/allowance/history`
+- `/api/allowance/diagnostics`
+- `/api/allowance/export`
+
+Schemas:
+
+- `codex-usage-tracker-allowance-history-v1`
+- `codex-usage-tracker-allowance-diagnostics-v1`
+- `codex-usage-tracker-allowance-evidence-export-v1`
+
+Allowance intelligence normalizes observed 5-hour and weekly usage snapshots from aggregate token-count rows. Diagnostics compare visible usage movement with locally estimated Codex credits and grade the evidence. Weekly windows are the primary signal; 5-hour windows are treated as noisy rolling counters. Weekly change candidates include `nonparametric-v1` statistical evidence and a stricter `summary.research_readiness.ready_for_public_claim` flag. Strict export omits prompts, assistant text, tool output, file paths, thread names, session IDs, and record IDs.
+
+HTTP report endpoints accept `limit=all`, `limit=0`, `limit=none`, and `limit=null` as all rows up to the endpoint safety cap.
+
+```json
+{
+  "schema": "codex-usage-tracker-allowance-diagnostics-v1",
+  "generated_at": "2026-06-01T00:00:00+00:00",
+  "privacy_mode": "strict",
+  "include_archived": false,
+  "window_kind": "weekly",
+  "summary": {
+    "observation_count": 4,
+    "primary_evidence_grade": "possible_regime_change",
+    "research_readiness": {
+      "detector_version": "nonparametric-v1",
+      "ready_for_public_claim": false,
+      "weekly_positive_span_count": 3,
+      "minimum_split_spans_for_public_claim": 6
+    }
+  },
+  "windows": [],
+  "spans": [],
+  "change_candidates": [
+    {
+      "evidence_grade": "possible_regime_change",
+      "capacity_ratio": 0.72,
+      "outside_usage_possible": true,
+      "statistical_evidence": {
+        "detector_version": "nonparametric-v1",
+        "method": "exact_permutation_mean_shift",
+        "effect_size_cliffs_delta": -0.67,
+        "p_value_one_sided": 0.18,
+        "signal": "directional_effect_limited",
+        "public_claim_ready": false
+      }
+    }
+  ],
+  "notes": []
+}
+```
+
 ## Session
 
 Command:
@@ -763,6 +842,168 @@ Schema: `codex-usage-tracker-pricing-coverage-v1`
 }
 ```
 
+## Source Coverage
+
+Command:
+
+```bash
+codex-usage-tracker source-coverage --json
+```
+
+MCP:
+
+- `usage_source_coverage(response_format="json")`
+
+Schema: `codex-usage-tracker-source-coverage-v1`
+
+```json
+{
+  "schema": "codex-usage-tracker-source-coverage-v1",
+  "content_mode": "aggregate_only",
+  "includes_indexed_content": false,
+  "includes_raw_fragments": false,
+  "include_archived": false,
+  "source_record_count": 2,
+  "source_file_count": 2,
+  "parser_version_count": 1,
+  "warning_record_count": 0,
+  "rows": [
+    {
+      "raw_shape_label": "token_count",
+      "parser_adapter": "codex-jsonl",
+      "parser_version": "codex-jsonl-v2",
+      "record_count": 2,
+      "source_file_count": 2,
+      "warning_record_count": 0
+    }
+  ]
+}
+```
+
+## Content Search
+
+MCP:
+
+- `usage_content_search(query="token waste")`
+
+Schema: `codex-usage-tracker-content-search-v1`
+
+This is an explicit local content-index investigation surface. It can include indexed snippets from local Codex logs, so do not treat it as a default shareable aggregate report.
+
+```json
+{
+  "schema": "codex-usage-tracker-content-search-v1",
+  "content_mode": "local_content_index",
+  "includes_indexed_content": true,
+  "includes_raw_fragments": true,
+  "privacy_mode": "normal",
+  "query": "token waste",
+  "filters": {
+    "since": null,
+    "until": null,
+    "model": null,
+    "effort": null,
+    "thread": null,
+    "include_archived": false,
+    "limit": 20,
+    "offset": 0,
+    "max_snippet_chars": 800
+  },
+  "search_mode": "fts5",
+  "row_count": 0,
+  "total_matched_rows": 0,
+  "truncated": false,
+  "has_more": false,
+  "next_offset": null,
+  "rows": []
+}
+```
+
+## Thread Trace
+
+MCP:
+
+- `usage_thread_trace(thread="Add Codex token tracking")`
+- `usage_thread_trace(session_id="...")`
+- `usage_thread_trace(record_id="...")`
+
+Schema: `codex-usage-tracker-thread-trace-v1`
+
+This is an explicit local content-index investigation surface. It returns aggregate call metadata plus indexed fragments for a selected thread/session scope.
+
+```json
+{
+  "schema": "codex-usage-tracker-thread-trace-v1",
+  "content_mode": "local_content_index",
+  "includes_indexed_content": true,
+  "includes_raw_fragments": true,
+  "privacy_mode": "normal",
+  "filters": {
+    "thread": "Add Codex token tracking",
+    "thread_key": null,
+    "session_id": null,
+    "record_id": null,
+    "since": null,
+    "until": null,
+    "include_archived": false,
+    "limit": 100,
+    "offset": 0,
+    "max_snippet_chars": 800
+  },
+  "call_count": 0,
+  "total_matched_calls": 0,
+  "truncated": false,
+  "has_more": false,
+  "next_offset": null,
+  "calls": []
+}
+```
+
+## Pattern Scan
+
+MCP:
+
+- `usage_repetition_scan(min_occurrences=2)`
+- `usage_command_loop_scan(min_occurrences=2)`
+- `usage_file_churn_scan(min_occurrences=2)`
+- `usage_context_bloat_scan(min_occurrences=2)`
+
+Schema: `codex-usage-tracker-pattern-scan-v1`
+
+This explicit local content/event-index diagnostic surface scans normalized fragment hashes, command roots, file hashes/basenames, and aggregate token rows. It does not include raw fragments.
+
+```json
+{"schema":"codex-usage-tracker-pattern-scan-v1","content_mode":"local_content_index","includes_indexed_content":true,"includes_raw_fragments":false,"privacy_mode":"normal","scan_type":"command_loop","scan_types":["command_loop"],"filters":{"since":null,"until":null,"thread":null,"include_archived":false,"min_occurrences":2,"limit":20},"pattern_count":0,"total_patterns":0,"patterns":[]}
+```
+
+## Investigation Walk
+
+MCP:
+
+- `usage_investigation_walk(question="look for token waste")`
+
+Schema: `codex-usage-tracker-investigation-walk-v1`
+
+Runs a bounded local hypothesis walk over normalized pattern scans, ranks candidate branches, prunes branches without evidence, and returns recommended next MCP tools. Does not include raw fragments.
+
+```json
+{"schema":"codex-usage-tracker-investigation-walk-v1","content_mode":"local_content_index","includes_indexed_content":true,"includes_raw_fragments":false,"privacy_mode":"normal","question":"look for token waste","filters":{"since":null,"until":null,"thread":null,"include_archived":false,"min_occurrences":2,"evidence_limit":5},"summary":{"branch_count":4,"supported_branch_count":0,"top_hypothesis":null,"confidence":"insufficient_local_evidence"},"branches":[],"recommended_next_tools":[]}
+```
+
+## Local Evidence Export
+
+MCP:
+
+- `usage_local_evidence_export(question="share token waste evidence")`
+
+Schema: `codex-usage-tracker-local-evidence-export-v1`
+
+Strict shareable summary derived from local investigation evidence. It omits raw fragments, snippets, record ids, thread names, command labels, file basenames, full paths, raw commands, and raw tool output.
+
+```json
+{"schema":"codex-usage-tracker-local-evidence-export-v1","content_mode":"shareable_local_evidence","includes_indexed_content":false,"includes_raw_fragments":false,"privacy_mode":"strict","question":"share token waste evidence","filters":{"since":null,"until":null,"thread":null,"include_archived":false,"min_occurrences":2,"evidence_limit":5},"summary":{"branch_count":4,"supported_branch_count":0,"top_hypothesis":null,"confidence":"insufficient_local_evidence","export_branch_count":0},"branches":[],"omitted_fields":["record_id","session_id","thread_name","raw_fragment","snippet","raw_command","raw_tool_output","full_path","path_basename","command_label"],"caveats":["Local evidence only; not an official OpenAI ledger."]}
+```
+
 ## Lifecycle Commands
 
 Most setup and file-writing commands accept `--json` and return a schema-specific payload with written paths and counts:
@@ -776,6 +1017,7 @@ Most setup and file-writing commands accept `--json` and return a schema-specifi
 - `dashboard --json`: `codex-usage-tracker-dashboard-v1`
 - `export --json`: `codex-usage-tracker-export-v1`
 - `pricing-coverage --json`
+- `source-coverage --json`
 - `recommendations --json`
 - `init-pricing --json`, `update-pricing --json`, `pin-pricing --json`
 - `init-allowance --json`, `parse-allowance --json`