npm - @hk_net/pi-usage-bars - Versions diffs - 0.4.1 → 0.4.3 - Mend

@hk_net/pi-usage-bars 0.4.1 → 0.4.3

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 (9) hide show

package/CHANGELOG.md +28 -0
package/LICENSE +21 -21
package/README.md +129 -127
package/docs/provider-research.md +39 -0
package/docs/releasing.md +84 -84
package/extensions/usage-bars/core.ts +1274 -1268
package/extensions/usage-bars/index.ts +672 -665
package/package.json +66 -66
package/docs/financial-metrics-plan.md +0 -75

package/CHANGELOG.md CHANGED Viewed

@@ -2,6 +2,34 @@
 ## Unreleased
+## [0.4.3] - 2026-08-22
+### Fixed
+- Resolve kimi-coding OAuth credentials that Pi exposes only as a Bearer `Authorization` header (no `apiKey`), so the Kimi For Coding usage indicator no longer reports "auth resolution failed (configured authentication did not resolve a token)". Thanks to [@Rakkael](https://github.com/Rakkael) for the contribution in [#2](https://github.com/hknet/pi-usage-bars/pull/2).
+### Changed
+- Updated the development and test baseline to Pi SDK 0.84.2 while retaining runtime compatibility with Pi 0.81.1 and newer.
+### Documentation
+- Recorded Qwen Token Plan and Baseten usage-API research, including the conditions for revisiting provider support.
+## [0.4.2] - 2026-08-13
+### Fixed
+- Added support for credit-based ZAI plan tiers that report `CREDIT_LIMIT` quota windows. Thanks to [@chrislucca](https://github.com/chrislucca) for the contribution in [#1](https://github.com/hknet/pi-usage-bars/pull/1).
+### Changed
+- Updated the development and test baseline to Pi SDK 0.84.1 while retaining runtime compatibility with Pi 0.81.1 and newer.
+### Security
+- Updated the Pi SDK development dependency chain to use `undici` 8.9.0, resolving the advisories affecting earlier 8.x releases.
 ## [0.4.1] - 2026-07-31
 ### Fixed

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,127 +1,129 @@
-# 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 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
-- 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 [Financial metrics plan](docs/financial-metrics-plan.md) for the normalized model and future provider rollout.
-## 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, runs the Bun test suite, and smoke-loads the extension with the pinned current Pi release.
-Maintainers should follow the complete [release and npm publication guide](docs/releasing.md). npm publication is manual; 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 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)

package/docs/provider-research.md ADDED Viewed

@@ -0,0 +1,39 @@
+# 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.
+## Qwen Token Plan
+**Status:** Blocked — no account-usage surface found as of 2026-08-13.
+Pi 0.84.1 supports these provider IDs:
+- `qwen-token-plan`
+- `qwen-token-plan-individual`
+- `qwen-token-plan-cn`
+The Individual provider shares the international inference endpoint and `QWEN_TOKEN_PLAN_API_KEY` with the existing international provider, but exposes a narrower model catalog.
+Research found no documented API-key-authenticated endpoint that reports consumed or remaining quota, percentages, or reset times. Independent probing of eight likely usage/quota paths on `token-plan.ap-southeast-1.maas.aliyuncs.com` returned `404`, and successful inference responses did not include quota or rate-limit headers. Qwen's client can recognize an exhausted-quota error, but that provides no usage percentage or reset timestamp.
+Do not estimate account-wide quota from requests observed by this extension: other clients and sessions would make that value incomplete and misleading.
+**Recheck when:** Alibaba Model Studio documents a Token Plan usage endpoint, adds quota headers to inference responses, or exposes a key-authenticated portal API.
+## Baseten
+**Status:** Blocked — no account-usage surface found as of 2026-08-13.
+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.
+**Recheck when:** Baseten publishes a first-party balance, credits, budget, or billing-usage API accessible with the inference credential or a documented monitoring credential.
+## Acceptance criteria for a new provider
+A provider is suitable when a documented first-party API or response header supplies at least one meaningful account-level value:
+- quota consumed or remaining, ideally with a reset time;
+- account balance or credits; or
+- spend for a defined billing period.
+Authentication must work through Pi's provider credential API. The extension must not import browser cookies, scrape console pages, estimate account-wide usage from local traffic, or send credentials to third-party services.

package/docs/releasing.md CHANGED Viewed

@@ -1,84 +1,84 @@
-# Releasing
-This repository uses semantic versions. The package version, changelog heading, Git tag, and npm version must agree.
-Local publication uses npm browser authentication. 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 0.4.1
-```
-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 0.4.1 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.
-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 0.4.1 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 0.4.1 --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
+```
+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.