@slkiser/opencode-quota 2.7.1 → 2.9.1

package/README.md

@@ -1,24 +1,34 @@
-# Opencode Quota
+# OpenCode Quota
 
 `opencode-quota` gives you two things:
 
 - Automatic quota toasts after assistant responses
-- Manual `/quota` and `/tokens_*` commands for deeper local reporting with zero context window pollution
+- Manual `/quota`, `/pricing_refresh`, and `/tokens_*` commands for deeper local reporting with zero context window pollution
+
+**Quota providers**: GitHub Copilot, OpenAI (Plus/Pro), Cursor, Qwen Code, Alibaba Coding Plan, Chutes AI, Firmware AI, Google Antigravity, and Z.ai coding plan.
+
+**Token reports**: All models and providers in [models.dev](https://models.dev), plus deterministic local pricing for Cursor Auto/Composer and Cursor model aliases that are not on models.dev.
+
+<table>
+  <tr>
+    <td width="50%" align="center">Example of toast</td>
+    <td width="50%" align="center">Example of <code>/tokens_weekly</code></td>
+  </tr>
+  <tr>
+    <td width="50%">
+      <img src="https://github.com/slkiser/opencode-quota/blob/main/toasts.webp" alt="Image of opencode-quota toast" />
+    </td>
+    <td width="50%">
+      <img src="https://github.com/slkiser/opencode-quota/blob/main/tokens.webp" alt="Image of opencode-quota /tokens_weekly output" />
+    </td>
+  </tr>
+</table>
 
-**Quota provider supports**: GitHub Copilot, OpenAI (Plus/Pro), Cursor (ACP), Qwen Code, Alibaba Coding Plan, Chutes AI, Firmware AI, Google Antigravity, and Z.ai coding plan.
-
-**Token provider supports**: All models and providers in [models.dev](https://models.dev), plus deterministic local pricing for Cursor Auto/Composer and Cursor model aliases that are not on models.dev.
-
-
-![Image of quota toasts](https://github.com/slkiser/opencode-quota/blob/main/toast.png)
-
-![Image of /quota and /tokens_daily outputs](https://github.com/slkiser/opencode-quota/blob/main/quota.png)
+Quota and `/tokens_*` output are computed from local OpenCode session history.
 
 ## Quick Start
 
-OpenCode `>= 1.2.0` is required.
-
-Add the plugin to your `opencode.json` or `opencode.jsonc`:
+OpenCode `>= 1.2.0` is required. Add the plugin to your `opencode.json` or `opencode.jsonc`:
 
 ```jsonc
 {
@@ -30,42 +40,93 @@ Then:
 
 1. Restart or reload OpenCode.
 2. Run `/quota_status` to confirm provider detection.
-3. Run `/quota` to see the manual grouped report.
+3. Run `/quota` or `/tokens_today`.
 
-That is enough for most installs. Providers are auto-detected from your existing OpenCode setup.
+That is enough for most installs. Providers are auto-detected from your existing OpenCode setup, and most providers work from your existing OpenCode auth. If a provider needs anything extra, use the setup table below.
 
-## What You Get
-
-- Toasts after assistant responses, idle transitions, and compaction events
-- `/quota` for a grouped manual quota report such as `[OpenAI] (Pro)` or `[Copilot] (business)`, with a local call timestamp in the heading
-- `/tokens_*` commands backed by local OpenCode history and a local pricing snapshot, each with a local call timestamp in the heading
-- No model calls to compute the toast or report output
+<details>
+<summary><strong>Example: Turn off auto-detection and choose providers</strong></summary>
 
-## Common Install Patterns
+```jsonc
+{
+  "experimental": {
+    "quotaToast": {
+      "enabledProviders": ["copilot", "openai", "google-antigravity"]
+    }
+  }
+}
+```
 
-### Basic install
+</details>
 
-If you already use Copilot, OpenAI, Firmware, Chutes, or Z.ai in OpenCode, start here:
+<details>
+<summary><strong>Example: Grouped toast layout instead of the default classic toast</strong></summary>
 
 ```jsonc
 {
-  "plugin": ["@slkiser/opencode-quota"]
+  "experimental": {
+    "quotaToast": {
+      "toastStyle": "grouped"
+    }
+  }
 }
 ```
 
-### Cursor
+</details>
+
+### Provider Setup At A Glance
 
-Cursor model support requires the `opencode-cursor` [companion ACP plugin](https://github.com/Nomadcxx/opencode-cursor):
+| Provider | Auto setup | How it works |
+| --- | --- | --- |
+| **GitHub Copilot** | Usually | OpenCode auth; PAT only for managed billing. |
+| **OpenAI** | Yes | OpenCode auth. |
+| **Cursor** | Needs [quick setup](#cursor-quick-setup) | Companion auth plugin + `provider.cursor`. |
+| **Qwen Code** | Needs [quick setup](#qwen-code-quick-setup) | Companion auth plugin. |
+| **Alibaba Coding Plan** | Yes | OpenCode auth + local request estimation. |
+| **Firmware AI** | Usually | User/global OpenCode config or env; repo-local secrets ignored. |
+| **Chutes AI** | Usually | User/global OpenCode config or env; repo-local secrets ignored. |
+| **Google Antigravity** | Needs [quick setup](#google-antigravity-quick-setup) | Companion auth plugin. |
+| **Z.ai** | Yes | OpenCode auth. |
+
+<a id="cursor-quick-setup"></a>
+<details>
+<summary><strong>Quick setup: Cursor</strong></summary>
+
+Cursor quota support requires the `opencode-cursor-oauth` [plugin](https://github.com/ephraimduncan/opencode-cursor):
 
 ```jsonc
 {
-  "plugin": ["@rama_nigg/open-cursor", "@slkiser/opencode-quota"]
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-cursor-oauth", "@slkiser/opencode-quota"],
+  "provider": {
+    "cursor": {
+      "name": "Cursor"
+    }
+  },
+  "experimental": {
+    "quotaToast": {
+      "cursorPlan": "pro",
+      "cursorBillingCycleStartDay": 7
+    }
+  }
 }
 ```
 
-### Google Antigravity
+Then authenticate once:
 
-Google quota support requires the `opencode-antigravity-auth` [companion auth plugin](https://github.com/NoeFabris/opencode-antigravity-auth):
+```sh
+opencode auth login --provider cursor
+```
+
+For behavior details and troubleshooting, see [Cursor notes](#cursor-notes).
+
+</details>
+
+<a id="google-antigravity-quick-setup"></a>
+<details>
+<summary><strong>Quick setup: Google Antigravity</strong></summary>
+
+Google quota support requires the `opencode-antigravity-auth` [plugin](https://github.com/NoeFabris/opencode-antigravity-auth):
 
 ```jsonc
 {
@@ -73,9 +134,15 @@ Google quota support requires the `opencode-antigravity-auth` [companion auth pl
 }
 ```
 
-### Qwen Code
+For behavior details and troubleshooting, see [Google Antigravity notes](#google-antigravity-notes).
+
+</details>
+
+<a id="qwen-code-quick-setup"></a>
+<details>
+<summary><strong>Quick setup: Qwen Code</strong></summary>
 
-Qwen quota support requires the `opencode-qwencode-auth` [companion auth plugin](https://github.com/gustavodiasdev/opencode-qwencode-auth):
+Qwen quota support requires the `opencode-qwencode-auth` [plugin](https://github.com/gustavodiasdev/opencode-qwencode-auth):
 
 ```jsonc
 {
@@ -83,7 +150,9 @@ Qwen quota support requires the `opencode-qwencode-auth` [companion auth plugin]
 }
 ```
 
-Quota and `/tokens_*` output are computed from local OpenCode session history.
+For behavior details and troubleshooting, see [Qwen Code notes](#qwen-code-notes).
+
+</details>
 
 ## Commands
 
@@ -91,6 +160,7 @@ Quota and `/tokens_*` output are computed from local OpenCode session history.
 | --- | --- |
 | `/quota` | Manual grouped quota report with a local call timestamp |
 | `/quota_status` | Concise diagnostics for config, provider availability, account detection, and pricing snapshot health |
+| `/pricing_refresh` | Pull the local runtime pricing snapshot from `models.dev` on demand |
 | `/tokens_today` | Tokens used today (calendar day) |
 | `/tokens_daily` | Tokens used in the last 24 hours |
 | `/tokens_weekly` | Tokens used in the last 7 days |
@@ -101,70 +171,21 @@ Quota and `/tokens_*` output are computed from local OpenCode session history.
 
 There is no `/token` command. The reporting commands are the `/tokens_*` family.
 
-## Minimal Config
-
-You do not need extra config to get started. If you want to narrow the plugin to specific providers, use:
-
-```jsonc
-{
-  "experimental": {
-    "quotaToast": {
-      "enabledProviders": ["copilot", "openai", "google-antigravity"]
-    }
-  }
-}
-```
-
-If you want grouped toast layout instead of the default classic toast:
-
-```jsonc
-{
-  "experimental": {
-    "quotaToast": {
-      "toastStyle": "grouped"
-    }
-  }
-}
-```
-
-If Alibaba Coding Plan auth does not include a `tier`, you can set the fallback tier here:
-
-```jsonc
-{
-  "experimental": {
-    "quotaToast": {
-      "alibabaCodingPlanTier": "lite"
-    }
-  }
-}
-```
-
-`/quota` already uses grouped formatting by default, even if toast style stays `classic`.
-
-## Provider Setup At A Glance
-
-| Provider | Works automatically | Extra setup when needed |
-| --- | --- | --- |
-| GitHub Copilot | Usually yes | Add `copilot-quota-token.json` only for managed org or enterprise billing |
-| OpenAI | Yes | None |
-| Cursor | Needs `opencode-cursor` | Optional `cursorPlan`, `cursorIncludedApiUsd`, and `cursorBillingCycleStartDay` for monthly API budget tracking |
-| Qwen Code | Needs `opencode-qwencode-auth` | Local free-tier request estimation |
-| Alibaba Coding Plan | Yes | Local request-count estimation |
-| Firmware AI | Usually yes | Optional API key |
-| Chutes AI | Usually yes | Optional API key |
-| Google Antigravity | Needs `opencode-antigravity-auth` | Multi-account account file lives in OpenCode runtime config |
-| Z.ai | Yes | None |
-
 ## Provider-Specific Notes
 
+<a id="github-copilot-notes"></a>
 <details>
 <summary><strong>GitHub Copilot</strong></summary>
 
-Personal Copilot quota works automatically when OpenCode is already signed in. When no `copilot-quota-token.json` exists, the plugin reads the OpenCode Copilot OAuth token from `~/.local/share/opencode/auth.json` and queries `GET https://api.github.com/copilot_internal/user` with `Authorization: Bearer <access token>`.
+Personal quota works automatically when OpenCode is already signed in. Without `copilot-quota-token.json`, the plugin reads the OpenCode Copilot OAuth token from `~/.local/share/opencode/auth.json` and calls `GET https://api.github.com/copilot_internal/user`.
 
-For managed billing, create `copilot-quota-token.json` under the OpenCode runtime config directory. You can find the directory with `opencode debug paths`.
+- Managed billing uses `copilot-quota-token.json` in the OpenCode runtime config directory (`opencode debug paths`). `business` requires `organization`; `enterprise` requires `enterprise` and can also filter by `organization` or `username`.
+- `copilot-quota-token.json` takes precedence over OAuth. If the PAT config is invalid, the plugin reports that error and does not silently fall back.
+- Output is labeled `[Copilot] (personal)` or `[Copilot] (business)`, and managed output includes the org or enterprise slug.
+- Enterprise premium usage does not support fine-grained PATs or GitHub App tokens.
+- Check `/quota_status` for `copilot_quota_auth`, `billing_mode`, `billing_scope`, `quota_api`, `effective_source`, and `billing_api_access_likely`.
 
-Organization example:
+Example `copilot-quota-token.json`:
 
 ```json
 {
@@ -174,8 +195,6 @@ Organization example:
 }
 ```
 
-Enterprise example:
-
 ```json
 {
   "token": "ghp_...",
@@ -186,68 +205,21 @@ Enterprise example:
 }
 ```
 
-Behavior notes:
-
-- Personal output is labeled `[Copilot] (personal)`.
-- Managed organization and enterprise output is labeled `[Copilot] (business)`.
-- Managed output includes the org or enterprise slug in the value line so the billing scope is still visible.
-- If both OpenCode OAuth and `copilot-quota-token.json` exist, the PAT config wins.
-- If no PAT config exists, OpenCode Copilot OAuth is treated as personal quota auth via `/copilot_internal/user`.
-- If the PAT config is invalid, the plugin reports that error and does not silently fall back to OAuth.
-- `business` requires `organization`.
-- Enterprise premium usage does not support fine-grained PATs or GitHub App tokens. Use a supported enterprise token such as a classic PAT.
-
-Useful checks:
-
-- Run `/quota_status` and inspect `copilot_quota_auth`.
-- Look for `billing_mode`, `billing_scope`, `quota_api`, `effective_source`, and `billing_api_access_likely`.
-
-</details>
-
-<details>
-<summary><strong>OpenAI</strong></summary>
-
-No extra setup is required if OpenCode already has OpenAI or ChatGPT auth configured.
-
 </details>
 
+<a id="cursor-notes"></a>
 <details>
 <summary><strong>Cursor</strong></summary>
 
-Cursor support requires the `opencode-cursor` plugin and stays local-only and deterministic once `@rama_nigg/open-cursor` is installed in OpenCode.
-
-Recommended install path:
-
-- Follow Option B from the upstream [`opencode-cursor` README](https://github.com/Nomadcxx/opencode-cursor).
-- Keep the Cursor model list in sync with `cursor-agent models`.
-
-Current behavior:
-
-- Detects Cursor usage from OpenCode history when the current model or stored message model is `cursor-acp/*`
-- `/tokens_*` maps Cursor API-pool models into official pricing and uses bundled static rates for `auto` and `composer*`
-- `/quota` and toasts estimate the current billing-cycle spend from local OpenCode history
-- Percentage remaining is shown only when you configure `cursorPlan` or `cursorIncludedApiUsd`
-- Billing cycle defaults to the local calendar month unless you set `cursorBillingCycleStartDay`
+See [Cursor quick setup](#cursor-quick-setup) for auth. Quota and token reporting stays local to OpenCode history and local pricing data.
 
-Notes:
-
-- Session cookies and Cursor team APIs are not required for this local reporting path
-- Unknown future Cursor model ids are surfaced in `/quota_status` under Cursor diagnostics and `unknown_pricing`
-
-Example config for a personal Pro account:
-
-```jsonc
-{
-  "experimental": {
-    "quotaToast": {
-      "cursorPlan": "pro",
-      "cursorBillingCycleStartDay": 7
-    }
-  }
-}
-```
+- Detects Cursor usage when the provider is `cursor` or the stored/current model id is `cursor/*`.
+- `/tokens_*` maps Cursor API-pool models to official pricing and uses bundled static pricing for `auto` and `composer*`.
+- `/quota` and toasts estimate the current billing-cycle spend from local history only. Session cookies and team APIs are not required.
+- Remaining percentage appears only when `experimental.quotaToast.cursorPlan` or `experimental.quotaToast.cursorIncludedApiUsd` is set. Billing cycle defaults to the local calendar month unless `experimental.quotaToast.cursorBillingCycleStartDay` is set.
+- Legacy `cursor-acp/*` history remains readable. Unknown future Cursor model ids appear in `/quota_status` under Cursor diagnostics and `unknown_pricing`.
 
-If you need a custom included API budget, override it directly:
+Example override:
 
 ```jsonc
 {
@@ -262,49 +234,57 @@ If you need a custom included API budget, override it directly:
 
 </details>
 
+<a id="qwen-code-notes"></a>
 <details>
 <summary><strong>Qwen Code</strong></summary>
 
-Qwen support is local-only estimation for the free plan. The plugin does not call an Alibaba quota API.
-
-Current behavior:
-
-- Free tier only: 1000 requests per UTC day
-- Free tier only: 60 requests per rolling minute
-- Counters increment on successful question-tool completions while the current model is `qwen-code/*`
-
-State file path:
+See [Qwen Code quick setup](#qwen-code-quick-setup) for auth. Usage is local-only estimation for the free plan; the plugin does not call an Alibaba quota API.
 
-- `.../opencode/opencode-quota/qwen-local-quota.json`
-
-Run `/quota_status` to verify auth detection, `qwen_local_plan`, and local counter status.
+- Free tier limits: `1000` requests per UTC day and `60` requests per rolling minute.
+- Counters increment on successful question-tool completions while the current model is `qwen-code/*`.
+- State file: `.../opencode/opencode-quota/qwen-local-quota.json`.
+- Check `/quota_status` for auth detection, `qwen_local_plan`, and local counter state.
 
 </details>
 
+<a id="alibaba-coding-plan-notes"></a>
 <details>
 <summary><strong>Alibaba Coding Plan</strong></summary>
 
-Alibaba Coding Plan uses native OpenCode auth from either `alibaba` or `alibaba-coding-plan` in `auth.json`, instead of the Qwen companion plugin. Quota estimation is request-count based with rolling windows.
-
-Supported tiers:
-
-- `lite`: 1200 requests / 5 hours, 9000 / week, 18000 / month
-- `pro`: 6000 requests / 5 hours, 45000 / week, 90000 / month
-- If `tier` is missing from auth, the plugin uses `experimental.quotaToast.alibabaCodingPlanTier` and defaults that setting to `lite`
-- Counters increment on successful question-tool completions while the current model is `alibaba/*` or `alibaba-cn/*`
+Uses native OpenCode auth from `alibaba` or `alibaba-coding-plan`. Quota is local request-count estimation with rolling windows.
 
-State file path:
+- `lite`: `1200 / 5h`, `9000 / week`, `18000 / month`
+- `pro`: `6000 / 5h`, `45000 / week`, `90000 / month`
+- If auth omits `tier`, the plugin uses `experimental.quotaToast.alibabaCodingPlanTier`, which defaults to `lite`.
+- Counters increment on successful question-tool completions while the current model is `alibaba/*` or `alibaba-cn/*`.
+- State file: `.../opencode/opencode-quota/alibaba-coding-plan-local-quota.json`.
+- `/quota_status` shows auth detection, resolved tier, state-file path, and current 5h/weekly/monthly usage.
 
-- `.../opencode/opencode-quota/alibaba-coding-plan-local-quota.json`
+Example fallback tier:
 
-`/quota_status` shows whether Alibaba auth is configured, the resolved Alibaba coding-plan tier, the Alibaba state-file path, and the current 5h/weekly/monthly usage when this plan is active.
+```jsonc
+{
+  "experimental": {
+    "quotaToast": {
+      "alibabaCodingPlanTier": "lite"
+    }
+  }
+}
+```
 
 </details>
 
+<a id="firmware-ai-notes"></a>
 <details>
 <summary><strong>Firmware AI</strong></summary>
 
-If OpenCode already has Firmware configured, it usually works automatically. You can also provide an API key:
+If OpenCode already has Firmware configured, it usually works automatically. Optional API key: `provider.firmware.options.apiKey`.
+
+For security, provider secrets are read from environment variables or your user/global OpenCode config only. Repo-local `opencode.json` / `opencode.jsonc` is ignored for `provider.firmware.options.apiKey`.
+
+Allowed env templates are limited to `{env:FIRMWARE_AI_API_KEY}` and `{env:FIRMWARE_API_KEY}`.
+
+Example user/global config (`~/.config/opencode/opencode.jsonc` on Linux/macOS):
 
 ```jsonc
 {
@@ -314,23 +294,23 @@ If OpenCode already has Firmware configured, it usually works automatically. You
         "apiKey": "{env:FIRMWARE_API_KEY}"
       }
     }
-  },
-  "experimental": {
-    "quotaToast": {
-      "enabledProviders": ["firmware"]
-    }
   }
 }
 ```
 
-`{env:VAR_NAME}` and direct keys are both supported.
-
 </details>
 
+<a id="chutes-ai-notes"></a>
 <details>
 <summary><strong>Chutes AI</strong></summary>
 
-If OpenCode already has Chutes configured, it usually works automatically. You can also provide an API key:
+If OpenCode already has Chutes configured, it usually works automatically. Optional API key: `provider.chutes.options.apiKey`.
+
+For security, provider secrets are read from environment variables or your user/global OpenCode config only. Repo-local `opencode.json` / `opencode.jsonc` is ignored for `provider.chutes.options.apiKey`.
+
+Allowed env templates are limited to `{env:CHUTES_API_KEY}`.
+
+Example user/global config (`~/.config/opencode/opencode.jsonc` on Linux/macOS):
 
 ```jsonc
 {
@@ -340,30 +320,19 @@ If OpenCode already has Chutes configured, it usually works automatically. You c
         "apiKey": "{env:CHUTES_API_KEY}"
       }
     }
-  },
-  "experimental": {
-    "quotaToast": {
-      "enabledProviders": ["chutes"]
-    }
   }
 }
 ```
 
 </details>
 
+<a id="google-antigravity-notes"></a>
 <details>
 <summary><strong>Google Antigravity</strong></summary>
 
-This provider requires the `opencode-antigravity-auth` plugin. Account credentials are stored under the OpenCode runtime config directory.
+See [Google Antigravity quick setup](#google-antigravity-quick-setup). Credentials live under the OpenCode runtime config directory.
 
-If you are debugging detection, `/quota_status` prints the candidate paths checked for `antigravity-accounts.json`.
-
-</details>
-
-<details>
-<summary><strong>Z.ai</strong></summary>
-
-No extra setup is required if OpenCode already has Z.ai configured.
+If detection looks wrong, `/quota_status` prints the candidate paths checked for `antigravity-accounts.json`.
 
 </details>
 
@@ -371,9 +340,11 @@ No extra setup is required if OpenCode already has Z.ai configured.
 
 All plugin settings live under `experimental.quotaToast`.
 
+Workspace-local config can still customize display/report behavior, but user/global config is authoritative for network-affecting settings such as `enabled`, `enabledProviders`, `minIntervalMs`, `pricingSnapshot`, `showOnIdle`, `showOnQuestion`, and `showOnCompact`.
+
 | Option | Default | Meaning |
 | --- | --- | --- |
-| `enabled` | `true` | Master switch for the plugin. When `false`, `/quota`, `/quota_status`, and `/tokens_*` are no-ops. |
+| `enabled` | `true` | Master switch for the plugin. When `false`, `/quota`, `/quota_status`, `/pricing_refresh`, and `/tokens_*` are no-ops. |
 | `enableToast` | `true` | Show popup toasts |
 | `toastStyle` | `classic` | Toast layout: `classic` or `grouped` |
 | `enabledProviders` | `"auto"` | Auto-detect providers, or set an explicit provider list |
@@ -393,33 +364,26 @@ All plugin settings live under `experimental.quotaToast`.
 | `cursorPlan` | `"none"` | Cursor included API budget preset: `none`, `pro`, `pro-plus`, `ultra` |
 | `cursorIncludedApiUsd` | unset | Override Cursor monthly included API budget in USD |
 | `cursorBillingCycleStartDay` | unset | Local billing-cycle anchor day `1..28`; when unset, Cursor usage resets on the local calendar month |
+| `pricingSnapshot.source` | `"auto"` | Token pricing snapshot selection: `auto`, `bundled`, or `runtime` |
+| `pricingSnapshot.autoRefresh` | `5` | Refresh stale local pricing data after this many days |
 | `debug` | `false` | Include debug context in toast output |
 
 ## Token Pricing Snapshot
 
-`/tokens_*` uses a local `models.dev` pricing snapshot plus bundled static Cursor pricing for Cursor-only pool models.
+`/tokens_*` uses a local `models.dev` pricing snapshot. A bundled snapshot ships for offline use, and Cursor `auto` and `composer*` pricing stays bundled because those ids are not on `models.dev`.
 
-Behavior:
-
-- A bundled snapshot ships with the plugin for offline use.
-- The plugin can refresh the local runtime snapshot when the data is stale.
-- Reports continue to work if refresh fails.
-- Cursor `auto` and `composer*` pricing is bundled in the plugin because those ids are not on `models.dev`.
-
-Useful environment variables:
-
-```sh
-OPENCODE_QUOTA_PRICING_AUTO_REFRESH=0
-OPENCODE_QUOTA_PRICING_MAX_AGE_DAYS=5
-```
-
-Maintainer refresh commands:
+| `pricingSnapshot.source` | Active pricing behavior |
+| --- | --- |
+| `auto` | Newer runtime snapshot wins; otherwise bundled pricing stays active. |
+| `bundled` | Packaged bundled snapshot stays active. |
+| `runtime` | Runtime snapshot stays active when present; bundled pricing is fallback until one exists. |
 
-```sh
-npm run pricing:refresh
-npm run pricing:refresh:if-stale
-npm run build
-```
+- See [Configuration Reference](#configuration-reference) for option defaults.
+- `pricingSnapshot.autoRefresh` controls how many days a runtime snapshot can age before background refresh.
+- `/pricing_refresh` refreshes only the local runtime snapshot under the OpenCode cache directory. It never rewrites the packaged bundled snapshot.
+- If `pricingSnapshot.source` is `bundled`, `/pricing_refresh` still updates the runtime cache, but active pricing stays bundled.
+- Reports keep working if refresh fails.
+- Pricing selection stays local and deterministic. There are no custom URLs or arbitrary pricing sources.
 
 ## Troubleshooting
 
@@ -429,42 +393,21 @@ If something is missing or looks wrong:
 2. Confirm the expected provider appears in the detected provider list.
 3. If token reports are empty, make sure OpenCode has already created `opencode.db`.
 4. If Copilot managed billing is expected, confirm `copilot-quota-token.json` is present and valid.
-5. If Google or Qwen support is expected, confirm the companion auth plugin is installed. If Alibaba Coding Plan support is expected, confirm OpenCode `alibaba` or `alibaba-coding-plan` auth is configured; `tier` may be `lite` or `pro`, and if it is missing the plugin falls back to `experimental.quotaToast.alibabaCodingPlanTier`.
+5. If provider setup looks wrong, check [Provider Setup At A Glance](#provider-setup-at-a-glance) and [Provider-Specific Notes](#provider-specific-notes). For Google Antigravity or Qwen Code, confirm the companion auth plugin is installed. For Alibaba Coding Plan, confirm OpenCode `alibaba` or `alibaba-coding-plan` auth is configured; `tier` may be `lite` or `pro`, and if it is missing the plugin falls back to `experimental.quotaToast.alibabaCodingPlanTier`.
 
 If `opencode.db` is missing, start OpenCode once and let its local migration complete.
 
-## Development
-
-```sh
-npm install
-npm run typecheck
-npm test
-npm run build
-```
+## Contribution
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution workflow and repository policy.
 
-## LLM Agent Installation Notes
-
-If you are using an agent to install the plugin for you, the safe default is:
-
-```jsonc
-{
-  "plugin": ["@slkiser/opencode-quota"]
-}
-```
-
-Then verify with `/quota_status`.
-
-Only add explicit `enabledProviders` if you want to limit which providers are queried. Only add companion plugins when the user actually uses Google Antigravity or Qwen Code, and only add `@rama_nigg/open-cursor` when the user actually uses Cursor models in OpenCode.
-
 ## License
 
 MIT
 
 ## Remarks
 
-Opencode Quota is not built by the OpenCode team and is not affiliated with OpenCode or any provider listed above.
+OpenCode Quota is not built by the OpenCode team and is not affiliated with OpenCode or any provider listed above.
 
 ## Star History
 

package/dist/index.d.ts

@@ -6,5 +6,5 @@
  * @packageDocumentation
  */
 export { QuotaToastPlugin } from "./plugin.js";
-export type { QuotaToastConfig, GoogleModelId, CopilotEnterpriseUsageResult, CopilotOrganizationUsageResult, CopilotQuotaResult, GoogleQuotaResult, GoogleModelQuota, } from "./lib/types.js";
+export type { QuotaToastConfig, GoogleModelId, PricingSnapshotSource, CopilotEnterpriseUsageResult, CopilotOrganizationUsageResult, CopilotQuotaResult, GoogleQuotaResult, GoogleModelQuota, } from "./lib/types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,4BAA4B,EAC5B,8BAA8B,EAC9B,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,4BAA4B,EAC5B,8BAA8B,EAC9B,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,8EAA8E;AAC9E,iFAAiF;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAa/C,yEAAyE;AACzE,wCAAwC;AAExC,6EAA6E;AAC7E,uFAAuF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,8EAA8E;AAC9E,iFAAiF;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAc/C,yEAAyE;AACzE,wCAAwC;AAExC,6EAA6E;AAC7E,uFAAuF"}

package/dist/lib/api-key-resolver.d.ts

@@ -16,6 +16,13 @@ export interface ConfigCandidate {
  * Within each location, .jsonc takes precedence over .json.
  */
 export declare function getOpencodeConfigCandidatePaths(): ConfigCandidate[];
+/**
+ * Get trusted global-only candidate paths for opencode.json/opencode.jsonc files.
+ *
+ * Provider secrets must not be sourced from repo-local config because the
+ * current workspace may be untrusted.
+ */
+export declare function getGlobalOpencodeConfigCandidatePaths(): ConfigCandidate[];
 /**
  * Read and parse an opencode config file.
  *
@@ -50,6 +57,8 @@ export interface ResolveApiKeyConfig<Source extends string> {
     extractFromAuth: (auth: unknown) => string | null;
     /** Source label for auth.json */
     authSource: Source;
+    /** Candidate config file paths to trust for provider-secret lookup. */
+    getConfigCandidates?: () => ConfigCandidate[];
 }
 /**
  * Resolve an API key from multiple sources with consistent priority.
@@ -68,6 +77,8 @@ export interface DiagnosticsConfig<Source extends string> {
     envVarNames: string[];
     /** Resolver function to get the current key result */
     resolve: () => Promise<ApiKeyResult<Source> | null>;
+    /** Candidate config file paths to report for provider-secret lookup. */
+    getConfigCandidates?: () => ConfigCandidate[];
 }
 /**
  * Get diagnostic info about API key configuration.