npm - @hk_net/pi-usage-bars - Versions diffs - 0.4.5 → 0.6.0 - Mend

@hk_net/pi-usage-bars 0.4.5 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/CHANGELOG.md +29 -0
package/LICENSE +21 -21
package/README.md +145 -129
package/docs/provider-research.md +4 -4
package/docs/releasing.md +104 -84
package/extensions/usage-bars/core.ts +1341 -1274
package/extensions/usage-bars/index.ts +781 -672
package/package.json +75 -74

package/CHANGELOG.md CHANGED Viewed

@@ -2,6 +2,35 @@
 ## Unreleased
+## [0.6.0] - 2026-08-29
+### Added
+- Added Baseten current calendar-month credits-used reporting through its documented key-authenticated billing usage API. Baseten has no documented remaining-credit or quota percentage in this API, so the extension renders only the reported usage.
+### Changed
+- Updated the development and test baseline to Pi SDK 0.84.4.
+## [0.5.0] - 2026-08-22
+### Added
+- Added a `--usage` extension flag that prints one JSON line for the active provider and exits, providing a non-interactive Pi loader, credential, and endpoint smoke test.
+### Changed
+- Raised the minimum supported Pi version from 0.81.1 to 0.84.2; older Pi releases are no longer claimed or tested as compatible.
+- Namespaced the footer status and inter-extension usage update event to avoid collisions with other Pi extensions. **Breaking for event consumers:** listeners using the previous undocumented `usage:update` event must switch to `@hk_net/pi-usage-bars:update`.
+- Bounded the `/usage` provider viewport, expanded only the selected provider, and added the configured page-up/page-down navigation bindings for smaller terminals.
+- Removed redundant active-model checks on every turn in favor of Pi's `session_start` and `model_select` lifecycle events.
+- Cancelled an obsolete in-flight provider request immediately when the selected model provider changes, allowing the new provider to refresh without waiting for the old request timeout.
+- Isolated and documented the current Pi OAuth source-label compatibility check. Pi 0.84.2 exposes `AuthResult.source` as a human-readable label but no public typed credential discriminator, so Claude subscription detection must currently recognize the `"OAuth"` label.
+### Tests
+- Added lifecycle coverage for shutdown and replacement-session cancellation, repeated-start interval cleanup, `/usage` closure cancellation, model changes during active polling, and model-selection event wiring.
 ## [0.4.5] - 2026-08-22
 ### Changed

package/LICENSE CHANGED Viewed

