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

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

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

{codex_usage_tracking-0.3.1 → codex_usage_tracking-0.4.0}/AGENTS.md

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

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

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 0.4.0 - 2026-06-09
+
+- Add official Python 3.14 support across CI, package classifiers, README/install docs, and installed-package Docker smoke coverage.
+- Add a release recovery runbook for failed publish workflows, stale PyPI/TestPyPI pages, Trusted Publishing issues, bad artifacts, and patch-forward recovery.
+- Add synthetic large-history benchmark thresholds for active/all-history dashboard queries, date filtering, model/effort filtering, recommendations, pricing coverage, and project summaries.
+- Add stricter privacy regression coverage for generated dashboards, CSV exports, API payloads, and support bundles.
+- Redact sensitive strings and local diagnostic paths in support bundles, including nested doctor output in redacted and strict privacy modes.
+- Add aggregate schema migration, JSON contract parity, installed-package smoke, and protected-main workflow readiness coverage.
+- Pin the marketplace MCP runtime launcher to the exact `codex-usage-tracking==0.4.0` package.
+
+## 0.3.2 - 2026-06-08
+
+- Make `open-dashboard` and `serve-dashboard` refresh active-session logs by default, with `--no-refresh` as the explicit cached-index mode.
+- Add a token-protected dashboard action for enabling context loading without restarting a localhost server that started with context loading off.
+
 ## 0.3.1 - 2026-06-08
 
 - Fix packaged Codex Usage Tracker skills so dashboard-open requests start the live localhost dashboard instead of a static snapshot.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.3.1
+Version: 0.4.0
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Monitoring
 Requires-Python: >=3.10
