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

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

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

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

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.13.1 - 2026-06-30
+
+- Add guided usage-summary diagnostics across CLI, API, and dashboard to explain the largest aggregate drivers behind usage.
+
+## 0.13.0 - 2026-06-30
+
+- Add first-run onboarding docs covering install, setup, live-dashboard launch, empty-dashboard troubleshooting, plugin discovery, and safe issue diagnostics.
+- Improve `doctor --json` first-run environment reporting so support requests can distinguish missing logs, empty history, and plugin/runtime path issues faster.
+- Add safe support-bundle issue-report fields and issue-template guidance so users can attach diagnostics without leaking prompts, tool outputs, commands, patches, or raw paths in strict mode.
+- Strengthen installed-wheel lifecycle smoke coverage across setup, doctor, dashboard generation, strict support bundles, and plugin resources.
+- Harden strict support-bundle redaction for nested diagnostic paths, Python executable paths, and resolved `/private/var`-style platform path aliases.
+
 ## 0.12.1 - 2026-06-29
 
 - Ship the package-domain boundary refactor behind compatibility facades so existing CLI, imports, dashboard routes, JSON payloads, and MCP entrypoints keep working while the source tree is organized by responsibility.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.12.1
+Version: 0.13.1
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -53,7 +53,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/)
-[![PyPI Downloads](https://static.pepy.tech/personalized-badge/codex-usage-tracking?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=BLUE&left_text=downloads)](https://pepy.tech/projects/codex-usage-tracking)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/codex-usage-tracking?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=RED&left_text=downloads)](https://pepy.tech/projects/codex-usage-tracking)
 ![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)
 
@@ -78,6 +78,8 @@ 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`.
 
+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.
 
 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.
@@ -319,6 +321,8 @@ This is optional. The normal shell install above is the fastest trusted path for
 
 ## Roadmap
 
+The next phase is adoption hardening: better first-run setup, safer support bundles, clearer guided diagnostics, and scale/reliability checks now that more people are trying the project. See [Adoption Hardening Roadmap](docs/adoption-hardening-roadmap.md) for the branch-by-branch plan.
+
 - 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.

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

@@ -9,7 +9,7 @@ Local-first dashboard, Codex plugin, and companion skill for understanding where
 
 [![CI](https://github.com/douglasmonsky/codex-usage-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/douglasmonsky/codex-usage-tracker/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/codex-usage-tracking.svg)](https://pypi.org/project/codex-usage-tracking/)
-[![PyPI Downloads](https://static.pepy.tech/personalized-badge/codex-usage-tracking?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=BLUE&left_text=downloads)](https://pepy.tech/projects/codex-usage-tracking)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/codex-usage-tracking?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=RED&left_text=downloads)](https://pepy.tech/projects/codex-usage-tracking)
 ![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)
 
@@ -34,6 +34,8 @@ 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`.
 
+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.
 
 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.
@@ -275,6 +277,8 @@ This is optional. The normal shell install above is the fastest trusted path for
 
 ## Roadmap
 
+The next phase is adoption hardening: better first-run setup, safer support bundles, clearer guided diagnostics, and scale/reliability checks now that more people are trying the project. See [Adoption Hardening Roadmap](docs/adoption-hardening-roadmap.md) for the branch-by-branch plan.
+
 - 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.

codex_usage_tracking-0.13.1/docs/adoption-hardening-roadmap.md

@@ -0,0 +1,130 @@
+# Adoption Hardening Roadmap
+
+This roadmap covers the next phase after the `0.12.x` architecture repair. The project is now getting enough outside attention that the priority shifts from fast feature expansion to making first-run setup, support, diagnostics, and large-history behavior boring for new users.
+
+## Current Signals
+
+- GitHub interest has moved beyond personal-use scale: stars, forks, clones, and traffic are all growing.
+- The project has already handled outside bug reports around Windows dashboard serving and large-history SQLite limits.
+- The release cadence has been fast, so the next minor releases should tighten trust and support surfaces before adding more complex diagnostics.
+- Current local gates are healthy: Ruff, MyPy, Tach, release checks, Agent Maintainer fast profile, and pytest pass.
+- Main technical debt is no longer giant files, but there are still dense domains: `usage_drain`, `server`, dashboard APIs, and large integration tests.
+
+## Operating Rules
+
+- Keep `main` always releasable.
+- Use one short-lived branch per reviewable capability.
+- Prefer PRs even for solo-maintainer work so each change has a review artifact.
+- Avoid stacking branches unless a later branch truly depends on an earlier one.
+- Do not release every small branch. Release after a coherent group of user-facing improvements lands.
+- Preserve privacy guarantees: no raw prompts, assistant messages, tool outputs, patch text, secrets, or private config values in stored snapshots, support bundles, screenshots, generated dashboards, or test fixtures.
+
+## 0.13: Adoption Hardening
+
+Goal: make first-time installs and bug reports easier for users who did not build the tool.
+
+Branches:
+
+- `feature/doctor-first-run-report`
+  - Make `doctor` clearly report Python version, package version, Codex log discovery, tracker DB path, dashboard asset health, plugin registration state, and common Windows/browser pitfalls.
+  - Add `--json` parity for any new fields shown in text output.
+  - Acceptance: focused doctor tests plus installed-package smoke coverage.
+
+- `feature/support-bundle-issue-flow`
+  - Improve strict support bundle output for issue reports.
+  - Add a short CLI hint showing which safe fields users can paste into GitHub issues.
+  - Acceptance: privacy tests prove strict bundles do not leak raw prompts, outputs, full paths, tokens, or private config values.
+
+- `test/installed-wheel-platform-smokes`
+  - Strengthen wheel-level smoke tests for setup, dashboard generation, `serve-dashboard --help`, `doctor`, support bundle, and bundled dashboard assets.
+  - Keep CI runtime reasonable by using synthetic logs and selected commands.
+  - Acceptance: wheel smoke catches entrypoint and package-data regressions before release.
+
+- `docs/first-five-minutes-onboarding`
+  - Add a concise first-run walkthrough: install, setup, launch, verify, troubleshoot.
+  - Include "what to do if the dashboard is empty" and "what to attach to an issue" sections.
+  - Acceptance: README stays scannable; deeper details live in docs.
+
+Release target:
+
+- Ship `0.13.0` once the user-facing flow feels reliable.
+
+## 0.14: Guided Diagnostics
+
+Goal: turn powerful diagnostics into plain answers before exposing more raw charts.
+
+Branches:
+
+- `feature/guided-usage-summary`
+  - Add a "What is driving my usage?" report across dashboard and CLI.
+  - Prioritize threads, models, effort, cache misses, subagents, command/tool activity, and usage-drain signals.
+
+- `feature/weekly-allowance-change-report`
+  - Add a guided report explaining projected weekly credits, confidence bands, observed usage coverage, and caveats.
+  - Avoid overclaiming; frame changes as local evidence, not universal allowance proof.
+
+- `feature/thread-efficiency-report`
+  - Add thread-level efficiency indicators: cost per visible call, cache behavior, cold resume signs, context pressure, and long-thread tradeoffs.
+
+- `feature/diagnostics-refresh-diff`
+  - Show what changed since the previous diagnostics refresh.
+  - Keep this snapshot-based and on demand.
+
+Release target:
+
+- Ship `0.14.0` when at least two guided reports are useful end to end.
+
+## 0.15: Reliability And Scale
+
+Goal: make large histories and long diagnostics predictable.
+
+Branches:
+
+- `perf/large-history-refresh-benchmarks`
+  - Add synthetic benchmark thresholds for setup, refresh, diagnostics refresh, and dashboard API payloads.
+
+- `feature/diagnostics-refresh-progress`
+  - Add progress/status for expensive diagnostics refreshes so users know whether work is running, stale, failed, or complete.
+
+- `fix/resumable-diagnostic-snapshots`
+  - Make failed diagnostic snapshot refreshes isolated and resumable by section.
+
+- `test/parser-compat-fixtures`
+  - Add focused parser fixtures for new Codex log shapes as users report them.
+
+Release target:
+
+- Ship `0.15.0` when refresh behavior is explainable for both normal and large histories.
+
+## 0.16: Maintainability Ratchet
+
+Goal: keep the project easy to change while adoption grows.
+
+Branches:
+
+- `refactor/usage-drain-subpackages`
+  - Split usage-drain internals by spans, features, models, reports, charts, and allowance helpers.
+
+- `refactor/server-api-boundaries`
+  - Split server routing, static assets, diagnostics APIs, usage APIs, and response helpers.
+
+- `refactor/xenon-b-ranked-modules`
+  - Reduce the current B-ranked Xenon modules until `xenon --max-absolute B --max-modules A --max-average A src` can pass.
+
+- `chore/expand-mypy-coverage`
+  - Expand MyPy coverage in small safe slices.
+
+Release target:
+
+- These can land behind compatibility facades and may ship as `0.16.0` or be spread across smaller minors if that materially reduces release risk.
+
+## 1.0 Readiness Bar
+
+Do not call the project `1.0` until:
+
+- First-run setup is boring on macOS, Windows, and Linux.
+- The support-bundle issue flow is privacy-safe and easy to use.
+- Dashboard and CLI JSON contracts are documented and stable.
+- Diagnostics are useful but clearly caveated where inference is uncertain.
+- Large-history refresh behavior is predictable.
+- Several outside issue reports have been handled without emergency patch churn.

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

@@ -37,6 +37,7 @@ Tracked schema ids:
 | --- | --- |
 | `codex-usage-tracker-setup-v1` | CLI `setup --json` |
 | `codex-usage-tracker-doctor-v1` | CLI `doctor --json`, MCP `usage_doctor(response_format="json")` |
+| | Includes an `environment` object with package and Python versions, important local paths, lightweight Codex log discovery counts, and packaged dashboard asset health. Support bundles sanitize this payload according to the selected privacy mode. |
 | `codex-usage-tracker-plugin-install-v1` | CLI `install-plugin --json`, setup plugin payload |
 | `codex-usage-tracker-plugin-upgrade-v1` | CLI `upgrade-plugin --json` |
 | `codex-usage-tracker-plugin-uninstall-v1` | CLI `uninstall-plugin --json` |
@@ -55,6 +56,7 @@ Tracked schema ids:
 | `codex-usage-tracker-diagnostic-file-modifications-v1` | CLI `diagnostics file-modifications --json`, dashboard server `/api/diagnostics/file-modifications` |
 | `codex-usage-tracker-diagnostic-read-productivity-v1` | CLI `diagnostics read-productivity --json`, dashboard server `/api/diagnostics/read-productivity` |
 | `codex-usage-tracker-diagnostic-concentration-v1` | CLI `diagnostics concentration --json`, dashboard server `/api/diagnostics/concentration` |
+| `codex-usage-tracker-diagnostic-guided-summary-v1` | CLI `diagnostics guided-summary --json`, dashboard server `/api/diagnostics/guided-summary` |
 | `codex-usage-tracker-diagnostic-usage-drain-v1` | CLI `diagnostics usage-drain --json`, dashboard server `/api/diagnostics/usage-drain` |
 | `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_tracking-0.12.1 → codex_usage_tracking-0.13.1}/docs/cli-reference.md

@@ -128,6 +128,7 @@ codex-usage-tracker diagnostics file-reads --refresh
 codex-usage-tracker diagnostics file-modifications --refresh
 codex-usage-tracker diagnostics read-productivity --refresh
 codex-usage-tracker diagnostics concentration --refresh
+codex-usage-tracker diagnostics guided-summary --refresh
 codex-usage-tracker diagnostics fact-calls --fact-type compaction --fact-name post_compaction
 ```
 
@@ -135,7 +136,7 @@ Diagnostics expose structured event patterns and their associated token totals.
 
 Snapshot diagnostics are persisted aggregate reports. Without `--refresh`, snapshot commands return the latest stored payload or a `missing` status. With `--refresh`, they recompute from indexed source logs and replace the stored section snapshot. Ordinary `refresh`, `open-dashboard`, and dashboard `Refresh` update usage rows only; they do not recompute diagnostic snapshots.
 
-The snapshot sections answer different questions: `overview` summarizes usage rows and aggregate token totals, `tool-output` counts functions and terminal `Original token count` coverage, `commands` keeps command roots plus bounded safe child labels, `git-interactions` counts safe Git/GitHub CLI operations and token-count coverage, `file-reads` counts reader/path activity and allocated read-output tokens, `file-modifications` counts patch modification events and safe modified-path aggregates, `read-productivity` reports later-edit correlations for matching path keys, and `concentration` shows top-N token share by source/session, cwd/project, and day.
+The snapshot sections answer different questions: `overview` summarizes usage rows and aggregate token totals, `tool-output` counts functions and terminal `Original token count` coverage, `commands` keeps command roots plus bounded safe child labels, `git-interactions` counts safe Git/GitHub CLI operations and token-count coverage, `file-reads` counts reader/path activity and allocated read-output tokens, `file-modifications` counts patch modification events and safe modified-path aggregates, `read-productivity` reports later-edit correlations for matching path keys, `concentration` shows top-N token share by source/session, cwd/project, and day, and `guided-summary` turns aggregate usage patterns into a short "what is driving usage" report.
 
 Diagnostic payloads are aggregate-only. They do not include prompts, assistant text, tool arguments, tool output, patch text, raw commands, command arguments, file contents, raw absolute paths, or JSONL fragments. Git interaction diagnostics persist only root and operation labels such as `git/status` or `gh/pr`, category counts, and token coverage; they do not persist branch names, remotes, file paths, tags, commit messages, PR titles, or release notes. File-read and file-modification diagnostics use basename-only path labels plus short irreversible hashes, read-productivity percentages are temporal correlations rather than proof that a read caused a later edit, and concentration reports use safe source/session, cwd, and day labels only.
 
@@ -187,6 +188,8 @@ codex-usage-tracker --privacy-mode strict support-bundle --output ~/.codex-usage
 
 Support bundles are diagnostic summaries for issues. They include package, platform, doctor, schema, parser, pricing, allowance, threshold, project-config, and privacy metadata. They exclude raw logs, aggregate rows, prompts, assistant messages, tool output, and context text.
 
+Strict support bundles include an `issue_report` section that lists the paste-safe sections and fields for GitHub issues. Review the JSON before posting, and do not add raw JSONL logs, prompts, assistant messages, tool output, command text, patch text, full local paths, secrets, credentials, or private config values.
+
 ## Local Config
 
 ```bash

{codex_usage_tracking-0.12.1 → codex_usage_tracking-0.13.1}/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.12.1
+release/0.13.1
 hotfix/0.3.3
 ```
 
@@ -91,7 +91,10 @@ blocked
 Recommended milestones:
 
 ```text
-0.12.1
+0.13-adoption-hardening
+0.14-guided-diagnostics
+0.15-reliability-scale
+0.16-maintainability-ratchet
 1.0-readiness
 1.0.0
 ```
@@ -146,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.12.1
-python scripts/smoke_installed_package.py --docker --from-pypi --version 0.12.1
+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
 ```
 
 `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.
@@ -294,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.12.1 -m "codex-usage-tracker 0.12.1"
-git push origin v0.12.1
+git tag -a v0.13.1 -m "codex-usage-tracker 0.13.1"
+git push origin v0.13.0
 ```
 
 Do not create or push release tags without maintainer approval.
@@ -304,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.
+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.
 
 - 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`

codex_usage_tracking-0.13.1/docs/first-five-minutes.md

@@ -0,0 +1,93 @@
+# First Five Minutes
+
+This is the shortest path from a fresh machine to a working local dashboard.
+
+## 1. Install
+
+Use `pipx` so the tracker runs as its own command-line app:
+
+```bash
+python -m pip install --user pipx
+python -m pipx ensurepath
+pipx install codex-usage-tracking
+```
+
+Use `python3` on macOS/Linux if that is your normal launcher. On Windows, `py -m pip install --user pipx` and `py -m pipx ensurepath` may be the right form. If `codex-usage-tracker` is not found after install, open a new terminal or add the path printed by `pipx ensurepath`.
+
+## 2. Set Up
+
+```bash
+codex-usage-tracker setup
+```
+
+`setup` installs the local Codex plugin wrapper, initializes local config templates, refreshes the aggregate SQLite index from local Codex logs, and runs `doctor`. Restart Codex after setup if you want the companion MCP tools and skills to appear in new Codex sessions.
+
+## 3. Launch
+
+```bash
+codex-usage-tracker serve-dashboard --open
+```
+
+This starts a localhost dashboard and refreshes active-session usage first. Keep the terminal running while using the live dashboard.
+
+## 4. Verify
+
+The first healthy state usually looks like this:
+
+- Browser opens a `127.0.0.1` dashboard URL.
+- The top badge says `Live`, not only `Static`.
+- `Visible Calls` is greater than zero if local Codex logs exist.
+- `doctor` does not report a `fail` status:
+
+```bash
+codex-usage-tracker doctor --suggest-repair
+```
+
+## If The Dashboard Is Empty
+
+Run these checks in order:
+
+```bash
+codex-usage-tracker doctor --suggest-repair
+codex-usage-tracker refresh
+codex-usage-tracker serve-dashboard --open --refresh
+```
+
+Common causes:
+
+- No local Codex logs exist yet on that machine.
+- Codex logs are somewhere other than `~/.codex`; use `--codex-home <path>` with `setup`, `refresh`, or `serve-dashboard`.
+- You are looking only at active sessions while the data is archived; use the dashboard `History` selector or run with `--include-archived`.
+- Browser cached an old static file; reload the `serve-dashboard` URL.
+- On Windows, use a recent version if JavaScript files fail to load. Older releases could inherit a `.js` MIME type from the Windows registry.
+
+## If The Plugin Does Not Show In Codex
+
+The dashboard can work even when plugin discovery is not active. For plugin discovery:
+
+```bash
+codex-usage-tracker doctor --suggest-repair
+codex-usage-tracker install-plugin
+```
+
+Then restart Codex and start a fresh Codex session.
+
+## What To Attach To Issues
+
+For public GitHub issues, prefer a strict support bundle:
+
+```bash
+codex-usage-tracker --privacy-mode strict support-bundle --output ~/.codex-usage-tracker/support-bundle.json
+```
+
+Review the JSON before posting it. The bundle's `issue_report.safe_fields` lists the safest fields to paste. Do not add raw Codex JSONL logs, prompts, assistant messages, tool output, command text, patch text, full local paths, secrets, credentials, or private config values.
+
+## Next Useful Commands
+
+```bash
+codex-usage-tracker summary --preset last-7-days
+codex-usage-tracker query --min-tokens 100000
+codex-usage-tracker diagnostics overview --refresh
+```
+
+For deeper details, see the [Install Guide](install.md), [Dashboard Guide](dashboard-guide.md), and [CLI Reference](cli-reference.md).

{codex_usage_tracking-0.12.1 → codex_usage_tracking-0.13.1}/docs/install.md

@@ -1,5 +1,7 @@
 # Install Guide
 
+New user? Start with the [First Five Minutes](first-five-minutes.md) guide, then return here for deeper install details.
+
 ## Recommended Install
 
 Use `pipx` so the tracker is installed from PyPI as a command-line app without mixing dependencies into another project.
@@ -150,6 +152,6 @@ codex-usage-tracker reset-db --yes
 codex-usage-tracker --privacy-mode strict support-bundle --output ~/.codex-usage-tracker/support-bundle.json
 ```
 
-`support-bundle` writes package, Python, OS/platform, doctor status, database schema, parser diagnostics, pricing status, allowance status, threshold status, project config status, and privacy metadata. It does not include raw logs, prompts, assistant messages, tool output, context text, or aggregate rows.
+`support-bundle` writes package, Python, OS/platform, doctor status, database schema, parser diagnostics, pricing status, allowance status, threshold status, project config status, privacy metadata, and an `issue_report` list of paste-safe issue fields. It does not include raw logs, prompts, assistant messages, tool output, context text, or aggregate rows.
 
 Default `support-bundle` mode keeps local diagnostic paths because they can help troubleshoot setup on your machine. Use `--privacy-mode strict` before sharing: strict mode redacts local diagnostic path strings in the bundle and doctor details while preserving existence flags, counts, parser diagnostics, and status fields.

{codex_usage_tracking-0.12.1 → codex_usage_tracking-0.13.1}/docs/one-dot-oh-readiness.md

@@ -24,12 +24,12 @@ Not guaranteed:
 
 ## 1. Public Install And Package Metadata
 
-- [x] Verify the current public PyPI version is visible as `0.12.1`: `python -c "import json, urllib.request; print(json.load(urllib.request.urlopen('https://pypi.org/pypi/codex-usage-tracking/json'))['info']['version'])"`.
-- [x] Verify public venv install for `0.12.1`: `python -m venv /tmp/codex-usage-pypi-smoke && . /tmp/codex-usage-pypi-smoke/bin/activate && python -m pip install codex-usage-tracking==0.12.1 && codex-usage-tracker --version`.
-- [x] Verify public pipx install path for `0.12.1`: `PIPX_HOME=/tmp/codex-usage-pipx-home PIPX_BIN_DIR=/tmp/codex-usage-pipx-bin pipx install codex-usage-tracking==0.12.1 && /tmp/codex-usage-pipx-bin/codex-usage-tracker --version`.
+- [x] Verify the current public PyPI version is visible as `0.13.1`: `python -c "import json, urllib.request; print(json.load(urllib.request.urlopen('https://pypi.org/pypi/codex-usage-tracking/json'))['info']['version'])"`.
+- [x] Verify public venv install for `0.13.1`: `python -m venv /tmp/codex-usage-pypi-smoke && . /tmp/codex-usage-pypi-smoke/bin/activate && python -m pip install codex-usage-tracking==0.13.1 && codex-usage-tracker --version`.
+- [x] Verify public pipx install path for `0.13.1`: `PIPX_HOME=/tmp/codex-usage-pipx-home PIPX_BIN_DIR=/tmp/codex-usage-pipx-bin pipx install codex-usage-tracking==0.13.1 && /tmp/codex-usage-pipx-bin/codex-usage-tracker --version`.
 - [x] Verify installed package resources from a built wheel: `python scripts/smoke_installed_package.py`.
 - [x] Verify installed package resources in Linux Docker: `python scripts/smoke_installed_package.py --docker`.
-- [x] Verify public PyPI package in Docker: `python scripts/smoke_installed_package.py --docker --from-pypi --version 0.12.1`.
+- [x] Verify public PyPI package in Docker: `python scripts/smoke_installed_package.py --docker --from-pypi --version 0.13.1`.
 - [x] Verify PyPI metadata names remain unchanged: `python scripts/check_release.py`.
 - [x] Add Python 3.14 as an official support target after CI, package classifiers, docs, and installed-package smoke coverage were added. Docker smoke coverage uses `python:3.14-slim` by default. Track this in issue #12.
 
@@ -134,14 +134,14 @@ Not guaranteed:
 
 ## Evidence References
 
-These references are the concrete proof behind completed checklist items. Public package smoke commands are version-specific to `0.12.1`; all repo tests use synthetic or aggregate-only data.
+These references are the concrete proof behind completed checklist items. Public package smoke commands are version-specific to `0.13.1`; all repo tests use synthetic or aggregate-only data.
 
 ### Public Install And Package Metadata
 
 - Public PyPI version, public venv install, and public pipx install are proven by the exact public-install commands in section 1.
 - Built-wheel and installed-resource coverage is proven by `scripts/smoke_installed_package.py` and `tests/test_cli_release.py::test_installed_package_smoke_checks_help_for_stable_commands`.
 - Linux package-resource coverage is proven by `scripts/smoke_installed_package.py --docker`.
-- Public PyPI Docker coverage is proven by `scripts/smoke_installed_package.py --docker --from-pypi --version 0.12.1`.
+- Public PyPI Docker coverage is proven by `scripts/smoke_installed_package.py --docker --from-pypi --version 0.13.1`.
 - PyPI metadata, package/distribution names, package resources, source/wheel member names, Python 3.10-3.14 support metadata, CI workflow requirements, publish workflow safety text, and tracked secret patterns are proven by `scripts/check_release.py`, `scripts/check_release.py --dist`, and `tests/test_cli_release.py::test_release_check_script_passes`.
 
 ### Upgrade And Migration
@@ -219,8 +219,8 @@ These references are the concrete proof behind completed checklist items. Public
 - Publish workflow package name, Trusted Publishing, TestPyPI/PyPI job presence, event guards, no push/PR publishing, no token/password publishing, and manual PyPI main/tag preflight are proven by `scripts/check_release.py::_check_publish_workflow`.
 - The GitHub `pypi` environment gate is proven by `gh api repos/douglasmonsky/codex-usage-tracker/environments/pypi`, which reports a `required_reviewers` protection rule and `can_admins_bypass=false`.
 - Dist filename and wheel/sdist member checks are proven by `python -m build`, `python -m twine check dist/*`, and `python scripts/check_release.py --dist`.
-- TestPyPI publish process is proven by a workflow-dispatch run on `main`, followed by TestPyPI metadata and clean virtualenv install checks for `codex-usage-tracking==0.12.1`.
-- PyPI publish process is proven by a workflow-dispatch run on `main`, protected `pypi` environment approval, PyPI metadata visibility, clean virtualenv install, temporary pipx install, and Docker public-package smoke for `codex-usage-tracking==0.12.1`.
+- TestPyPI publish process is proven by a workflow-dispatch run on `main`, followed by TestPyPI metadata and clean virtualenv install checks for `codex-usage-tracking==0.13.1`.
+- PyPI publish process is proven by a workflow-dispatch run on `main`, protected `pypi` environment approval, PyPI metadata visibility, clean virtualenv install, temporary pipx install, and Docker public-package smoke for `codex-usage-tracking==0.13.1`.
 - Release recovery documentation is proven by `scripts/check_release.py` required-file and docs checks.
 
 ### Known Limitations

{codex_usage_tracking-0.12.1 → codex_usage_tracking-0.13.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-usage-tracking"
-version = "0.12.1"
+version = "0.13.1"
 description = "Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns."
 readme = "README.md"
 requires-python = ">=3.10"