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

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

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

{codex_usage_tracking-0.5.0 → codex_usage_tracking-0.7.0}/AGENTS.md

@@ -142,10 +142,9 @@ 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
+for file in src/codex_usage_tracker/plugin_data/dashboard/dashboard*.js; do
+  node --check "$file"
+done
 python scripts/check_release.py
 git diff --check
 rm -rf dist build src/codex_usage_tracker.egg-info src/codex_usage_tracking.egg-info
@@ -159,8 +158,9 @@ Additional smoke checks for touched CLI surfaces:
 ```bash
 python -m pytest
 python -m compileall src
-node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard.js
-node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard_state.js
+for file in src/codex_usage_tracker/plugin_data/dashboard/dashboard*.js; do
+  node --check "$file"
+done
 python -m build
 python scripts/check_release.py --dist
 git diff --check
@@ -216,10 +216,9 @@ 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
+for file in src/codex_usage_tracker/plugin_data/dashboard/dashboard*.js; do
+  node --check "$file"
+done
 python scripts/check_release.py
 git diff --check
 rm -rf dist build src/codex_usage_tracker.egg-info src/codex_usage_tracking.egg-info

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

@@ -2,9 +2,37 @@
 
 ## Unreleased
 
+## 0.7.0 - 2026-06-18
+
+- Parse latest observed Codex usage snapshots from local rate-limit and token-count log events without persisting raw transcript text.
+- Store observed 5h and weekly usage snapshot fields in aggregate rows and expose a latest-observed usage summary for dashboard and API consumers.
+- Add a dashboard card for latest observed 5h and weekly usage with wording that distinguishes local observations from authoritative account limits.
+- Default the dashboard table experience to time-sorted Calls, replace the visible Signals column with Reasoning Output, and keep the Signals field out of the table for now.
+- Ignore known non-token parser events so refreshes stay focused on usage-bearing records.
+
+## 0.6.1 - 2026-06-13
+
+- Polish the README landing screenshots with matched dashboard/investigator previews and an additional lower investigator evidence view.
+- Restore the companion plugin prompt preview near the companion skill section and package companion screenshots with installed docs assets.
+- Keep dashboard toolbar links styled like buttons in the call investigator.
+
+## 0.6.0 - 2026-06-13
+
+- Remove low-value call/thread anchor diagnostics from the experimental call investigator to avoid an extra source-log scan per context load.
+- Persist call-origin metadata as categorical aggregate fields during indexing so normal dashboard payloads do not reopen source JSONL logs to infer user-vs-Codex initiation.
+- Persist archived-session scope, conservative thread keys, and per-thread previous/next call links as aggregate helper fields for faster dashboard filtering and investigator navigation.
+- Add opt-in localhost API timing diagnostics for `/api/usage` and `/api/context` without exposing raw transcript content.
+- Reduce explicit context loading to a quick default mode that omits tool output and serialized buckets, with full serialized JSONL bucket analysis still available on demand.
+- Add source-log-aware synthetic benchmark coverage that verifies normal dashboard payload assembly does not open generated source JSONL files.
+- Add SQL-backed live dashboard API slices for status, calls, one call, threads, thread calls, summary, and recommendations while preserving the compatibility `/api/usage` endpoint.
+- Materialize active and all-history thread summaries in SQLite so live thread APIs can read pre-aggregated totals.
+- Add source-file refresh cursors so live refresh skips unchanged logs, seeks to appended JSONL bytes when safe, and safely replaces aggregate rows for changed or truncated source logs.
+- Hydrate direct call-investigator links from the aggregate `/api/call` endpoint when the selected record is outside the currently loaded table slice or filter state.
+- Replace placeholder non-English dashboard locale catalogs with translated UI catalogs and add regression coverage for core visible labels.
+
 ## 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 the dashboard localization foundation, including initial 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.5.0
+Version: 0.7.0
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -26,6 +26,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mcp>=1.2.0
+Requires-Dist: tiktoken>=0.13.0
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: mypy>=1.10; extra == "dev"
@@ -38,8 +39,8 @@ Dynamic: license-file
 # Codex Usage Tracker
 
 <p align="center">
-  <a href="docs/assets/plugin-prompts.png"><img src="docs/assets/plugin-prompts.png?v=short-prompts" alt="Codex Usage Tracker companion prompts for opening the dashboard, finding the heaviest thread, and showing a thread leaderboard." width="49%"></a>
-  <a href="docs/assets/dashboard-calls.png"><img src="docs/assets/dashboard-calls-preview.png?v=usage-dashboard" alt="Codex Usage Tracker dashboard showing filters, usage totals, call rows, and call details." width="49%"></a>
+  <a href="docs/assets/dashboard-calls.png"><img src="docs/assets/dashboard-calls-preview.png?v=readme-drilldown" alt="Codex Usage Tracker dashboard showing filters, usage totals, and named model-call rows." width="49%"></a>
+  <a href="docs/assets/dashboard-call-investigator.png"><img src="docs/assets/dashboard-call-investigator-preview.png?v=readme-drilldown" alt="Codex Usage Tracker call investigator showing token accounting, cache diagnostics, and redacted runtime evidence." width="49%"></a>
 </p>
 
 Local-first dashboard, Codex plugin, and companion skill for understanding where your Codex tokens and usage credits are going.
@@ -84,45 +85,55 @@ pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
 
 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.`
 
