codex-usage-tracking 0.13.1__tar.gz → 0.14.0__tar.gz

{codex_usage_tracking-0.13.1 → codex_usage_tracking-0.14.0}/.codex-plugin/plugin.json

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

{codex_usage_tracking-0.13.1 → codex_usage_tracking-0.14.0}/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.14.0 - 2026-07-04
+
+- Make `serve-dashboard --open` prefer the React dashboard route while keeping legacy `/dashboard.html` available as a localhost fallback, and expose both URLs in `serve-dashboard --json`.
+- Restore major legacy dashboard parity in the React dashboard, including overview recent-call loading controls, sticky thread/header table affordances, row-to-investigator actions, diagnostics fact-call pagination, report and call sorting state, and legacy URL/filter normalization.
+- Add local-only transition safeguards: the prominent unofficial-project banner, aggregate-only privacy boundaries, rebuilt dashboard assets, and release-gate documentation for the React bundle.
+- Prioritize weekly usage windows in Overview and Settings so weekly remaining usage is surfaced ahead of short 5-hour windows.
+- Expose dashboard-shaped MCP payloads for status, calls, call details, threads, report packs, and dashboard recommendations, and teach bundled skills concrete token-waste investigation prompts.
+
 ## 0.13.1 - 2026-06-30
 
 - Add guided usage-summary diagnostics across CLI, API, and dashboard to explain the largest aggregate drivers behind usage.
@@ -90,7 +98,7 @@
 - Add an aggregate Diagnostics dashboard for inspecting diagnostic facts, associated calls, token totals, and on-demand evidence without persisting raw transcript text.
 - Add diagnostic fact extraction, reporting APIs, dashboard drilldowns, sortable associated-call tables, and load-more controls for larger diagnostic result sets.
 - Add source byte offsets and context seek diagnostics so on-demand evidence loading can seek when offsets are valid and fall back safely when they are missing or stale.
-- Harden dashboard startup so visiting Diagnostics before other views load no longer prevents Calls, Threads, or Insights from hydrating.
+- Harden dashboard startup so visiting Diagnostics before other views load no longer prevents Calls, Threads, or Overview from hydrating.
 - Make Live refresh use the cached/indexed append path and fetch only newly visible leading rows instead of running the full manual refresh reset cycle.
 
 ## 0.7.0 - 2026-06-18

