opencode-token-tracker 1.6.5 → 1.7.1

package/dist/bin/opencode-tokens.js

@@ -1,11 +1,17 @@
 #!/usr/bin/env node
 import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { BUILTIN_PRICING, DEFAULT_CONFIG, findModelConfigPricing, formatCost, formatTokens, getStartOfDay, getStartOfMonth, getStartOfWeek, validateConfig } from "../lib/shared.js";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { BUILTIN_PRICING, BUILTIN_PRICING_META, DEFAULT_CONFIG, formatCost, formatLocalDateKey, formatTokens, getStartOfDay, getStartOfMonth, getStartOfWeek, hasBillableTokenUsage, resolvePricingStatus, round2, validateConfig, } from "../lib/shared.js";
 const CONFIG_DIR = join(homedir(), ".config", "opencode");
 const CONFIG_FILE = join(CONFIG_DIR, "token-tracker.json");
 const LOG_FILE = join(CONFIG_DIR, "logs", "token-tracker", "tokens.jsonl");
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const OPENCODE_CONFIG_FILES = [
+    join(CONFIG_DIR, "opencode.json"),
+    join(CONFIG_DIR, "opencode.jsonc"),
+];
 // ============================================================================
 // Helpers
 // ============================================================================
@@ -20,6 +26,41 @@ function truncateSessionId(sessionId) {
         return "unknown";
     return sessionId.length > 16 ? `${sessionId.slice(0, 14)}…` : sessionId;
 }