-After plugin discovery, Codex can use the companion usage skill to refresh local aggregates, call the MCP tools, and explain usage patterns conversationally. Examples: [MCP And Codex Skills](docs/mcp.md).
+## Dashboard Preview
 
-<p align="center">
-  <a href="docs/assets/plugin-thread-leaderboard.png"><img src="docs/assets/plugin-thread-leaderboard.png?v=thread-leaderboard" alt="Synthetic Codex chat preview showing the companion skill ranking threads by token usage after refreshing the local aggregate index." width="86%"></a>
-</p>
+The Calls table is the main investigation surface: filter, sort, inspect details, and export the exact aggregate rows you are looking at.
 
-If you only want plugin registration after installing the package:
+![Calls view showing filters, totals, the model-call table, and the compact details rail.](docs/assets/dashboard-calls.png?v=readme-drilldown)
 
-```bash
-codex-usage-tracker install-plugin
-```
+Click a call to open the dedicated investigator for exact token accounting, cache/accounting deltas, local serialized evidence buckets, and redacted turn-log evidence loaded only at runtime.
 
-More install paths: [Install Guide](docs/install.md).
+![Call investigator showing token accounting, cache diagnostics, serialized evidence groups, and raw evidence controls.](docs/assets/dashboard-call-investigator.png?v=readme-drilldown)
 
-## Platform Support
+The lower investigator view keeps the raw JSONL evidence opt-in and runtime-only while still showing visible-context estimates, serialized evidence upper bounds, and redacted turn-log entries.
 
-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.
+![Lower call investigator view showing context-change estimates, serialized evidence groups, and redacted runtime evidence entries.](docs/assets/dashboard-call-investigator-evidence.png?v=readme-drilldown)
 
-## Dashboard Preview
+Threads view groups related calls so long chats, subagents, and auto-review passes are easier to reason about as one work session.
 
-The Calls table is the main investigation surface: filter, sort, inspect details, and export the exact aggregate rows you are looking at.
+![Threads view with one expanded thread and its calls in chronological order.](docs/assets/dashboard-threads.png?v=readme-drilldown)
 
-![Calls view showing filters, totals, the model-call table, and the details panel.](docs/assets/dashboard-calls.png?v=aa16502)
+Insights still gives a fast triage layer for costly threads, low cache reuse, context bloat, and pricing gaps.
 
-Threads view groups related calls so long chats, subagents, and auto-review passes are easier to reason about as one work session.
+![Insights view with ranked Needs Attention cards, investigation presets, and top threads by attention score.](docs/assets/dashboard-insights.png?v=readme-drilldown)
+
+The dashboard screenshots use synthetic aggregate fixture data, and the companion prompt and chat previews are synthetic. They do not contain prompts from local logs, assistant responses, tool output, real thread names, real usage totals, or real Codex session content. See the [Dashboard Guide](docs/dashboard-guide.md) for the full walkthrough.
 