{codex_usage_tracking-0.13.1 → codex_usage_tracking-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.13.1
+Version: 0.14.0
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -45,8 +45,8 @@ Dynamic: license-file
 # Codex Usage Tracker
 
 <p align="center">
-  <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>
+  <a href="docs/assets/dashboard-calls.png?v=readme-smart-20260704"><img src="docs/assets/dashboard-calls-preview.png?v=readme-smart-20260704" alt="Codex Usage Tracker React dashboard showing model-call filters, frozen call rows, and row loading controls." width="49%"></a>
+  <a href="docs/assets/dashboard-call-investigator.png?v=readme-smart-20260704"><img src="docs/assets/dashboard-call-investigator-preview.png?v=readme-smart-20260704" alt="Codex Usage Tracker call investigator showing token accounting, cache diagnostics, and explicit evidence controls." width="49%"></a>
 </p>
 
 Local-first dashboard, Codex plugin, and companion skill for understanding where your Codex tokens and usage credits are going.
@@ -80,7 +80,7 @@ If `codex-usage-tracker` is not found after installing with pipx, open a new ter
 
 First install? Start with the [First Five Minutes guide](docs/first-five-minutes.md) for setup, verification, empty-dashboard checks, and safe issue diagnostics.
 
-`serve-dashboard` refreshes active-session usage before opening by default. Use `--no-refresh` only when you intentionally want to inspect the cached local index.
+`serve-dashboard` refreshes active-session usage before opening the React dashboard by default. The legacy dashboard remains available at `/dashboard.html` on the same localhost server. Use `--no-refresh` only when you intentionally want to inspect the cached local index.
 
 Package naming: the PyPI distribution is `codex-usage-tracking`; the installed command is `codex-usage-tracker`; the GitHub repository remains `douglasmonsky/codex-usage-tracker`. The `codex-usage-tracker` PyPI name is not this project, so avoid similarly named packages when following these docs.
 
@@ -96,35 +96,35 @@ Want Codex to do it for you? Paste: `Install codex-usage-tracking with pipx, run
 
 ## Dashboard Preview
 
-The Calls table is the main investigation surface: filter, sort, inspect details, and export the exact aggregate rows you are looking at.
+Overview is the dashboard landing workspace: it shows recent aggregate usage, weekly remaining usage context, row loading controls, and charts that open on recent dates.
 
-![Calls view showing filters, totals, the model-call table, and the compact details rail.](docs/assets/dashboard-calls.png?v=readme-drilldown)
+![Overview view showing high-level metrics, row loading controls, time-series charts, and recent aggregate calls.](docs/assets/dashboard-insights.png?v=readme-smart-20260704)
 
-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.
+Calls is the high-density investigation surface: filter, sort, inspect details, and export the exact aggregate rows you are looking at.
 
-![Call investigator showing token accounting, cache diagnostics, serialized evidence groups, and raw evidence controls.](docs/assets/dashboard-call-investigator.png?v=readme-drilldown)
+![Calls view showing the expanded model-call table with sticky thread rows and detail controls.](docs/assets/dashboard-calls.png?v=readme-smart-20260704)
 
-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 details rail stays beside the model-call table, so you can inspect aggregate call accounting before opening a full investigator route.
 
-![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)
+![Calls view showing the expanded model-call table beside the Call Drill-Down detail rail.](docs/assets/dashboard-details.png?v=readme-smart-20260704)
 
-Threads view groups related calls so long chats, subagents, and auto-review passes are easier to reason about as one work session.
+Click a call row to open the dedicated investigator for exact token accounting, cache/accounting deltas, local serialized evidence buckets, and runtime-only evidence controls.
 
-![Threads view with one expanded thread and its calls in chronological order.](docs/assets/dashboard-threads.png?v=readme-drilldown)
+![Call investigator showing token accounting, cache diagnostics, serialized evidence groups, and evidence controls.](docs/assets/dashboard-call-investigator.png?v=readme-smart-20260704)
 
-Diagnostics surfaces on-demand snapshot reports for tool output, commands, Git interactions, file reads, file modifications, read productivity, and concentration without tying them to the normal live refresh loop.
+The lower investigator view keeps local JSONL context gated behind explicit localhost actions; raw context is not embedded in generated dashboard HTML.
 
-![Diagnostics view showing weekly usage remaining and projected weekly credits from on-demand usage-drain reports.](docs/assets/dashboard-diagnostics.png?v=readme-usage-drain)
+![Lower call investigator view showing context estimates and the explicit raw-context evidence gate.](docs/assets/dashboard-call-investigator-evidence.png?v=readme-smart-20260704)
 
-The Git Interactions panel expands the safe Git and GitHub CLI operation families without storing command text, branch names, release notes, or patch content.
+Threads view groups related calls so long chats, subagents, and auto-review passes are easier to reason about as one work session.
 
-![Diagnostics Git Interactions panel showing aggregate Git and GitHub CLI operation counts.](docs/assets/dashboard-diagnostics-git-expanded.png?v=readme-diagnostics-git)
+![Threads view with one expanded thread and its calls.](docs/assets/dashboard-threads.png?v=readme-smart-20260704)
 
-Insights still gives a fast triage layer for costly threads, low cache reuse, context bloat, and pricing gaps.
+Diagnostics Notebook surfaces on-demand snapshot reports for usage drain, tool output, commands, Git interactions, file reads, file modifications, read productivity, and concentration without tying them to the normal live refresh loop.
 
-![Insights view with ranked Needs Attention cards, investigation presets, and top threads by attention score.](docs/assets/dashboard-insights.png?v=readme-drilldown)
+![Diagnostics Notebook view showing diagnostic snapshot modules and usage-drain reporting.](docs/assets/dashboard-diagnostics.png?v=readme-smart-20260704)
 
-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, real 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.
+Dashboard screenshots use synthetic aggregate fixture data, and companion prompt/chat previews are synthetic. They do not contain prompts, local logs, assistant responses, real 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 this helped you track Codex usage, starring the repo helps others find it. Issues and feature requests are welcome.
 
@@ -192,7 +192,7 @@ codex-usage-tracker serve-dashboard --open
 Then:
 
 1. Leave `Live` enabled while working, or click `Refresh` after a Codex run finishes.
-2. Start in `Insights` and scan the `Needs Attention` cards.
+2. Start in `Overview` and scan the high-level metrics and recent calls.
 3. Use `Time` presets or calendar fields to focus on today, this week, the last 7 days, this month, or a custom range.
 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.
@@ -211,7 +211,7 @@ The tracker cannot read your logged-in ChatGPT plan or live remaining usage auto
 
 - Local SQLite index at `~/.codex-usage-tracker/usage.sqlite3`.
 - Static dashboard generation plus localhost live refresh.
-- `Insights`, `Calls`, `Threads`, and `Diagnostics` dashboard views, including on-demand usage-drain report runs with cumulative per-thread cost curves.
+- `Overview`, `Calls`, `Threads`, and `Diagnostics` dashboard views, including on-demand usage-drain report runs with cumulative per-thread cost curves.
 - Active-only dashboards by default, with an explicit `All history` toggle for archived sessions.
 - CLI summaries, queries, CSV export, dashboard generation, doctor checks, and support bundles.
 - MCP tools for Codex sessions that want to query local usage data.

{codex_usage_tracking-0.13.1 → codex_usage_tracking-0.14.0}/README.md

@@ -1,8 +1,8 @@
 # Codex Usage Tracker
 
 <p align="center">
-  <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>
+  <a href="docs/assets/dashboard-calls.png?v=readme-smart-20260704"><img src="docs/assets/dashboard-calls-preview.png?v=readme-smart-20260704" alt="Codex Usage Tracker React dashboard showing model-call filters, frozen call rows, and row loading controls." width="49%"></a>
+  <a href="docs/assets/dashboard-call-investigator.png?v=readme-smart-20260704"><img src="docs/assets/dashboard-call-investigator-preview.png?v=readme-smart-20260704" alt="Codex Usage Tracker call investigator showing token accounting, cache diagnostics, and explicit evidence controls." width="49%"></a>
 </p>
 
 Local-first dashboard, Codex plugin, and companion skill for understanding where your Codex tokens and usage credits are going.
@@ -36,7 +36,7 @@ If `codex-usage-tracker` is not found after installing with pipx, open a new ter
 
 First install? Start with the [First Five Minutes guide](docs/first-five-minutes.md) for setup, verification, empty-dashboard checks, and safe issue diagnostics.
 
-`serve-dashboard` refreshes active-session usage before opening by default. Use `--no-refresh` only when you intentionally want to inspect the cached local index.
+`serve-dashboard` refreshes active-session usage before opening the React dashboard by default. The legacy dashboard remains available at `/dashboard.html` on the same localhost server. Use `--no-refresh` only when you intentionally want to inspect the cached local index.
 
 Package naming: the PyPI distribution is `codex-usage-tracking`; the installed command is `codex-usage-tracker`; the GitHub repository remains `douglasmonsky/codex-usage-tracker`. The `codex-usage-tracker` PyPI name is not this project, so avoid similarly named packages when following these docs.
 
@@ -52,35 +52,35 @@ Want Codex to do it for you? Paste: `Install codex-usage-tracking with pipx, run
 
 ## Dashboard Preview
 
-The Calls table is the main investigation surface: filter, sort, inspect details, and export the exact aggregate rows you are looking at.
+Overview is the dashboard landing workspace: it shows recent aggregate usage, weekly remaining usage context, row loading controls, and charts that open on recent dates.
 
-![Calls view showing filters, totals, the model-call table, and the compact details rail.](docs/assets/dashboard-calls.png?v=readme-drilldown)
+![Overview view showing high-level metrics, row loading controls, time-series charts, and recent aggregate calls.](docs/assets/dashboard-insights.png?v=readme-smart-20260704)
 
-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.
+Calls is the high-density investigation surface: filter, sort, inspect details, and export the exact aggregate rows you are looking at.
 
-![Call investigator showing token accounting, cache diagnostics, serialized evidence groups, and raw evidence controls.](docs/assets/dashboard-call-investigator.png?v=readme-drilldown)
+![Calls view showing the expanded model-call table with sticky thread rows and detail controls.](docs/assets/dashboard-calls.png?v=readme-smart-20260704)
 
-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 details rail stays beside the model-call table, so you can inspect aggregate call accounting before opening a full investigator route.
 
-![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)
+![Calls view showing the expanded model-call table beside the Call Drill-Down detail rail.](docs/assets/dashboard-details.png?v=readme-smart-20260704)
 
-Threads view groups related calls so long chats, subagents, and auto-review passes are easier to reason about as one work session.
+Click a call row to open the dedicated investigator for exact token accounting, cache/accounting deltas, local serialized evidence buckets, and runtime-only evidence controls.
 
-![Threads view with one expanded thread and its calls in chronological order.](docs/assets/dashboard-threads.png?v=readme-drilldown)
+![Call investigator showing token accounting, cache diagnostics, serialized evidence groups, and evidence controls.](docs/assets/dashboard-call-investigator.png?v=readme-smart-20260704)
 
-Diagnostics surfaces on-demand snapshot reports for tool output, commands, Git interactions, file reads, file modifications, read productivity, and concentration without tying them to the normal live refresh loop.
+The lower investigator view keeps local JSONL context gated behind explicit localhost actions; raw context is not embedded in generated dashboard HTML.
 
-![Diagnostics view showing weekly usage remaining and projected weekly credits from on-demand usage-drain reports.](docs/assets/dashboard-diagnostics.png?v=readme-usage-drain)
+![Lower call investigator view showing context estimates and the explicit raw-context evidence gate.](docs/assets/dashboard-call-investigator-evidence.png?v=readme-smart-20260704)
 
-The Git Interactions panel expands the safe Git and GitHub CLI operation families without storing command text, branch names, release notes, or patch content.
+Threads view groups related calls so long chats, subagents, and auto-review passes are easier to reason about as one work session.
 
-![Diagnostics Git Interactions panel showing aggregate Git and GitHub CLI operation counts.](docs/assets/dashboard-diagnostics-git-expanded.png?v=readme-diagnostics-git)
+![Threads view with one expanded thread and its calls.](docs/assets/dashboard-threads.png?v=readme-smart-20260704)
 
-Insights still gives a fast triage layer for costly threads, low cache reuse, context bloat, and pricing gaps.
+Diagnostics Notebook surfaces on-demand snapshot reports for usage drain, tool output, commands, Git interactions, file reads, file modifications, read productivity, and concentration without tying them to the normal live refresh loop.
 
-![Insights view with ranked Needs Attention cards, investigation presets, and top threads by attention score.](docs/assets/dashboard-insights.png?v=readme-drilldown)
+![Diagnostics Notebook view showing diagnostic snapshot modules and usage-drain reporting.](docs/assets/dashboard-diagnostics.png?v=readme-smart-20260704)
 
-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, real 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.
+Dashboard screenshots use synthetic aggregate fixture data, and companion prompt/chat previews are synthetic. They do not contain prompts, local logs, assistant responses, real 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 this helped you track Codex usage, starring the repo helps others find it. Issues and feature requests are welcome.
 
@@ -148,7 +148,7 @@ codex-usage-tracker serve-dashboard --open
 Then:
 
 1. Leave `Live` enabled while working, or click `Refresh` after a Codex run finishes.
-2. Start in `Insights` and scan the `Needs Attention` cards.
+2. Start in `Overview` and scan the high-level metrics and recent calls.
 3. Use `Time` presets or calendar fields to focus on today, this week, the last 7 days, this month, or a custom range.
 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.
@@ -167,7 +167,7 @@ The tracker cannot read your logged-in ChatGPT plan or live remaining usage auto
 
 - Local SQLite index at `~/.codex-usage-tracker/usage.sqlite3`.
 - Static dashboard generation plus localhost live refresh.
-- `Insights`, `Calls`, `Threads`, and `Diagnostics` dashboard views, including on-demand usage-drain report runs with cumulative per-thread cost curves.
+- `Overview`, `Calls`, `Threads`, and `Diagnostics` dashboard views, including on-demand usage-drain report runs with cumulative per-thread cost curves.
 - Active-only dashboards by default, with an explicit `All history` toggle for archived sessions.
 - CLI summaries, queries, CSV export, dashboard generation, doctor checks, and support bundles.
 - MCP tools for Codex sessions that want to query local usage data.

{codex_usage_tracking-0.13.1 → codex_usage_tracking-0.14.0}/docs/cli-json-schemas.md

@@ -46,7 +46,8 @@ Tracked schema ids:
 | `codex-usage-tracker-reset-db-v1` | CLI `reset-db --yes --json` |
 | `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")` |
+| `codex-usage-tracker-recommendations-v1` | CLI `recommendations --json`, MCP `usage_recommendations(response_format="json")`, MCP `usage_dashboard_recommendations(...)` |
+| `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` |
 | `codex-usage-tracker-diagnostic-tool-output-v1` | CLI `diagnostics tool-output --json`, dashboard server `/api/diagnostics/tool-output` |
@@ -64,14 +65,14 @@ Tracked schema ids:
 | `codex-usage-tracker-context-settings-v1` | Dashboard server `/api/context-settings` response |
 | `codex-usage-tracker-open-investigator-v1` | Dashboard server `/api/open-investigator` response |
 | `codex-usage-tracker-live-api-v1` | Dashboard server live API payload family marker |
-| `codex-usage-tracker-status-v1` | Dashboard server `/api/status` response |
-| `codex-usage-tracker-calls-v1` | Dashboard server `/api/calls` response |
-| `codex-usage-tracker-call-v1` | Dashboard server `/api/call` response |
-| `codex-usage-tracker-threads-v1` | Dashboard server `/api/threads` response |
+| `codex-usage-tracker-status-v1` | Dashboard server `/api/status` response, MCP `usage_status()` |
+| `codex-usage-tracker-calls-v1` | Dashboard server `/api/calls` response, MCP `usage_calls(...)` |
+| `codex-usage-tracker-call-v1` | Dashboard server `/api/call` response, MCP `usage_call_detail(record_id=...)` |
+| `codex-usage-tracker-threads-v1` | Dashboard server `/api/threads` response, MCP `usage_threads(...)` |
 | `codex-usage-tracker-thread-calls-v1` | Dashboard server `/api/thread-calls` 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-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-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_tracking-0.13.1 → codex_usage_tracking-0.14.0}/docs/cli-reference.md

