docs: README overhaul — add analyze.js, wake integration, Quick start, fix provider table and architecture

Six changes:
- Add ## Quick start block (monitor.js, analyze.js, token-status.sh)
- Add ## Analysis section with all 8 analyze.js subcommands and output descriptions
- Add ## Wake integration section — token-status.sh docs, output format, cache guard note
- Provider support table: add google-gemini and xai-* rows
- Architecture block: add analyze.js, gemini.js, xai.js, docs/analyze.md
- Related: add token-status.sh as first item, fix issue link to trentuna/token-monitor#1

164/164 tests pass.

README.md

@@ -4,6 +4,14 @@ Modular LLM API quota and usage visibility tool. Extracts rate-limit and usage d
 
 **Why it exists:** team-vigilio hit its 7-day rate limit (9+ days of 429s). api-ateam ran out of credit mid-session. We kept flying blind. This tool surfaces quota health before the failure.
 
+## Quick start
+
+```bash
+node monitor.js          # run now — human-readable output + log
+node analyze.js          # analyze accumulated logs — burn rates, rotation
+~/os/token-status.sh     # what Vigilio's wake prompt sees (automated path)
+```
+
 ## Usage
 
 ```bash
@@ -14,6 +22,29 @@ node monitor.js --provider team-nadja    # single provider
 node monitor.js --no-log                 # suppress log file write
 ```
 
+## Analysis
+
+```bash
+node analyze.js                         # full report
+node analyze.js --burn-rate             # burn rate per account
+node analyze.js --weekly                # weekly budget reconstruction
+node analyze.js --stagger               # reset schedule (next 48h)
+node analyze.js --rotation              # rotation recommendation
+node analyze.js --json                  # JSON output (all sections)
+node analyze.js --provider team-nadja   # filter to one provider
+node analyze.js --prune [--dry-run]     # archive and prune logs > 30 days
+```
+
+**Burn Rate** — delta analysis of 7d utilization over time, projected exhaustion at current rate.
+
+**Reset Schedule** — providers resetting within the next 48 hours, sorted ascending by time to reset.
+
+**Weekly Reconstruction** — peak and average 7d utilization per provider per ISO week. Shows exhaustion events.
+
+**Rotation Recommendation** — ranked provider list by headroom, deprioritizing maxed/rejected/invalid-key accounts.
+
+**Underspend Alerts** — active accounts with ≥ 40% of 5h window unused and < 2h until reset.
+
 ## Example output
 
 ```
@@ -80,6 +111,8 @@ Overall: 1 CRITICAL, 3 OK, 3 UNKNOWN
 | team-vigilio, team-ludo, team-molto, team-nadja, team-buio | Anthropic Teams (direct) | 5h/7d utilization (0–100%), status, reset countdown, severity |
 | shelley-proxy | Shelley/exe.dev proxy | Token headroom, request headroom, per-call USD cost |
 | api-ateam | Anthropic API (pay-per-use) | Key validity only — no billing API exists |
+| google-gemini | Gemini API (free tier) | Quota violation detail, retry delay, key validity |
+| xai-face, xai-amy, xai-murdock, xai-ba, xai-vigilio | xAI/Grok | Request/token remaining counts, rate limit status |
 
 ## Severity levels
 
@@ -124,14 +157,19 @@ grep '"team-vigilio"' ~/.logs/token-monitor/*.jsonl | \
 
 ```
 monitor.js              — CLI entrypoint, orchestrates probes
+analyze.js              — analysis CLI (burn rates, weekly, stagger, rotation)
 providers/
   index.js              — reads ~/.pi/agent/models.json, returns typed provider list
   anthropic-teams.js    — unified schema parser (oat01 keys, all team-* providers)
   anthropic-api.js      — pay-per-use (api03 keys) — reports "no billing data"
   shelley-proxy.js      — classic schema + Exedev-Gateway-Cost header
+  gemini.js             — Gemini API (free tier, quota via response body)
+  xai.js                — x.ai/Grok (rate-limit headers)
 logger.js               — JSONL log to ~/.logs/token-monitor/
 report.js               — human-readable summary + severity logic
 test.js                 — test suite (run: node test.js)
+docs/
+  analyze.md            — analysis CLI full reference
 ```
 
 ## How to add a new provider
@@ -152,6 +190,30 @@ The tool makes one minimal API call per provider to extract headers:
 
 ## Related
 
+- `~/os/token-status.sh` — wake-prompt integration (calls monitor.js, formats for beat.sh)
 - `~/projects/provider-check/` — predecessor (liveness only, no quota depth)
 - `~/.pi/agent/models.json` — provider configuration source
-- Forgejo issue: trentuna/a-team#91
+- Forgejo issue: trentuna/token-monitor#1
+
+## Wake integration
+
+`~/os/token-status.sh` is the automated interface. It runs `monitor.js --json`
+and formats the output into a compact summary block for injection into
+Vigilio's wake prompt via `beat.sh`.
+
+```bash
+# Manual invocation (same as what the wake prompt sees)
+~/os/token-status.sh
+
+# Output format:
+## Token Economics
+Anthropic Teams (5 seats):
+  team-vigilio     ✗ MAXED 7d:100% resets 23h
+  team-molto       ✓ 5h:32% 7d:45% resets 4h
+  ...
+→ Current recommendation: use team-molto | avoid team-vigilio
+```
+
+File location: `~/os/token-status.sh`  
+Called by: `~/os/beat.sh` (Vigilio wake script)  
+Uses: `monitor.js --json` with 20-minute cache guard (won't double-probe within a session)