-![Threads view with one expanded thread and its calls in chronological order.](docs/assets/dashboard-threads.png?v=3cd7338)
+If this helped you track Codex usage, starring the repo helps others find it. Issues and feature requests are welcome.
 
-The details panel keeps the primary cost, cache, context, allowance, and pricing signals visible before raw identifiers.
+## Companion Skill And Plugin
 
-![Details panel showing aggregate fields for the selected usage row.](docs/assets/dashboard-details.png?v=84cf6dd)
+The dashboard is the core product surface. The Codex plugin and companion usage skill are add-ons that let Codex refresh local aggregates, call the MCP tools, and explain usage patterns conversationally after plugin discovery. Examples: [MCP And Codex Skills](docs/mcp.md).
 
-Insights still gives a fast triage layer for costly threads, low cache reuse, context bloat, and pricing gaps.
+<p align="center">
+  <a href="docs/assets/plugin-prompts.png"><img src="docs/assets/plugin-prompts.png?v=readme-drilldown" alt="Synthetic Codex plugin prompt preview showing usage dashboard and thread investigation suggestions." width="86%"></a>
+</p>
 
-![Insights view with ranked Needs Attention cards, investigation presets, and top threads by attention score.](docs/assets/dashboard-insights.png?v=4a40e4f)
+<p align="center">
+  <a href="docs/assets/plugin-thread-leaderboard.png"><img src="docs/assets/plugin-thread-leaderboard.png?v=readme-drilldown" alt="Synthetic Codex chat preview showing the companion skill ranking threads by token usage after refreshing the local aggregate index." width="86%"></a>
+</p>
 
-The dashboard screenshots use synthetic aggregate fixture data, and the companion prompt and chat previews are synthetic. They do not contain prompts from local logs, assistant responses, tool output, real thread names, real usage totals, or real Codex session content. See the [Dashboard Guide](docs/dashboard-guide.md) for the full walkthrough.
+If you only want plugin registration after installing the package:
 
-If this helped you track Codex usage, starring the repo helps others find it. Issues and feature requests are welcome.
+```bash
+codex-usage-tracker install-plugin
+```
+
+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.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.
 
 ## Why This Exists
 
@@ -169,7 +180,7 @@ Then:
 4. Use investigation presets for highest-cost threads, highest-credit calls, context bloat, cache misses, pricing gaps, or estimated-price review.
 5. Open `Threads` to see how a conversation grew and whether subagent or auto-review work attached to it.
 6. Hover or click rows to inspect aggregate fields in `Call Details`.
-7. Use `Load context` only when aggregate fields are not enough; context is fetched on demand from the local source JSONL and is not saved into SQLite or the dashboard.
+7. Use `Show turn log evidence` only when aggregate fields are not enough; context is fetched on demand from the local source JSONL and is not saved into SQLite or the dashboard.
 
 Optional allowance context:
 