@@ -79,7 +79,7 @@ codex-usage-tracker serve-dashboard --no-context-api --open
 
 `serve-dashboard --context-api explicit` is the default and keeps context loading as an explicit per-row action. `serve-dashboard --no-context-api` or `--context-api disabled` starts with context loading off; a token-protected button in the local details panel can enable it without restarting the server.
 
-`open-dashboard` and `serve-dashboard` refresh active-session logs before opening by default. Use `--no-refresh` only for an intentionally cached snapshot. The lower-level `dashboard` command writes from the current SQLite index and does not rescan logs.
+`open-dashboard` and `serve-dashboard` refresh active-session logs before opening by default. `serve-dashboard --open` opens the React dashboard; the legacy dashboard remains available at `/dashboard.html` on the same localhost server. Use `--no-refresh` only for an intentionally cached snapshot. The lower-level `dashboard` command writes from the current SQLite index and does not rescan logs.
 
 Dashboards default to active sessions only. Use `--include-archived` for an all-history static/opened dashboard, or switch the served dashboard's `History` control from `Active sessions only` to `All history` when you intentionally want archived logs scanned and included.
 

{codex_usage_tracking-0.13.1 → codex_usage_tracking-0.14.0}/docs/dashboard-guide.md

@@ -35,7 +35,7 @@ codex-usage-tracker --privacy-mode strict dashboard --open
 
 Redacted mode hides raw cwd/source paths, hides Git remote labels, and hashes unnamed projects while preserving configured aliases. Strict mode also hides project-relative cwd, Git branch, and tags. The dashboard header shows the active metadata mode.
 
