burnwatch 0.8.2 → 0.10.0

package/skills/burnwatch-interview/SKILL.md

@@ -30,19 +30,33 @@ cd $PROJECT_ROOT && burnwatch interview --json
 
 Parse the JSON output. Do NOT show the raw JSON to the user.
 
-## Step 2: Present a brief overview, then start the interview
+## Step 2: BEFORE the interview — Auto-discover API keys
+
+**This is the most important step.** Before asking the user anything, try to find API keys automatically:
+
+1. **Check .env files** — Read `.env`, `.env.local`, `.env.development` for known key patterns
+2. **Check the interview JSON** — the `keySource` field shows if a key was already found in env or global config
+3. **Check probeResult** — if the JSON includes probe results, use them
+
+For each service where you found a key or probe data:
+- If `probeResult` has `confidence: "high"` — the plan is detected. Just confirm it.
+- If `probeResult` exists — mention what was found.
+- If a key exists but no probe — still good, tell the user you'll use it for live tracking.
+
+**The utopia is: you found the service, you found the key, you probed the API, and you just confirm.** Only ask questions when you genuinely don't know.
+
+## Step 3: Present a brief overview, then start the interview
 
 Open with a short summary (2-3 lines max), then immediately start with the first service:
 
-> I found **N services** in your project. Let me walk through each one to make sure we're tracking accurately.
+> I found **N services** in your project. I've already detected API keys for X of them and probed their billing APIs.
 >
-> First up — **Anthropic**. You're defaulted to "API Usage" at $100/mo.
-> [If probe data exists: "I checked your API — you've spent $47.23 this month."]
-> Does $100/mo feel right, or want to adjust?
+> First up — **Anthropic**. I found your API key in `.env` and checked your billing — you've spent $47.23 this month.
+> Want me to track your actual spend and alert you if it crosses a threshold? What monthly amount should trigger a warning?
 
 Then STOP. Wait for the user.
 
-## Step 3: Walk through services ONE AT A TIME
+## Step 4: Walk through services ONE AT A TIME
 
 ### Order: highest risk first
 
@@ -51,42 +65,39 @@ Then STOP. Wait for the user.
 3. **Infrastructure** — one at a time (Vercel, Supabase, AWS)
 4. **Free-tier / flat-rate** — batch these: "PostHog, Inngest, and Resend are all on free tiers at $0. Any of those need updating? If not, moving on."
 
-### For each paid service, present:
+### For each service, the approach depends on what you already know:
 
-1. **What was detected**: service name, current default plan, default budget
-2. **What the probe found** (if anything): actual spend, credits used, plan detected
-3. **One clear question**: "Does this look right?" or "What plan are you actually on?"
+#### If you have a key AND probe data (best case):
+> **Scrapfly** — I found your API key and probed the billing API.
+> You're on the **Pro plan** ($100/mo, 1M credits). 250K credits used this month.
+> Want me to track credit consumption and alert at a threshold? [default: alert at 80% of 1M]
 
-Example per-service message:
+#### If you have a key but NO probe data:
+> **Vercel** — I found a token in your env. I'll use it for live billing tracking.
+> What plan are you on? (Hobby is free, Pro is $20/mo)
 
-> **Scrapfly** — defaulted to Pro ($100/mo, 1M credits).
-> Probe detected: Pro plan confirmed, 250K/1M credits used this month.
-> Keep the $100/mo budget? [Y/adjust]
+#### If you have NO key but a billing API exists:
+> **Anthropic** — this service has a billing API but I need an admin key to access it.
+> You can create one at console.anthropic.com → Settings → Admin API Keys (sk-ant-admin-*).
+> Want to provide one now, or should I just set a budget alert?
 
-Then STOP. Wait for response.
+#### If there's NO billing API (Gemini, Inngest, etc.):
+> **Gemini** — no billing API available for this service.
+> What plan are you on? I'll track your fixed cost and flag any activity that might cause overages.
 
-### After the user responds:
+### Smart inference:
 
-1. Run `burnwatch configure` with their answer
-2. Confirm what was written (one line)
-3. Present the NEXT service
+- If you see `gpt-4o-mini` or other lightweight models in the codebase, infer low/free tier usage — don't suggest $100 budgets
+- If a service is on a paid plan (e.g., GPT Plus at $20/mo), ask if they want to track API overages beyond their subscription
+- For flat-rate plans, the "budget" IS the plan cost — don't ask for a separate budget number
 
-Example:
+### Budget philosophy:
 