@@ -45,7 +46,7 @@ Local-first dashboard, Codex plugin, and companion skill for understanding where
 
 [![CI](https://github.com/douglasmonsky/codex-usage-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/douglasmonsky/codex-usage-tracker/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/codex-usage-tracking.svg)](https://pypi.org/project/codex-usage-tracking/)
-![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-blue)
+![Python 3.10-3.14](https://img.shields.io/badge/python-3.10--3.14-blue)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 > **Unofficial project:** Codex Usage Tracker is an independent open-source project. It is not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. OpenAI and Codex are trademarks of OpenAI; this project only reads local log files from your machine.
@@ -67,6 +68,9 @@ codex-usage-tracker serve-dashboard --open
 ```
 
 Use your normal Python launcher for your platform: `python3` is common on macOS/Linux, and `py` may be preferable on Windows. On macOS with Homebrew, `brew install pipx` is also fine.
+If `codex-usage-tracker` is not found after installing with pipx, open a new terminal or add the binary directory printed by `pipx ensurepath` to your `PATH`.
+
+`serve-dashboard` refreshes active-session usage before opening by default. Use `--no-refresh` only when you intentionally want to inspect the cached local index.
 
 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,7 +100,7 @@ More install paths: [Install Guide](docs/install.md).
 
 ## Platform Support
 
-The core app is not macOS-only. The CLI, SQLite index, dashboard generator, and localhost server are Python-based and CI-tested on Ubuntu for Python 3.10-3.13. It defaults to `~/.codex` for local Codex logs and `~/.codex-usage-tracker` for tracker data; pass `--codex-home` or `--db` when your local layout differs. Codex plugin discovery depends on Codex's local plugin directories on your machine, so run `codex-usage-tracker doctor` after setup if plugin registration does not appear in Codex.
+The core app is not macOS-only. The CLI, SQLite index, dashboard generator, and localhost server are Python-based and CI-tested on Ubuntu for Python 3.10-3.14. The installed-package Docker smoke path uses `python:3.14-slim` by default so packaged resources and CLI entry points are exercised on the newest supported runtime. It defaults to `~/.codex` for local Codex logs and `~/.codex-usage-tracker` for tracker data; pass `--codex-home` or `--db` when your local layout differs. Codex plugin discovery depends on Codex's local plugin directories on your machine, so run `codex-usage-tracker doctor` after setup if plugin registration does not appear in Codex.
 
 ## Dashboard Preview
 
@@ -193,7 +197,7 @@ codex-usage-tracker summary --preset last-7-days
 codex-usage-tracker query --since 2026-06-01 --min-credits 1
 codex-usage-tracker session <session-id>
 codex-usage-tracker export --output usage.csv
-codex-usage-tracker dashboard --open
+codex-usage-tracker open-dashboard
 codex-usage-tracker support-bundle --output ~/.codex-usage-tracker/support-bundle.json
 ```
 
@@ -205,7 +209,7 @@ The tracker stores aggregate metrics only: session ids, timestamps, local source
 
 It does **not** store prompts, assistant messages, tool output, pasted secrets, raw transcript snippets, or raw context in SQLite, CSV exports, generated dashboard HTML, or synthetic screenshots.
 
-On-demand context loading reads a single original local JSONL file only after an explicit row action, redacts common secret patterns, caps returned text size, and can be disabled with:
+On-demand context loading reads a single original local JSONL file only after an explicit row action, redacts common secret patterns, caps returned text size, and can start off until you enable it from the details panel:
 
 ```bash
 codex-usage-tracker serve-dashboard --no-context-api --open
@@ -257,6 +261,7 @@ This is optional. The normal shell install above is the fastest trusted path for
 
 ## Roadmap
 
+- Keep Python runtime support validated with CI matrix coverage, package classifiers, release docs, and installed-package smoke tests.
 - Improve the `Set limits` flow with a paste/import experience for 5-hour and weekly allowance snapshots.
 - Track allowance snapshot history so local Codex credits can be compared against visible remaining-usage changes over time.
 - Clarify top-card token accounting by showing output tokens and reasoning output as a subset instead of implying all token cards add together.

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

@@ -9,7 +9,7 @@ Local-first dashboard, Codex plugin, and companion skill for understanding where
 
 [![CI](https://github.com/douglasmonsky/codex-usage-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/douglasmonsky/codex-usage-tracker/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/codex-usage-tracking.svg)](https://pypi.org/project/codex-usage-tracking/)
-![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-blue)
+![Python 3.10-3.14](https://img.shields.io/badge/python-3.10--3.14-blue)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 > **Unofficial project:** Codex Usage Tracker is an independent open-source project. It is not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. OpenAI and Codex are trademarks of OpenAI; this project only reads local log files from your machine.
@@ -31,6 +31,9 @@ codex-usage-tracker serve-dashboard --open
 ```
 
 Use your normal Python launcher for your platform: `python3` is common on macOS/Linux, and `py` may be preferable on Windows. On macOS with Homebrew, `brew install pipx` is also fine.
+If `codex-usage-tracker` is not found after installing with pipx, open a new terminal or add the binary directory printed by `pipx ensurepath` to your `PATH`.
+
+`serve-dashboard` refreshes active-session usage before opening by default. Use `--no-refresh` only when you intentionally want to inspect the cached local index.
 
 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.
 
@@ -60,7 +63,7 @@ More install paths: [Install Guide](docs/install.md).
 
 ## Platform Support
 
-The core app is not macOS-only. The CLI, SQLite index, dashboard generator, and localhost server are Python-based and CI-tested on Ubuntu for Python 3.10-3.13. It defaults to `~/.codex` for local Codex logs and `~/.codex-usage-tracker` for tracker data; pass `--codex-home` or `--db` when your local layout differs. Codex plugin discovery depends on Codex's local plugin directories on your machine, so run `codex-usage-tracker doctor` after setup if plugin registration does not appear in Codex.
+The core app is not macOS-only. The CLI, SQLite index, dashboard generator, and localhost server are Python-based and CI-tested on Ubuntu for Python 3.10-3.14. The installed-package Docker smoke path uses `python:3.14-slim` by default so packaged resources and CLI entry points are exercised on the newest supported runtime. It defaults to `~/.codex` for local Codex logs and `~/.codex-usage-tracker` for tracker data; pass `--codex-home` or `--db` when your local layout differs. Codex plugin discovery depends on Codex's local plugin directories on your machine, so run `codex-usage-tracker doctor` after setup if plugin registration does not appear in Codex.
 
 ## Dashboard Preview
 
@@ -157,7 +160,7 @@ codex-usage-tracker summary --preset last-7-days
 codex-usage-tracker query --since 2026-06-01 --min-credits 1
 codex-usage-tracker session <session-id>
 codex-usage-tracker export --output usage.csv
-codex-usage-tracker dashboard --open
+codex-usage-tracker open-dashboard
 codex-usage-tracker support-bundle --output ~/.codex-usage-tracker/support-bundle.json
 ```
 
@@ -169,7 +172,7 @@ The tracker stores aggregate metrics only: session ids, timestamps, local source
 
 It does **not** store prompts, assistant messages, tool output, pasted secrets, raw transcript snippets, or raw context in SQLite, CSV exports, generated dashboard HTML, or synthetic screenshots.
 
-On-demand context loading reads a single original local JSONL file only after an explicit row action, redacts common secret patterns, caps returned text size, and can be disabled with:
+On-demand context loading reads a single original local JSONL file only after an explicit row action, redacts common secret patterns, caps returned text size, and can start off until you enable it from the details panel:
 
 ```bash
 codex-usage-tracker serve-dashboard --no-context-api --open
@@ -221,6 +224,7 @@ This is optional. The normal shell install above is the fastest trusted path for
 
 ## Roadmap
 
+- Keep Python runtime support validated with CI matrix coverage, package classifiers, release docs, and installed-package smoke tests.
 - Improve the `Set limits` flow with a paste/import experience for 5-hour and weekly allowance snapshots.
 - Track allowance snapshot history so local Codex credits can be compared against visible remaining-usage changes over time.
 - Clarify top-card token accounting by showing output tokens and reasoning output as a subset instead of implying all token cards add together.

{codex_usage_tracking-0.3.1 → codex_usage_tracking-0.4.0}/SECURITY.md

@@ -22,7 +22,7 @@ The MCP `usage_call_context` tool is disabled unless the MCP server process expl
 
 ## Localhost Dashboard Token
 
-`serve-dashboard` creates a random per-server API token and embeds it in the generated dashboard HTML for that local server session. The token is used for localhost `/api/usage` refreshes and `/api/context` requests. Treat generated active dashboard files and URLs as local-only artifacts; do not publish them or send them to someone else.
+`serve-dashboard` creates a random per-server API token and embeds it in the generated dashboard HTML for that local server session. The token is used for localhost `/api/usage` refreshes, `/api/context` requests, and runtime context-loading settings. Treat generated active dashboard files and URLs as local-only artifacts; do not publish them or send them to someone else.
 
 The dashboard server rejects non-loopback hosts and cross-origin requests. This is a local hardening measure, not a reason to expose the server on a network interface.
 

{codex_usage_tracking-0.3.1 → codex_usage_tracking-0.4.0}/docs/architecture.md

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

{codex_usage_tracking-0.3.1 → codex_usage_tracking-0.4.0}/docs/cli-json-schemas.md

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

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

@@ -33,11 +33,15 @@ codex-usage-tracker inspect-log ~/.codex/sessions/YYYY/MM/DD/rollout-...jsonl --
 codex-usage-tracker dashboard --open
 codex-usage-tracker dashboard --include-archived --open
 codex-usage-tracker open-dashboard
+codex-usage-tracker open-dashboard --no-refresh
 codex-usage-tracker serve-dashboard --open
+codex-usage-tracker serve-dashboard --no-refresh --open
 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` serves live aggregate refresh while disabling `/api/context` entirely.
+`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.
 
 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.3.1 → codex_usage_tracking-0.4.0}/docs/dashboard-guide.md

@@ -35,6 +35,8 @@ 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.
+
 The server keeps the HTML aggregate-only and enables two live features:
 
 - `Refresh` rescans local Codex logs and updates the dashboard rows.
@@ -43,12 +45,12 @@ The server keeps the HTML aggregate-only and enables two live features:
 For a static snapshot, use:
 
 ```bash
-codex-usage-tracker dashboard --open
+codex-usage-tracker open-dashboard
 ```
 
-Static file mode can still filter, sort, and inspect aggregate call fields. It cannot refresh from logs or load raw context until you open the dashboard through `serve-dashboard`.
+Static file mode can still filter, sort, and inspect aggregate call fields. `open-dashboard` refreshes before writing the snapshot unless you pass `--no-refresh`. Static files cannot refresh from logs or load raw context after opening; use `serve-dashboard` when you want those live controls.
 
-The localhost server uses a random per-server token for refresh and context API calls, validates loopback `Host` and `Origin` headers, and can run as aggregate-only with `codex-usage-tracker serve-dashboard --no-context-api`.
+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
 
@@ -141,12 +143,12 @@ When served from localhost, the details panel includes `Load context` and `Inclu
 - `Load context` fetches a size-limited, redacted context excerpt for only that call.
 - `Include tool output` repeats the request with tool output included, still redacted and capped.
 - Raw context is not written to SQLite, CSV, or the generated dashboard HTML.
-- If the server was started with `--no-context-api`, the context buttons stay disabled and the dashboard remains aggregate-only.
+- If the server was started with `--no-context-api`, context loading starts off. Use `Enable context loading` in the details panel when you want to allow explicit row actions without restarting the dashboard server.
 
 ## Practical Workflow
 
 1. Start with `serve-dashboard --open`.
-2. Use `Refresh` after a Codex run finishes, or leave `Live` enabled while you work.
+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.