-`serve-dashboard` refreshes active-session logs before opening by default. Use `--no-refresh` only when you intentionally want a cached view of the existing local index.
+`serve-dashboard` refreshes active-session logs before opening the React dashboard by default. The legacy dashboard remains available at `/dashboard.html` on the same localhost server. Use `--no-refresh` only when you intentionally want a cached view of the existing local index.
 
 Set the initial dashboard language with the global `--lang` option before the command, or use `CODEX_USAGE_TRACKER_LANG`:
 
@@ -61,21 +61,21 @@ Static file mode can still filter, sort, and inspect aggregate call fields. `ope
 
 The localhost server uses a random per-server token for refresh and context API calls, validates loopback `Host` and `Origin` headers, and can start with context loading off through `codex-usage-tracker serve-dashboard --no-context-api`.
 
-## Insights View
+## Overview View
 
-![Insights view with ranked attention cards, investigation presets, and top threads by attention score.](assets/dashboard-insights.png)
+![Overview view showing high-level metrics, row loading controls, time-series charts, and recent aggregate calls.](assets/dashboard-insights.png)
 
-Open the `Insights` view when you want to answer "what needs attention?" before you start sorting tables.
+Open `Overview` when you want a quick read on current aggregate usage before sorting deeper tables.
 
-- `Needs Attention` cards rank costly threads, Codex allowance usage, low cache reuse, context bloat, unpriced usage, estimated pricing, and reasoning-output spikes from aggregate fields only.
-- `Investigation Presets` apply a view, derived filter, sort order, and explanatory caption together.
-- Presets include highest-cost threads, highest Codex credits, context bloat, cache misses, pricing gaps, and estimated-price review.
-- The top table shows threads by attention score so you can jump from a summary signal into a thread timeline or selected call.
-- Clear an active preset to return to normal manual filtering and sorting.
+- Global dashboard filters narrow Overview and the secondary workspaces by model, reasoning effort, pricing/credit confidence, and time range using the same URL parameters as legacy dashboard links.
+- Metric cards summarize loaded aggregate rows without exposing prompts, assistant text, or raw tool output.
+- Time-series charts open on the most recent dates first and can scroll left for earlier history while keeping the value axis visible.
+- `Recent Calls` keeps the homepage modular: it shows the latest matching calls and lets any row open Call Investigator directly.
+- Use `Investigator` or `Calls` when you need deeper ranking, filtering, or preset-style investigation workflows.
 
 ## Calls View
 
-![Calls view showing filters, totals, the model-call table, and the compact details rail.](assets/dashboard-calls.png)
+![Calls view showing the expanded model-call table with sticky thread rows and detail controls.](assets/dashboard-calls.png)
 
 Use `Calls` view when you want to inspect individual model calls.
 
@@ -101,7 +101,7 @@ Use `Calls` view when you want to inspect individual model calls.
 - The first detail section includes a recommended action and a "why flagged" explanation derived only from aggregate counters and pricing/allowance metadata.
 - Raw aggregate identifiers and source file metadata are collapsed until you need them.
 - The expanded details panel reserves a visible scrollbar so long field lists are discoverable before you start scrolling.
-- `Load more` appears when the active Insights, Calls, Threads, or expanded thread-call section has more rows to reveal.
+- `Load more` appears when the active Overview, Calls, Threads, or expanded thread-call section has more rows to reveal.
 - When served from localhost, `/api/usage` accepts `limit` and `offset` so automation can page aggregate rows without loading an entire large history.
 - After you scroll down, the bottom-right `Top` button returns to the top of the dashboard.
 
@@ -117,7 +117,7 @@ Useful interpretation notes:
 
 ## Threads View
 
-![Threads view with one expanded thread and sortable newest-first calls.](assets/dashboard-threads.png)
+![Threads view with one expanded thread and its calls.](assets/dashboard-threads.png)
 
 Use `Threads` view when you want to understand a work session as a group instead of one call at a time.
 
@@ -130,7 +130,7 @@ Use `Threads` view when you want to understand a work session as a group instead
 
 ## Diagnostics View
 
-![Diagnostics view showing on-demand usage-drain charts for weekly usage remaining and projected weekly credits.](assets/dashboard-diagnostics.png)
+![Diagnostics Notebook view showing diagnostic snapshot modules and usage-drain reporting.](assets/dashboard-diagnostics.png)
 
 Use `Diagnostics` view when you want to see what structured event patterns are happening and what token totals are associated with those patterns.
 
@@ -149,26 +149,26 @@ Use `Diagnostics` view when you want to see what structured event patterns are h
 - Click `Calls` on a fact row to load associated model calls. Call links and largest-call links open the Call Investigator, where raw context remains explicit and on demand.
 - Associated token totals are not causal allocations and are not additive when one call has multiple diagnostic facts.
 
-The same time range, model, reasoning, history scope, cards, and load controls apply in `Insights`, `Calls`, `Threads`, and `Diagnostics` views. Search, confidence, and sort controls currently scope the call/thread tables, not Diagnostics fact totals.
+The same model, reasoning, confidence, time range, history scope, cards, and load controls apply in `Overview`, `Threads`, `Diagnostics`, and the other secondary workspaces. `Calls` keeps a fuller table-specific filter row for local search, source coverage, sorting, density, and selected-row state.
 
 ## Call Investigator
 
-![Call investigator showing exact token accounting, cache/accounting deltas, context estimates, and runtime evidence.](assets/dashboard-call-investigator.png)
+![Call investigator showing exact token accounting, cache/accounting deltas, context estimates, and evidence controls.](assets/dashboard-call-investigator.png)
 
-Clicking a Calls row opens `dashboard.html?view=call&record=<record_id>` for one model call. Hover remains the fast scanning surface; the investigator is the deeper diagnostic page for a single selected call. Expanded Threads rows and the details panel can still expose explicit investigator actions where a row click already has another meaning.
+Clicking a Calls row opens `react-dashboard.html?view=call&record=<record_id>` for one model call. Legacy `dashboard.html?view=call&record=...` links remain accepted and hydrate the same investigator route. Hover remains the fast scanning surface; the investigator is the deeper diagnostic page for a single selected call. Expanded Threads rows and the details panel can still expose explicit investigator actions where a row click already has another meaning.
 
 The investigator separates evidence by confidence:
 
 - `Exact`: logged token callback counts, cost, Codex credits, cache ratio, model, effort, source, and context-window pressure.
 - `Derived`: previous/next calls in the same resolved thread and cache/accounting deltas versus the previous chronological call.
 - `Estimated`: visible new-context estimates, serialized local JSONL upper bounds, candidate serialized-overhead groups, and any remaining gap after that upper bound. These are attribution aids, not exact cached text spans.
-- `Evidence`: redacted local JSONL turn-log evidence loaded at runtime for the selected investigator call.
+- `Evidence`: redacted local JSONL turn-log evidence loaded at runtime for the selected investigator call after explicit localhost action.
 
 Previous and next buttons move chronologically within the same resolved thread and keep the selected call in the URL. Cache diagnostics label common patterns such as warm cache reuse, cold resume or stale cache, partial cache miss, uncached spike, and post-compaction. Delta cards compare input, cached input, uncached input, output/reasoning output, and cache ratio to the previous call and use "cache/accounting delta" terminology because logs do not expose exact cached text spans.
 
 ## Details And Context
 
-![Calls view with a selected usage row and the compact Call Details rail collapsed.](assets/dashboard-details.png)
+![Calls view showing the expanded model-call table beside the Call Drill-Down detail rail.](assets/dashboard-details.png)
 
 The details rail is collapsed by default to preserve table space. Open `Call Details` when you want a compact aggregate preview without leaving the table. When expanded on desktop, it sticks inside the viewport and scrolls internally when the selected call has more fields or loaded context than can fit on screen.
 
@@ -191,7 +191,7 @@ For selected threads, the panel shows:
 - a compact thread timeline with recent calls, cost, credits, cache, context, and pricing cues
 - direct, subagent, auto-review, attached-call, and spawned-thread relationship counts
 
-When served from localhost, the call investigator automatically fetches quick, redacted source evidence for only that call. The details panel still uses an explicit `Show turn log evidence` action so hovering rows does not pull raw context unexpectedly.
+When served from localhost with the context API enabled, the call investigator can fetch quick, redacted source evidence for only the selected call. The details panel still uses an explicit `Show turn log evidence` action so hovering rows does not pull raw context unexpectedly.
 
 - `Hide tool output` reloads evidence without tool output when the output is noisy.
 - `Show tool output` appears after hiding it and reloads evidence with redacted tool output included again.
@@ -206,7 +206,7 @@ When served from localhost, the call investigator automatically fetches quick, r
 2. Leave `Live` enabled while you work, or click `Refresh` after a Codex run finishes.
 3. Leave `History` on `Active sessions only` for current work. Switch to `All history` when you intentionally want archived sessions included in the live refresh.
 4. Optionally run `parse-allowance` with copied values from Codex Usage or `/status`, or initialize and edit `allowance.json` manually.
-5. Start in `Insights` view and review the highest-severity attention cards.
+5. Start in `Overview` view and review high-level totals, recent trends, and recent calls.
 6. Narrow the `Time` filter when you are investigating a recent spike or a specific work window.
 7. Use a preset when the question is already clear: highest-cost threads, highest Codex credits, context bloat, cache misses, pricing gaps, or estimated-price review.
 8. Use `Threads` view to find the active work thread and any spawned subagent calls.

{codex_usage_tracking-0.13.1 → codex_usage_tracking-0.14.0}/docs/development.md

@@ -38,7 +38,7 @@ fix/<issue-number>-short-description
 docs/<issue-number>-short-description
 chore/<issue-number>-short-description
 test/<issue-number>-short-description
-release/0.13.1
+release/0.14.0
 hotfix/0.3.3
 ```
 
