From c1c24edb83d0cf6f182399fc0318d4c76aa1359a Mon Sep 17 00:00:00 2001
From: admin <admin@gitea.local>
Date: Tue, 6 Oct 2026 12:24:38 +0000
Subject: [PATCH] Add README.md

---
 README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..87b1ea1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+# UnoRouter Balance — Hermes Desktop Plugin
+
+Statusbar chip for [Hermes Agent](https://hermes-agent.nousresearch.com) Desktop
+showing how much UnoRouter credit you have left, plus a popover with the full
+breakdown.
+
+## What it shows
+
+Statusbar readout — `left/total (pct%)` of your spendable budget:
+
+```
+7.02/10 (70%)
+```
+
+Click opens a popover:
+
+- **UnoRouter** heading with a refresh button
+- **Available** — total spendable, with a progress bar
+- Subscription credit, plan name, time to weekly reset
+- Wallet balance, lifetime spend, request count
+
+Hover shows a one-line tip; details live in the popover only.
+
+## Install
+
+1. Create an **access token** (not an `sk-` API key) at
+   unorouter.com → Settings → Security → API access.
+2. Copy this folder to `$HERMES_HOME/desktop-plugins/unorouter-balance/`.
+   - Windows: `%LOCALAPPDATA%\hermes\desktop-plugins\unorouter-balance\`
+   - Linux/macOS: `~/.hermes/desktop-plugins/unorouter-balance/`
+   - The folder name must match the plugin id.
+3. Either paste the token into `DEFAULT_TOKEN` at the top of `plugin.js`, or
+   run ⌘K → **UnoRouter: set access token** (persisted per plugin).
+4. ⌘K → **Reload desktop plugins**.
+
+The app watches the folder, so later saves hot-reload in place.
+
+## Two credit pools
+
+This trips people up. UnoRouter keeps two separate pools:
+
+| Pool | Source | Expiry |
+|---|---|---|
+| Subscription credit | weekly delivery on a plan | resets weekly, does **not** carry over |
+| Wallet | one-time top-ups | never expires |
+
+`/api/user/self` → `quota` is the **wallet only**. It reads `0` on an active
+subscription, so a naive plugin reports "$0.00" to a paying subscriber. This
+plugin adds the subscription remainder (`/api/subscription/self`) and shows the
+sum, because `billing_preference` is `subscription_first` and the subscription
+carries `allow_wallet_overflow: true`.
+
+## API
+
+Both endpoints take the access token as `Authorization: Bearer <token>`.
+Quota units: `500000 == $1`.
+
+```
+GET /api/user/self          # wallet quota, lifetime spend, request count
+GET /api/subscription/self  # subscription credit, next reset, plan title
+```
+
+`/api/subscription/self` is **not in the public docs**. It answers 200.
+Dead ends: `/api/subscription`, `/api/billing`, `/api/plan` → 404;
+`/api/user/subscription`, `/api/user/plan` → 403.
+
+Most failures answer HTTP 200 with `success: false` — check that field, not the
+status code. Real 401/403 means a bad or revoked token.
+
+## Refresh
+
+Polls every 5 minutes via React Query (`REFRESH_MS`). Background polling is off
+by default, so an unfocused window doesn't tick. Manual refresh: the button in
+the popover, or ⌘K → **UnoRouter: refresh balance**.
+
+## Palette commands
+
+- `UnoRouter: refresh balance`
+- `UnoRouter: set access token`
+- `UnoRouter: open billing page`
+
+## Note on the token
+
+`DEFAULT_TOKEN` in this repo is empty on purpose — don't commit a live token.