@@ -177,7 +188,7 @@ Optional allowance context:
 codex-usage-tracker parse-allowance "5h 79% 6:50 PM Weekly 33% Jun 7"
 ```
 
-The tracker cannot read your logged-in ChatGPT plan or live remaining usage automatically. Allowance values are only as accurate as the values you manually copy from Codex Settings, `/status`, or another trusted usage display. Details: [Pricing, Credits, And Allowance](docs/pricing-and-credits.md).
+The tracker cannot read your logged-in ChatGPT plan or live remaining usage automatically. When local Codex logs include `token_count.rate_limits`, the dashboard can show the latest observed 5-hour and weekly remaining percentages from those logs. Otherwise, allowance values are only as accurate as the values you manually copy from Codex Settings, `/status`, or another trusted usage display. Details: [Pricing, Credits, And Allowance](docs/pricing-and-credits.md).
 
 ## What It Includes
 
@@ -192,7 +203,7 @@ The tracker cannot read your logged-in ChatGPT plan or live remaining usage auto
 
 ## Dashboard Language
 
-The dashboard supports localized UI text. English is the canonical catalog, and the project includes starter locale catalogs for common dashboard languages.
+The dashboard supports localized UI text. English is the canonical catalog, and the project includes translated locale catalogs for common dashboard languages.
 
 Set the initial dashboard language with `--lang`:
 
@@ -208,7 +219,7 @@ 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.
+Supported dashboard locales include English, Vietnamese, Spanish, French, German, Portuguese, Japanese, Simplified Chinese, Korean, Russian, Italian, and Arabic. This localizes dashboard UI text, not raw Codex log content, thread names, project names, paths, full CLI output, or data exports.
 
 ### Adding A Dashboard Language
 
@@ -285,7 +296,7 @@ This is optional. The normal shell install above is the fastest trusted path for
 - Token counts come from Codex's logged counters; the tracker does not re-tokenize prompts.
 - 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.
+- Live account allowance cannot be read automatically by this local tracker; remaining 5-hour and weekly allowance is shown only from local Codex `token_count.rate_limits` snapshots when present, or from copied values you configure.
 - 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.

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

@@ -1,8 +1,8 @@
 # Codex Usage Tracker
 
 <p align="center">
-  <a href="docs/assets/plugin-prompts.png"><img src="docs/assets/plugin-prompts.png?v=short-prompts" alt="Codex Usage Tracker companion prompts for opening the dashboard, finding the heaviest thread, and showing a thread leaderboard." width="49%"></a>
-  <a href="docs/assets/dashboard-calls.png"><img src="docs/assets/dashboard-calls-preview.png?v=usage-dashboard" alt="Codex Usage Tracker dashboard showing filters, usage totals, call rows, and call details." width="49%"></a>
+  <a href="docs/assets/dashboard-calls.png"><img src="docs/assets/dashboard-calls-preview.png?v=readme-drilldown" alt="Codex Usage Tracker dashboard showing filters, usage totals, and named model-call rows." width="49%"></a>
+  <a href="docs/assets/dashboard-call-investigator.png"><img src="docs/assets/dashboard-call-investigator-preview.png?v=readme-drilldown" alt="Codex Usage Tracker call investigator showing token accounting, cache diagnostics, and redacted runtime evidence." width="49%"></a>
 </p>
 
 Local-first dashboard, Codex plugin, and companion skill for understanding where your Codex tokens and usage credits are going.
@@ -47,45 +47,55 @@ pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
 
 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.`
 
-After plugin discovery, Codex can use the companion usage skill to refresh local aggregates, call the MCP tools, and explain usage patterns conversationally. Examples: [MCP And Codex Skills](docs/mcp.md).
+## Dashboard Preview
 
-<p align="center">
-  <a href="docs/assets/plugin-thread-leaderboard.png"><img src="docs/assets/plugin-thread-leaderboard.png?v=thread-leaderboard" alt="Synthetic Codex chat preview showing the companion skill ranking threads by token usage after refreshing the local aggregate index." width="86%"></a>
-</p>
+The Calls table is the main investigation surface: filter, sort, inspect details, and export the exact aggregate rows you are looking at.
 
-If you only want plugin registration after installing the package:
+![Calls view showing filters, totals, the model-call table, and the compact details rail.](docs/assets/dashboard-calls.png?v=readme-drilldown)
 
-```bash
-codex-usage-tracker install-plugin
-```
+Click a call to open the dedicated investigator for exact token accounting, cache/accounting deltas, local serialized evidence buckets, and redacted turn-log evidence loaded only at runtime.
 
-More install paths: [Install Guide](docs/install.md).
+![Call investigator showing token accounting, cache diagnostics, serialized evidence groups, and raw evidence controls.](docs/assets/dashboard-call-investigator.png?v=readme-drilldown)
 