-> Got it — Scrapfly set to Pro, $100/mo budget. ✅
->
-> Next — **Stripe**. Defaulted to "Standard (2.9% + 30¢)" at $50/mo.
-> I checked your balance: $1,247.83 available.
-> $50/mo budget for Stripe's processing fees — sound right?
+- **LIVE services with billing API access**: Default to "track actual spend, alert at threshold" — NOT an arbitrary budget. Ask: "At what spend level should I flag a warning?"
+- **CALC services (flat-rate)**: Budget = plan cost. Only ask about overages if the service has overage pricing.
+- **BLIND services**: Ask for a budget cap as a safety net since we can't see actual spend.
 
-Then STOP again.
-
-### For free-tier services, batch them:
-
-> **PostHog**, **Inngest**, and **Resend** are all set to free tiers at $0/mo.
-> Any of those need updating, or should I lock them in and move on?
-
-## Step 4: Configure each service
+## Step 5: Configure each service
 
 After the user confirms or corrects, write it back immediately:
 
@@ -104,37 +115,51 @@ To exclude a service:
 burnwatch configure --service <id> --exclude
 ```
 
+**Check the JSON output for `tierNote`** — if the configure command returns a `tierNote`, relay it to the user. This happens when a key is saved but the service doesn't have a billing connector yet (key works for probes but not live polling).
+
 Always check the JSON output for `"success": true`.
 
-## Step 5: Wrap up
+## Step 6: Wrap up
 
 After all services are configured, run `burnwatch status` and present the brief:
 
 > All done! Here's your updated spend brief:
 > [burnwatch status output]
 >
-> N services tracked, total budget $X/mo.
+> N services with live billing, M estimated, K need API keys.
+> The brief appears automatically at the start of every Claude Code session.
 
 ## Key Behaviors
 
 - **Lead with what you know.** If the probe detected their plan, state it confidently and ask for confirmation — don't make them pick from a list.
+- **Discovery first, questions second.** Search .env files, check for existing keys, try probes. Only ask the user when you genuinely can't figure it out.
 - **One question at a time.** Never ask about budget AND plan AND API key in the same message. If the plan is confirmed, ask about budget. If budget is confirmed, offer the API key option.
 - **Be brief.** Each message should be 2-4 lines, not paragraphs.
 - **Respect shortcuts.** If the user says "defaults are fine for everything" — configure them all and show the summary. Don't force 14 rounds.
-- **If they offer a key unprompted**, use it immediately and show what the probe found.
+- **If they offer a key unprompted**, use it immediately — run `burnwatch configure --service <id> --key <KEY>` and tell them what the probe found.
 - **Surface concerns.** If Anthropic spend is $87 of $100 budget, say so. If Scrapfly credits are 85% consumed, flag it.
-
-## Probe Data Reference
-
-| Service | Confidence | What's detected |
-|---------|-----------|-----------------|
-| Scrapfly | high | Plan name, credits used/total |
-| Vercel | high | Plan tier (hobby/pro/enterprise) |
-| Supabase | high | Plan tier (free/pro/team) |
-| Anthropic | medium | USD spend this billing period |
-| OpenAI | medium | Token usage this period |
-| Stripe | medium | Balance (available + pending) |
-| Browserbase | medium | Session count, browser hours |
-| Upstash | low | Database count (key validation) |
-| PostHog | low | Org found (key validation) |
-| Gemini, Resend, Inngest, Voyage AI, AWS | none | No API — ask user directly |
+- **For services that offer to create a token** (Vercel, Supabase), give the user the direct URL to create one and offer to wait while they do it.
+
+## Services with Billing Connectors (can do LIVE tracking)
+
+| Service | Key Type | Where to Get It |
+|---------|----------|-----------------|
+| Anthropic | Admin key (sk-ant-admin-*) | console.anthropic.com → Settings → Admin API Keys |
+| OpenAI | Admin key (sk-admin-*) | platform.openai.com → Settings → API Keys |
+| Vercel | Personal access token | vercel.com/account/tokens |
+| Scrapfly | API key | scrapfly.io/dashboard |
+| Supabase | Personal access token (PAT) | supabase.com/dashboard → Account → Access Tokens |
+| Browserbase | API key | browserbase.com → Settings → API Keys |
+
+## Services WITHOUT Billing Connectors (CALC/BLIND only)
+
+| Service | Why | Workaround |
+|---------|-----|-----------|
+| Stripe | Complex — tracks customer payments, not Stripe's fees to you | Set budget based on expected processing volume |
+| Upstash | Stats API exists but no cost data | Set budget based on plan tier |
+| PostHog | Free tier common, org API limited | Set plan cost, track overages manually |
+| Gemini | No billing API | Set plan cost |
+| Resend | No billing API | Set plan cost |
+| Inngest | No billing API | Set plan cost (Free: $0, Pro: varies) |
+| Voyage AI | No billing API | Set budget based on expected token usage |
+| AWS | Complex IAM requirements | Set budget, recommend checking AWS console |