quotacap 0.0.19 → 0.0.20

package/README.md

@@ -1,69 +1,63 @@
 # QuotaCap
 
-**Cross-harness AI quota dashboard + harness-callable advice.**
+QuotaCap helps you get more from the AI coding subscriptions you already pay for: Claude Code, Codex, Kimi Code, and Grok. It tracks one current usage window and reset time for each plan, then estimates which plan to use next from remaining usage and recent pace when available.
 
-One place to see how much of each AI subscription you've used. Shows when it resets and what to burn next. Goal is 100% use at reset.
+[![npm](https://img.shields.io/npm/v/quotacap)](https://www.npmjs.com/package/quotacap)
+[![CI](https://github.com/carlosboeing/quotacap/actions/workflows/test.yml/badge.svg)](https://github.com/carlosboeing/quotacap/actions)
+[![license](https://img.shields.io/github/license/carlosboeing/quotacap)](LICENSE)
+[![node](https://img.shields.io/node/v/quotacap)](package.json)
 
-Polls pluggable adapters (Claude, Codex, Gemini, Kimi, Grok, OpenCode). Stores history in SQLite. Serves:
+## Features
 
-* **Web dashboard** at `http://localhost:8787` — banner + 7-day strip + table with burn vs ideal. Includes stale badges and degraded banner.
-* **CLI** `quotacap` / `npx quotacap` — `status`, `advise --json`, `ingest`, `web`, `init`, `daemon`
-* **MCP server** — `get_quotas`, `get_recommendation`, `forecast` for any harness
+- **Visibility**: remaining usage and reset time for one current window per connected plan
+- **Pacing**: recent usage when history is available, or an estimated pace while QuotaCap collects it
+- **Advice**: an estimate of which plan to use next so you can use more of each allowance without exhausting one early
+- **Dashboard, CLI, and MCP**: the same data and advice on every surface
 
-Runs local-only by default. No prompts or file contents leave your machine.
+## Providers
+
+| Provider | Source |
+|---|---|
+| Claude Code | Live |
+| Codex | Live |
+| Kimi Code | Live |
+| Grok | Live |
+| Antigravity / Gemini | Manual (`quotacap ingest`) |
+
+Live adapters reuse the matching CLI login.
 
 ## Install
 
 ```bash
-# Binary — no Node needed (macOS + Linux, arm64/x64)
+# Binary: macOS and Linux, arm64 and x64. No Node.
 curl -fsSL https://raw.githubusercontent.com/carlosboeing/quotacap/main/install.sh | sh
 
-# Or via npm (requires Node 22.13+; node:sqlite needs --experimental-sqlite before 22.13)
-npm install -g quotacap   # global install
-npx quotacap              # run without install
+# Or install with npm (Node 22.13+)
+npm install -g quotacap
 ```
 
-The binary is a self-contained Bun-compiled executable from GitHub Releases.
-The npm package runs the same CLI on Node. Both put `quotacap` on your PATH.
+The binary is a self-contained executable from GitHub Releases.
+The npm package runs the same CLI on Node. To run without a global install, replace `quotacap` with `npx quotacap` in any command, for example `npx quotacap web`.
 
 ## Quick start
 
 ```bash
-quotacap init
-quotacap ingest --provider kimi --text "Current week: 22% used · resets Aug 29 at 11am"
-quotacap status --json
-quotacap web                          # http://localhost:8787
-quotacap advise --json                # tries HTTP, falls back to local DB
-quotacap advise --json --task heavy
-```
-
-## HTTP API
+# Terminal 1: leave this running
+quotacap init                 # writes ~/.quotacap/config.json
+quotacap web                  # dashboard at http://localhost:8787
 
-```bash
-curl http://localhost:8787/health
-curl http://localhost:8787/api/quotas
-curl "http://localhost:8787/api/recommendation?task=any"
-curl -X POST http://localhost:8787/api/refresh
+# Terminal 2: after the dashboard table fills
+quotacap status
+quotacap advise
 ```
 
-* `GET /health` → `{ok, uptime, lastPollAt}`
-* `GET /api/quotas` → `Quota[]` with `stale`, `ageMs`
-* `GET /api/recommendation?task=any` → `{use, reason, advisories}`
-* `POST /api/refresh` → `{fulfilled, rejected, lastPollAt, degraded}` — debounced 60s, always 200
-* `GET /` → `web/dist/index.html` if built, else `web/index.html`
+`web` stays in the foreground and starts the daemon.
 
-## CLI
+For a provider without a live adapter:
 
+```bash
+quotacap ingest --provider agy --text "65% used · resets Sep 1"
 ```
-quotacap status [--json]
-quotacap advise [--json] [--task any|heavy|light]
-quotacap ingest --provider <id> --text "..."
-quotacap web [--port 8787]
-quotacap daemon [--foreground]
-quotacap init
-```
-
-`advise` fetches `http://localhost:$port/api/recommendation` with 2s timeout. Falls back to local `recommend()` when daemon is down.
 
 ## MCP
 
@@ -76,44 +70,34 @@ quotacap init
 ```
 
 Use `"command": "npx", "args": ["quotacap", "mcp"]` when installed via npm only.
-Tools: `get_quotas`, `get_recommendation`, `forecast`. Wrapper over HTTP. Set `QUOTACAP_URL` to override.
 
-## How it works
+Tools: `get_quotas`, `get_recommendation`, `forecast`.
 
-```
-Adapters (claude-cli ✓, manual ✓, others → manual-paste)
-  → daemon (poll 15m + jitter, SQLite ~/.quotacap/quotacap.db)
-  → HTTP :8787
-  → dashboard + CLI + MCP (same handler)
-```
+## Privacy
 
-Adapters are isolated. One failure does not block others. Uses `Promise.allSettled` and per-adapter catch. `POST /api/refresh` always 200.
+Bound to `127.0.0.1`, with usage history stored under `~/.quotacap/`. Live adapters contact provider usage endpoints or invoke the provider CLI using your existing login. Codex, Kimi, and Grok adapters may refresh expired OAuth tokens and update the CLI-owned credential file. QuotaCap stores no API keys.
 
-## Config
+## Docs
 
-`~/.quotacap/config.json`:
+- [Architecture](docs/architecture.md)
+- [Changelog](docs/CHANGELOG.md)
+- [Roadmap](docs/ROADMAP.md)
 
-```json
-{ "port": 8787, "pollMinutes": 15, "enabledProviders": ["claude"] }
-```
+## License
 
-DB is `~/.quotacap/quotacap.db` (`quotas`, `snapshots`).
+MIT. See [LICENSE](LICENSE).
 
-## Development
+<details>
+<summary>Development</summary>
 
 ```bash
-npm test              # vitest run (10 files) — builds first via pretest
+npm test              # vitest (builds first via pretest)
 bun test tests/bun/   # bun-runtime tests (sqlite adapter, MCP translation)
-npm run build         # vite build → embed web assets → tsc → flatten dist → chmod bin
-npm run build:bin     # bun build --compile (current platform, or pass targets)
-npx tsc --noEmit
+npm run build
+npm run build:bin
 ```
 
-The `store/db.ts` adapter picks `node:sqlite` on Node and `bun:sqlite` on Bun, so
-the same code runs as an npm package and as a compiled binary.
-
-See `.workbench/2-design/2026-08-28-quotacap-design.md` for spec. See `docs/ROADMAP.md` for next steps.
-
-## License
+The store uses `node:sqlite` on Node and `bun:sqlite` on Bun.
+The same code is an npm package and a compiled binary.
 
-MIT — see [LICENSE](LICENSE).
+</details>

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // generated by scripts/build-embed.mjs — do not edit
-export const VERSION = "0.0.19";
+export const VERSION = "0.0.20";

package/dist/version.js

@@ -1,2 +1,2 @@
 // generated by scripts/build-embed.mjs — do not edit
-export const VERSION = "0.0.19";
+export const VERSION = "0.0.20";

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "quotacap",
-  "version": "0.0.19",
+  "version": "0.0.20",
+  "description": "Local quota tracker for AI coding plans with a dashboard, CLI, MCP server, and next-plan recommendations.",
+  "license": "MIT",
+  "keywords": ["ai-coding", "cli", "mcp", "quota-tracker", "usage-limits", "usage-tracker", "claude-code", "codex", "kimi-code", "grok"],
   "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/carlosboeing/quotacap.git"
   },
+  "bugs": {
+    "url": "https://github.com/carlosboeing/quotacap/issues"
+  },
   "bin": {
     "quotacap": "dist/cli/index.js"
   },