-## Platform Support
+The lower investigator view keeps the raw JSONL evidence opt-in and runtime-only while still showing visible-context estimates, serialized evidence upper bounds, and redacted turn-log entries.
 
-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.
+![Lower call investigator view showing context-change estimates, serialized evidence groups, and redacted runtime evidence entries.](docs/assets/dashboard-call-investigator-evidence.png?v=readme-drilldown)
 
-## Dashboard Preview
+Threads view groups related calls so long chats, subagents, and auto-review passes are easier to reason about as one work session.
 
-The Calls table is the main investigation surface: filter, sort, inspect details, and export the exact aggregate rows you are looking at.
+![Threads view with one expanded thread and its calls in chronological order.](docs/assets/dashboard-threads.png?v=readme-drilldown)
 
-![Calls view showing filters, totals, the model-call table, and the details panel.](docs/assets/dashboard-calls.png?v=aa16502)
+Insights still gives a fast triage layer for costly threads, low cache reuse, context bloat, and pricing gaps.
 
-Threads view groups related calls so long chats, subagents, and auto-review passes are easier to reason about as one work session.
+![Insights view with ranked Needs Attention cards, investigation presets, and top threads by attention score.](docs/assets/dashboard-insights.png?v=readme-drilldown)
+
+The dashboard screenshots use synthetic aggregate fixture data, and the companion prompt and chat previews are synthetic. They do not contain prompts from local logs, assistant responses, tool output, real thread names, real usage totals, or real Codex session content. See the [Dashboard Guide](docs/dashboard-guide.md) for the full walkthrough.
 
-![Threads view with one expanded thread and its calls in chronological order.](docs/assets/dashboard-threads.png?v=3cd7338)
+If this helped you track Codex usage, starring the repo helps others find it. Issues and feature requests are welcome.
 
-The details panel keeps the primary cost, cache, context, allowance, and pricing signals visible before raw identifiers.
+## Companion Skill And Plugin
 
-![Details panel showing aggregate fields for the selected usage row.](docs/assets/dashboard-details.png?v=84cf6dd)
+The dashboard is the core product surface. The Codex plugin and companion usage skill are add-ons that let Codex refresh local aggregates, call the MCP tools, and explain usage patterns conversationally after plugin discovery. Examples: [MCP And Codex Skills](docs/mcp.md).
 
-Insights still gives a fast triage layer for costly threads, low cache reuse, context bloat, and pricing gaps.
+<p align="center">
+  <a href="docs/assets/plugin-prompts.png"><img src="docs/assets/plugin-prompts.png?v=readme-drilldown" alt="Synthetic Codex plugin prompt preview showing usage dashboard and thread investigation suggestions." width="86%"></a>
+</p>
 
-![Insights view with ranked Needs Attention cards, investigation presets, and top threads by attention score.](docs/assets/dashboard-insights.png?v=4a40e4f)
+<p align="center">
+  <a href="docs/assets/plugin-thread-leaderboard.png"><img src="docs/assets/plugin-thread-leaderboard.png?v=readme-drilldown" alt="Synthetic Codex chat preview showing the companion skill ranking threads by token usage after refreshing the local aggregate index." width="86%"></a>
+</p>
 
-The dashboard screenshots use synthetic aggregate fixture data, and the companion prompt and chat previews are synthetic. They do not contain prompts from local logs, assistant responses, tool output, real thread names, real usage totals, or real Codex session content. See the [Dashboard Guide](docs/dashboard-guide.md) for the full walkthrough.
+If you only want plugin registration after installing the package:
 
-If this helped you track Codex usage, starring the repo helps others find it. Issues and feature requests are welcome.
+```bash
+codex-usage-tracker install-plugin
+```
+
+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.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.
 
 ## Why This Exists
 
@@ -132,7 +142,7 @@ Then:
 4. Use investigation presets for highest-cost threads, highest-credit calls, context bloat, cache misses, pricing gaps, or estimated-price review.
 5. Open `Threads` to see how a conversation grew and whether subagent or auto-review work attached to it.
 6. Hover or click rows to inspect aggregate fields in `Call Details`.