@@ -1,21 +1,21 @@
-MIT License
-Copyright (c) 2026 ajarellanod and hknet
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+Copyright (c) 2026 ajarellanod and hknet
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -1,129 +1,145 @@
-# pi-usage-bars
-Quota, balance, and spend indicators for [Pi](https://github.com/earendil-works/pi).
-![Codex footer bar](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/codex.png)
-It adds:
-- a footer status bar for the active supported provider
-- a `/usage` command showing configured quota, balance, and spend data
-## Supported providers
-| Provider | Pi provider ID | Authentication |
-| --- | --- | --- |
-| OpenAI Codex | `openai-codex` | ChatGPT subscription OAuth |
-| Anthropic Claude | `anthropic` | Claude Pro/Max OAuth |
-| ZAI Coding Plan (Global) | `zai` | ZAI API key |
-| ZAI Coding Plan (China) | `zai-coding-cn` | ZAI China API key |
-| Kimi For Coding | `kimi-coding` | Kimi Coding Plan OAuth or API key |
-| MiniMax Coding Plan (Global) | `minimax` | MiniMax Global API key |
-| MiniMax Coding Plan (China) | `minimax-cn` | MiniMax China API key |
-| OpenRouter | `openrouter` | OpenRouter API key |
-| DeepSeek | `deepseek` | DeepSeek API key |
-| Moonshot/Kimi API (Global) | `moonshotai` | Moonshot Global API key |
-| Moonshot/Kimi API (China) | `moonshotai-cn` | Moonshot China API key |
-DeepSeek shows total, topped-up, and granted balances in the currency returned by the API. Moonshot shows available, cash, and voucher balances; this is separate from the Kimi For Coding subscription provider. Pi uses `MOONSHOT_API_KEY` for both Moonshot regions, so `/usage` automatically hides the expected authentication failure from the region where a shared environment key is not valid.
-OpenRouter shows the account credit balance and current daily, weekly, and monthly key spend. If the API key has a configured credit limit, that limit is also rendered as a usage bar.
-MiniMax Subscription Keys can represent an active Token Plan, purchased Credits, or both. The extension shows quota windows when present and a neutral credit-balance line if a first-party key-authenticated response exposes `points_balance`/`credits_balance`. MiniMax currently exposes Credits-only balances through a console endpoint requiring browser-cookie authentication, so a key-only Credits account is shown as “No active Token Plan” with a direction to check the console rather than a fabricated percentage. The extension does not import browser cookies.
-Google Gemini CLI and Google Antigravity are not supported because Pi removed those built-in providers in version 0.71.0.
-## Requirements
-- Pi 0.81.1 or newer (tested with the current Pi 0.84.2 release)
-- Node.js 22.19 or newer when using the npm-distributed Pi CLI
-Authenticate providers through Pi's `/login` command. The extension resolves credentials through Pi's provider API; it does not read or write `auth.json` itself.
-## Install
-Install the npm package:
-```bash
-pi install npm:@hk_net/pi-usage-bars
-```
-Or install the latest source directly from GitHub:
-```bash
-pi install https://github.com/hknet/pi-usage-bars
-```
-Restart Pi after installation, or use `/reload` when the package is already installed.
-Update an existing npm installation with:
-```bash
-pi update npm:@hk_net/pi-usage-bars
-```
-## Use
-### Footer usage bars
-When the active model belongs to a configured supported provider, the footer shows its available quota windows with reset countdowns when provided by the service.
-![Claude footer bar](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/claude.png)
-Usage refresh runs in interactive TUI sessions every two minutes. It does not run in print, JSON, or RPC mode.
-### `/usage`
-Run `/usage` to open a searchable list of configured supported providers.
-![/usage command](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/usage-command.png)
-## Endpoint configuration
-First-party monitoring endpoints can be overridden:
-| Variable | Default |
-| --- | --- |
-| `PI_ZAI_USAGE_ENDPOINT` | `https://api.z.ai/api/monitor/usage/quota/limit` |
-| `PI_ZAI_CODING_CN_USAGE_ENDPOINT` | `https://open.bigmodel.cn/api/monitor/usage/quota/limit` |
-| `PI_KIMI_USAGE_ENDPOINT` | `https://api.kimi.com/coding/v1/usages` |
-| `PI_MINIMAX_USAGE_ENDPOINT` | `https://api.minimax.io/v1/token_plan/remains` |
-| `PI_MINIMAX_LEGACY_USAGE_ENDPOINT` | `https://api.minimax.io/v1/api/openplatform/coding_plan/remains` |
-| `PI_MINIMAX_CN_USAGE_ENDPOINT` | `https://api.minimaxi.com/v1/token_plan/remains` |
-| `PI_MINIMAX_CN_LEGACY_USAGE_ENDPOINT` | `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` |
-| `PI_OPENROUTER_CREDITS_ENDPOINT` | `https://openrouter.ai/api/v1/credits` |
-| `PI_OPENROUTER_KEY_ENDPOINT` | `https://openrouter.ai/api/v1/key` |
-| `PI_DEEPSEEK_BALANCE_ENDPOINT` | `https://api.deepseek.com/user/balance` |
-| `PI_MOONSHOT_BALANCE_ENDPOINT` | `https://api.moonshot.ai/v1/users/me/balance` |
-| `PI_MOONSHOT_CN_BALANCE_ENDPOINT` | `https://api.moonshot.cn/v1/users/me/balance` |
-**Security:** the corresponding provider token is sent as a bearer token to the configured endpoint. Only override these variables with an endpoint you trust.
-The Codex and Claude usage endpoints are fixed to their first-party services. Claude responses are cached briefly in the system temporary directory to coordinate multiple Pi processes and reduce rate limiting. The cache contains usage values, not credentials.
-## Financial metrics roadmap
-Quota percentages and monetary account data have different meaning and color semantics. OpenRouter, DeepSeek, Moonshot, and MiniMax financial data are rendered as neutral account values; percentages are used only when an actual limit exists.
-See [provider support research](docs/provider-research.md) for providers investigated but currently blocked by the absence of a suitable first-party usage API, including Qwen Token Plan and Baseten.
-## Development
-Install Node.js 22.19+ and Bun 1.3, then run:
-```bash
-npm install
-npm run check
-```
-`npm run check` performs a strict TypeScript check and runs the Bun test suite.
-Maintainers should follow the complete [release and npm publication guide](docs/releasing.md): prepare the release, stage it for npm browser approval, then finalize it after 2FA approval. Pushing a Git tag does not publish automatically.
-## Credits
-This extension is based on and inspired by:
-- [CodexBar](https://github.com/steipete/CodexBar)
-- [rho usage-bars](https://github.com/mikeyobrien/rho/tree/main/extensions/usage-bars)
-- [ajarellanod/pi-usage-bars](https://github.com/ajarellanod/pi-usage-bars)
+# pi-usage-bars
+Quota, balance, and spend indicators for [Pi](https://github.com/earendil-works/pi).
+![Codex footer bar](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/codex.png)
+It adds:
+- a footer status bar for the active supported provider
+- a `/usage` command showing configured quota, balance, and spend data
+## Supported providers
+| Provider | Pi provider ID | Authentication |
+| --- | --- | --- |
+| OpenAI Codex | `openai-codex` | ChatGPT subscription OAuth |
+| Anthropic Claude | `anthropic` | Claude Pro/Max OAuth |
+| ZAI Coding Plan (Global) | `zai` | ZAI API key |
+| ZAI Coding Plan (China) | `zai-coding-cn` | ZAI China API key |
+| Kimi For Coding | `kimi-coding` | Kimi Coding Plan OAuth or API key |
+| MiniMax Coding Plan (Global) | `minimax` | MiniMax Global API key |
+| MiniMax Coding Plan (China) | `minimax-cn` | MiniMax China API key |
+| OpenRouter | `openrouter` | OpenRouter API key |
+| DeepSeek | `deepseek` | DeepSeek API key |
+| Moonshot/Kimi API (Global) | `moonshotai` | Moonshot Global API key |
+| Moonshot/Kimi API (China) | `moonshotai-cn` | Moonshot China API key |
+| Baseten | `baseten` | Baseten API key |
+DeepSeek shows total, topped-up, and granted balances in the currency returned by the API. Moonshot shows available, cash, and voucher balances; this is separate from the Kimi For Coding subscription provider. Pi uses `MOONSHOT_API_KEY` for both Moonshot regions, so `/usage` automatically hides the expected authentication failure from the region where a shared environment key is not valid.
+OpenRouter shows the account credit balance and current daily, weekly, and monthly key spend. If the API key has a configured credit limit, that limit is also rendered as a usage bar. Baseten shows current calendar-month credits used, aggregated across its documented dedicated, training, and Model APIs billing categories; it does not invent a remaining-balance or quota percentage.
+MiniMax Subscription Keys can represent an active Token Plan, purchased Credits, or both. The extension shows quota windows when present and a neutral credit-balance line if a first-party key-authenticated response exposes `points_balance`/`credits_balance`. MiniMax currently exposes Credits-only balances through a console endpoint requiring browser-cookie authentication, so a key-only Credits account is shown as “No active Token Plan” with a direction to check the console rather than a fabricated percentage. The extension does not import browser cookies.
+Google Gemini CLI and Google Antigravity are not supported because Pi removed those built-in providers in version 0.71.0.
+## Requirements
+- Pi 0.84.2 or newer (tested with the current Pi 0.84.4 release)
+- Node.js 22.19 or newer when using the npm-distributed Pi CLI
+Authenticate providers through Pi's `/login` command. The extension resolves credentials through Pi's provider API; it does not read or write `auth.json` itself.
+## Install
+Install the npm package:
+```bash
+pi install npm:@hk_net/pi-usage-bars
+```
+Or install the latest source directly from GitHub:
+```bash
+pi install https://github.com/hknet/pi-usage-bars
+```
+Restart Pi after installation, or use `/reload` when the package is already installed.
+Update an existing npm installation with:
+```bash
+pi update npm:@hk_net/pi-usage-bars
+```
+## Use
+### Footer usage bars
+When the active model belongs to a configured supported provider, the footer shows its available quota windows with reset countdowns when provided by the service.
+![Claude footer bar](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/claude.png)
+Usage refresh runs in interactive TUI sessions every two minutes. It does not run in print, JSON, or RPC mode.
+### `/usage`
+Run `/usage` to open a searchable list of configured supported providers. The selected provider's details are expanded; use the configured selection and page-navigation keybindings to browse the bounded list.
+![/usage command]
+### `--usage`
+Pass `--usage` to print one JSON line for the active model provider and exit without opening the usage UI. This is also useful as a loader and credential smoke test:
+```powershell
+pi --no-extensions -e C:\hk\code\pi-usage-bars\extensions\usage-bars\index.ts --usage
+```
+The result has `status` set to `ok`, `unconfigured`, `unsupported`, or `error`. No credential is included in the output.(https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/usage-command.png)
+## Endpoint configuration
+First-party monitoring endpoints can be overridden:
+| Variable | Default |
+| --- | --- |
+| `PI_ZAI_USAGE_ENDPOINT` | `https://api.z.ai/api/monitor/usage/quota/limit` |
+| `PI_ZAI_CODING_CN_USAGE_ENDPOINT` | `https://open.bigmodel.cn/api/monitor/usage/quota/limit` |
+| `PI_KIMI_USAGE_ENDPOINT` | `https://api.kimi.com/coding/v1/usages` |
+| `PI_MINIMAX_USAGE_ENDPOINT` | `https://api.minimax.io/v1/token_plan/remains` |
+| `PI_MINIMAX_LEGACY_USAGE_ENDPOINT` | `https://api.minimax.io/v1/api/openplatform/coding_plan/remains` |
+| `PI_MINIMAX_CN_USAGE_ENDPOINT` | `https://api.minimaxi.com/v1/token_plan/remains` |
+| `PI_MINIMAX_CN_LEGACY_USAGE_ENDPOINT` | `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` |
+| `PI_OPENROUTER_CREDITS_ENDPOINT` | `https://openrouter.ai/api/v1/credits` |
+| `PI_OPENROUTER_KEY_ENDPOINT` | `https://openrouter.ai/api/v1/key` |
+| `PI_DEEPSEEK_BALANCE_ENDPOINT` | `https://api.deepseek.com/user/balance` |
+| `PI_MOONSHOT_BALANCE_ENDPOINT` | `https://api.moonshot.ai/v1/users/me/balance` |
+| `PI_MOONSHOT_CN_BALANCE_ENDPOINT` | `https://api.moonshot.cn/v1/users/me/balance` |
+| `PI_BASETEN_USAGE_ENDPOINT` | `https://api.baseten.co/v1/billing/usage_summary` |
+**Security:** the corresponding provider token is sent as a bearer token to the configured endpoint. Only override these variables with an endpoint you trust.
+The Codex and Claude usage endpoints are fixed to their first-party services. Claude responses are cached briefly in the system temporary directory to coordinate multiple Pi processes and reduce rate limiting. The cache contains usage values, not credentials.
+## Financial metrics roadmap
+Quota percentages and monetary account data have different meaning and color semantics. OpenRouter, DeepSeek, Moonshot, and MiniMax financial data are rendered as neutral account values; percentages are used only when an actual limit exists.
+### Future: Qwen Token Plan
+Qwen Token Plan Individual has a documented seven-day Credits quota, but Qwen currently directs users to console usage details and prohibits API-key automation. Add Qwen support only when Qwen documents and authorizes a key-authenticated usage endpoint compatible with Pi's resolved `sk-sp-…` credential. Do not use browser cookies or console-session tokens. The endpoint must expose used Credits, quota limit, reset time, and any separate Credit Pack balance; validate it with redacted fixtures before implementation.
+See [provider support research](docs/provider-research.md) for the supporting Qwen investigation.
+## Development
+Install Node.js 22.19+ and Bun 1.3, then run:
+```bash
+npm install
+npm run check
+```
+`npm run check` performs a strict TypeScript check and runs the Bun test suite.
+Maintainers should follow the complete [release and npm publication guide](docs/releasing.md): prepare the release, stage it for npm browser approval, then finalize it after 2FA approval. Pushing a Git tag does not publish automatically.
+## Credits
+This extension is based on and inspired by:
+- [CodexBar](https://github.com/steipete/CodexBar)
+- [rho usage-bars](https://github.com/mikeyobrien/rho/tree/main/extensions/usage-bars)
+- [ajarellanod/pi-usage-bars](https://github.com/ajarellanod/pi-usage-bars)

package/docs/provider-research.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Provider support research
-This document records providers considered for usage-bar support but currently blocked by the absence of a suitable first-party API. Recheck these findings when a provider publishes a new quota, balance, or billing API.
+This document records providers considered for usage-bar support. Recheck blocked findings when a provider publishes a new quota, balance, or billing API.
 ## Qwen Token Plan
@@ -22,11 +22,11 @@ Do not estimate account-wide quota from requests observed by this extension: oth
 ## Baseten
-**Status:** Blocked — no account-usage surface found as of 2026-08-13.
+**Status:** Supported as of 2026-08-28.
-Pi 0.84.0 added the `baseten` provider using `BASETEN_API_KEY`. Baseten is primarily usage-billed, and research found no documented API-key endpoint for account balance, credits, budget utilization, or billing usage that this extension could safely query.
+Pi's `baseten` provider resolves `BASETEN_API_KEY`. Baseten documents `GET https://api.baseten.co/v1/billing/usage_summary`, authenticated with `Authorization: Bearer $BASETEN_API_KEY`, with required UTC `start_date` and `end_date` parameters (maximum range: 31 days). The response reports `credits_used` for dedicated serving, training, and Model APIs. The extension queries the current UTC calendar month and reports the aggregate Credits used; it intentionally does not manufacture a remaining balance or quota percentage.
-**Recheck when:** Baseten publishes a first-party balance, credits, budget, or billing-usage API accessible with the inference credential or a documented monitoring credential.
+**Recheck when:** Baseten publishes a first-party balance, budget, or quota API that permits a more complete account indicator.
 ## Acceptance criteria for a new provider

package/docs/releasing.md CHANGED Viewed

@@ -1,84 +1,104 @@
-# Releasing
-This repository uses semantic versions. The package version, changelog heading, Git tag, and npm version must agree.
-Local releases use npm staged publishing followed by browser 2FA approval. Browser login only authenticates the CLI; it does not publish or approve a staged package. The GitHub Actions publish workflow is manual-only; pushing a tag does not publish the package.
-## Prerequisites
-- Write access to `hknet/pi-usage-bars`.
-- Publish access to the npm scope `@hk_net`.
-- Node.js 22.19 or newer.
-- A clean, synchronized `main` branch.
-Never place an npm token in the repository, command history, or endpoint configuration. Complete npm's browser or OTP authorization when prompted.
-## Recommended release script
-From the repository root, provide the exact new semantic version:
-```bash
-cd /path/to/pi-usage-bars
-scripts/release.sh X.Y.Z
-```
-This **default command only prepares the release**. It deliberately stops before npm login or publication, so the pushed release commit can be reviewed first. The launcher first executes an immutable temporary copy of itself, so editing the script while a release is running cannot corrupt that run.
-Preparation:
-1. verifies that `main` is clean and synchronized with `origin/main`;
-2. rejects an existing npm version or Git tag;
-3. updates `package.json` and `package-lock.json` without creating an early tag;
-4. promotes the `Unreleased` changelog entries into a dated release while preserving an empty `Unreleased` heading;
-5. installs dependencies with `npm ci --no-audit`, provisions a temporary pinned Bun binary, and runs typecheck, tests, detailed dependency audits, and package dry-run; and
-6. commits and pushes the release source.
-After reviewing the prepared commit, stage it for browser approval:
-```bash
-scripts/release.sh X.Y.Z stage
-```
-`stage` submits the package to npm's staged-publishing queue. It **does not publish live**, does not open a browser, and does not tag Git. If npm authentication is needed, run `npm login --auth-type=web` manually first; this only authenticates the CLI.
-In [npmjs.com](https://www.npmjs.com), open **Staged Packages**, review the staged tarball, and click **Approve**. npm prompts for 2FA during approval. After npm shows the version as live, finalize the release:
-```bash
-scripts/release.sh X.Y.Z finalize
-```
-`finalize` refuses to run until the exact version is live in the npm registry. It then verifies registry metadata and creates/pushes the annotated Git tag. It never stages or publishes a package.
-Use `--yes` only for attended preparation:
-```bash
-scripts/release.sh X.Y.Z --yes  # prepare only
-```
-## Recovery
-Staging and finalization are safe to rerun: `stage` refuses if the exact version is already live, and `finalize` refuses until it is live. Never force-push a release tag.
-The release script first prints a full dependency audit with package names, dependency paths, affected ranges, and available fixes. This is informational because it includes development-only dependencies. It then runs a blocking production-only audit, which rejects high or critical production findings.
-Show script help with:
-```bash
-scripts/release.sh --help
-```
-## Post-release verification
-Confirm installation through Pi:
-```bash
-pi install npm:@hk_net/pi-usage-bars
-# If already installed from npm:
-pi update npm:@hk_net/pi-usage-bars
-```
-Restart Pi, or use `/reload`, then run `/usage`.
-## GitHub Actions alternative
-The **Publish to npm (manual)** workflow is available as an alternative. It requires the `NPM_TOKEN` repository secret and publishes with npm provenance. Do not run it after publishing the same version locally.
+# Releasing
+This repository uses semantic versions. The package version, changelog heading, Git tag, and npm version must agree.
+Local releases use npm staged publishing followed by browser 2FA approval. Browser login only authenticates the CLI; it does not publish or approve a staged package. The GitHub Actions publish workflow is manual-only; pushing a tag does not publish the package.
+## Prerequisites
+- Write access to `hknet/pi-usage-bars`.
+- Publish access to the npm scope `@hk_net`.
+- Node.js 22.19 or newer.
+- A clean, synchronized `main` branch.
+Never place an npm token in the repository, command history, or endpoint configuration. Complete npm's browser or OTP authorization when prompted.
+## Recommended release script
+From the repository root, provide the exact new semantic version:
+```bash
+cd /path/to/pi-usage-bars
+scripts/release.sh X.Y.Z
+```
+From Windows PowerShell, run the Bash workflow through WSL (replace the WSL path with your checkout):
+```powershell
+wsl bash -lc 'cd /mnt/c/path/to/pi-usage-bars && ./scripts/release.sh X.Y.Z'
+```
+The repository's `.gitattributes` keeps shell scripts on LF endings so they remain executable in WSL even when Git for Windows uses `core.autocrlf=true`.
+This **default command only prepares the release**. It deliberately stops before npm login or publication, so the pushed release commit can be reviewed first. The launcher first executes an immutable temporary copy of itself, so editing the script while a release is running cannot corrupt that run.
+Preparation:
+1. verifies that `main` is clean and synchronized with `origin/main`;
+2. rejects an existing npm version or Git tag;
+3. updates `package.json` and `package-lock.json` without creating an early tag;
+4. promotes the `Unreleased` changelog entries into a dated release while preserving an empty `Unreleased` heading;
+5. installs dependencies with `npm ci --no-audit`, provisions a temporary pinned Bun binary, and runs typecheck, tests, detailed dependency audits, and package dry-run; and
+6. commits and pushes the release source.
+After reviewing the prepared commit, stage it for browser approval:
+```bash
+scripts/release.sh X.Y.Z stage
+```
+From Windows PowerShell:
+```powershell
+wsl bash -lc 'cd /mnt/c/path/to/pi-usage-bars && ./scripts/release.sh X.Y.Z stage'
+```
+`stage` submits the package to npm's staged-publishing queue. It **does not publish live**, does not open a browser, and does not tag Git. If npm authentication is needed, run `npm login --auth-type=web` manually first; this only authenticates the CLI.
+In [npmjs.com](https://www.npmjs.com), open **Staged Packages**, review the staged tarball, and click **Approve**. npm prompts for 2FA during approval. After npm shows the version as live, finalize the release:
+```bash
+scripts/release.sh X.Y.Z finalize
+```
+From Windows PowerShell:
+```powershell
+wsl bash -lc 'cd /mnt/c/path/to/pi-usage-bars && ./scripts/release.sh X.Y.Z finalize'
+```
+`finalize` refuses to run until the exact version is live in the npm registry. It then verifies registry metadata and creates/pushes the annotated Git tag. It never stages or publishes a package.
+Use `--yes` only for attended preparation:
+```bash
+scripts/release.sh X.Y.Z --yes  # prepare only
+```
+## Recovery
+Staging and finalization are safe to rerun: `stage` refuses if the exact version is already live, and `finalize` refuses until it is live. Never force-push a release tag.
+The release script first prints a full dependency audit with package names, dependency paths, affected ranges, and available fixes. This is informational because it includes development-only dependencies. It then runs a blocking production-only audit, which rejects high or critical production findings.
+Show script help with:
+```bash
+scripts/release.sh --help
+```
+## Post-release verification
+Confirm installation through Pi:
+```bash
+pi install npm:@hk_net/pi-usage-bars
+# If already installed from npm:
+pi update npm:@hk_net/pi-usage-bars
+```
+Restart Pi, or use `/reload`, then run `/usage`.
+## GitHub Actions alternative
+The **Publish to npm (manual)** workflow is available as an alternative. It requires the `NPM_TOKEN` repository secret and publishes with npm provenance. Do not run it after publishing the same version locally.