fix(usage): separate subscription refresh from local refresh

README.ja.md

@@ -110,6 +110,7 @@ AI支援開発の時代において、**トークンは新しいエネルギー*
   - [Cursor IDEコマンド](#cursor-ideコマンド)
   - [Antigravity コマンド](#antigravity-コマンド)
   - [Trae コマンド](#trae-コマンド)
+  - [Subscription Usage](#subscription-usage)
   - [出力例](#出力例--lightバージョン)
   - [設定](#設定)
   - [環境変数](#環境変数)
@@ -263,7 +264,7 @@ tokscale models --json > report.json   # ファイルに保存
   - `v`: テーブル/プロフィールビューを切り替え（Hourly タブ）
   - `y`: 選択行をクリップボードにコピー
   - `p`: 9色テーマを循環
-  - `r`: データを更新; `Shift+R` で自動更新の切り替え; `+`/`-` で間隔調整
+  - `r`: ローカルレポートを更新; `Shift+R` でローカルレポートの自動更新を切り替え; `+`/`-` で間隔調整; `u` は Usage タブでのみサブスクリプション使用量を更新
   - `e`: JSONにエクスポート
   - `q` または `Ctrl+C`: 終了
 - **マウスサポート**: タブ、ボタン、フィルターをクリック
@@ -512,6 +513,23 @@ tokscale trae logout --variant solo
 
 > **中国版**: 中国版（`trae.com.cn`）は意図的に未対応です。CN バックエンドはセッション単位の使用量クエリ API を公開していません。上流で公式エンドポイントが提供された場合に追加します。
 
+### Subscription Usage
+
+`tokscale usage` は、明示的な CLI 操作として、利用可能な資格情報を持つ provider のサブスクリプション quota を取得します。
+
+TUI では `usageTabEnabled` を有効にし、`usageProviders` に許可する provider ID を列挙します。空の `usageProviders` はキャッシュ表示モードで、Usage タブはリモートリクエストを送りません。Usage タブへ初めて入ったときは TUI セッションごとに最大 1 回だけ自動取得し、その後のサブスクリプション更新は Usage タブの `u` キーだけで実行します。`r` は常にローカルレポート更新、`R` はローカルレポート自動更新です。
+
+```json
+{
+  "usageTabEnabled": true,
+  "usageProviders": ["codex", "zai", "minimax-token-plan-cn"]
+}
+```
+
+Canonical TUI provider IDs: `claude`, `codex`, `zai`, `amp`, `copilot`, `grok`, `kimi`, `minimax-token-plan-cn`, `minimax-token-plan-global`, `warp`.
+
+`zai` は Z.ai/Zhipu GLM Coding Plan quota を意味し、通常の Z.ai API 残高ではありません。GLM Coding Plan は domestic/global の provider ID に分割しません。MiniMax Token Plan は CN と Global で分かれ、key は相互利用できません。Kimi は Kimi Code membership quota で、Kimi Code Console API key または Kimi Code OAuth を使います。`ZAI_API_KEY`、`GLM_API_KEY`、`KIMI_API_KEY`、`MINIMAX_API_KEY`、`MINIMAX_API_TOKEN` などの汎用環境変数はサブスクリプション quota 取得では意図的に無視されます。
+
 ### 出力例（`--light`バージョン）
 
 <img alt="CLI Light" src="./.github/assets/cli-light.png" />
@@ -524,7 +542,9 @@ Tokscaleは設定を`~/.config/tokscale/settings.json`に保存します：
 {
   "colorPalette": "blue",
   "includeUnusedModels": false,
-  "defaultClients": ["opencode", "claude"]
+  "defaultClients": ["opencode", "claude"],
+  "usageTabEnabled": true,
+  "usageProviders": ["codex", "zai", "minimax-token-plan-cn"]
 }
 ```
 
@@ -537,6 +557,8 @@ Tokscaleは設定を`~/.config/tokscale/settings.json`に保存します：
 | `nativeTimeoutMs` | number | `300000` | ネイティブサブプロセス処理の最大時間（5000-3600000ms） |
 | `defaultClients` | string[] | `[]` | `--client/-c` フラグを渡さない場合に適用されるクライアントフィルター。`--client` と同じ ID を受け付けます（例: `["opencode", "claude", "zed"]`）。未知の ID は無視されます。CLI フラグが指定されるとこのリストは完全に無視されます — マージはしません。 |
 | `light.writeCache` | boolean | `false` | `true` のとき、`tokscale --light` はレンダリング直後に TUI キャッシュを原子的に上書きします。CLI フラグ `--write-cache` / `--no-write-cache` が実行ごとに優先されます。 |
+| `usageTabEnabled` | boolean | `false` | TUI にサブスクリプション quota の Usage タブを表示します。 |
+| `usageProviders` | string[] | `[]` | Usage タブが取得してよいサブスクリプション provider の明示 allowlist。空配列はキャッシュ表示モードで、リモートリクエストを送りません。 |
 
 #### キャッシュディレクトリ構成
 
@@ -558,6 +580,10 @@ Tokscaleは設定を`~/.config/tokscale/settings.json`に保存します：
 |----------|---------|-------------|
 | `TOKSCALE_NATIVE_TIMEOUT_MS` | `300000`（5分） | `nativeTimeoutMs` 設定をオーバーライド |
 | `TOKSCALE_CONFIG_DIR` | unset | 設定ディレクトリのルート（`settings.json`、`star-cache.json`、`cache/`、`antigravity-cache/`、`trae-cache/` の保存場所）をオーバーライドします。絶対パス推奨；相対パスはプロセス CWD を基準に解決されます。CI サンドボックスや非デフォルトの場所を固定したい場合に便利です。設定されている場合、tokscale は macOS のレガシーパス（`~/Library/Application Support/tokscale/`）にフォールバックしません。 |
+| `TOKSCALE_USAGE_ZAI_CODING_PLAN_API_KEY` | unset | Z.ai/Zhipu GLM Coding Plan key for subscription quota lookup. |
+| `TOKSCALE_USAGE_KIMI_CODING_PLAN_API_KEY` | unset | Kimi Code Console API key for Kimi Code membership quota lookup. |
+| `TOKSCALE_USAGE_MINIMAX_TOKEN_PLAN_CN_KEY` | unset | MiniMax CN Token Plan subscription key. |
+| `TOKSCALE_USAGE_MINIMAX_TOKEN_PLAN_GLOBAL_KEY` | unset | MiniMax Global Token Plan subscription key. |
 
 ```bash
 # 例：非常に大きなデータセット用にタイムアウトを増加

README.ko.md

@@ -110,6 +110,7 @@ AI 지원 개발 시대에 **토큰은 새로운 에너지**입니다. 토큰은
   - [Cursor IDE 명령어](#cursor-ide-명령어)
   - [Antigravity 명령어](#antigravity-명령어)
   - [Trae 명령어](#trae-명령어)
+  - [Subscription Usage](#subscription-usage)
   - [예시 출력](#예시-출력---light-버전)
   - [설정](#설정)
   - [환경 변수](#환경-변수)
@@ -262,7 +263,7 @@ tokscale models --json > report.json   # 파일로 저장
   - `v`: Table/Profile 뷰 전환 (Hourly 탭)
   - `y`: 선택된 행을 클립보드에 복사
   - `p`: 9가지 색상 테마 순환
-  - `r`: 데이터 새로고침; `Shift+R`로 자동 새로고침 토글; `+`/`-`로 간격 조정
+  - `r`: 로컬 리포트 새로고침; `Shift+R`로 로컬 리포트 자동 새로고침 토글; `+`/`-`로 간격 조정; `u`는 Usage 탭에서만 구독 사용량 새로고침
   - `e`: JSON으로 내보내기
   - `q` 또는 `Ctrl+C`: 종료
 - **마우스 지원**: 탭, 버튼, 필터 클릭
@@ -511,6 +512,23 @@ tokscale trae logout --variant solo
 
 > **중국판**: 중국판(`trae.com.cn`)은 의도적으로 지원하지 않습니다. CN 백엔드는 세션 단위 사용량 조회 API를 공개하지 않습니다. 공식 엔드포인트가 제공되면 지원을 추가할 예정입니다.
 
+### Subscription Usage
+
+`tokscale usage`는 명시적인 CLI 작업이므로, 사용 가능한 자격 증명이 있는 provider의 구독 quota를 가져옵니다.
+
+TUI에서는 `usageTabEnabled`를 켜고 `usageProviders`에 허용할 provider ID를 적어야 합니다. 빈 `usageProviders`는 캐시 표시 모드이며 Usage 탭은 원격 요청을 보내지 않습니다. Usage 탭에 처음 들어갈 때는 TUI 세션당 최대 한 번만 자동 요청하고, 이후 구독 새로고침은 Usage 탭의 `u` 키로만 실행합니다. `r`은 항상 로컬 리포트 새로고침이고, `R`은 로컬 리포트 자동 새로고침입니다.
+
+```json
+{
+  "usageTabEnabled": true,
+  "usageProviders": ["codex", "zai", "minimax-token-plan-cn"]
+}
+```
+
+Canonical TUI provider IDs: `claude`, `codex`, `zai`, `amp`, `copilot`, `grok`, `kimi`, `minimax-token-plan-cn`, `minimax-token-plan-global`, `warp`.
+
+`zai`는 Z.ai/Zhipu GLM Coding Plan quota를 의미하며 일반 Z.ai API 잔액이 아닙니다. GLM Coding Plan은 domestic/global provider ID로 나누지 않습니다. MiniMax Token Plan은 CN과 Global이 분리되어 key를 서로 사용할 수 없습니다. Kimi는 Kimi Code membership quota이며 Kimi Code Console API key 또는 Kimi Code OAuth를 사용합니다. `ZAI_API_KEY`, `GLM_API_KEY`, `KIMI_API_KEY`, `MINIMAX_API_KEY`, `MINIMAX_API_TOKEN` 같은 범용 환경 변수는 구독 quota 조회에서 의도적으로 무시됩니다.
+
 ### 예시 출력 (`--light` 버전)
 
 <img alt="CLI Light" src="./.github/assets/cli-light.png" />
@@ -523,7 +541,9 @@ Tokscale은 설정을 `~/.config/tokscale/settings.json`에 저장합니다:
 {
   "colorPalette": "blue",
   "includeUnusedModels": false,
-  "defaultClients": ["opencode", "claude"]
+  "defaultClients": ["opencode", "claude"],
+  "usageTabEnabled": true,
+  "usageProviders": ["codex", "zai", "minimax-token-plan-cn"]
 }
 ```
 
@@ -536,6 +556,8 @@ Tokscale은 설정을 `~/.config/tokscale/settings.json`에 저장합니다:
 | `nativeTimeoutMs` | number | `300000` | 네이티브 서브프로세스 처리 최대 시간 (5000-3600000ms) |
 | `defaultClients` | string[] | `[]` | `--client/-c` 플래그를 전달하지 않을 때 적용되는 기본 클라이언트 필터. `--client`와 동일한 ID를 받습니다 (예: `["opencode", "claude", "zed"]`). 알 수 없는 ID는 자동으로 무시됩니다. CLI 플래그가 있으면 이 목록은 완전히 무시됩니다 — 병합되지 않습니다. |
 | `light.writeCache` | boolean | `false` | `true`이면 `tokscale --light`가 렌더링 직후 TUI 캐시를 원자적으로 덮어씁니다. CLI 플래그 `--write-cache` / `--no-write-cache`가 실행별로 우선합니다. |
+| `usageTabEnabled` | boolean | `false` | TUI에 구독 quota Usage 탭을 표시합니다. |
+| `usageProviders` | string[] | `[]` | Usage 탭이 요청할 수 있는 구독 provider 명시 allowlist. 빈 배열은 캐시 표시 모드이며 원격 요청을 보내지 않습니다. |
 
 #### 캐시 디렉터리 레이아웃
 
@@ -557,6 +579,10 @@ Tokscale은 설정을 `~/.config/tokscale/settings.json`에 저장합니다:
 |----------|---------|-------------|
 | `TOKSCALE_NATIVE_TIMEOUT_MS` | `300000` (5분) | `nativeTimeoutMs` 설정 오버라이드 |
 | `TOKSCALE_CONFIG_DIR` | unset | 설정 디렉토리 루트(`settings.json`, `star-cache.json`, `cache/`, `antigravity-cache/`, `trae-cache/` 위치)를 오버라이드합니다. 절대 경로 권장; 상대 경로는 프로세스 CWD 기준으로 해석됩니다. CI 샌드박스나 비기본 위치를 고정할 때 유용합니다. 설정되면 tokscale은 macOS 레거시 경로(`~/Library/Application Support/tokscale/`)로 폴백하지 않습니다. |
+| `TOKSCALE_USAGE_ZAI_CODING_PLAN_API_KEY` | unset | Z.ai/Zhipu GLM Coding Plan key for subscription quota lookup. |
+| `TOKSCALE_USAGE_KIMI_CODING_PLAN_API_KEY` | unset | Kimi Code Console API key for Kimi Code membership quota lookup. |
+| `TOKSCALE_USAGE_MINIMAX_TOKEN_PLAN_CN_KEY` | unset | MiniMax CN Token Plan subscription key. |
+| `TOKSCALE_USAGE_MINIMAX_TOKEN_PLAN_GLOBAL_KEY` | unset | MiniMax Global Token Plan subscription key. |
 
 ```bash
 # 예시: 매우 큰 데이터셋에 대한 타임아웃 증가

README.md

@@ -268,7 +268,7 @@ The interactive TUI mode provides:
   - `v`: Toggle Table/Profile view (Hourly tab)
   - `y`: Copy selected row to clipboard
   - `p`: Cycle through 9 color themes
-  - `r`: Refresh data; `Shift+R` toggles auto-refresh; `+`/`-` adjusts interval
+  - `r`: Refresh local reports; `Shift+R` toggles local-report auto-refresh; `+`/`-` adjusts interval; `u` refreshes subscription usage only on the Usage tab
   - `e`: Export to JSON
   - `q` or `Ctrl+C`: Quit
 - **Mouse Support**: Click tabs, buttons, and filters
@@ -646,7 +646,9 @@ tokscale usage --json
 tokscale usage --light
 ```
 
-In the TUI, enable `usageTabEnabled`, then navigate to the **Usage** tab to see subscription data. Press `u` or `r` to refresh.
+In the TUI, enable `usageTabEnabled` and list the remote providers in `usageProviders`, then navigate to the **Usage** tab to see subscription data. The first visit to the Usage tab may fetch once per TUI session. After that, press `u` on the Usage tab to refresh subscription usage explicitly. `r` always refreshes local reports only, and `R` controls local-report auto-refresh only; tokscale does not poll subscription quotas in the background.
+
+An empty `usageProviders` array is cache-display mode: the Usage tab can show cached subscription data, but it will not make remote requests. The `tokscale usage` command is different: running that command is already explicit user intent, so the CLI still tries every provider that has usable credentials.
 
 > **Note**: Subscription quotas and balances are **vendor-reported** — tokscale calls each provider's own quota endpoint and surfaces the response verbatim. Numbers reflect what the provider reports (which is also what shows up in their official dashboards) and are not independently verified against tokscale's own usage tracking.
 
@@ -656,13 +658,16 @@ In the TUI, enable `usageTabEnabled`, then navigate to the **Usage** tab to see
 |----------|-------------|---------|-------|
 | **Claude** | OAuth (credentials file or macOS Keychain) | Session (5hr), Weekly, Opus quotas | Run `claude` to log in |
 | **Codex** (OpenAI) | OAuth (`~/.config/codex/auth.json` or `~/.codex/auth.json`) | Session, Weekly quotas | Run `codex` to log in |
-| **Z.ai** | API key (env var) | Token limits, Web Searches | Set `ZAI_API_KEY` or `GLM_API_KEY` |
+| **Z.ai GLM Coding Plan** | GLM Coding Plan API key (`TOKSCALE_USAGE_ZAI_CODING_PLAN_API_KEY`) | Token limits, Web Searches | Use the GLM Coding Plan key, not a general Z.ai API key |
 | **Amp** | API key (`~/.local/share/amp/secrets.json`) | Free tier balance, Credits | Run `amp` to log in |
 | **GitHub Copilot** | GitHub token (keychain or `~/.config/gh/hosts.yml`) | Premium interactions, Chat quotas | Run `gh auth login` |
-| **Kimi** | OAuth (`$KIMI_CODE_HOME/credentials/kimi-code.json`, fallback: `~/.kimi-code/credentials/kimi-code.json`) | Session, Weekly quotas | Run `kimi` to log in |
-| **MiniMax** | API key (env var) | Prompt quotas per model | Set `MINIMAX_API_KEY` or `MINIMAX_API_TOKEN` |
+| **Kimi Code** | Kimi Code API key (`TOKSCALE_USAGE_KIMI_CODING_PLAN_API_KEY`) or Kimi Code OAuth (`$KIMI_CODE_HOME/credentials/kimi-code.json`) | Session, Weekly quotas | Use a Kimi Code Console API key or run `kimi` to log in |
+| **MiniMax Token Plan CN** | CN Token Plan subscription key (`TOKSCALE_USAGE_MINIMAX_TOKEN_PLAN_CN_KEY`) | 5-hour and weekly Token Plan windows | Use the CN Token Plan key from the CN console |
+| **MiniMax Token Plan Global** | Global Token Plan subscription key (`TOKSCALE_USAGE_MINIMAX_TOKEN_PLAN_GLOBAL_KEY`) | 5-hour and weekly Token Plan windows | Use the Global Token Plan key from the Global console |
+
+Canonical TUI `usageProviders` IDs: `claude`, `codex`, `zai`, `amp`, `copilot`, `grok`, `kimi`, `minimax-token-plan-cn`, `minimax-token-plan-global`, `warp`.
 
-Providers are auto-detected — only those with valid credentials are shown. If a provider is missing, ensure you've logged in or set the required environment variable.
+Z.ai's `zai` provider means GLM Coding Plan quota. Z.ai/Zhipu GLM Coding Plan keys are not split into domestic/global provider IDs. MiniMax Token Plan is split: CN and Global keys are not interchangeable. General-purpose provider keys such as `ZAI_API_KEY`, `GLM_API_KEY`, `KIMI_API_KEY`, `MINIMAX_API_KEY`, and `MINIMAX_API_TOKEN` are intentionally ignored for subscription quota lookups.
 
 #### Example Output
 
@@ -693,6 +698,8 @@ Tokscale stores settings in `~/.config/tokscale/settings.json`:
   "colorPalette": "blue",
   "includeUnusedModels": false,
   "defaultClients": ["opencode", "claude"],
+  "usageTabEnabled": true,
+  "usageProviders": ["codex", "zai", "minimax-token-plan-cn"],
   "scanner": {
     "extraScanPaths": {
       "codex": [
@@ -721,6 +728,7 @@ Tokscale stores settings in `~/.config/tokscale/settings.json`:
 | `defaultClients` | string[] | `[]` | Client filter applied when no `--client/-c` flag is passed. Accepts the same ids as `--client` (e.g. `["opencode", "claude", "zed"]`). Unknown ids are silently dropped. CLI flags always override this list completely — no merging. |
 | `light.writeCache` | boolean | `false` | When true, `tokscale --light` overwrites the TUI cache atomically after rendering. CLI flags `--write-cache` / `--no-write-cache` override per-invocation. |
 | `usageTabEnabled` | boolean | `false` | Show the subscription quota Usage tab in the TUI. Default-off because local token usage is the primary TUI workflow and subscription lookups are optional. |
+| `usageProviders` | string[] | `[]` | Explicit allowlist of subscription providers the TUI may fetch from the Usage tab. Empty means cache-display mode: show cached Usage content only and never send remote subscription requests. |
 | `scanner.extraScanPaths` | object | `{}` | Additional per-client scan roots for sessions outside Tokscale's default home-root locations |
 
 Use `scanner.extraScanPaths` for persistent extra roots such as project-level `.codex` directories, imported Gemini/OpenClaw histories, Hermes profile databases, or a Windows Zed data directory mounted from WSL. Hermes entries may point at a profile directory containing `state.db` or directly at a `state.db` file. Zed entries may point at a `threads` directory containing `threads.db` or directly at `threads.db`. Tokscale merges these paths with the default scan roots on every run and deduplicates overlapping roots by canonical path.
@@ -749,6 +757,10 @@ Environment variables override config file values. For CI/CD or one-off use:
 | `TOKSCALE_API_TOKEN` | unset | Tokscale personal API token for non-interactive `submit` and `delete-submitted-data` runs. Create one from Settings > API Tokens or save it locally with `tokscale login --token tt_xxx`. |
 | `TOKSCALE_EXTRA_DIRS` | unset | One-off extra session roots as `client:/abs/path,client:/abs/path` |
 | `TOKSCALE_CONFIG_DIR` | unset | Overrides the config directory root (where `settings.json`, `star-cache.json`, `cache/`, `antigravity-cache/`, and `trae-cache/` live). Absolute path recommended; relative paths resolve against the process CWD. Useful for CI sandboxes or pinning a non-default location. When set, tokscale will not fall back to the legacy macOS `~/Library/Application Support/tokscale/` path. |
+| `TOKSCALE_USAGE_ZAI_CODING_PLAN_API_KEY` | unset | Z.ai/Zhipu GLM Coding Plan key for subscription quota lookup. |
+| `TOKSCALE_USAGE_KIMI_CODING_PLAN_API_KEY` | unset | Kimi Code Console API key for Kimi Code membership quota lookup. |
+| `TOKSCALE_USAGE_MINIMAX_TOKEN_PLAN_CN_KEY` | unset | MiniMax CN Token Plan subscription key. |
+| `TOKSCALE_USAGE_MINIMAX_TOKEN_PLAN_GLOBAL_KEY` | unset | MiniMax Global Token Plan subscription key. |
 
 ```bash
 # Example: Increase timeout for very large datasets