pi-vault · lanhhoang · Jul 6, 2026 · Jul 6, 2026 · Jul 6, 2026 · Jul 6, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,51 +2,117 @@
 
 All notable changes to `@pi-vault/pi-usage` are documented here.
 
-## v0.5.1
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-- updated `@earendil-works/pi-coding-agent` to `^0.80.2`, `@earendil-works/pi-tui` to `^0.80.2`, `@types/node` to `^26.0.0`, and `vitest` to `^4.1.9`
+## [0.6.0] - 2026-07-05
 
-## v0.5.0
+### Added
 
-- added `usage.json` provider toggles so you can disable live providers you do not want queried
-- added dashboard insights for project, active skill, and MCP server breakdowns
-- grouped insight rows by category and cap each insight section with an overflow summary to keep the dashboard readable
-- improved offline session parsing to extract project names, active skills, MCP server names, and builtin tool usage more accurately
-- fixed dashboard readability around usage statistics spacing and grouped insight rendering
-- updated runtime requirements and tooling to Node `>=24.15.0`, refreshed dependencies, and aligned CI with Node 24 and pnpm 11.8.0
+- Tabbed overlay layout for the dashboard with three tabs: Usage Statistics, Current Usage, and Insights. The tab bar follows the same pattern as `@earendil-works/pi-extension-manager` for visual consistency.
+- Independent period selector for the Insights tab so the Insights period no longer follows the Usage Statistics period.
+- Per-tab contextual footer strings in `src/shared/constants.ts` so each tab shows only the keys that are relevant in that tab.
+- `DashboardTheme.inverse()` and `DashboardTheme.bg()` methods to support the new overlay rendering primitives.
+- New `src/tui/overlay-render.ts` module that owns `frame()`, `renderTabBar()`, and `pad()` utilities for drawing the overlay chrome.
 
-## v0.4.0
+### Changed
 
-- reorganized the extension around a dedicated `UsageCore`, with the package entrypoint reduced to a thin Pi adapter
-- split shared provider runtime behavior into reusable utilities for timeouts, JSON parsing, and percentage handling
-- broke the OpenCode Go provider into focused modules for dashboard scraping, SQLite reads, and quota window calculation
-- extracted dashboard formatting and table layout logic into smaller TUI modules
-- expanded automated coverage for orchestration, state projection, runtime utilities, dashboard formatting, and provider integrations
-- kept the public usage flow stable: `/usage`, `/usage:refresh`, exported events, and exported types remain intact
+- Refactored `src/tui/dashboard.ts` to render the new tabbed overlay layout. The `render()`, `handleInput()`, and `activeTab` state replace the previous stacked-section renderer.
+- Dashboard description in `package.json` updated to "Pi extension that tracks Pi usage across your sessions in one dashboard".
+- Updated `@biomejs/biome` to `^2.5.2`, `@earendil-works/pi-coding-agent` to `^0.80.3`, `@earendil-works/pi-tui` to `^0.80.3`, `@types/node` to `^26.1.0`, and `typebox` to `^1.3.3`.
+- Moved `typebox` from `peerDependencies` to `devDependencies` since it is only used for compile-time schema construction in this package.
 
-## v0.3.0
+### Removed
 
-- added StepFun live usage support
-- refreshed the README and provider setup guidance
-- refactored the source tree into the current `core`, `providers`, `shared`, and `tui` layout
-- updated dependencies, toolchain config, and Node requirements for the current runtime model
+- `v` keyboard shortcut for toggling the Insights panel — Insights is now its own tab, reached via `Tab` / `Shift-Tab`.
+- Legacy dashboard footer and border character constants from `src/shared/constants.ts` (replaced by per-tab footer strings and `overlay-render`).
+- Unused helper code that was only consumed by the legacy single-scroll renderer.
 
-## v0.2.0
+### Compatibility
 
-- added the `/usage:refresh` command for explicit live refreshes
-- added OpenRouter live usage and balance support
-- reworked the dashboard UI with Pi-themed styling, improved quota formatting, and current-provider tabs
-- improved MiniMax usage parsing and compatibility window handling
+- Node.js requirement unchanged: `>=24.15.0`.
+- Peer dependencies unchanged: `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`.
+- Public API unchanged: `/usage`, `/usage:refresh`, exported events, exported types all retain their previous surface.
+- `biome.json` schema URL updated to `https://biomejs.dev/schemas/2.5.2/schema.json` to match the new biome version.
 
-## v0.1.1
+## [0.5.1] - 2026-06-25
 
-- added the request/reply event API for consumers that need the latest usage snapshot
-- exported the event and type modules through `package.json`
-- added regression coverage for the event API surface
+### Changed
 
-## v0.1.0
+- Updated `@earendil-works/pi-coding-agent` to `^0.80.2`, `@earendil-works/pi-tui` to `^0.80.2`, `@types/node` to `^26.0.0`, and `vitest` to `^4.1.9`.
 
