rinco-pi-hud 1.2.0 → 1.3.1

package/README.md

@@ -2,49 +2,36 @@
 
 # Rinco Pi HUD
 
-**A dynamic HUD footer for [Pi](https://github.com/earendil-works/pi).**
+**A live status footer for [Pi](https://github.com/earendil-works/pi).** Project, git, session, tool and cost state in four groups, updated while you work.
 
 [![Pi package](https://img.shields.io/badge/Pi-package-F2A7C6?style=flat-square)](https://github.com/earendil-works/pi) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Tests](https://img.shields.io/badge/tests-Vitest-6E9F18?style=flat-square&logo=vitest&logoColor=white)](https://vitest.dev/) [![License](https://img.shields.io/badge/license-MIT-C7B8F5?style=flat-square)](LICENSE)
 
-[Features](#features) · [Installation](#installation) · [Usage](#usage) · [Customization](#customization) · [Development](#development)
+[Install](#install) · [Commands](#commands) · [What it shows](#what-it-shows) · [Layout](#layout) · [Development](#development)
 
 [简体中文](docs/README.zh-CN.md)
 
 </div>
 
-Rinco Pi HUD provides a rich, real-time status footer for Pi TUI sessions. It displays project state, Git metrics, runtime versions, session activity, model usage, token costs, and more — all in a responsive four-group or customizable single-line layout. Pi loads the TypeScript extension directly, so no build step is required (`tsconfig.json` sets `noEmit: true` and is used only for `npm run typecheck`).
+<p align="center">
+  <img src="./assets/readme/hero.svg" width="100%" alt="The Rinco Pi HUD footer inside Pi: a Project row with directory, git branch and Node version, a Session row with provider and model, an Activity row with tool counts, and a Usage row with context window, tokens, cache hit rate and cost.">
+</p>
 
-## Features
+Rinco Pi HUD takes over Pi's footer with four groups of live state and lets you switch off anything you do not want. Pi loads the TypeScript extension directly, so there is no build step: `tsconfig.json` sets `noEmit: true` and exists only for `npm run typecheck`.
 
-- **Project state** — Working directory, Git branch, commit, tag, status, operation state, diff metrics, and runtime versions.
-- **Session activity** — Model, provider, context usage, independently controlled input/output tokens, cache, session cost, turn count, and thinking level.
-- **Tool and agent activity** — Independent controls for running tools, completed tool counts, active agents, idle state, skills, and MCP server status.
-- **Model quota** — Automatic Codex weekly quota or Token Switch balance display by model provider.
-- **Git awareness** — Branches, detached HEAD, tags, ahead/behind, stash, merge/rebase conflicts, and dirty state.
-- **Runtime detection** — Node, Python, Go, Rust, Java, and 60+ other runtimes with package version parsing.
-- **Configurable layout** — Responsive Project, Session, Activity, and Usage groups by default, or fully customizable single-line templates.
-- **Granular status controls** — Toggle Git operation state, tool runtime/counts, active/idle agents, and input/output tokens separately from `/zentui`.
-- **Extension statuses** — Reads third-party extension statuses and places them by configurable position and color mode.
-- **Safe fallback** — Graceful timeout and error handling; no stale data after session shutdown.
-
-## Installation
-
-### Install from npm (recommended)
+## Install
 
 ```bash
 pi install npm:rinco-pi-hud
 ```
 
-The published package is available on [npm](https://www.npmjs.com/package/rinco-pi-hud).
+Restart Pi afterwards, or run `/reload`. The footer is enabled by default and `/zentui` opens the settings UI.
 
-### Install from GitHub
+From GitHub, or from a local checkout:
 
 ```bash
 pi install git:github.com/Rinisnotarobot/rinco-pi-hud
 ```
 
-### Install from a local checkout
-
 ```bash
 git clone https://github.com/Rinisnotarobot/rinco-pi-hud.git
 cd rinco-pi-hud
@@ -54,34 +41,62 @@ pi install "$PWD"
 > [!IMPORTANT]
 > Pi extensions run with your user permissions. Review the source before installing any third-party extension.
 
-## Usage
+> [!NOTE]
+> The footer needs a Truecolor terminal. The screenshot above renders with ASCII icon mode; `/zentui` switches between the `auto`, `nerd`, and `ascii` glyph sets.
 
-Restart Pi after installation, or run:
+## Commands
 
-```text
-/reload
-```
+| Command | Effect |
+| --- | --- |
+| `/zentui` | Settings UI: rows, segments, separator, icons, colors, templates |
+| `/zentui statusline enable\|disable\|toggle` | Show or hide the whole footer |
+| `/zentui row project\|session\|activity\|usage <enable\|disable\|toggle>` | Turn one row on or off |
+| `/zentui format "<template>"` | Replace the four rows with a single-line template |
+| `/codex-status` | Print Codex subscription usage and rate-limit windows |
+| `/usage-refresh` | Refresh the model usage or balance shown in the footer |
+
+## What it shows
+
+| Row | Segments, each with its own switch under **Built-in segments** in `/zentui` |
+| --- | --- |
+| **Project** | directory, git branch, commit and tag, working-tree status, operation state (`MERGING`, `REBASING`, …), diff metrics, runtime, package version, OS, user |
+| **Session** | session name, provider and model, thinking level, turn count, duration |
+| **Activity** | running tools, completed tool counts, active agents, `Agent idle`, skills, MCP servers |
+| **Usage** | context window with a gauge, input and output tokens, cache read/write volume and hit rate, cost, model quota, clock |
+
+Rows are toggled with `/zentui row usage disable`; the segments inside them have individual switches in the same UI. Existing configs that used the former aggregate `tokens`, `toolActivity`, or `agentActivity` switches are migrated automatically.
+
+### Model quota
+
+The Usage row follows the active model's provider:
+
+- **openai-codex** — ChatGPT subscription rate limits and reset credits, queried through Pi auth with a `codex app-server` fallback. Reads as `codex 60% 5h (14:30) 75% wk`; the reset stamp becomes `14:30 12 Feb` when the window rolls into another day.
+- **token-switch** — billing balance from the `TOKEN_SWITCH_API_KEY` environment variable, as `token-switch $750.00`.
+- **deepseek** — account balance from the DeepSeek API using the credential Pi holds for the provider, either from `/login` or `DEEPSEEK_API_KEY`. Reads as `deepseek ¥110.00`, preferring CNY when the account reports several currencies.
 
-The HUD footer is enabled by default. Run `/zentui` to open the interactive settings UI.
+These queries use a 15-second timeout and a 5-minute cache, and `/usage-refresh` refreshes the active one on demand.
 
-### Common commands
+## Layout
+
+<p align="center">
+  <img src="./assets/readme/responsive.svg" width="100%" alt="The same footer rendered at 72 and 56 columns: rows wrap between segments, continuation lines realign under the separator column, and a tool-count segment that cannot fit is shortened with an ellipsis while the segments after it still render.">
+</p>
+
+Groups wrap only at segment boundaries. A continuation line realigns under the separator column, and a segment that no longer fits is shortened with `…` instead of pushing the segments after it off the row.
+
+Set a template for a single-line footer instead of the four groups:
 
 ```text
-/zentui statusline enable
-/zentui statusline disable
-/zentui statusline toggle
-/zentui row project toggle
-/zentui row session disable
-/zentui row activity enable
-/zentui row usage toggle
-/zentui format clear
-/zentui format "$model · $context · $cost · $git_branch( $git_commit) · $session_duration"
-/codex-status
-/usage-refresh
+/zentui format "$cwd( $git_branch)$fill($context)( $tokens)( $cost)"
 ```
 
-> [!NOTE]
-> For the best result, use a Truecolor terminal and a Nerd Font. The footer uses Unicode glyphs that render best with proper font support.
+Variables accept `$name` or `${name}`. The [footer reference](docs/footer.md) lists all of them, along with the aliases (`$directory`, `$status`, `$codex`, …). Run `/zentui format` with no argument, or `/zentui format clear`, to go back to the four groups.
+
+## Configuration
+
+`/zentui` writes to `~/.pi/agent/rinco-pi-hud.json` and applies changes immediately. It covers the separator style, icon mode (`nerd`, `ascii`, or `auto`), footer colors (Pi theme tokens or terminal palette styles), context rendering (text, gauge, or both), the project refresh interval, and third-party extension statuses with their own placement and color mode.
+
+See [docs/footer.md](docs/footer.md) for the full variable and segment reference.
 
 ## Project contents
 
@@ -91,119 +106,66 @@ The HUD footer is enabled by default. Run `/zentui` to open the interactive sett
 | [`extensions/hud/config/`](extensions/hud/config/config.ts) | Configuration model, normalization, migration, and persistence |
 | [`extensions/hud/footer/`](extensions/hud/footer/index.ts) | Footer rendering, semantic grouping, responsive layout, and template parsing |
 | [`extensions/hud/segments/`](extensions/hud/segments/) | State collectors: Git, runtime, MCP, skills, projects, etc. |
-| [`extensions/hud/telemetry/`](extensions/hud/telemetry/format.ts) | Usage formatting, token switch, and Codex subscription client |
+| [`extensions/hud/telemetry/`](extensions/hud/telemetry/format.ts) | Usage formatting, provider balance probes, and the Codex subscription client |
 | [`extensions/hud/session/`](extensions/hud/session/) | Pi event registration, session lifecycle, and live context overlay |
 | [`extensions/hud/state/`](extensions/hud/state/) | Aggregated state, telemetry reducer, and project refresh controller |
 | [`extensions/hud/commands/`](extensions/hud/commands/settings.ts) | `/zentui` settings UI and configuration controller |
 | [`extensions/hud/ui/`](extensions/hud/ui/) | Icons and terminal style utilities |
 | [`docs/footer.md`](docs/footer.md) | Complete footer configuration reference |
 | [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) | Local development, testing guidance, and pull request checklist |
-| [`tests/`](tests/) | Vitest test suite (41 tests across 8 files) |
-
-## Customization
-
-### Layout
-
-The default layout groups Project, Session, Activity, and Usage information. Long groups wrap at complete segment boundaries with aligned continuation lines. Set `footerFormat` to a template string for a single-line layout:
-
-```text
-/zentui format "$cwd( $git_branch)$fill($context)( $tokens)( $cost)"
-```
-
-Template variables use `$name` or `${name}` syntax. See the [footer reference](docs/footer.md) for the complete variable list.
-
-### Segments
-
-Open `/zentui`, then select **Built-in segments** to enable or disable individual statuses. Fine-grained controls include:
-
-| Group | Independently controlled statuses |
-| --- | --- |
-| Project | Git status, Git operation state (`MERGING`, `REBASING`, etc.), commit, metrics, runtime, package, OS, and user |
-| Session | Model, thinking level, turn count, and duration |
-| Activity | Running tools, completed tool counts, active agents, `Agent idle`, skills, and MCP |
-| Usage | Context, input tokens, output tokens, cache details/hit rate, cost, quota, and time |
-
-Existing configs using the former aggregate `tokens`, `toolActivity`, or `agentActivity` switches are migrated automatically. The whole footer can still be controlled with `/zentui statusline enable|disable|toggle`.
-
-In the default four-row layout, each semantic row can also be controlled directly:
-
-```text
-/zentui row <project|session|activity|usage> <enable|disable|toggle>
-```
-
-Row switches are persisted in `footerRows`. They do not affect a custom single-line `footerFormat`.
-
-### Extension statuses
-
-Third-party extensions publish statuses that the HUD footer can display. Configure placement (`left`, `middle`, `right`, `off`) and color mode (`zentui`, `original`) for each extension status key.
+| [`tests/`](tests/) | Vitest suite: footer layout, telemetry, provider balances, MCP configuration counts |
 
 ## Development
 
-### Prerequisites
-
-- [Node.js](https://nodejs.org/) 22.19 or later
-- [Pi](https://github.com/earendil-works/pi)
-
-Install development dependencies:
+Node.js 22.19 or later, and [Pi](https://github.com/earendil-works/pi) itself.
 
 ```bash
 npm install
+npm test          # Vitest suite
+npm run typecheck # tsc --noEmit
+npm run verify    # format, types, lint, tests
 ```
 
-### Available commands
-
-<!-- AUTO-GENERATED: package-scripts:start -->
-<!-- Source: package.json#scripts. Do not edit manually. -->
-
-| Command | Description |
-| --- | --- |
-| `npm test` | Run the complete Vitest suite once. |
-| `npm run test:watch` | Run Vitest in watch mode and retest when files change. |
-| `npm run typecheck` | Run TypeScript type checking with `tsc --noEmit`. |
-| `npm run pack:check` | Inspect the publishable package with `npm pack --dry-run` without publishing it. |
-
-<!-- AUTO-GENERATED: package-scripts:end -->
-
-Run the test suite:
+Every script is defined in [`package.json`](package.json); [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) lists them all, including `lint`, `format`, and `test:watch`.
 
-```bash
-npm test
-```
+### README images
 
-Check types:
+The two boards above are generated from a real footer render rather than drawn by hand. `assets/readme/source/capture-footer.mts` drives the extension's own `installFooter` path over this repository's state and a real Pi session transcript, then `build-assets.mts` turns the ANSI rows into SVG:
 
 ```bash
-npm run typecheck
+npx tsx assets/readme/source/capture-footer.mts . ~/.pi/agent/sessions/<session>.jsonl 118 72 56 > /tmp/footer.json
+npx tsx assets/readme/source/build-assets.mts /tmp/footer.json
 ```
 
-Verify formatting, types, lint rules, tests, and package contents:
-
-```bash
-npm run verify
-npm run pack:check
-```
+## Troubleshooting
 
-Vitest covers footer layout, telemetry, codex usage, token switch, config counts, and MCP status parsing. Pi loads the TypeScript source directly, so this project has no separate build command.
+<details>
+<summary>The footer does not appear</summary>
 
-## Troubleshooting
+Confirm Pi is running in TUI mode rather than headless, JSON, or print mode. Then run `/reload`, and `pi list` to confirm the package is installed.
+</details>
 
-### The footer does not appear
+<details>
+<summary>The layout looks wrong in a narrow terminal</summary>
 
-1. Confirm that Pi is running in TUI mode rather than headless, JSON, or print mode.
-2. Run `/reload` or restart Pi.
-3. Run `pi list` to confirm that the package is installed.
+The footer measures the terminal and wraps at segment boundaries, so narrow windows show fewer segments per line. Set a `footerFormat` template, or disable low-priority segments in `/zentui`.
+</details>
 
-### The footer layout looks wrong
+<details>
+<summary>Colors look incorrect</summary>
 
-The footer auto-detects terminal width and truncates content. In narrow terminals, some segments may be clipped. Adjust the layout by setting a custom `footerFormat` template, or disable low-priority segments in `/zentui`.
+The default palette emits `38;2;r;g;b` Truecolor sequences that terminals without Truecolor support approximate or ignore.
+</details>
 
-### Colors look incorrect
+<details>
+<summary>Icons are missing or misaligned</summary>
 
-Make sure your terminal supports Truecolor. The footer emits `38;2;r;g;b` ANSI sequences.
+Unicode and Nerd Font glyphs vary between terminals and fonts. Install a Nerd Font, or switch to ASCII icons in `/zentui`.
+</details>
 
-### Unicode icons are missing or misaligned
+## License
 
-Unicode and Nerd Font glyphs vary between terminals and fonts. Install a Nerd Font, or switch to ASCII icon mode via `/zentui`.
+MIT. See [`LICENSE`](LICENSE).
 
 ## Third-party licenses
 
@@ -216,4 +178,4 @@ This package incorporates work from the following open-source projects:
 - **pi-codex-usage** by narumiruna — MIT licensed. The Codex usage client under `extensions/hud/telemetry/codex-usage/` derives from this project.  
   Source: https://github.com/narumiruna/pi-codex-usage
 
-See [NOTICE](NOTICE) for details.
+See [NOTICE](NOTICE) for details.

package/assets/readme/hero.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="430" viewBox="0 0 1200 430" role="img" aria-labelledby="t d" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif">
+  <title id="t">Rinco Pi HUD — a live HUD footer for the Pi terminal agent</title>
+  <desc id="d">The footer from a real Pi session, rendered at 118 columns: a Project row with directory, git branch, commit and Node version; a Session row with provider, model, thinking level and turn count; an Activity row with real tool counts; and a Usage row with context window, tokens, cache hit rate and cost.</desc>
+  <rect width="1200" height="430" rx="26" fill="#0E0C15"/>
+  <g id="title-block">
+    <text x="56" y="72" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="18" letter-spacing="2.4" fill="#F2A7C6">PI · TUI FOOTER EXTENSION</text>
+    <text x="56" y="126" font-size="60" font-weight="700" fill="#F5F2F8">Rinco Pi HUD<tspan fill="#F2A7C6">.</tspan></text>
+    <text x="56" y="162" font-size="22" fill="#B9B2C0">Live project, session, tool and cost status in your Pi footer.</text>
+  </g>
+  <g id="panel-118">
+    <rect x="56" y="196" width="1088" height="178" rx="14" fill="#16131F" stroke="#2C2640"/>
+    <text x="80" y="219" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="18" fill="#A99BAE">extensions/hud/footer/index.ts</text>
+    <text x="1120" y="219" text-anchor="end" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="18" fill="#A99BAE">render(118) · ASCII icons</text>
+    <line x1="56" y1="230" x2="1144" y2="230" stroke="#2C2640"/>
+
+    <text x="80" y="260" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan> </tspan><tspan fill="#f2a7c6" font-weight="700">Project</tspan><tspan> </tspan><tspan fill="#716879"> › </tspan><tspan fill="#f2a7c6" font-weight="700">rinco-pi-hud</tspan><tspan fill="#716879"> › </tspan><tspan>on </tspan><tspan fill="#c7b8f5" font-weight="700">*</tspan><tspan> </tspan><tspan fill="#c7b8f5" font-weight="700">main</tspan><tspan fill="#716879"> › </tspan><tspan fill="#9fd3f2">via</tspan><tspan> </tspan><tspan fill="#AEE5C5" font-weight="700">node v24.18.0</tspan><tspan fill="#716879"> › </tspan><tspan fill="#f7eef8">linux</tspan></text>
+    <text x="80" y="290" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan> </tspan><tspan fill="#9fd3f2">Session</tspan><tspan> </tspan><tspan fill="#716879"> › </tspan><tspan fill="#9fd3f2">deepseek/deepseek-flash</tspan><tspan fill="#716879"> › </tspan><tspan fill="#efc3e6">Thinking level: max</tspan><tspan fill="#716879"> › </tspan><tspan fill="#efc3e6">Turn 3</tspan></text>
+    <text x="80" y="320" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan> </tspan><tspan fill="#efc3e6">Activity</tspan><tspan fill="#716879"> › </tspan><tspan fill="#aee5c5">Tool read × 30 write × 7 edit × 13 bash × 76</tspan><tspan fill="#716879"> › </tspan><tspan fill="#a99bae">Agent idle</tspan></text>
+    <text x="80" y="350" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan> </tspan><tspan fill="#aee5c5">Usage</tspan><tspan>   </tspan><tspan fill="#716879"> › </tspan><tspan fill="#aee5c5">[##--------] 17%/1.0M</tspan><tspan fill="#716879"> › </tspan><tspan fill="#a99bae">↑ 177k</tspan><tspan fill="#716879"> › </tspan><tspan fill="#a99bae">↓ 74k</tspan><tspan fill="#716879"> › </tspan><tspan fill="#a99bae">R 10M</tspan><tspan> </tspan><tspan fill="#aee5c5">CH 99.8%</tspan><tspan fill="#716879"> › </tspan><tspan fill="#aee5c5" font-weight="700">$ 0.204</tspan></text>
+  </g>
+</svg>

package/assets/readme/responsive.svg

@@ -0,0 +1,36 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="722" viewBox="0 0 1200 722" role="img" aria-labelledby="t d" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif">
+  <title id="t">Rinco Pi HUD width-aware footer layout</title>
+  <desc id="d">The same Pi session footer rendered at 72 and 56 columns. Groups wrap only at complete segment boundaries, so the Activity row keeps its tool counts together; continuation lines realign under the separator column; a segment that no longer fits is truncated with an ellipsis instead of splitting the numbers.</desc>
+  <rect width="1200" height="722" rx="26" fill="#0E0C15"/>
+  <g id="board-title">
+    <text x="56" y="56" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="18" letter-spacing="2.4" fill="#F2A7C6">WIDTH-AWARE LAYOUT</text>
+    <text x="56" y="96" font-size="30" font-weight="700" fill="#F5F2F8">Wrap between segments, shorten only what cannot fit</text>
+  </g>
+  <g id="panel-72">
+    <rect x="56" y="126" width="1088" height="208" rx="14" fill="#16131F" stroke="#2C2640"/>
+    <text x="80" y="149" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="18" fill="#A99BAE">render(72)</text>
+    <text x="1120" y="149" text-anchor="end" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="18" fill="#A99BAE">5 rows · continuations align</text>
+    <line x1="56" y1="160" x2="1144" y2="160" stroke="#2C2640"/>
+    <line x1="194" y1="160" x2="194" y2="334" stroke="#716879" stroke-dasharray="3 5" opacity="0.55"/>
+    <text x="80" y="190" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan> </tspan><tspan fill="#f2a7c6" font-weight="700">Project</tspan><tspan> </tspan><tspan fill="#716879"> › </tspan><tspan fill="#f2a7c6" font-weight="700">rinco-pi-hud</tspan><tspan fill="#716879"> › </tspan><tspan>on </tspan><tspan fill="#c7b8f5" font-weight="700">*</tspan><tspan> </tspan><tspan fill="#c7b8f5" font-weight="700">main</tspan><tspan fill="#716879"> › </tspan><tspan fill="#9fd3f2">via</tspan><tspan> </tspan><tspan fill="#AEE5C5" font-weight="700">node v24.18.0</tspan><tspan fill="#716879"> › </tspan><tspan fill="#f7eef8">linux</tspan></text>
+    <text x="80" y="220" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan> </tspan><tspan fill="#9fd3f2">Session</tspan><tspan> </tspan><tspan fill="#716879"> › </tspan><tspan fill="#9fd3f2">deepseek/deepseek-flash</tspan><tspan fill="#716879"> › </tspan><tspan fill="#efc3e6">Thinking level: max</tspan><tspan fill="#716879"> › </tspan><tspan fill="#efc3e6">Turn 3</tspan></text>
+    <text x="80" y="250" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan> </tspan><tspan fill="#efc3e6">Activity</tspan><tspan fill="#716879"> › </tspan><tspan fill="#aee5c5">Tool read × 30 write × 7 edit × 13 bash × 76</tspan><tspan fill="#716879"> › </tspan><tspan fill="#a99bae">Agent idle</tspan></text>
+    <text x="80" y="280" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan> </tspan><tspan fill="#aee5c5">Usage</tspan><tspan>   </tspan><tspan fill="#716879"> › </tspan><tspan fill="#aee5c5">[##--------] 17%/1.0M</tspan><tspan fill="#716879"> › </tspan><tspan fill="#a99bae">↑ 177k</tspan><tspan fill="#716879"> › </tspan><tspan fill="#a99bae">↓ 74k</tspan><tspan fill="#716879"> › </tspan><tspan fill="#a99bae">R 10M</tspan><tspan> </tspan><tspan fill="#aee5c5">CH 99.8%</tspan></text>
+    <text x="80" y="310" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan>         </tspan><tspan fill="#716879"> › </tspan><tspan fill="#aee5c5" font-weight="700">$ 0.204</tspan></text>
+  </g>
+  <g id="panel-56">
+    <rect x="56" y="368" width="1088" height="298" rx="14" fill="#16131F" stroke="#2C2640"/>
+    <text x="80" y="391" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="18" fill="#A99BAE">render(56)</text>
+    <text x="1120" y="391" text-anchor="end" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="18" fill="#A99BAE">8 rows · continuations align</text>
+    <line x1="56" y1="402" x2="1144" y2="402" stroke="#2C2640"/>
+    <line x1="194" y1="402" x2="194" y2="666" stroke="#716879" stroke-dasharray="3 5" opacity="0.55"/>
+    <text x="80" y="432" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan> </tspan><tspan fill="#f2a7c6" font-weight="700">Project</tspan><tspan> </tspan><tspan fill="#716879"> › </tspan><tspan fill="#f2a7c6" font-weight="700">rinco-pi-hud</tspan><tspan fill="#716879"> › </tspan><tspan>on </tspan><tspan fill="#c7b8f5" font-weight="700">*</tspan><tspan> </tspan><tspan fill="#c7b8f5" font-weight="700">main</tspan></text>
+    <text x="80" y="462" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan>         </tspan><tspan fill="#716879"> › </tspan><tspan fill="#9fd3f2">via</tspan><tspan> </tspan><tspan fill="#AEE5C5" font-weight="700">node v24.18.0</tspan><tspan fill="#716879"> › </tspan><tspan fill="#f7eef8">linux</tspan></text>
+    <text x="80" y="492" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan> </tspan><tspan fill="#9fd3f2">Session</tspan><tspan> </tspan><tspan fill="#716879"> › </tspan><tspan fill="#9fd3f2">deepseek/deepseek-flash</tspan></text>
+    <text x="80" y="522" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan>         </tspan><tspan fill="#716879"> › </tspan><tspan fill="#efc3e6">Thinking level: max</tspan><tspan fill="#716879"> › </tspan><tspan fill="#efc3e6">Turn 3</tspan></text>
+    <text x="80" y="552" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan> </tspan><tspan fill="#efc3e6">Activity</tspan><tspan fill="#716879"> › </tspan><tspan fill="#aee5c5">Tool read × 30 write × 7 edit × 13 bash × </tspan><tspan>…</tspan></text>
+    <text x="80" y="582" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan>         </tspan><tspan fill="#716879"> › </tspan><tspan fill="#a99bae">Agent idle</tspan></text>
+    <text x="80" y="612" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan> </tspan><tspan fill="#aee5c5">Usage</tspan><tspan>   </tspan><tspan fill="#716879"> › </tspan><tspan fill="#aee5c5">[##--------] 17%/1.0M</tspan><tspan fill="#716879"> › </tspan><tspan fill="#a99bae">↑ 177k</tspan><tspan fill="#716879"> › </tspan><tspan fill="#a99bae">↓ 74k</tspan></text>
+    <text x="80" y="642" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="20" xml:space="preserve"><tspan>         </tspan><tspan fill="#716879"> › </tspan><tspan fill="#a99bae">R 10M</tspan><tspan> </tspan><tspan fill="#aee5c5">CH 99.8%</tspan><tspan fill="#716879"> › </tspan><tspan fill="#aee5c5" font-weight="700">$ 0.204</tspan></text>
+  </g>
+</svg>

package/docs/CONTRIBUTING.md

@@ -22,17 +22,20 @@ Pi loads the TypeScript extension directly, so this project has no separate buil
 
 ## Available commands
 
-<!-- AUTO-GENERATED: package-scripts:start -->
-<!-- Source: package.json#scripts. Do not edit manually. -->
-
 | Command | Description |
 | --- | --- |
 | `npm test` | Run the complete Vitest suite once. |
 | `npm run test:watch` | Run Vitest in watch mode and retest when files change. |
 | `npm run typecheck` | Run TypeScript type checking with `tsc --noEmit`. |
+| `npm run lint` | Run ESLint over `extensions/` and `tests/`. |
+| `npm run lint:fix` | Run ESLint and apply its automatic fixes. |
+| `npm run format:check` | Check Prettier formatting for the TypeScript sources and the two config files. |
+| `npm run format` | Apply Prettier formatting to the same files. |
+| `npm run verify` | Run `format:check`, `typecheck`, `lint`, and `test`, in that order. |
 | `npm run pack:check` | Inspect the publishable package with `npm pack --dry-run` without publishing it. |
 
-<!-- AUTO-GENERATED: package-scripts:end -->
+This table mirrors `package.json#scripts`. Nothing in this repository generates it, so update it by hand
+when a script is added, renamed, or removed.
 
 ## Testing
 
@@ -47,7 +50,8 @@ npm run pack:check
 
 Tests live in `tests/`:
 
-- `zentui-status.test.ts` — Config counts, MCP status parsing, and extension status helpers.
+- `zentui-status.test.ts` — Config counts, MCP configuration counts, and extension status helpers.
+- `mcp-footer.test.ts` — MCP count rendering, segment controls, custom formats, and legacy third-party statuses.
 - `codex-usage.test.ts` — Codex payload normalization and model-specific quota formatting.
 - `footer-layout.test.ts` — Four-group categorized layout, segment wrapping, and narrow-width budget.
 - `footer-groups.test.ts` — Semantic Project, Session, Activity, and Usage segment ordering.
@@ -56,6 +60,7 @@ Tests live in `tests/`:
 - `model-switch-statusline.test.ts` — Model switch statusline integration.
 - `model-usage-refresh.test.ts` — Model usage refresh integration.
 - `token-switch-usage.test.ts` — Token Switch balance formatting.
+- `deepseek-balance.test.ts` — DeepSeek balance parsing, formatting, and query safety.
 
 When adding tests:
 
@@ -83,9 +88,7 @@ Follow the configured conventions:
 - Use TypeScript ESM and explicit types.
 - Use tab indentation, double quotes, and semicolons.
 - Keep extension lifecycle handling clear and release timers and UI state during `session_shutdown`.
-- Do not edit content enclosed by `AUTO-GENERATED` markers manually; regenerate it from the source identified in the marker.
-
-Do not add ignore rules, skip tests, or weaken types merely to bypass a check.
+- Do not add ignore rules, skip tests, or weaken types merely to bypass a check.
 
 ## Architecture notes
 
@@ -98,9 +101,14 @@ The HUD extension is organized into functional modules under `extensions/hud/`:
 - **`segments/`** — State collectors: Git, runtime, MCP, skills, projects, etc.
 - **`session/`** — Pi event registration, lifecycle generations, and live-context throttling.
 - **`state/`** — Shared footer state, telemetry reducer, and project-refresh controller.
-- **`telemetry/`** — Usage formatting, token switch, and Codex subscription client.
+- **`telemetry/`** — Usage formatting, provider balance probes, and Codex subscription client.
 - **`ui/`** — Icons and terminal style utilities.
 
+`assets/readme/` holds the README visuals. Both boards are generated, not drawn: `source/capture-footer.mts`
+runs the real `installFooter` render path over a checkout plus a real Pi session transcript, and
+`source/build-assets.mts` converts the ANSI rows into SVG. Regenerate them with `npx tsx` as described in
+the README instead of editing the `.svg` files by hand.
+
 Key conventions:
 
 - Keep composition in `index.ts`, Pi event listeners in `session/event-handlers.ts`, and avoid file reads or subprocesses in `render()`.

package/docs/README.zh-CN.md

@@ -2,49 +2,36 @@
 
 # Rinco Pi HUD
 
-**为 [Pi](https://github.com/earendil-works/pi) 打造的动态 HUD 脚注。**
+**为 [Pi](https://github.com/earendil-works/pi) 打造的实时状态脚注。** 项目、Git、会话、工具与费用状态分成四组，随你的操作即时更新。
 
 [![Pi package](https://img.shields.io/badge/Pi-package-F2A7C6?style=flat-square)](https://github.com/earendil-works/pi) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Tests](https://img.shields.io/badge/tests-Vitest-6E9F18?style=flat-square&logo=vitest&logoColor=white)](https://vitest.dev/) [![License](https://img.shields.io/badge/license-MIT-C7B8F5?style=flat-square)](../LICENSE)
 
-[功能](#功能) · [安装](#安装) · [使用](#使用) · [定制](#定制) · [开发](#开发)
+[安装](#安装) · [命令](#命令) · [显示什么](#显示什么) · [布局](#布局) · [开发](#开发)
 
 [English](../README.md)
 
 </div>
 
-Rinco Pi HUD 为 Pi TUI 会话提供丰富的实时状态脚注，可显示项目状态、Git 指标、运行时版本、会话活动、模型用量、Token 费用等信息，支持响应式四分组布局或可定制的单行布局。Pi 可直接加载 TypeScript 扩展，无需构建步骤（`tsconfig.json` 设置了 `noEmit: true`，仅用于 `npm run typecheck` 类型检查）。
+<p align="center">
+  <img src="../assets/readme/hero.svg" width="100%" alt="Rinco Pi HUD 在 Pi 中的实际脚注：Project 行显示目录、Git 分支与 Node 版本，Session 行显示 Provider 与模型，Activity 行显示工具调用计数，Usage 行显示 Context 窗口、Token、缓存命中率与费用。">
+</p>
 
-## 功能
-
-- **Project state**：当前目录、Git 分支、Commit、Tag、工作区状态、Git 操作状态、差异指标和运行时版本。
-- **Session activity**：模型、Provider、Context 用量、可独立控制的输入/输出 Token、缓存、会话费用、轮次和 Thinking 等级。
-- **Tool and agent activity**：可分别控制正在运行的 Tool、已完成 Tool 计数、活跃 Agent、空闲状态、Skill 和 MCP Server 状态。
-- **Model quota**：根据当前模型自动切换 Codex 周限额或 Token Switch 余额。
-- **Git awareness**：分支、Detached HEAD、Tag、Ahead/Behind、Stash、合并冲突和脏状态。
-- **Runtime detection**：支持 Node、Python、Go、Rust、Java 等 60+ 运行时，并解析项目清单版本。
-- **Configurable layout**：默认使用响应式 Project、Session、Activity、Usage 四分组布局，或完全自定义的单行模板。
-- **Granular status controls**：可在 `/zentui` 中分别控制 Git 操作状态、Tool 运行状态/计数、Agent 活跃/空闲状态及输入/输出 Token。
-- **Extension statuses**：读取第三方扩展发布的状态，按配置的位置和颜色模式显示。
-- **Safe fallback**：超时和错误处理优雅，会话关闭后不留过期数据。
+Rinco Pi HUD 用四组实时状态替换 Pi 的脚注行，不需要的部分都能单独关掉。Pi 直接加载 TypeScript 扩展，没有构建步骤：`tsconfig.json` 设了 `noEmit: true`，只服务于 `npm run typecheck`。
 
 ## 安装
 
-### 从 npm 安装（推荐）
-
 ```bash
 pi install npm:rinco-pi-hud
 ```
 
-该包已发布至 [npm](https://www.npmjs.com/package/rinco-pi-hud)。
+装完重启 Pi，或执行 `/reload`。脚注默认启用，`/zentui` 打开设置界面。
 
-### 从 GitHub 安装
+从 GitHub 或本地目录安装：
 
 ```bash
 pi install git:github.com/Rinisnotarobot/rinco-pi-hud
 ```
 
-### 从本地目录安装
-
 ```bash
 git clone https://github.com/Rinisnotarobot/rinco-pi-hud.git
 cd rinco-pi-hud
@@ -54,36 +41,64 @@ pi install "$PWD"
 > [!IMPORTANT]
 > Pi 扩展以当前用户权限运行。安装任何第三方扩展前，请先审查其源码。
 
-## 使用
+> [!NOTE]
+> 脚注需要支持 Truecolor 的终端。上图用的是 ASCII 图标模式，`/zentui` 可以在 `auto`、`nerd`、`ascii` 三套符号之间切换。
 
-安装后重启 Pi，或执行：
+## 命令
 
-```text
-/reload
-```
+| 命令 | 作用 |
+| --- | --- |
+| `/zentui` | 设置界面：行、状态段、分隔符、图标、颜色、模板 |
+| `/zentui statusline enable\|disable\|toggle` | 显示或隐藏整个脚注 |
+| `/zentui row project\|session\|activity\|usage <enable\|disable\|toggle>` | 开关某一行 |
+| `/zentui format "<template>"` | 用单行模板替换四行布局 |
+| `/codex-status` | 打印 Codex 订阅用量与限额窗口 |
+| `/usage-refresh` | 立即刷新脚注上的模型用量或余额 |
+
+## 显示什么
+
+| 行 | 状态段。每段在 `/zentui` 的 **Built-in segments** 里都有独立开关 |
+| --- | --- |
+| **Project** | 目录、Git 分支、Commit 与 Tag、工作区状态、Git 操作状态（`MERGING`、`REBASING` 等）、差异指标、运行时、包版本、OS、用户 |
+| **Session** | 会话名称、Provider 与模型、Thinking 等级、轮次、会话时长 |
+| **Activity** | 正在运行的 Tool、已完成 Tool 计数、活跃 Agent、`Agent idle`、Skill、MCP Server |
+| **Usage** | Context 窗口与进度条、输入/输出 Token、缓存读写量与命中率、费用、模型限额、时间 |
+
+行用 `/zentui row usage disable` 开关；行内每个状态段在同一界面里各有开关。使用旧版聚合开关 `tokens`、`toolActivity`、`agentActivity` 的配置会自动迁移。
+
+### 模型限额
+
+Usage 行跟随当前模型的 Provider：
+
+- **openai-codex**：ChatGPT 订阅限额与重置额度，优先走 Pi 认证，失败时回落到 `codex app-server`。显示形如 `codex 60% 5h (14:30) 75% wk`，窗口跨天时重置时间变成 `14:30 12 Feb`。
+- **token-switch**：从 `TOKEN_SWITCH_API_KEY` 环境变量读取账单余额，显示形如 `token-switch $750.00`。
+- **deepseek**：用 Pi 为 deepseek 供应商保存的凭据（`/login` 写入的，或 `DEEPSEEK_API_KEY`）查询 DeepSeek 余额接口，显示形如 `deepseek ¥110.00`；账户同时有 CNY 和 USD 时优先显示 CNY。
 
-HUD 脚注默认启用。运行 `/zentui` 打开交互式设置。
+这些查询超时 15 秒、缓存 5 分钟，`/usage-refresh` 可以立即刷新当前生效的那一个。
 
-### 常用命令
+## 布局
+
+<p align="center">
+  <img src="../assets/readme/responsive.svg" width="100%" alt="同一个脚注在 72 列和 56 列终端下的渲染：行只在状态段边界换行，续行在分隔符列对齐，放不下的工具计数状态段用省略号截断，其后的状态段照常显示。">
+</p>
+
+分组只在状态段边界换行。续行重新对齐到分隔符列下方，放不下的状态段用 `…` 截断，而不是把后面的状态段挤出这一行。
+
+想换成单行脚注，设置模板即可：
 
 ```text
-/zentui statusline enable
-/zentui statusline disable
-/zentui statusline toggle
-/zentui row project toggle
-/zentui row session disable
-/zentui row activity enable
-/zentui row usage toggle
-/zentui format clear
-/zentui format "$model · $context · $cost · $git_branch( $git_commit) · $session_duration"
-/codex-status
-/usage-refresh
+/zentui format "$cwd( $git_branch)$fill($context)( $tokens)( $cost)"
 ```
 
-> [!NOTE]
-> 最佳显示效果需要支持 Truecolor 的终端和 Nerd Font。脚注使用 Unicode 符号，需要合适的字体支持。
+变量可以写成 `$name` 或 `${name}`。[脚注参考](footer.md)列出了全部变量和别名（`$directory`、`$status`、`$codex` 等）。不带参数的 `/zentui format`（或 `/zentui format clear`）恢复四行分组布局。
+
+## 配置
+
+`/zentui` 把配置写入 `~/.pi/agent/rinco-pi-hud.json`，改动立即生效。可配置分隔符样式、图标模式（`nerd`、`ascii`、`auto`）、脚注配色（Pi 主题色或终端调色板样式）、Context 渲染方式（文本、进度条或两者）、项目刷新间隔，以及第三方扩展状态的位置与颜色模式。
 
-## 包含内容
+完整的变量与状态段参考见 [docs/footer.md](footer.md)。
+
+## 仓库结构
 
 | 路径 | 说明 |
 | --- | --- |
@@ -91,119 +106,66 @@ HUD 脚注默认启用。运行 `/zentui` 打开交互式设置。
 | [`extensions/hud/config/`](../extensions/hud/config/config.ts) | 配置模型、归一化、迁移与持久化 |
 | [`extensions/hud/footer/`](../extensions/hud/footer/index.ts) | 脚注渲染、语义分组、响应式布局与模板解析 |
 | [`extensions/hud/segments/`](../extensions/hud/segments/) | 状态采集器：Git、运行时、MCP、Skill、项目等 |
-| [`extensions/hud/telemetry/`](../extensions/hud/telemetry/format.ts) | 用量格式化、Token Switch 与 Codex 订阅客户端 |
+| [`extensions/hud/telemetry/`](../extensions/hud/telemetry/format.ts) | 用量格式化、各家余额探测与 Codex 订阅客户端 |
 | [`extensions/hud/session/`](../extensions/hud/session/) | Pi 事件注册、会话生命周期与实时 Context 覆盖 |
 | [`extensions/hud/state/`](../extensions/hud/state/) | 聚合状态、Telemetry Reducer 与项目刷新 Controller |
 | [`extensions/hud/commands/`](../extensions/hud/commands/settings.ts) | `/zentui` 设置界面与配置 Controller |
 | [`extensions/hud/ui/`](../extensions/hud/ui/) | 图标与终端样式工具 |
 | [`docs/footer.md`](footer.md) | 完整脚注配置参考 |
 | [`docs/CONTRIBUTING.md`](CONTRIBUTING.md) | 本地开发、测试规范和 PR 检查清单 |
-| [`tests/`](../tests/) | Vitest 测试套件（41 个测试用例，8 个文件） |
-
-## 定制
-
-### 布局
-
-默认布局将信息分为 Project、Session、Activity 和 Usage 四组；超长分组会在完整状态项边界处换行，并保持续行对齐。设置 `footerFormat` 模板字符串可切换为单行布局：
-
-```text
-/zentui format "$cwd( $git_branch)$fill($context)( $tokens)( $cost)"
-```
-
-模板变量使用 `$name` 或 `${name}` 语法。完整变量列表见[脚注参考](footer.md)。
-
-### 状态段
-
-运行 `/zentui` 并进入 **Built-in segments**，即可启用或禁用单个状态：
-
-| 分组 | 可独立控制的状态 |
-| --- | --- |
-| Project | Git 状态、Git 操作状态（`MERGING`、`REBASING` 等）、Commit、差异指标、运行时、包版本、OS 和用户 |
-| Session | 模型、Thinking 等级、轮次和会话时长 |
-| Activity | 正在运行的 Tool、已完成 Tool 计数、活跃 Agent、`Agent idle`、Skill 和 MCP |
-| Usage | Context、输入 Token、输出 Token、缓存详情/命中率、费用、限额和时间 |
-
-使用旧版聚合开关 `tokens`、`toolActivity` 或 `agentActivity` 的配置会自动迁移。仍可通过 `/zentui statusline enable|disable|toggle` 控制整个脚注。
-
-默认四行布局中的每个语义行也可以通过命令单独控制：
-
-```text
-/zentui row <project|session|activity|usage> <enable|disable|toggle>
-```
-
-行开关会持久化到 `footerRows`。使用自定义单行 `footerFormat` 时，这些开关不生效。
-
-### 扩展状态
-
-第三方扩展发布的状态可由 HUD 脚注显示。可为每个扩展状态键配置位置（`left`、`middle`、`right`、`off`）和颜色模式（`zentui`、`original`）。
+| [`tests/`](../tests/) | Vitest 测试套件：脚注布局、遥测、各家余额与 MCP 配置计数 |
 
 ## 开发
 
-### 环境要求
-
-- [Node.js](https://nodejs.org/) 22.19 或更高版本
-- [Pi](https://github.com/earendil-works/pi)
-
-安装开发依赖：
+需要 Node.js 22.19 或更高版本，以及 [Pi](https://github.com/earendil-works/pi) 本身。
 
 ```bash
 npm install
+npm test          # Vitest 测试套件
+npm run typecheck # tsc --noEmit
+npm run verify    # 格式、类型、Lint、测试
 ```
 
-### 可用命令
-
-<!-- AUTO-GENERATED: package-scripts:start -->
-<!-- Source: package.json#scripts. Do not edit manually. -->
-
-| 命令 | 说明 |
-| --- | --- |
-| `npm test` | 使用 Vitest 运行一次完整测试套件。 |
-| `npm run test:watch` | 以监听模式运行 Vitest，并在文件变化后重新测试。 |
-| `npm run typecheck` | 使用 `tsc --noEmit` 运行 TypeScript 类型检查。 |
-| `npm run pack:check` | 使用 `npm pack --dry-run` 检查发布包内容，不生成正式发布。 |
-
-<!-- AUTO-GENERATED: package-scripts:end -->
-
-运行测试：
+全部脚本定义在 [`package.json`](package.json) 里，完整清单（含 `lint`、`format`、`test:watch`）见 [docs/CONTRIBUTING.md](CONTRIBUTING.md)。
 
-```bash
-npm test
-```
+### README 图片
 
-类型检查：
+上面两张图不是手绘的，而是从真实脚注渲染结果生成的。`assets/readme/source/capture-footer.mts` 用扩展自己的 `installFooter` 渲染路径跑本仓库的状态和一份真实 Pi 会话记录，`build-assets.mts` 再把 ANSI 文本转成 SVG：
 
 ```bash
-npm run typecheck
+npx tsx assets/readme/source/capture-footer.mts . ~/.pi/agent/sessions/<session>.jsonl 118 72 56 > /tmp/footer.json
+npx tsx assets/readme/source/build-assets.mts /tmp/footer.json
 ```
 
-验证格式、类型、Lint、测试与发布内容：
-
-```bash
-npm run verify
-npm run pack:check
-```
+## 常见问题
 
-本项目使用 Vitest 测试脚注布局、遥测、Codex 用量、Token Switch、配置统计和 MCP 状态解析。Pi 运行时会直接加载 TypeScript 源码，因此没有单独的构建命令。
+<details>
+<summary>脚注没有显示</summary>
 
-## 常见问题
+确认当前运行在 Pi TUI 模式，而不是 Headless、JSON 或 Print 模式。然后执行 `/reload`，并用 `pi list` 确认包已安装。
+</details>
 
-### 脚注没有显示
+<details>
+<summary>窄终端里布局看起来不对</summary>
 
-1. 确认当前运行在 Pi TUI 模式，而不是 Headless、JSON 或 Print 模式。
-2. 执行 `/reload` 或重启 Pi。
-3. 使用 `pi list` 确认包已安装。
+脚注会测量终端宽度，只在状态段边界换行，所以窗口越窄，每行容纳的状态段越少。可以设置 `footerFormat` 模板，或在 `/zentui` 中关闭低优先级状态段。
+</details>
 
-### 脚注布局异常
+<details>
+<summary>颜色显示异常</summary>
 
-脚注会自动检测终端宽度并截断内容。在窄终端中，部分状态段可能被裁剪。可通过设置自定义 `footerFormat` 模板调整布局，或在 `/zentui` 中关闭低优先级段。
+默认配色输出 `38;2;r;g;b` Truecolor 序列，不支持 Truecolor 的终端会近似处理或直接忽略。
+</details>
 
-### 颜色显示异常
+<details>
+<summary>图标缺失或错位</summary>
 
-确认终端已启用 Truecolor。脚注使用 `38;2;r;g;b` ANSI 序列。
+Unicode 与 Nerd Font 符号的显示效果因终端和字体而异。建议安装 Nerd Font，或在 `/zentui` 中切换到 ASCII 图标。
+</details>
 
-### Unicode 图标缺失或错位
+## 许可证
 
-Unicode 和 Nerd Font 符号的显示效果因终端和字体而异。建议安装 Nerd Font，或在 `/zentui` 中切换到 ASCII 图标模式。
+MIT，详见 [`LICENSE`](../LICENSE)。
 
 ## 第三方许可证
 
@@ -216,4 +178,4 @@ Unicode 和 Nerd Font 符号的显示效果因终端和字体而异。建议安
 - **pi-codex-usage**（narumiruna）— MIT 许可。`extensions/hud/telemetry/codex-usage/` 下的 Codex 用量客户端衍生自该项目。  
   源码：https://github.com/narumiruna/pi-codex-usage
 
-详见 [NOTICE](../NOTICE)。
+详见 [NOTICE](../NOTICE)。

package/docs/footer.md

@@ -7,10 +7,12 @@ When `footerFormat` is empty, the HUD displays four semantic groups:
 ```text
 Project  · pi-sakura ·  main ·  24.18
 Session  · gpt-5.3 · Thinking level: high · Turn 8
-Activity · Agent idle · Skill 2/3 · MCP 2/2
+Activity · Agent idle · Skill 2/3 · MCP 2
 Usage    · 35%/200k · ↑ 4.2k · ↓ 1.1k · $ 0.030
 ```
 
+The MCP segment counts server entries in Pi's agent-directory `mcp.json` and the project's `.pi/mcp.json`. Same-name entries count once; disabled entries are included. Zero entries hide the segment. Counts refresh with the project state polling interval. This does not report connection state, validate individual server settings, or include servers registered dynamically by extensions. Missing, unreadable, malformed, or larger-than-1-MiB files contribute no entries. Legacy adapter footer statuses remain ordinary third-party statuses.
+
 The category column is sized from visible text so every separator aligns. When a row exceeds the terminal width, complete status segments move to an indented continuation line. Only a single segment that is wider than the available content area is truncated. Third-party extension statuses appear on the Activity group in configured `left`, `middle`, then `right` order.
 
 Control each default-layout row independently:
@@ -50,7 +52,7 @@ The command shape is `/zentui row <project|session|activity|usage> <enable|disab
 | `activeAgents` | on | Activity | Active primary agent runs |
 | `agentIdle` | on | Activity | `Agent idle` when no primary agent run is active |
 | `skills` | on | Activity | Active/available skills count, e.g. `Skill 1/3` |
-| `mcp` | on | Activity | MCP connected/total servers |
+| `mcp` | on | Activity | File-configured MCP servers, e.g. `MCP 2` |
 | `context` | on | Usage | Context percentage, window size, and/or gauge |
 | `inputTokens` | on | Usage | Cumulative input tokens |
 | `outputTokens` | on | Usage | Cumulative output tokens |
@@ -119,7 +121,7 @@ Clear it:
 | `$skills` | Active/available skills, e.g. `Skill 1/3` |
 | `$active_skills` | Active skills count only |
 | `$extensions` | Installed Pi packages count |
-| `$mcp` | MCP connected/total |
+| `$mcp` | File-configured MCP server count |
 | `$tool_counts` | Native tool completion counts |
 | `$running_tools` | Recently running tools |
 | `$active_agents` | Active primary agent runs |
@@ -151,5 +153,6 @@ The status line automatically switches quota display based on model provider:
 
 - **openai-codex**: Uses Pi Model Registry's Codex Auth to query ChatGPT usage endpoint; falls back to `codex app-server --listen stdio://`. Shows the remaining 5h window with its reset time plus the weekly limit percentage, e.g. `codex 60% 5h (14:30) 75% wk` (the reset stamp becomes `14:30 12 Feb` when the window rolls over on a later day).
 - **token-switch**: Uses `TOKEN_SWITCH_API_KEY` environment variable to query billing subscription and usage. Shows available balance, e.g. `token-switch $750.00`.
+- **deepseek**: Uses the credential Pi holds for the DeepSeek provider (the one `/login` stores for `deepseek`, or `DEEPSEEK_API_KEY`) to query `https://api.deepseek.com/user/balance`. Shows the total balance, preferring CNY when the account reports several currencies, e.g. `deepseek ¥110.00`. A balance query without a usable key reads as `balance error` in the footer.
 
-Both queries use 15-second timeout, 5-minute cache, and auto-refresh. Switching models via `/model` forces a refresh.
+All queries use a 15-second timeout, a 5-minute cache, and auto-refresh. Switching models via `/model` forces a refresh, and `/usage-refresh` refreshes whichever probe currently owns the row.

package/extensions/hud/commands/settings.ts

@@ -133,7 +133,7 @@ const footerSegmentSettingLabels: Record<FooterSegmentSettingId, string> = {
 	activeAgents: "Active agents",
 	agentIdle: "Agent idle status",
 	skills: "Skill activity",
-	mcp: "MCP connections",
+	mcp: "MCP configured servers",
 	context: "Context usage",
 	inputTokens: "Input tokens",
 	outputTokens: "Output tokens",
@@ -173,7 +173,7 @@ const footerSegmentSettingDescriptions: Record<FooterSegmentSettingId, string> =
 	codexUsage: "Show OpenAI Codex subscription rate limits on the usage row when available.",
 	configCounts: "Show instruction-file and installed Pi package counts on the project row.",
 	skills: "Show active/available Pi skill counts on the activity row.",
-	mcp: "Show parsed MCP connected/total server counts on the activity row.",
+	mcp: "Show the configured server count from global and project mcp.json, including disabled entries.",
 	runningTools: "Show currently running native tools and their elapsed time.",
 	toolCounts: "Show cumulative completed native-tool counts.",
 	activeAgents: "Show active main agent runs on the activity row (not subagent count).",

package/extensions/hud/config/config-counts.ts

@@ -1,6 +1,7 @@
 import { createRequire } from "node:module";
 import { readFileSync, statSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
+import { countConfiguredMcpServers } from "../segments/mcp-status.js";
 
 export interface ConfigCounts {
 	instructionFiles: {
@@ -9,6 +10,7 @@ export interface ConfigCounts {
 		total: number;
 	};
 	packages: number;
+	mcpServers: number;
 }
 
 export interface ConfigCountOptions {
@@ -82,6 +84,7 @@ export function countConfigEntries(cwd: string, options: ConfigCountOptions = {}
 			total: agentsMd + claudeMd,
 		},
 		packages: countPackages(agentDir),
+		mcpServers: countConfiguredMcpServers(cwd, agentDir),
 	};
 }
 

package/extensions/hud/footer/index.ts

@@ -31,7 +31,6 @@ import {
 } from "../telemetry/format.js";
 import { resolveRuntimeSymbol } from "../ui/icons.js";
 import type { LiveContextOverride } from "../session/live-context.js";
-import { parseMcpStatus } from "../segments/mcp-status.js";
 import type { FooterState } from "../state/index.js";
 import { renderStyleForSource } from "../ui/style.js";
 
@@ -74,7 +73,6 @@ export function installFooter(
 				const colorSource = config.colorSources.starship;
 				const iconMode = config.icons.mode;
 				const rawExtensionStatuses = footerData.getExtensionStatuses();
-				const mcpStatus = parseMcpStatus(rawExtensionStatuses.get("mcp"));
 				const { safeCwd, safeRuntime, safePackageVersion, safeCommit } = sanitizeFooterInputs(
 					ctx,
 					state,
@@ -166,7 +164,7 @@ export function installFooter(
 					runningToolsLabel,
 					activeAgentsLabel,
 					agentIdleLabel,
-				} = buildTelemetryLabels(ctx, state, config, theme, colorSource, mcpStatus);
+				} = buildTelemetryLabels(ctx, state, config, theme, colorSource);
 				const renderVariable = (name: string): string => {
 					const canonical = FOOTER_FORMAT_ALIASES[name] ?? name;
 					switch (canonical) {
@@ -439,14 +437,7 @@ export function installFooter(
 							formatTimeLabel(""),
 						)}`
 					: "";
-				const formatNeedsMcp = /\$\{?mcp\b/.test(config.footerFormat);
-				const dedicatedMcpVisible = Boolean(
-					mcpStatus && (config.footerFormat ? formatNeedsMcp : config.footerSegments.mcp),
-				);
-				const extensionStatusSource = dedicatedMcpVisible
-					? new Map([...rawExtensionStatuses].filter(([key]) => key !== "mcp"))
-					: rawExtensionStatuses;
-				const extensionStatuses = collectExtensionStatusSegments(extensionStatusSource, config);
+				const extensionStatuses = collectExtensionStatusSegments(rawExtensionStatuses, config);
 				const renderExtensionStatus = (segment: ExtensionStatusSegment) =>
 					segment.colorMode === "original"
 						? segment.text

package/extensions/hud/footer/render-labels.ts

@@ -11,7 +11,6 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { ColorSource, PolishedTuiConfig } from "../config/config.js";
-import type { McpStatus } from "../segments/mcp-status.js";
 import { formatSkillCounts } from "../segments/skill-activity.js";
 import type { FooterState } from "../state/index.js";
 import { getTelemetryStats } from "../state/telemetry.js";
@@ -164,7 +163,6 @@ export function buildTelemetryLabels(
 	config: PolishedTuiConfig,
 	theme: ThemeLike,
 	colorSource: ColorSource,
-	mcpStatus: McpStatus | undefined,
 ): TelemetryLabels {
 	const statusStyle = (style: string, text: string) =>
 		text ? renderStyleForSource(theme, colorSource, style, text) : "";
@@ -267,9 +265,10 @@ export function buildTelemetryLabels(
 			: "";
 	const configCountsLabel = [instructionFilesLabel, extensionsLabel].filter(Boolean).join(" ");
 
-	const mcpLabel = mcpStatus
-		? statusStyle(config.colors.gitStatus, `MCP ${mcpStatus.connected}/${mcpStatus.total}`)
-		: "";
+	const mcpLabel =
+		state.configCounts.mcpServers > 0
+			? statusStyle(config.colors.gitStatus, `MCP ${state.configCounts.mcpServers}`)
+			: "";
 
 	const telemetryStats = getTelemetryStats(state.telemetry);
 	const toolCountsText = Object.entries(telemetryStats.completedToolCounts)

package/extensions/hud/segments/mcp-status.ts

@@ -1,26 +1,31 @@
-import { stripVTControlCharacters } from "node:util";
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
 
-export interface McpStatus {
-	connected: number;
-	total: number;
+const MAX_CONFIG_BYTES = 1024 * 1024;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-/** Parses the adapter's public status text without intercepting or modifying UI methods. */
-export function parseMcpStatus(text: string | undefined): McpStatus | undefined {
-	if (typeof text !== "string" || text.length === 0) return undefined;
-	const status = stripVTControlCharacters(text.slice(0, 2048));
-	const enabledMatch = status.match(
-		/MCP:\s*(\d{1,5})\s+servers?\s+enabled(?:\s*\(\s*(\d{1,5})\s+connected\s*\))?(?:\s*\(\s*(\d{1,5})\s+disabled\s*\))?\s*$/i,
-	);
-	const legacyMatch = status.match(/MCP:\s*(\d{1,5})\s*\/\s*(\d{1,5})\s+servers\b/i);
-	if (!enabledMatch && !legacyMatch) return undefined;
-	const connected = Number(enabledMatch ? (enabledMatch[2] ?? 0) : legacyMatch![1]);
-	const total = Number(enabledMatch ? enabledMatch[1] : legacyMatch![2]);
-	const disabled = enabledMatch?.[3] === undefined ? 0 : Number(enabledMatch[3]);
-	if (![connected, total, disabled].every(Number.isSafeInteger)) return undefined;
-	if (connected < 0 || total < 0 || connected > total || total > 10_000 || disabled > 10_000)
-		return undefined;
-	return { connected, total };
+function readServerNames(path: string): string[] {
+	try {
+		const stats = statSync(path);
+		if (!stats.isFile() || stats.size > MAX_CONFIG_BYTES) return [];
+		const config: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (!isRecord(config) || !isRecord(config.mcpServers)) return [];
+		return Object.entries(config.mcpServers)
+			.filter(([name, entry]) => /^[A-Za-z0-9_-]+$/.test(name) && isRecord(entry))
+			.map(([name]) => name);
+	} catch {
+		return [];
+	}
 }
 
-export const parseMcpAdapterStatus = parseMcpStatus;
+/** Count file-configured server entries, including disabled ones, without resolving secrets
+ * or starting connections. Project entries override global entries with the same name.
+ * This is not a connection count or a validation of individual server settings. */
+export function countConfiguredMcpServers(cwd: string, agentDir: string): number {
+	const globalNames = agentDir ? readServerNames(join(agentDir, "mcp.json")) : [];
+	const projectNames = readServerNames(join(cwd, ".pi", "mcp.json"));
+	return new Set([...globalNames, ...projectNames]).size;
+}

package/extensions/hud/state/index.ts

@@ -42,6 +42,7 @@ export function createInitialState(gitDefaults: GitStatusSummary): FooterState {
 		configCounts: {
 			instructionFiles: { agentsMd: 0, claudeMd: 0, total: 0 },
 			packages: 0,
+			mcpServers: 0,
 		},
 		skillCounts: undefined,
 		codexUsageStatus: undefined,

package/extensions/hud/telemetry/codex-usage/index.ts

@@ -5,6 +5,13 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { formatCodexUsageStatusline, formatQueryErrors, showReport } from "./format.ts";
 import { isOpenAICodexModel, isStaleExtensionContextError, queryUsage } from "./query.ts";
+import {
+	DEEPSEEK_PROVIDER_ID,
+	formatDeepSeekBalance,
+	isDeepSeekModel,
+	queryDeepSeekBalance,
+	type DeepSeekBalance,
+} from "../deepseek-balance.ts";
 import {
 	formatTokenSwitchBalance,
 	isTokenSwitchModel,
@@ -28,6 +35,11 @@ interface CommandArgumentCompletion {
 	description?: string;
 }
 
+/** Providers whose statusline is an account balance rather than a rate-limit window. */
+function isBalanceProviderModel(model: Pick<CodexUsageModel, "provider"> | undefined): boolean {
+	return isTokenSwitchModel(model) || isDeepSeekModel(model);
+}
+
 /** Provider-specific hooks driving the shared usage-statusline refresh pipeline. */
 interface UsageProbe<T> {
 	readCache: () => { createdAt: number; value: T } | undefined;
@@ -59,6 +71,7 @@ export default function registerCodexUsage(
 ) {
 	let cache: CachedReport | undefined;
 	let tokenSwitchCache: { createdAt: number; balance: number } | undefined;
+	let deepSeekCache: { createdAt: number; balance: DeepSeekBalance } | undefined;
 	let statuslineClearTimer: ReturnType<typeof setTimeout> | undefined;
 	let statuslineRefreshTimer: ReturnType<typeof setTimeout> | undefined;
 	let statuslineRequestId = 0;
@@ -92,6 +105,19 @@ export default function registerCodexUsage(
 		}
 	};
 
+	// The DeepSeek balance rides on the credential Pi already holds for the
+	// provider, so a model switched in via /login works without extra setup.
+	const runDeepSeekQuery = async (ctx: ExtensionContext, timeoutMs: number) => {
+		const apiKey = await ctx.modelRegistry.getApiKeyForProvider(DEEPSEEK_PROVIDER_ID);
+		const controller = new AbortController();
+		activeQueries.add(controller);
+		try {
+			return await queryDeepSeekBalance({ apiKey, timeoutMs, signal: controller.signal });
+		} finally {
+			activeQueries.delete(controller);
+		}
+	};
+
 	const clearStatuslineTimers = () => {
 		if (statuslineClearTimer) clearTimeout(statuslineClearTimer);
 		if (statuslineRefreshTimer) clearTimeout(statuslineRefreshTimer);
@@ -235,6 +261,23 @@ export default function registerCodexUsage(
 		activeStatuslineContext = ctx;
 		const selectedModel = model ?? ctx.model;
 
+		if (isDeepSeekModel(selectedModel)) {
+			await refreshUsageStatusline<DeepSeekBalance>(ctx, force, {
+				readCache: () =>
+					deepSeekCache
+						? { createdAt: deepSeekCache.createdAt, value: deepSeekCache.balance }
+						: undefined,
+				writeCache: (balance) => {
+					deepSeekCache = { createdAt: Date.now(), balance };
+				},
+				query: () => runDeepSeekQuery(ctx, DEFAULT_TIMEOUT_MS),
+				render: formatDeepSeekBalance,
+				pendingLabel: "checking balance",
+				errorLabel: "balance error",
+			});
+			return;
+		}
+
 		if (isTokenSwitchModel(selectedModel)) {
 			await refreshUsageStatusline<number>(ctx, force, {
 				readCache: () =>
@@ -284,9 +327,9 @@ export default function registerCodexUsage(
 				return;
 			}
 
-			// On a Token Switch model the statusline belongs to the balance probe, so the
-			// Codex report is shown without overwriting it.
-			const useStatusline = options.value.statusline && !isTokenSwitchModel(ctx.model);
+			// On a balance provider the statusline belongs to that probe, so the Codex
+			// report is shown without overwriting it.
+			const useStatusline = options.value.statusline && !isBalanceProviderModel(ctx.model);
 
 			const cached = cache && Date.now() - cache.createdAt < CACHE_TTL_MS ? cache : undefined;
 			if (cached && !options.value.refresh) {
@@ -338,7 +381,7 @@ export default function registerCodexUsage(
 		description: "Refresh the model usage or balance shown in the footer now",
 		handler: async (_args, ctx) => {
 			// Refresh whichever probe owns the statusline for the active provider.
-			if (isTokenSwitchModel(ctx.model)) {
+			if (isBalanceProviderModel(ctx.model)) {
 				await refreshCurrentUsageStatusline(ctx, true).catch(rethrowUnlessStaleContextError(ctx));
 				return;
 			}
@@ -353,6 +396,7 @@ export default function registerCodexUsage(
 		clearStatuslineTimers();
 		cache = undefined;
 		tokenSwitchCache = undefined;
+		deepSeekCache = undefined;
 		activeStatuslineContext = undefined;
 		sessionActive = true;
 		void refreshCurrentUsageStatusline(ctx, false, ctx.model).catch(

package/extensions/hud/telemetry/deepseek-balance.ts

@@ -0,0 +1,128 @@
+export const DEEPSEEK_PROVIDER_ID = "deepseek";
+const DEEPSEEK_BALANCE_URL = "https://api.deepseek.com/user/balance";
+const MAX_RESPONSE_BODY_BYTES = 64 * 1024;
+
+// DeepSeek reports one entry per currency; CNY is the default top-up currency,
+// so an account holding both reads out its CNY balance.
+const PREFERRED_CURRENCY = "CNY";
+const CURRENCY_SYMBOLS: Record<string, string> = { CNY: "¥", USD: "$" };
+
+export type DeepSeekModel = { provider: string };
+
+export type DeepSeekBalance = { amount: number; currency: string };
+
+type QueryDeepSeekBalanceOptions = {
+	apiKey?: string;
+	fetchImpl?: typeof fetch;
+	timeoutMs: number;
+	signal?: AbortSignal;
+};
+
+export function isDeepSeekModel(model: Pick<DeepSeekModel, "provider"> | undefined): boolean {
+	return model?.provider === DEEPSEEK_PROVIDER_ID;
+}
+
+export function parseDeepSeekBalance(payload: unknown): DeepSeekBalance {
+	const infos = readBalanceInfos(payload);
+	return infos.find((info) => info.currency === PREFERRED_CURRENCY) ?? infos[0]!;
+}
+
+export function formatDeepSeekBalance(balance: DeepSeekBalance): string {
+	const symbol = CURRENCY_SYMBOLS[balance.currency];
+	return symbol
+		? `deepseek ${symbol}${balance.amount.toFixed(2)}`
+		: `deepseek ${balance.amount.toFixed(2)} ${balance.currency}`;
+}
+
+export async function queryDeepSeekBalance({
+	apiKey,
+	fetchImpl = fetch,
+	timeoutMs,
+	signal,
+}: QueryDeepSeekBalanceOptions): Promise<DeepSeekBalance> {
+	if (!apiKey?.trim()) {
+		throw new Error(
+			"No DeepSeek API key is available. Use a DeepSeek model or run /login for DeepSeek.",
+		);
+	}
+
+	const controller = new AbortController();
+	const abortFromExternal = () => controller.abort();
+	if (signal?.aborted) controller.abort();
+	else signal?.addEventListener("abort", abortFromExternal, { once: true });
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+	try {
+		const response = await fetchImpl(DEEPSEEK_BALANCE_URL, {
+			method: "GET",
+			headers: {
+				Accept: "application/json",
+				Authorization: `Bearer ${apiKey}`,
+			},
+			redirect: "error",
+			signal: controller.signal,
+		});
+		if (!response.ok) {
+			throw new Error(`DeepSeek balance endpoint returned HTTP ${response.status}.`);
+		}
+
+		const text = await response.text();
+		if (Buffer.byteLength(text, "utf8") > MAX_RESPONSE_BODY_BYTES) {
+			throw new Error("DeepSeek balance response exceeded the size limit.");
+		}
+		let payload: unknown;
+		try {
+			payload = JSON.parse(text) as unknown;
+		} catch {
+			throw new Error("DeepSeek balance response was not valid JSON.");
+		}
+		return parseDeepSeekBalance(payload);
+	} catch (error) {
+		if (controller.signal.aborted) {
+			throw new Error(
+				signal?.aborted
+					? "DeepSeek balance query was cancelled."
+					: `Timed out after ${Math.round(timeoutMs / 1000)}s while fetching the DeepSeek balance.`,
+			);
+		}
+		throw error;
+	} finally {
+		clearTimeout(timeout);
+		signal?.removeEventListener("abort", abortFromExternal);
+	}
+}
+
+function readBalanceInfos(payload: unknown): DeepSeekBalance[] {
+	if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+		throw new Error("DeepSeek balance response did not contain balance_infos.");
+	}
+	const infos = (payload as Record<string, unknown>).balance_infos;
+	if (!Array.isArray(infos) || infos.length === 0) {
+		throw new Error("DeepSeek balance response did not contain balance_infos.");
+	}
+	return infos.map(parseBalanceInfo);
+}
+
+function parseBalanceInfo(entry: unknown, index: number): DeepSeekBalance {
+	const label = `balance_infos[${index}]`;
+	if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+		throw new Error(`DeepSeek ${label} was not an object.`);
+	}
+
+	const record = entry as Record<string, unknown>;
+	const currency = record.currency;
+	if (typeof currency !== "string" || !currency.trim()) {
+		throw new Error(`DeepSeek ${label}.currency was not a currency code.`);
+	}
+
+	const total = record.total_balance;
+	if (typeof total !== "string" || !total.trim()) {
+		throw new Error(`DeepSeek ${label}.total_balance was not a decimal string.`);
+	}
+	const amount = Number(total);
+	if (!Number.isFinite(amount)) {
+		throw new Error(`DeepSeek ${label}.total_balance was not a finite number.`);
+	}
+
+	return { amount, currency: currency.trim().toUpperCase() };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rinco-pi-hud",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "A dynamic HUD footer for Pi, ported from Sakura Zentui Footer.",
   "type": "module",
   "license": "MIT",
@@ -22,6 +22,7 @@
   "files": [
     "extensions",
     "docs",
+    "assets/readme/*.svg",
     "README.md",
     "LICENSE",
     "NOTICE"