-7. Use `Load context` only when aggregate fields are not enough; context is fetched on demand from the local source JSONL and is not saved into SQLite or the dashboard.
+7. Use `Show turn log evidence` only when aggregate fields are not enough; context is fetched on demand from the local source JSONL and is not saved into SQLite or the dashboard.
 
 Optional allowance context:
 
@@ -140,7 +150,7 @@ Optional allowance context:
 codex-usage-tracker parse-allowance "5h 79% 6:50 PM Weekly 33% Jun 7"
 ```
 
-The tracker cannot read your logged-in ChatGPT plan or live remaining usage automatically. Allowance values are only as accurate as the values you manually copy from Codex Settings, `/status`, or another trusted usage display. Details: [Pricing, Credits, And Allowance](docs/pricing-and-credits.md).
+The tracker cannot read your logged-in ChatGPT plan or live remaining usage automatically. When local Codex logs include `token_count.rate_limits`, the dashboard can show the latest observed 5-hour and weekly remaining percentages from those logs. Otherwise, allowance values are only as accurate as the values you manually copy from Codex Settings, `/status`, or another trusted usage display. Details: [Pricing, Credits, And Allowance](docs/pricing-and-credits.md).
 
 ## What It Includes
 
@@ -155,7 +165,7 @@ The tracker cannot read your logged-in ChatGPT plan or live remaining usage auto
 
 ## Dashboard Language
 
-The dashboard supports localized UI text. English is the canonical catalog, and the project includes starter locale catalogs for common dashboard languages.
+The dashboard supports localized UI text. English is the canonical catalog, and the project includes translated locale catalogs for common dashboard languages.
 
 Set the initial dashboard language with `--lang`:
 
@@ -171,7 +181,7 @@ 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.
+Supported dashboard locales include English, Vietnamese, Spanish, French, German, Portuguese, Japanese, Simplified Chinese, Korean, Russian, Italian, and Arabic. This localizes dashboard UI text, not raw Codex log content, thread names, project names, paths, full CLI output, or data exports.
 
 ### Adding A Dashboard Language
 
@@ -248,7 +258,7 @@ This is optional. The normal shell install above is the fastest trusted path for
 - Token counts come from Codex's logged counters; the tracker does not re-tokenize prompts.
 - 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.
+- Live account allowance cannot be read automatically by this local tracker; remaining 5-hour and weekly allowance is shown only from local Codex `token_count.rate_limits` snapshots when present, or from copied values you configure.
 - 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.

{codex_usage_tracking-0.5.0 → codex_usage_tracking-0.7.0}/docs/architecture.md

@@ -4,31 +4,32 @@ Codex Usage Tracker is a local sidecar app. It reads aggregate token counters fr
 
 ## Boundaries
 
-- `parser.py` converts local JSONL events into aggregate `UsageEvent` records. It must not persist prompts, assistant text, tool output, or transcript snippets.
+- `parser.py` converts local JSONL events into aggregate `UsageEvent` records. It also attaches metadata-only call-origin categories, archived-session flags, and conservative thread keys. It must not persist prompts, assistant text, tool output, or transcript snippets.
+- `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 parser refresh or explicit context loading only.
 - `schema.py` owns persisted `usage_events` columns. Add columns there before changing SQLite migrations or export behavior.
-- `store.py` owns SQLite setup, refresh, rebuild, and query access. Keep filesystem scanning, database writes, SQL prefilters, counts, limits, and offsets here.
+- `store.py` owns SQLite setup, refresh, rebuild, query access, persisted per-thread previous/next call links, materialized thread summaries, source-file refresh cursors, and SQL-backed live dashboard API slices. Keep filesystem scanning, database writes, SQL prefilters, counts, limits, offsets, and incremental refresh decisions here.
 - `reports.py` is the application-service layer for summaries, expensive-call reports, recommendations, pricing coverage, and filtered query payloads. CLI and MCP 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 the lightweight contract checks for schema-versioned CLI/MCP payloads. Add payload builders and contract entries together when both surfaces need the same shape.