-- introduced the initial Pi usage dashboard with offline aggregation across local sessions
-- added live provider support for OpenAI/Codex, MiniMax, OpenCode Go, and Command Code
-- added the interactive TUI dashboard, provider registry, packaging metadata, release workflow, and test/lint/typecheck automation
-- published the first public package documentation and project license
+## [0.5.0] - 2026-06-22
+
+### Added
+
+- `usage.json` provider toggles so you can disable live providers you do not want queried.
+- Dashboard insights for project, active skill, and MCP server breakdowns.
+- Grouped insight rows by category, with an overflow summary per section to keep the dashboard readable.
+- Improved offline session parsing to extract project names, active skills, MCP server names, and builtin tool usage more accurately.
+
+### Fixed
+
+- Dashboard readability around usage statistics spacing and grouped insight rendering.
+
+### Compatibility
+
+- Runtime requirement updated to Node `>=24.15.0`.
+- CI aligned with Node 24 and pnpm 11.8.0.
+
+## [0.4.0] - 2026-06-14
+
+### Added
+
+- Expanded automated coverage for orchestration, state projection, runtime utilities, dashboard formatting, and provider integrations.
+
+### Changed
+
+- Reorganized the extension around a dedicated `UsageCore`, with the package entrypoint reduced to a thin Pi adapter.
+- Split shared provider runtime behavior into reusable utilities for timeouts, JSON parsing, and percentage handling.
+- Broke the OpenCode Go provider into focused modules for dashboard scraping, SQLite reads, and quota window calculation.
+- Extracted dashboard formatting and table layout logic into smaller TUI modules.
+
+### Compatibility
+
+- Public usage flow kept stable: `/usage`, `/usage:refresh`, exported events, and exported types remain intact.
+
+## [0.3.0] - 2026-06-08
+
+### Added
+
+- StepFun live usage support.
+
+### Changed
+
+- Refreshed the README and provider setup guidance.
+- Refactored the source tree into the current `core`, `providers`, `shared`, and `tui` layout.
+- Updated dependencies, toolchain config, and Node requirements for the current runtime model.
+
+## [0.2.0] - 2026-06-01
+
+### Added
+
+- The `/usage:refresh` command for explicit live refreshes.
+- OpenRouter live usage and balance support.
+
+### Changed
+
+- Reworked the dashboard UI with Pi-themed styling, improved quota formatting, and current-provider tabs.
+- Improved MiniMax usage parsing and compatibility window handling.
+
+## [0.1.1] - 2026-05-31
+
+### Added
+
+- The request/reply event API for consumers that need the latest usage snapshot.
+- Exported the event and type modules through `package.json`.
+- Regression coverage for the event API surface.
+
+## [0.1.0] - 2026-05-31
+
+### Added
+
+- Initial Pi usage dashboard with offline aggregation across local sessions.
+- Live provider support for OpenAI/Codex, MiniMax, OpenCode Go, and Command Code.
+- Interactive TUI dashboard, provider registry, packaging metadata, release workflow, and test/lint/typecheck automation.
+- First public package documentation and project license.
diff --git a/README.md b/README.md
@@ -7,8 +7,6 @@
 
 Track Pi usage across your sessions in one dashboard. `@pi-vault/pi-usage` combines offline history with live provider snapshots so you can review costs, tokens, session activity, current quotas, and usage insights without leaving Pi.
 
-![Pi usage dashboard showing the aggregated usage table for the "All Time" period, current usage quota bars for OpenAI/Codex, and the keyboard navigation hints at the bottom](docs/assets/dashboard-ui.png)
-
 ## Install
 
 ```bash
@@ -21,49 +19,89 @@ Then reload Pi:
 /reload
 ```
 
+## Quick Start
+
+Open the dashboard with cached data:
+
+```text
+/usage
+```
+
+Force a live refresh, rescan local history, and reopen:
+
+```text
+/usage:refresh
+```
+
 ## Commands
 
-- `/usage` opens the dashboard using cached live data when available. Use it for quick inspection.
-- `/usage:refresh` forces a live refresh, rescans local history, and then opens the dashboard.
+| Command           | Purpose                                                                                  |
+| ----------------- | ---------------------------------------------------------------------------------------- |
+| `/usage`          | Open the dashboard. Uses cached live data when available. Quick inspection.              |
+| `/usage:refresh`  | Force a live refresh, rescan local session history, then open the dashboard.             |
+
+## Dashboard Tabs
+
+The dashboard renders as a tabbed overlay. Switch tabs with `Tab` / `Shift-Tab`.
+
+### Usage Statistics (default)
 
-## What the dashboard shows
+![Usage Statistics tab](docs/assets/usage-statistics.png)
 
-### Usage statistics
+Aggregates local Pi session history for the selected period.
 