+function formatAge(ts) {
+    const diffMs = Date.now() - ts;
+    if (diffMs < 60_000)
+        return "less than 1m ago";
+    const minutes = Math.floor(diffMs / 60_000);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    return `${Math.floor(hours / 24)}d ago`;
+}
+const ZERO_COST_PROVIDER_HINTS = [
+    { match: "copilot", reason: "subscription/bundled provider" },
+    { match: "cursor", reason: "subscription/bundled provider" },
+    { match: "free", reason: "free provider name" },
+    { match: "ollama", reason: "local/self-hosted provider" },
+    { match: "lmstudio", reason: "local/self-hosted provider" },
+    { match: "lm-studio", reason: "local/self-hosted provider" },
+    { match: "llamacpp", reason: "local/self-hosted provider" },
+    { match: "llama.cpp", reason: "local/self-hosted provider" },
+    { match: "local", reason: "local/self-hosted provider" },
+    { match: "localhost", reason: "local/self-hosted provider" },
+    { match: "self-hosted", reason: "local/self-hosted provider" },
+    { match: "selfhosted", reason: "local/self-hosted provider" },
+];
+function getZeroCostProviderMatch(provider) {
+    const normalized = provider.toLowerCase().replace(/\s+/g, "");
+    for (const hint of ZERO_COST_PROVIDER_HINTS) {
+        if (normalized.includes(hint.match)) {
+            return { provider, reason: hint.reason };
+        }
+    }
+    return undefined;
+}
 function parseArgs(args) {
     const positional = [];
     const flags = new Map();
@@ -49,7 +90,7 @@ function parseArgs(args) {
             i++;
             continue;
         }
-        if (arg.startsWith("-") && arg.length === 2 && arg !== "--") {
+        if (/^-[A-Za-z]$/.test(arg)) {
             const next = args[i + 1];
             if (next && !next.startsWith("-")) {
                 flags.set(arg.slice(1), next);
@@ -109,7 +150,7 @@ function loadEntries(since) {
                     shouldStop = true;
                     break;
                 }
-                if (!entry.input && !entry.output)
+                if (!hasBillableTokenUsage(entry))
                     continue;
                 entries.push(entry);
             }
@@ -122,7 +163,7 @@ function loadEntries(since) {
     if (!shouldStop && leftover.trim()) {
         try {
             const entry = JSON.parse(leftover.trim());
-            if (entry.type === "tokens" && (!since || entry._ts >= since) && (entry.input || entry.output)) {
+            if (entry.type === "tokens" && (!since || entry._ts >= since) && hasBillableTokenUsage(entry)) {
                 entries.push(entry);
             }
         }
@@ -233,7 +274,7 @@ function printTable(title, groups, labelHeader) {
 function printDailyBreakdown(entries) {
     const byDay = groupBy(entries, (e) => {
         const date = new Date(e._ts);
-        return date.toISOString().slice(0, 10);
+        return formatLocalDateKey(date);
     });
     const sorted = Array.from(byDay.entries()).sort((a, b) => b[0].localeCompare(a[0]));
     if (sorted.length === 0) {
@@ -258,6 +299,38 @@ function printDailyBreakdown(entries) {
 // ============================================================================
 // Commands
 // ============================================================================
+const STATS_BREAKDOWNS = ["model", "agent", "provider", "day", "daily", "session", "all"];
+const STATS_PERIODS = ["today", "week", "month", "all"];
+const TOP_LEVEL_COMMANDS = ["budget", "doctor", "pricing", "models", "config", "export", "trend"];
+function isStatsBreakdown(value) {
+    return STATS_BREAKDOWNS.includes(value);
+}
+function isStatsPeriod(value) {
+    return STATS_PERIODS.includes(value);
+}
+function isTopLevelCommand(value) {
+    return TOP_LEVEL_COMMANDS.includes(value);
+}
+function getStatsBreakdown(flags) {
+    const longValue = flagValue(flags, "by");
+    const shortValue = flagValue(flags, "b");
+    if (flags.has("by") && !longValue) {
+        failCli("Missing value for --by", "Usage: opencode-tokens [today|week|month|all] --by model|agent|provider|daily|session|all");
+        return undefined;
+    }
+    if (flags.has("b") && !shortValue) {
+        failCli("Missing value for -b", "Usage: opencode-tokens [today|week|month|all] -b model|agent|provider|daily|session|all");
+        return undefined;
+    }
+    const breakdown = longValue ?? shortValue;
+    if (!breakdown)
+        return undefined;
+    if (!isStatsBreakdown(breakdown)) {
+        failCli(`Unsupported stats breakdown: ${breakdown}`, "Allowed breakdowns: model, agent, provider, daily, day, session, all");
+        return undefined;
+    }
+    return breakdown;
+}
 function cmdStats(period, breakdown) {
     const now = new Date();
     let since;
@@ -314,17 +387,20 @@ function cmdStats(period, breakdown) {
 function cmdPricing() {
     const config = loadConfig();
     console.log(`
-  Built-in Pricing Table (USD per 1M tokens) - Updated 2026-02-11
+  Built-in Pricing Table (USD per 1M tokens)
   ══════════════════════════════════════════════════════════════════
+  Pricing last updated:  ${BUILTIN_PRICING_META.pricingLastUpdated}
+  Metadata last updated: ${BUILTIN_PRICING_META.metadataLastUpdated}
+  Source:                ${BUILTIN_PRICING_META.source}
 `);
     // Group by provider
     const groups = {
-        "Anthropic Claude": ["claude-opus-4.6", "claude-opus-4.5", "claude-sonnet-4.5", "claude-sonnet-4", "claude-haiku-4.5", "claude-haiku-4", "claude-opus-4.1", "claude-opus-4", "claude-haiku-3"],
-        "OpenAI": ["gpt-5.2", "gpt-5.2-pro", "gpt-5-mini", "gpt-5.1", "gpt-5", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini", "o3", "o3-mini", "o4-mini", "o1", "o1-mini"],
-        "DeepSeek": ["deepseek-chat", "deepseek-reasoner"],
-        "Google Gemini": ["gemini-3-pro", "gemini-3-pro-preview", "gemini-3-flash", "gemini-3-flash-preview", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-2.0-flash", "gemini-2.0-flash-lite"],
+        "Anthropic Claude": ["claude-opus-4.8", "claude-opus-4.7", "claude-opus-4.6", "claude-opus-4.5", "claude-sonnet-4.6", "claude-sonnet-4.5", "claude-sonnet-4", "claude-haiku-4.5", "claude-haiku-4", "claude-opus-4.1", "claude-opus-4", "claude-haiku-3"],
+        "OpenAI": ["gpt-5.5", "gpt-5.5-pro", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.4-pro", "gpt-5.3-codex", "gpt-5.3-chat-latest", "gpt-5.2", "gpt-5.2-pro", "gpt-5-mini", "gpt-5-nano", "gpt-5.1", "gpt-5.1-chat-latest", "gpt-5.1-codex-max", "gpt-5.1-codex", "gpt-5.1-codex-mini", "gpt-5", "gpt-5-chat-latest", "gpt-5-codex", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini", "o3", "o3-mini", "o4-mini", "o1", "o1-mini"],
+        "DeepSeek": ["deepseek-chat", "deepseek-reasoner", "deepseek-v4-pro"],
+        "Google Gemini": ["gemini-3.1-pro-preview", "gemini-3-pro", "gemini-3-pro-preview", "gemini-3.5-flash", "gemini-3-flash", "gemini-3-flash-preview", "gemini-3.1-flash-lite", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-2.0-flash", "gemini-2.0-flash-lite"],
     };
-    const modelWidth = 20;
+    const modelWidth = 24;
     const priceWidth = 10;
     for (const [group, models] of Object.entries(groups)) {
         console.log(`  ${group}`);
@@ -347,6 +423,12 @@ function cmdPricing() {
     if (Object.keys(config.models || {}).length > 0) {
         console.log(`  * = overridden in config`);
     }
+    console.log(`  Fallback Pricing Notice:`);
+    console.log(`    When a model is not matched in the built-in pricing table or user configuration,`);
+    console.log(`    it falls back to the default rate ($1.0 / $4.0 per 1M tokens).`);
+    console.log(`    You can easily override it in your configuration.`);
+    console.log(`    ${BUILTIN_PRICING_META.notes}`);
+    console.log();
 }
 function cmdModels() {
     const entries = loadEntries();
@@ -383,29 +465,17 @@ function cmdModels() {
     const statusWidth = 12;
     console.log(`  ${padRight("Model", modelWidth)}  ${padRight("Provider", providerWidth)}  ${padLeft("Msgs", countWidth)}  ${padRight("Pricing", statusWidth)}`);
     console.log(`  ${"-".repeat(modelWidth)}  ${"-".repeat(providerWidth)}  ${"-".repeat(countWidth)}  ${"-".repeat(statusWidth)}`);
+    const defaultModels = [];
+    const zeroCostProviderModels = [];
     for (const { model, provider, count } of sorted) {
-        let status;
-        // Mirror the runtime pricing resolution order (getModelPricing in index.ts)
-        if (config.providers?.[provider]) {
-            status = "provider cfg";
-        }
-        else if (findModelConfigPricing(config.models, model, provider, false)) {
-            status = "model cfg";
-        }
-        else if (BUILTIN_PRICING[model]) {
-            status = "built-in";
-        }
-        else {
-            const modelLower = model.toLowerCase();
-            const hasBuiltinPartial = Object.keys(BUILTIN_PRICING).some(k => k !== "_default" && modelLower.includes(k.toLowerCase()));
-            if (hasBuiltinPartial) {
-                status = "built-in";
-            }
-            else if (findModelConfigPricing(config.models, model, provider, true)) {
-                status = "model cfg";
+        const status = resolvePricingStatus(config, model, provider);
+        if (status === "default") {
+            const zeroCostMatch = getZeroCostProviderMatch(provider);
+            if (zeroCostMatch) {
+                zeroCostProviderModels.push({ model, provider, count, reason: zeroCostMatch.reason });
             }
             else {
-                status = "default";
+                defaultModels.push({ model, provider, count });
             }
         }
         console.log(`  ${padRight(model, modelWidth)}  ${padRight(provider, providerWidth)}  ${padLeft(count.toString(), countWidth)}  ${padRight(status, statusWidth)}`);
@@ -417,28 +487,219 @@ function cmdModels() {
     console.log(`    model cfg    = overridden by models config`);
     console.log(`    default      = unknown model, using $1/$4 per 1M tokens`);
     console.log();
+    if (zeroCostProviderModels.length > 0 || defaultModels.length > 0) {
+        console.log(`  Next steps for default pricing:`);
+        const total = zeroCostProviderModels.length + defaultModels.length;
+        console.log(`    ${total} model/provider ${total === 1 ? "pair uses" : "pairs use"} the default $1/$4 estimate.`);
+        console.log(`    Run: opencode-tokens config init`);
+        console.log(`    Or:  opencode-tokens config generate`);
+        console.log();
+        if (zeroCostProviderModels.length > 0) {
+            console.log(`    Likely zero-cost provider overrides to review:`);
+            for (const { provider, reason } of dedupeZeroCostProviderMatches(zeroCostProviderModels).slice(0, 5)) {
+                console.log(`    - ${provider} (${reason}): { "input": 0, "output": 0 }`);
+            }
+            if (zeroCostProviderModels.length > 5) {
+                console.log(`    - ...and ${zeroCostProviderModels.length - 5} more model/provider pairs`);
+            }
+            console.log();
+        }
+        if (defaultModels.length > 0) {
+            console.log(`    Model overrides to review before saving:`);
+            for (const { model, provider, count } of defaultModels.slice(0, 5)) {
+                console.log(`    - ${model} (${provider}, ${count} msgs): { "input": 1, "output": 4 }`);
+            }
+            if (defaultModels.length > 5) {
+                console.log(`    - ...and ${defaultModels.length - 5} more`);
+            }
+            console.log();
+        }
+    }
+}
+function cmdDoctor() {
+    const entries = loadEntries();
+    const configDiagnostics = inspectTrackerConfig();
+    const pluginDiagnostics = inspectOpenCodePluginConfig();
+    console.log(`
+  OpenCode Token Tracker Doctor
+  ══════════════════════════════════════════════════════════════════
+`);
+    console.log(`  CLI`);
+    console.log(`    Entry: ${process.argv[1] ?? "unknown"}`);
+    console.log(`    Package version: ${readPackageJsonVersion()}`);
+    console.log();
+    console.log(`  OpenCode plugin config`);
+    if (pluginDiagnostics.found) {
+        console.log(`    File: ${pluginDiagnostics.path}`);
+        console.log(`    Plugin entry: ${pluginDiagnostics.hasPlugin ? "found" : "missing"}`);
+    }
+    else {
+        console.log(`    File: not found (${OPENCODE_CONFIG_FILES.map((p) => p.replace(`${homedir()}/`, "~/")).join(" or ")})`);
+        console.log(`    Plugin entry: unknown`);
+    }
+    console.log();
+    console.log(`  Tracker config`);
+    console.log(`    File: ${CONFIG_FILE}`);
+    console.log(`    Status: ${configDiagnostics.exists ? "exists" : "using defaults"}`);
+    if (configDiagnostics.parseError) {
+        console.log(`    Warning: ${configDiagnostics.parseError}`);
+    }
+    for (const warning of configDiagnostics.warnings) {
+        console.log(`    Warning: ${warning}`);
+    }
+    const budget = configDiagnostics.config.budget;
+    const hasBudget = Boolean(budget.daily || budget.weekly || budget.monthly);
+    console.log(`    Budget: ${hasBudget ? "configured" : "not configured"}`);
+    console.log();
+    console.log(`  Token log`);
+    if (!existsSync(LOG_FILE)) {
+        console.log(`    File: not found (${LOG_FILE})`);
+        console.log(`    Entries: 0`);
+    }
+    else {
+        const latest = entries[entries.length - 1];
+        console.log(`    File: ${LOG_FILE}`);
+        console.log(`    Entries: ${entries.length}`);
+        console.log(`    Latest: ${latest ? `${new Date(latest._ts).toISOString()} (${formatAge(latest._ts)})` : "none"}`);
+    }
+    console.log();
+    const defaultModels = getDefaultModelProviders(entries, configDiagnostics.config);
+    const zeroCostProviders = dedupeZeroCostProviderMatches(defaultModels.flatMap(({ model, provider, count }) => {
+        const match = getZeroCostProviderMatch(provider);
+        return match ? [{ model, provider, count, reason: match.reason }] : [];
+    }));
+    console.log(`  Pricing`);
+    console.log(`    Built-in pricing updated: ${BUILTIN_PRICING_META.pricingLastUpdated}`);
+    console.log(`    Default-priced model/provider pairs: ${defaultModels.length}`);
+    for (const { model, provider, count } of defaultModels.slice(0, 5)) {
+        console.log(`    - ${model} (${provider}, ${count} msgs)`);
+    }
+    if (defaultModels.length > 5) {
+        console.log(`    - ...and ${defaultModels.length - 5} more`);
+    }
+    if (zeroCostProviders.length > 0) {
+        console.log(`    Likely zero-cost providers:`);
+        for (const { provider, reason } of zeroCostProviders.slice(0, 5)) {
+            console.log(`    - ${provider} (${reason})`);
+        }
+    }
+    console.log();
+    const nextSteps = [];
+    if (!pluginDiagnostics.found || !pluginDiagnostics.hasPlugin) {
+        nextSteps.push(`Add "opencode-token-tracker" to your OpenCode plugin config.`);
+    }
+    if (!existsSync(LOG_FILE) || entries.length === 0) {
+        nextSteps.push(`Run an OpenCode request, then check ${LOG_FILE}.`);
+    }
+    if (configDiagnostics.parseError || configDiagnostics.warnings.length > 0) {
+        nextSteps.push(`Fix ${CONFIG_FILE} or regenerate it with: opencode-tokens config generate`);
+    }
+    if (defaultModels.length > 0) {
+        nextSteps.push(`Review default pricing with: opencode-tokens models`);
+        nextSteps.push(`Generate suggested overrides with: opencode-tokens config init`);
+    }
+    if (!hasBudget) {
+        nextSteps.push(`Configure optional budgets with: opencode-tokens config init`);
+    }
+    console.log(`  Next steps`);
+    if (nextSteps.length === 0) {
+        console.log(`    No obvious issues found.`);
+    }
+    else {
+        for (const step of nextSteps) {
+            console.log(`    - ${step}`);
+        }
+    }
+    console.log();
+}
+function readPackageJsonVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"));
+        return typeof pkg.version === "string" ? pkg.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function inspectOpenCodePluginConfig() {
+    for (const path of OPENCODE_CONFIG_FILES) {
+        if (!existsSync(path))
+            continue;
+        const raw = readFileSync(path, "utf-8");
+        return {
+            found: true,
+            path,
+            hasPlugin: raw.includes("opencode-token-tracker"),
+        };
+    }
+    return { found: false, hasPlugin: false };
+}
+function inspectTrackerConfig() {
+    if (!existsSync(CONFIG_FILE)) {
+        return { exists: false, config: DEFAULT_CONFIG, warnings: [] };
+    }
+    try {
+        const raw = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+        const result = validateConfig(raw);
+        return { exists: true, config: result.config, warnings: result.warnings };
+    }
+    catch {
+        return { exists: true, config: DEFAULT_CONFIG, warnings: [], parseError: "Config file is not valid JSON, using defaults" };
+    }
+}
+function getDefaultModelProviders(entries, config) {
+    const counts = new Map();
+    for (const e of entries) {
+        const model = e.model ?? "unknown";
+        const provider = e.provider ?? "unknown";
+        if (model === "unknown" || provider === "unknown")
+            continue;
+        const key = `${model}|${provider}`;
+        let item = counts.get(key);
+        if (!item) {
+            item = { model, provider, count: 0, lastUsed: 0 };
+            counts.set(key, item);
+        }
+        item.count++;
+        item.lastUsed = Math.max(item.lastUsed, e._ts);
+    }
+    return Array.from(counts.values())
+        .filter(({ model, provider }) => resolvePricingStatus(config, model, provider) === "default")
+        .sort((a, b) => b.lastUsed - a.lastUsed);
+}
+function dedupeZeroCostProviderMatches(items) {
+    const providers = new Map();
+    for (const item of items) {
+        if (!providers.has(item.provider)) {
+            providers.set(item.provider, { provider: item.provider, reason: item.reason });
+        }
+    }
+    return Array.from(providers.values());
 }
 function cmdConfig(positional) {
     const action = positional[1];
     const config = loadConfig();
     const entries = loadEntries();
     if (action === "init" || action === "generate") {
-        // Get unique providers from logs
+        // Get unique providers and model+provider combinations from logs
         const providers = new Set();
-        const models = new Set();
+        const modelProviders = new Set();
         for (const e of entries) {
             if (e.provider)
                 providers.add(e.provider);
-            if (e.model)
-                models.add(e.model);
+            const model = e.model ?? "unknown";
+            const provider = e.provider ?? "unknown";
+            modelProviders.add(`${model}|${provider}`);
         }
-        // Find providers/models without built-in pricing
-        const unknownModels = Array.from(models).filter(m => {
-            if (BUILTIN_PRICING[m])
-                return false;
-            const hasMatch = Object.keys(BUILTIN_PRICING).some(k => k !== "_default" && m.toLowerCase().includes(k.toLowerCase()));
-            return !hasMatch;
-        });
+        // Estimate daily avg from last 7 days
+        const now = Date.now();
+        const sevenDaysAgo = now - 7 * 24 * 60 * 60 * 1000;
+        const recentEntries = entries.filter(e => e._ts >= sevenDaysAgo);
+        const totalSpent = recentEntries.reduce((sum, e) => sum + (e.cost ?? 0), 0);
+        const dailyAvg = totalSpent / 7;
+        const dailyLimit = dailyAvg > 0 ? Math.max(0.5, round2(dailyAvg * 1.5)) : 5;
+        const weeklyLimit = dailyAvg > 0 ? Math.max(0.5, round2(dailyAvg * 7 * 1.3)) : 25;
+        const monthlyLimit = dailyAvg > 0 ? Math.max(0.5, round2(dailyAvg * 30 * 1.2)) : 100;
         const exampleConfig = {
             providers: {},
             models: {},
@@ -448,25 +709,78 @@ function cmdConfig(positional) {
                 showOnIdle: true,
             },
             budget: {
-                daily: 5,
-                weekly: 25,
-                monthly: 100,
+                daily: dailyLimit,
+                weekly: weeklyLimit,
+                monthly: monthlyLimit,
                 warnAt: 0.8,
             },
         };
-        // Add providers as comments/examples
+        const suggestedProviders = [];
+        const suggestedProviderNames = new Set();
+        // Add likely zero-cost providers detected from logs.
         for (const provider of providers) {
-            // Common free providers
-            if (provider.includes("copilot") || provider.includes("cursor") || provider.includes("free")) {
+            const zeroCostMatch = getZeroCostProviderMatch(provider);
+            if (zeroCostMatch) {
                 exampleConfig.providers[provider] = { input: 0, output: 0 };
+                suggestedProviders.push(zeroCostMatch);
+                suggestedProviderNames.add(provider);
             }
         }
-        // Add unknown models
-        for (const model of unknownModels) {
-            exampleConfig.models[model] = { input: 1, output: 4 };
+        const suggestedModels = [];
+        // Add unknown/fallback models where status is "default"
+        for (const mp of modelProviders) {
+            const [model, provider] = mp.split("|");
+            if (model === "unknown" || provider === "unknown")
+                continue;
+            if (suggestedProviderNames.has(provider))
+                continue;
+            const status = resolvePricingStatus(config, model, provider);
+            if (status === "default") {
+                exampleConfig.models[model] = { input: 1, output: 4 };
+                suggestedModels.push(`${model} (${provider})`);
+            }
         }
-        // Print explanation first
-        console.log(`
+        // Construct Dynamic Usage-Aware Suggestions Summary
+        let suggestionsSummary = `
+  📢 Usage-Aware Suggestions Summary
+  ══════════════════════════════════════════════════════════════════
+  - Analyzed timeframe: Last 7 days
+  - Found ${entries.length} historical usage entries in total.
+  - Calculated 7-day average daily cost: $${round2(dailyAvg).toFixed(4)}
+`;
+        if (dailyAvg > 0) {
+            suggestionsSummary += `
+  Recommended Budget Limits (derived from daily avg $${round2(dailyAvg).toFixed(4)}):
+    - Daily Limit   : $${dailyLimit.toFixed(2)} (Avg * 1.5 buffer, clamped min $0.50)
+    - Weekly Limit  : $${weeklyLimit.toFixed(2)} (Avg * 7 * 1.3 buffer, clamped min $0.50)
+    - Monthly Limit : $${monthlyLimit.toFixed(2)} (Avg * 30 * 1.2 buffer, clamped min $0.50)
+`;
+        }
+        else {
+            suggestionsSummary += `
+  No active usage logs detected in the last 7 days.
+  - Applying fallback default budgets: Daily $5.00, Weekly $25.00, Monthly $100.00.
+`;
+        }
+        if (suggestedProviders.length > 0) {
+            suggestionsSummary += `
+  Detected likely zero-cost providers:
+`;
+            for (const { provider, reason } of suggestedProviders) {
+                suggestionsSummary += `    • ${provider} (${reason}, automatically pre-configured to $0.00)\n`;
+            }
+        }
+        if (suggestedModels.length > 0) {
+            suggestionsSummary += `
+  Detected unrecognized fallback models:
+`;
+            for (const m of suggestedModels) {
+                suggestionsSummary += `    • ${m} (automatically pre-configured with fallback $1/$4 rate)\n`;
+            }
+        }
+        suggestionsSummary += `  ────────────────────────────────────────────────────────────────\n`;
+        // Print explanation first to stderr
+        const guideText = `
   Configuration Guide
   ══════════════════════════════════════════════════════════════════
 
@@ -480,11 +794,11 @@ function cmdConfig(positional) {
 
   Examples:
     { "input": 15, "output": 75 }     = $15 per 1M input, $75 per 1M output
-    { "input": 0, "output": 0 }       = Free (subscription or local model)
+    { "input": 0, "output": 0 }       = Free (subscription or local provider/model)
 
   Common scenarios:
     - GitHub Copilot, Cursor, etc.   → Set provider to { input: 0, output: 0 }
-    - Local/self-hosted models       → Set to 0
+    - Ollama, LM Studio, localhost   → Set provider to { input: 0, output: 0 }
     - Direct API usage               → Look up provider's pricing page
 
   Where to find pricing:
@@ -507,33 +821,36 @@ function cmdConfig(positional) {
 
   ────────────────────────────────────────────────────────────────
   Example config based on your usage:
-`);
-        console.log(JSON.stringify(exampleConfig, null, 2));
-        if (action === "generate") {
-            const json = JSON.stringify(exampleConfig, null, 2);
-            writeFileSync(CONFIG_FILE, json);
-            console.log(`
-  Config file created: ${CONFIG_FILE}
-`);
-        }
-        else {
-            console.log(`
+`;
+        process.stderr.write(suggestionsSummary + "\n");
+        process.stderr.write(guideText + "\n");
+        if (action === "init") {
+            // Print clean config to stdout ONLY on init
+            process.stdout.write(JSON.stringify(exampleConfig, null, 2) + "\n");
+            process.stderr.write(`
   To create this config file, run:
     opencode-tokens config generate
   
   Or manually create: ${CONFIG_FILE}
-`);
+\n`);
+        }
+        else if (action === "generate") {
+            // Generate has completely empty stdout! Writes to config file, alerts to stderr
+            saveConfig(exampleConfig);
+            process.stderr.write(`
+  Config file created: ${CONFIG_FILE}
+\n`);
         }
         return;
     }
     if (action === "get") {
         const key = positional[2];
         if (!key) {
-            console.log("\n  Usage: opencode-tokens config get <key>\n");
+            failCli("Missing config key", "Usage: opencode-tokens config get <key>");
             return;
         }
         if (!SETTABLE_KEYS[key]) {
-            console.log(`\n  Unknown key: ${key}\n  Available: ${Object.keys(SETTABLE_KEYS).join(", ")}\n`);
+            failCli(`Unknown config key: ${key}`, `Available keys: ${Object.keys(SETTABLE_KEYS).join(", ")}`);
             return;
         }
         const value = resolveConfigKey(config, key);
@@ -543,27 +860,31 @@ function cmdConfig(positional) {
     if (action === "set") {
         const key = positional[2];
         const rawValue = positional[3];
-        if (!key || !rawValue) {
-            console.log("\n  Usage: opencode-tokens config set <key> <value>\n");
+        if (!key) {
+            failCli("Missing config key", "Usage: opencode-tokens config set <key> <value>");
+            return;
+        }
+        if (!rawValue) {
+            failCli("Missing config value", "Usage: opencode-tokens config set <key> <value>");
             return;
         }
         const spec = SETTABLE_KEYS[key];
         if (!spec) {
-            console.log(`\n  Unknown key: ${key}\n  Available: ${Object.keys(SETTABLE_KEYS).join(", ")}\n`);
+            failCli(`Unknown config key: ${key}`, `Available keys: ${Object.keys(SETTABLE_KEYS).join(", ")}`);
             return;
         }
         const value = parseConfigValue(rawValue);
         if (typeof value !== spec.type) {
-            console.log(`\n  Invalid type: expected ${spec.type}, got ${typeof value}\n`);
+            failCli(`Invalid type for ${key}: expected ${spec.type}, got ${typeof value}`);
             return;
         }
         if (typeof value === "number") {
             if (value < 0) {
-                console.log(`\n  Value must be >= 0\n`);
+                failCli(`Invalid value for ${key}: must be >= 0`);
                 return;
             }
             if (spec.max !== undefined && value > spec.max) {
-                console.log(`\n  Value must be <= ${spec.max}\n`);
+                failCli(`Invalid value for ${key}: must be <= ${spec.max}`);
                 return;
             }
         }
@@ -574,12 +895,12 @@ function cmdConfig(positional) {
     if (action === "unset") {
         const key = positional[2];
         if (!key) {
-            console.log("\n  Usage: opencode-tokens config unset <key>\n");
+            failCli("Missing config key", "Usage: opencode-tokens config unset <key>");
             return;
         }
         const spec = SETTABLE_KEYS[key];
         if (!spec) {
-            console.log(`\n  Unknown key: ${key}\n  Available: ${Object.keys(SETTABLE_KEYS).join(", ")}\n`);
+            failCli(`Unknown config key: ${key}`, `Available keys: ${Object.keys(SETTABLE_KEYS).join(", ")}`);
             return;
         }
         applyConfigUnset(key);
@@ -587,8 +908,7 @@ function cmdConfig(positional) {
         return;
     }
     if (action && action !== "show") {
-        console.log(`\n  Unknown config action: ${action}`);
-        console.log(`  Usage: opencode-tokens config [show|init|generate|get|set|unset]\n`);
+        failCli(`Unknown config action: ${action}`, "Usage: opencode-tokens config [show|init|generate|get|set|unset]");
         return;
     }
     // Show current config
@@ -692,10 +1012,48 @@ function saveConfig(raw) {
 // ============================================================================
 // Export
 // ============================================================================
+const EXPORT_FORMATS = ["csv", "json"];
+const EXPORT_PERIODS = ["today", "week", "month", "all"];
+function failCli(message, usage) {
+    process.stderr.write(`\n  Error: ${message}\n`);
+    if (usage) {
+        process.stderr.write(`  ${usage}\n`);
+    }
+    process.stderr.write("\n");
+    process.exitCode = 1;
+}
+function isExportFormat(format) {
+    return EXPORT_FORMATS.includes(format);
+}
+function isExportPeriod(period) {
+    return EXPORT_PERIODS.includes(period);
+}
 function cmdExport(flags) {
-    const format = flagValue(flags, "format") || "csv";
-    const period = flagValue(flags, "period") || "all";
+    const formatValue = flagValue(flags, "format");
+    const periodValue = flagValue(flags, "period");
     const outputFile = flagValue(flags, "output");
+    if (flags.has("format") && !formatValue) {
+        failCli("Missing value for --format", "Usage: opencode-tokens export --format csv|json");
+        return;
+    }
+    if (flags.has("period") && !periodValue) {
+        failCli("Missing value for --period", "Usage: opencode-tokens export --period today|week|month|all");
+        return;
+    }
+    if (flags.has("output") && !outputFile) {
+        failCli("Missing value for --output", "Usage: opencode-tokens export --output <file>");
+        return;
+    }
+    const format = formatValue ?? "csv";
+    const period = periodValue ?? "all";
+    if (!isExportFormat(format)) {
+        failCli(`Unsupported export format: ${format}`, "Allowed formats: csv, json");
+        return;
+    }
+    if (!isExportPeriod(period)) {
+        failCli(`Unsupported export period: ${period}`, "Allowed periods: today, week, month, all");
+        return;
+    }
     const now = new Date();
     let since;
     switch (period) {
@@ -739,7 +1097,14 @@ function cmdExport(flags) {
         output = `${[headers.join(","), ...rows].join("\n")}\n`;
     }
     if (outputFile) {
-        writeFileSync(outputFile, output);
+        try {
+            writeFileSync(outputFile, output);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            failCli(`Failed to write export file: ${detail}`);
+            return;
+        }
         console.log(`\n  Exported ${entries.length} entries to ${outputFile}\n`);
     }
     else {
@@ -777,6 +1142,8 @@ function cmdBudget() {
   }
 
   Run: opencode-tokens config init  for more details.
+
+  Costs are estimates from local logs; budgets are warnings, not enforcement.
 `);
         return;
     }
@@ -841,6 +1208,7 @@ function cmdBudget() {
         console.log();
     }
     console.log(`  Legend: 🟢 OK  🟡 Warning (>${Math.round(warnAt * 100)}%)  🔴 Exceeded`);
+    console.log(`  Costs are estimates from local logs; budgets are warnings, not enforcement.`);
     console.log();
 }
 function cmdHelp() {
@@ -853,6 +1221,7 @@ function cmdHelp() {
   Commands:
     (default)     Show usage statistics
     budget        Show budget status (daily/weekly/monthly)
+    doctor        Diagnose plugin config, logs, and pricing fallbacks
     pricing       Show built-in pricing table
     models        Show your used models and their pricing status
     config        Show/generate/modify configuration
@@ -891,14 +1260,21 @@ function cmdHelp() {
 
   Examples:
     opencode-tokens                       # All-time summary
+    opencode-tokens doctor                # Diagnose setup and logs
     opencode-tokens today --by model      # Today by model
     opencode-tokens week --by session     # This week by session
     opencode-tokens trend --days 7        # 7-day cost trend
     opencode-tokens export --format csv   # Export all data as CSV
     opencode-tokens config set budget.daily 10  # Set daily budget to $10
     opencode-tokens config get toast.enabled   # Check if toast is enabled
+
+  Costs are estimates from local logs; budgets are warnings, not enforcement.
 `);
 }
+const TREND_METRICS = ["cost", "tokens", "messages"];
+function isTrendMetric(metric) {
+    return TREND_METRICS.includes(metric);
+}
 function getTrendValue(point, metric) {
     return metric === "tokens" ? point.tokens : metric === "messages" ? point.messages : point.cost;
 }
@@ -912,6 +1288,25 @@ function formatSignedTrendValue(value, metric) {
 function metricLabel(metric) {
     return metric === "tokens" ? "Token Trend" : metric === "messages" ? "Message Trend" : "Cost Trend";
 }
+function parsePositiveIntegerOption(flags, name, defaultValue, usage) {
+    const value = flagValue(flags, name);
+    if (flags.has(name) && !value) {
+        failCli(`Missing value for --${name}`, usage);
+        return undefined;
+    }
+    if (!value)
+        return defaultValue;
+    if (!/^\d+$/.test(value)) {
+        failCli(`Invalid value for --${name}: ${value}`, usage);
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (parsed <= 0) {
+        failCli(`Invalid value for --${name}: ${value}`, usage);
+        return undefined;
+    }
+    return parsed;
+}
 function buildLineRows(points, width, height) {
     const grid = Array.from({ length: height }, () => Array.from({ length: width }, () => " "));
     // 1. Calculate the exact integer row r[x] for every column x from 0 to width - 1
@@ -1018,9 +1413,22 @@ function buildTrendXAxis(points, chartPoints, chartWidth) {
     };
 }
 function cmdTrend(flags) {
-    const days = parseInt(String(flagValue(flags, "days") ?? "30"), 10);
-    const metric = flagValue(flags, "metric") ?? "cost";
-    const width = parseInt(String(flagValue(flags, "width") ?? "60"), 10);
+    const days = parsePositiveIntegerOption(flags, "days", 30, "Usage: opencode-tokens trend --days <positive-integer>");
+    if (days === undefined)
+        return;
+    const metricValue = flagValue(flags, "metric");
+    if (flags.has("metric") && !metricValue) {
+        failCli("Missing value for --metric", "Usage: opencode-tokens trend --metric cost|tokens|messages");
+        return;
+    }
+    const metric = metricValue ?? "cost";
+    if (!isTrendMetric(metric)) {
+        failCli(`Unsupported trend metric: ${metric}`, "Allowed metrics: cost, tokens, messages");
+        return;
+    }
+    const width = parsePositiveIntegerOption(flags, "width", 60, "Usage: opencode-tokens trend --width <positive-integer>");
+    if (width === undefined)
+        return;
     const since = getStartOfDay(new Date(Date.now() - days * 86400000));
     const entries = loadEntries(since);
     if (entries.length === 0) {
@@ -1127,33 +1535,45 @@ function main() {
         return;
     }
     const { command } = parsed;
-    switch (command) {
-        case "budget":
-            cmdBudget();
-            return;
-        case "pricing":
-            cmdPricing();
-            return;
-        case "models":
-            cmdModels();
-            return;
-        case "config":
-            cmdConfig(parsed.positional);
-            return;
-        case "export":
-            cmdExport(parsed.flags);
-            return;
-        case "trend":
-            cmdTrend(parsed.flags);
-            return;
-    }
+    if (isTopLevelCommand(command))
+        switch (command) {
+            case "budget":
+                cmdBudget();
+                return;
+            case "doctor":
+                cmdDoctor();
+                return;
+            case "pricing":
+                cmdPricing();
+                return;
+            case "models":
+                cmdModels();
+                return;
+            case "config":
+                cmdConfig(parsed.positional);
+                return;
+            case "export":
+                cmdExport(parsed.flags);
+                return;
+            case "trend":
+                cmdTrend(parsed.flags);
+                return;
+        }
     // Default: stats
     let period = "all";
-    const breakdown = flagValue(parsed.flags, "by") || (parsed.flags.has("b") ? String(parsed.flags.get("b")) : undefined);
-    for (const p of ["today", "week", "month", "all"]) {
-        if (parsed.positional.includes(p)) {
-            period = p;
-            break;
+    const breakdown = getStatsBreakdown(parsed.flags);
+    if (process.exitCode)
+        return;
+    if (command) {
+        if (!isStatsPeriod(command)) {
+            failCli(`Unknown command or stats period: ${command}`, "Usage: opencode-tokens [today|week|month|all] [--by model|agent|provider|daily|session|all]");
+            return;
+        }
+        period = command;
+        const extraArgs = parsed.positional.slice(1);
+        if (extraArgs.length > 0) {
+            failCli(`Unexpected argument for stats command: ${extraArgs[0]}`, "Usage: opencode-tokens [today|week|month|all] [--by model|agent|provider|daily|session|all]");
+            return;
         }
     }
     cmdStats(period, breakdown);