@@ -149,8 +149,8 @@ python scripts/smoke_installed_package.py --docker
 To verify the public PyPI package instead of the local checkout:
 
 ```bash
-python scripts/smoke_installed_package.py --from-pypi --version 0.13.1
-python scripts/smoke_installed_package.py --docker --from-pypi --version 0.13.1
+python scripts/smoke_installed_package.py --from-pypi --version 0.14.0
+python scripts/smoke_installed_package.py --docker --from-pypi --version 0.14.0
 ```
 
 `scripts/check_release.py` treats these public-package smoke commands as release-state claims. Keep their `--version` and `codex-usage-tracking==...` values aligned with `pyproject.toml`; the release gate fails when the docs claim a different public version. It also checks that install docs point at the real PyPI distribution, `codex-usage-tracking`, and keep the warning that `codex-usage-tracker` is a different PyPI package.
@@ -194,7 +194,7 @@ DASHBOARD_BASE_URL=http://127.0.0.1:8898 npm run smoke:dashboard:diagnostics
 
 ## Dashboard Screenshots
 
-Dashboard screenshots in `docs/assets/` and `src/codex_usage_tracker/plugin_data/docs/assets/` must be generated from synthetic aggregate fixture data only.
+Dashboard screenshots in `docs/assets/` and `src/codex_usage_tracker/plugin_data/docs/assets/` must be generated from synthetic aggregate fixture data only. Capture the React dashboard from the Vite fixture route, then mirror the refreshed files into the packaged docs asset directory.
 
 The tracked dashboard screenshot set is:
 