-The top section aggregates local Pi session history for the selected period.
+- Period selector: `Today`, `This Week`, `Last Week`, `All Time`.
+- Aggregated provider/model table with expandable rows.
+- Total row for everything currently shown.
+- Per-row counts for sessions, messages, cost, total tokens, input, output, cache reads, and cache writes.
 
-- switch between `Today`, `This Week`, `Last Week`, and `All Time`
-- expand provider rows to inspect model-level usage
-- compare sessions, messages, cost, total tokens, input, output, cache reads, and cache writes
-- keep a running total row for everything currently shown
+### Current Usage
 
-### Current usage
+![Current Usage tab](docs/assets/current-usage.png)
 
-The lower section shows the supported providers. Configured providers can return live quota and balance data, while unconfigured ones may show `unavailable` or local fallback states.
+Shows supported live providers. Configured providers return live quota and balance data; unconfigured ones may show `unavailable` or a local fallback.
 
-- switch between `OpenAI/Codex`, `MiniMax`, `StepFun`, `OpenCode Go`, `Command Code`, and `OpenRouter`
-- view rolling-window quota bars like `5h` and weekly usage
-- see balance-style fields where the provider exposes them
-- get inline status for live, cached, stale, local, or unavailable data
+- Provider selector: `OpenAI/Codex`, `MiniMax`, `StepFun`, `OpenCode Go`, `Command Code`, `OpenRouter`.
+- Rolling-window quota bars (e.g. `5h`, weekly).
+- Balance-style fields where the provider exposes them.
+- Inline status: `live`, `cached`, `stale`, `local`, `unavailable`.
 
 ### Insights
 
-Press `v` to toggle insights for the selected period.
+![Insights tab](docs/assets/insights.png)
 
-- review the most expensive projects in your local session history
-- see active skill and MCP server breakdowns when that data is present
-- keep long sections readable through grouped insight categories and capped lists with overflow summaries
+Breakdowns for the selected period. Toggle visibility by switching to this tab.
 
-## How to use it
+- Most expensive projects in your local session history.
+- Active skill breakdown when that data is present.
+- MCP server breakdown when that data is present.
+- Grouped insight categories with capped lists and overflow summaries so long sections stay readable.
 
-### Keyboard shortcuts
+The Insights period selector is independent of the Usage Statistics period.
 
-- `[Tab/Shift-Tab]` switch provider tabs
-- `[Left/Right]` switch time period
-- `[Up/Down]` move through rows
-- `[Enter/Space]` expand or collapse provider rows
-- `[v]` toggle insights
-- `[q/Esc]` close the dashboard
+## Keyboard Shortcuts
+
+Global:
+
+- `[Tab]` next tab.
+- `[Shift-Tab]` previous tab.
+- `[q]` / `[Esc]` close the dashboard.
+
+Usage Statistics tab:
+
+- `[Left/Right]` switch period.
+- `[Up/Down]` move through rows.
+- `[Enter]` / `[Space]` expand or collapse the selected provider row.
+
+Current Usage tab:
+
+- `[Left/Right]` switch provider.
+
+Insights tab:
+
+- `[Left/Right]` switch period.
+
+The footer at the bottom of the dashboard shows the contextual shortcuts for the active tab.
 
 ## Configuration
 
@@ -72,10 +110,11 @@ Press `v` to toggle insights for the selected period.
 Create `$PI_CODING_AGENT_DIR/extensions/usage.json` to disable specific live providers.
 
 Default behavior:
-- if the file is missing, all providers stay enabled
-- if the file is `{}`, all providers stay enabled
-- if a provider is omitted, that provider stays enabled
-- if the JSON is malformed, `@pi-vault/pi-usage` ignores it and falls back to the default behavior
+
+- File missing: all providers stay enabled.
+- File is `{}`: all providers stay enabled.
+- Provider omitted: that provider stays enabled.
+- JSON malformed: `@pi-vault/pi-usage` ignores it and falls back to the default behavior.
 
 Default example:
 
@@ -110,7 +149,7 @@ Disable MiniMax only:
 
 ### Provider setup
 
-Offline history works without extra setup. Provider cards appear for every supported live provider unless you disable them in `usage.json`. Providers you configure can return live data; others may show `unavailable` or local fallback states.
+Offline history works without extra setup. Provider cards appear for every supported live provider unless you disable them in `usage.json`. Providers you configure can return live data; others may show `unavailable` or a local fallback state.
 
 #### OpenAI/Codex
 

diff --git a/biome.json b/biome.json
@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.0/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.2/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",

diff --git a/docs/assets/current-usage.png b/docs/assets/current-usage.png
diff --git a/docs/assets/dashboard-ui.png b/docs/assets/dashboard-ui.png
diff --git a/docs/assets/insights.png b/docs/assets/insights.png
diff --git a/docs/assets/usage-statistics.png b/docs/assets/usage-statistics.png