+- `api_payloads.py` owns stable JSON payload helpers shared by CLI and MCP. `json_contracts.py` owns the lightweight contract checks for schema-versioned CLI/MCP payloads and localhost live API payloads. Add payload builders and contract entries together when surfaces need the same shape.
 - `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 also belongs in `projects.py` so CLI, MCP, dashboard, CSV, and support-bundle surfaces share the same behavior.
-- `dashboard.py` builds aggregate-only dashboard payloads and writes HTML/assets. `server.py` adds localhost refresh and explicit lazy context loading.
-- `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.
+- `dashboard.py` builds aggregate-only static dashboard payloads and writes HTML/assets. `server.py` adds localhost refresh, the compatibility `/api/usage` endpoint, SQL-backed live API slices, and explicit lazy context loading.
+- `plugin_data/dashboard/dashboard_format.js` owns dashboard formatting primitives. `dashboard_data.js` owns row payload and thread relationship helpers. `dashboard_analysis.js` owns scoring, sorting, recommendation, and thread grouping logic. `dashboard_cells.js` owns reusable table/cell HTML helpers. `dashboard_details.js` owns sidebar detail and thread narrative rendering. `dashboard_insights.js` owns insight cards and investigation preset UI. `dashboard_tables.js` owns Calls, Threads, and expanded thread-call table rendering. `dashboard_filters.js` owns date range parsing and row date matching. `dashboard_state.js` owns URL, CSV, and download state utilities. `dashboard_i18n.js`, `dashboard_payload_cache.js`, and `dashboard_tooltips.js` own localization, session aggregate cache, and fast tooltip helpers. `dashboard_call_investigator.js` owns the dedicated call drilldown surface. `dashboard.js` owns top-level DOM rendering, event handling, and API refresh orchestration.
+- `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. Its default quick mode omits tool output and serialized groups; full serialized JSONL group analysis is explicit.
 - `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 and threshold enforcement 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. Its optional `--with-source-logs` mode writes synthetic JSONL source logs to time explicit context loading and to guard normal dashboard payload assembly against source-log reads. 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`.
 
 ## Extension Rules
 
-1. Add new persisted metrics through `UsageEvent`, `schema.py`, migrations, store queries, dashboard payload tests, and CSV/export checks.
+1. Add new persisted usage-event metrics through `UsageEvent`, `schema.py`, migrations, store queries, dashboard payload tests, and CSV/export checks. Add auxiliary aggregate tables such as `thread_summaries` or `source_files` through `store.py` migrations plus focused migration/privacy tests.
 2. Add new report views through `reports.py` first, then wire CLI and MCP wrappers to that shared service.
 3. Add new machine-readable outputs through `api_payloads.py` or report payload methods with a `schema` value, a `json_contracts.py` entry, and focused tests.
 4. Add dashboard-only interactions in `plugin_data/dashboard/dashboard.js` and keep URL state in `dashboard_state.js`.
 5. Keep all examples, screenshots, mocks, and tests synthetic. Never derive fixtures from real logs.
 6. 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 that installable plugin assets stay complete and synced.
-7. When adding fields derived from `cwd`, Git metadata, or source paths, decide how they behave in `normal`, `redacted`, and `strict` privacy modes before exposing them in dashboard, JSON, CSV, MCP, or support-bundle output.
+7. When adding fields derived from `cwd`, Git metadata, source paths, or log-event metadata, decide how they behave in `normal`, `redacted`, and `strict` privacy modes before exposing them in dashboard, JSON, CSV, MCP, or support-bundle output.
 
 ## Validation
 
@@ -38,10 +39,9 @@ Use the narrowest useful check first, then the release suite before committing:
 python -m pytest
 python -m compileall src
 python -m mypy
-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
+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
@@ -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 --json --enforce-thresholds` after changing SQLite filters, dashboard payload loading, or indexes. Run the 500k benchmark before release work when practical.
+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 explicit context loading or source-log diagnostics. Run the 500k benchmark before release work when practical.