@@ -297,8 +297,8 @@ After the release branch merges, tag from updated `main`, not from an unreviewed
 ```bash
 git switch main
 git pull --ff-only
-git tag -a v0.13.1 -m "codex-usage-tracker 0.13.1"
-git push origin v0.13.0
+git tag -a v0.14.0 -m "codex-usage-tracker 0.14.0"
+git push origin v0.14.0
 ```
 
 Do not create or push release tags without maintainer approval.
@@ -307,7 +307,7 @@ Do not create or push release tags without maintainer approval.
 
 Publishing uses GitHub Actions Trusted Publishing through `.github/workflows/publish.yml`; do not upload from a local machine and do not add PyPI or TestPyPI API tokens.
 
-The first public package release, `0.3.0`, was published on June 8, 2026. Patch release `0.3.1` followed the same day to ship the live-dashboard skill launch fix. Patch release `0.3.2` made dashboard launch refresh the default and added runtime enablement for context loading. Minor release `0.4.0` added Python 3.14 support, release recovery docs, stricter privacy/support-bundle regression coverage, and large-history benchmark thresholds. Patch release `0.4.1` was published by workflow dispatch from `main`; it hardened the PyPI publish workflow and checked off completed 1.0 readiness gates. Minor release `0.5.0` added dashboard localization support and initial language catalogs. Minor release `0.6.0` is the performance and call-drilldown release with SQL-backed live API slices, materialized thread summaries, faster evidence loading, and dashboard runtime module refactors. Patch release `0.6.1` aligns the final README/package screenshots and companion plugin assets. Minor release `0.7.0` adds observed usage snapshots and the latest-observed dashboard card while keeping raw evidence on demand only. Minor release `0.8.0` adds aggregate diagnostics, source-offset context seeking, and live dashboard loading hardening. Patch release `0.8.1` improves Diagnostics fact table readability with pinned fact names and sortable fact columns. Minor release `0.9.0` adds persisted diagnostic snapshots, on-demand diagnostic refresh, tool/command/file-read/concentration reports, and Diagnostics dashboard panels. Minor release `0.10.0` adds Git/GitHub CLI diagnostics, file-modification diagnostics, and derived call timing fields across the dashboard and API. Patch release `0.10.1` adds lightweight action timing to context evidence and ships the synthetic Git Interactions README screenshot. Minor release `0.11.0` adds usage-drain diagnostic reports, projected weekly credit charts, and cumulative thread cost curves. Patch release `0.11.1` improves the Diagnostics weekly projection table and stale snapshot reload controls. Patch release `0.11.2` fixes served dashboard shell hydration and hardens the synthetic source-log benchmark smoke test. Patch release `0.11.3` fixes Windows live dashboard asset MIME handling. Patch release `0.11.4` fixes large-history setup refresh failures from SQLite variable limits. Minor release `0.12.0` ships the maintainability architecture repair, dashboard diagnostics hardening, Agent Maintainer ratchets, and warning-clean test suite. Patch release `0.12.1` ships the package-domain boundary split, allowance helper split, refreshed maintainability baselines, and CLI module entrypoint fix. Minor release `0.13.0` ships adoption-hardening onboarding, first-run diagnostics, support-bundle issue guidance, and installed-wheel lifecycle smoke hardening. Patch release `0.13.1` adds guided usage-summary diagnostics across CLI, API, and dashboard.
+The first public package release, `0.3.0`, was published on June 8, 2026. Patch releases `0.3.1` and `0.3.2` stabilized live-dashboard launch and context loading. Minor releases `0.4.0` through `0.13.1` added Python 3.14 support, localization, SQL-backed dashboard loading, observed usage snapshots, diagnostics, usage-drain reports, maintainability refactors, onboarding hardening, and guided usage-summary diagnostics. Minor release `0.14.0` ships the React dashboard transition with legacy parity fixes, local-only safeguards, and weekly-first usage remaining displays.
 
 - GitHub Release: `https://github.com/douglasmonsky/codex-usage-tracker/releases/tag/v0.3.0`
 - GitHub Release: `https://github.com/douglasmonsky/codex-usage-tracker/releases/tag/v0.3.1`