@jigyasudham/veto 2.0.1 → 2.0.2

package/README.md

@@ -2,22 +2,27 @@
 
 > **62 agentic tools. 50+ specialists. 4 AIs. Self-learning. Zero cost.**
 
-An MCP server that runs locally on your machine, plugs into Claude Code, Codex CLI, Gemini CLI, Antigravity CLI, Cursor, Windsurf, Zed, Copilot, and JetBrains using your existing subscriptions — giving every AI a council of specialist agents, local LLM support, SDD agents, playwright automation, persistent cross-platform memory, a self-learning router, CI/CD gates, workspace discovery, and bidirectional IDE communication.
+An MCP server that runs locally on your machine, plugs into Claude Code, Codex CLI, Gemini CLI, Antigravity CLI, Cursor, Windsurf, Zed, and JetBrains using your existing subscriptions — giving every AI a council of specialist agents, local LLM support, SDD agents, playwright automation, persistent cross-platform memory, a self-learning router, CI/CD gates, workspace discovery, and bidirectional IDE communication.
+
+> **Billing note:** "Zero cost" applies to subscription plans (Claude Max, Gemini Advanced, etc.). If you are on API/pay-per-token billing, MCP Sampling calls made by Veto agents will count toward your token usage. `veto init` detects API key environment variables and warns you automatically.
 
 ---
 
-## How the Agents Actually Work
+## How the Agents Work
+
+**Every tool uses a 2-phase agentic loop — no API keys required, zero extra cost.**
 
-**Veto v2.0 is now 100% Agentic.**
+### Phase 1 — MCP Sampling
+The tool attempts real LLM reasoning via MCP Sampling (`server.createMessage`). If your client supports it, the agent reasons deeply and returns a structured plan or analysis.
 
-Every tool in Veto uses a **2-phase agentic loop pattern** — no API keys required, zero extra cost, working identically across Claude Code, Gemini CLI, Antigravity CLI, and Codex CLI.
+### Phase 2 — Agentic Fallback
+If Sampling is unavailable, Veto returns an `llm_upgrade` prompt. The host AI reads the specialist's role, performs the reasoning itself, and passes the JSON response back to complete the operation.
 
-### The 2-Phase Agentic Loop
-1.  **Phase 1 (Sampling):** The tool first attempts real LLM reasoning via **MCP Sampling** (the host AI's native ability to "create a message"). If supported by your client (like Claude Code or Gemini CLI), the agent performs deep reasoning and returns a structured plan or analysis instantly.
-2.  **Phase 2 (Upgrade Prompt):** If Sampling is unavailable or fails, Veto returns an `llm_upgrade` prompt. You (the host AI) read the specialist's role and task, perform the reasoning yourself, and pass the JSON response back to complete the operation.
+Every worker agent supports both modes. When multiple agents run, they execute in parallel. LLM calls delegate back to the AI you're already using — no extra billing.
 
-### Specialist Roles
-Veto provides a council of 7 senior governance agents plus 55+ domain-specific worker agents.
+---
+
+## Specialist Roles
 
 | Agent Group | Specialist Roles |
 |---|---|
@@ -27,10 +32,6 @@ Veto provides a council of 7 senior governance agents plus 55+ domain-specific w
 | **Intelligence** | Task Planner · Researcher · Tech Advisor · Risk Assessor · Cost Analyzer · Ethics/Bias |
 | **Workflow** | File Manager · Git Agent · Search Agent · Reporter · Automation |
 
-### All 62 Tools are now 100% Agentic
-
-> Pattern matching, domain heuristics, and structured templates compiled into code. Offline capable. No LLM calls.
-
 **Development (12)**
 `Coder` · `Code Reviewer` · `Tester` · `Debugger` · `Refactor` · `Database` · `API` · `Frontend` · `Backend` · `DevOps` · `Performance` · `Migration`
 
@@ -107,11 +108,9 @@ veto hook install                # Install pre-commit secrets scan hook
 veto hook remove                 # Remove the veto pre-commit hook
 veto check                       # Scan staged changes for secrets (used by hook)
 veto help                        # Commands + MCP tools reference
-veto help --troubleshoot         # Full troubleshooting guide (14 scenarios)
+veto help --troubleshoot         # Full troubleshooting guide
 ```
 
-`veto help` shows all CLI commands, all 49 MCP tool names, MCP Resources, and MCP Prompts.
-
 ### `veto doctor`
 
 ```
@@ -128,6 +127,7 @@ veto doctor
   ─────────────────────────────────────────────────────
   ✓ Claude Code — registered
   ✓ Gemini CLI — registered
+  ✓ Antigravity CLI — registered
   · Codex CLI — not installed
   · Zed — not installed
 
@@ -138,7 +138,7 @@ veto doctor
 
 ## Council Debate
 
-Two-phase flow — works on Claude Code, Gemini CLI, and Codex CLI with no API keys:
+Two-phase flow — works on Claude Code, Gemini CLI, Antigravity CLI, and Codex CLI with no API keys:
 
 ```
 # Phase 1 — call with task, get instant deterministic result + LLM upgrade prompt
@@ -166,7 +166,7 @@ veto_council_debate {
     pm:        { verdict: "approve", reason: "JWT migration unblocks mobile clients", concerns: [], recommendation: "Ship behind a feature flag, roll back if logout issues" },
     architect: { verdict: "approve", reason: "Good fit for stateless microservice boundary", concerns: ["Clock skew can break expiry across services"], recommendation: "Add NTP sync check; use relative expiry not absolute timestamps" },
     ux:        { verdict: "approve", reason: "No user-visible change if migration is seamless", concerns: [], recommendation: "Silent migration — no logout required for existing sessions" },
-    devil:     { verdict: "warn",    reason: "What if the refresh token store goes down at 2AM?", concerns: ["Redis outage = all users logged out", "Token replay attack window between rotation and invalidation"], recommendation: "Fallback to session auth if Redis is down; use short rotation window" },
+    devil:     { verdict: "warn",    reason: "What if the refresh token store goes down at 2AM?", concerns: ["Redis outage = all users logged out"], recommendation: "Fallback to session auth if Redis is down; use short rotation window" },
     legal:     { verdict: "approve", reason: "JWTs are industry standard, no new compliance risk", concerns: [], recommendation: "Document token storage in privacy policy" },
     security:  { verdict: "warn",    reason: "Refresh token rotation must be atomic — TOCTOU risk", concerns: ["localStorage storage of access token is XSS-vulnerable"], recommendation: "Store access token in memory only; refresh token in httpOnly Secure SameSite=Strict cookie" }
   }
@@ -174,312 +174,34 @@ veto_council_debate {
 → {
     llm_backed: true,
     final_verdict: "YELLOW",
-    block_reasons: [],
     warnings: ["Refresh token rotation must be atomic...", "What if the refresh token store goes down..."],
     recommended: "Proceed with JWT. Use httpOnly cookies for refresh tokens, memory-only for access tokens..."
   }
 ```
 
-When the task presents a binary choice, agents name the option they prefer and the output includes a `🎯 Council leans toward:` line:
+### Council `strictness`
 
 ```
-veto_council_debate {
-  task: "Should we add an Express HTTP layer or keep Veto pure MCP with an external adapter?"
-}
-→ formatted_output includes:
-    🎯 Council leans toward: "pure MCP with an external adapter" (5 agents prefer it)
-    Lead Dev:  [Express HTTP vs external adapter] ... [WARN]
-               recommendation: Prefer "external adapter" — Express adds new infrastructure...
-    Security:  [Express HTTP vs external adapter] ... [WARN]
-               recommendation: Prefer "external adapter" — keeps the threat model local-only...
+veto_council_debate { task: "...", strictness: "fast" }     # 3 agents, instant
+veto_council_debate { task: "...", strictness: "standard" } # 7 agents, default
+veto_council_debate { task: "...", strictness: "strict" }   # 7 + devil rebuttal
 ```
 
 ---
 
 ## Session Tagging + Search
 
-Tag sessions when saving to make them findable later:
-
 ```
-# Let Veto generate the summary from conversation context
 veto_session_save {
   auto_summarize: true,
   tags: ["auth", "jwt", "middleware"]
 }
 
-# Or write it manually
-veto_session_save {
-  summary: "Implemented JWT auth middleware",
-  context: "...",
-  tags: ["auth", "jwt", "middleware"]
-}
-
-# Find it weeks later:
 veto_sessions_list { query: "auth" }
 → sessions matching "auth" in summary, context, tags, or project_dir
 ```
 
----
-
-## New in v1.4.4
-
-### Token count now updates from `veto_session_save`
-
-Previously, token count and context window usage only updated when `veto_status { token_count: N }` was called. Saving a session without calling status first left the VS Code extension and autosave status showing stale or zero values.
-
-Now `veto_session_save { token_count: N }` directly:
-- Calls `trackTokens()` to update the daily rate tracker
-- Upserts into the new `context_usage` table with `usage_pct` computed from the model's actual context window
-
-```
-veto_session_save {
-  summary: "...",
-  context: "...",
-  token_count: 45000,          ← now updates live display immediately
-  platform: "claude",
-  model: "claude-sonnet-4-6"   ← resolves exact 1M window for accurate %
-}
-→ { usage_pct: 4.5, auto_summarized: false, ... }
-```
-
-### `context_usage` table — live DB polling for VS Code extension
-
-A new single-row-per-platform table in `~/.veto/veto.db` that always holds the latest known context state. Your VS Code extension can poll or watch this table directly:
-
-```sql
-SELECT platform, model, token_count, context_window, usage_pct, updated_at
-FROM context_usage
-ORDER BY updated_at DESC
-```
-
-Updated by both `veto_session_save` and `veto_status` whenever `token_count > 0` is passed. `veto_autosave_status` now includes `live_context_usage` in its response.
-
----
-
-## New in v1.4.3
-
-### Council debate + session save — work on Gemini CLI and Codex CLI
-
-MCP Sampling (`server.createMessage`) is not yet implemented by any of the four CLI hosts. Previously this meant the council always used deterministic fallbacks and `auto_summarize` never ran on any platform.
-
-**v1.4.3 introduces the agentic loop pattern** — no API keys, no sampling dependency, works on all four platforms identically.
-
-#### Council debate — two-phase LLM upgrade
-
-```
-# Phase 1 — always returns an instant deterministic result
-veto_council_debate { task: "migrate auth to JWT" }
-→ {
-    llm_backed: false,
-    final_verdict: "YELLOW",
-    votes: { ... },           ← deterministic agent analysis
-    llm_upgrade: {
-      available: true,
-      instruction: "Read debate_prompt, reason as all 7 agents, call again with agent_responses",
-      debate_prompt: "You are running a Veto Council debate. Analyze the task as each specialist..."
-    }
-  }
-
-# Phase 2 — call again with your agent_responses → get the LLM-backed verdict
-veto_council_debate {
-  task: "migrate auth to JWT",
-  agent_responses: {
-    lead_dev:  { verdict: "warn", reason: "...", concerns: [], recommendation: "..." },
-    pm:        { verdict: "approve", ... },
-    architect: { verdict: "warn", ... },
-    ux:        { verdict: "approve", ... },
-    devil:     { verdict: "warn", ... },
-    legal:     { verdict: "warn", ... },
-    security:  { verdict: "warn", ... }
-  }
-}
-→ { llm_backed: true, final_verdict: "YELLOW", votes: { ... } }
-```
-
-The host AI (Claude, Gemini, or Codex) reads the `debate_prompt`, reasons as all 7 specialists, and passes the structured JSON back. Veto runs the verdict engine on the real LLM output.
-
-#### Session save — agentic fallback
-
-When `auto_summarize: true` and MCP Sampling is unavailable, `veto_session_save` now returns a structured template and instructions for the calling AI to fill in and call again — instead of silently saving nothing:
-
-```
-veto_session_save { auto_summarize: true }
-→ {
-    mode: "agentic",
-    instruction: "Generate the session summary yourself from the conversation above, then call veto_session_save again with the filled-in fields.",
-    summarize_prompt: "Review the conversation above and produce a session checkpoint...",
-    template: {
-      auto_summarize: false,
-      summary: "<one sentence describing what was accomplished>",
-      context: "{ task, decisions[], findings[] with file:line }",
-      task_state: "{ completed[], remaining[], nextAction: 'Edit src/X.ts line N — ...' }"
-    }
-  }
-```
-
----
-
-## New in v1.4.2
-
-### `veto_session_save` — LLM auto-summarization
-
-Pass `auto_summarize: true` and Veto reads the full conversation via MCP Sampling, then generates an accurate, structured session checkpoint itself — you don't write summary, context, or task_state manually.
-
-```
-# Simplest possible save — Veto does the work
-veto_session_save {
-  auto_summarize: true,
-  project_dir: "/your/project",
-  tags: ["auth", "migration"]
-}
-→ {
-    success: true,
-    auto_summarized: true,
-    session_id: "abc-123",
-    summary: "Implemented JWT auth middleware with refresh token rotation",
-    context: {
-      task: "migrate session auth to JWT",
-      decisions: [{ decision: "store refresh token in httpOnly cookie", rationale: "XSS protection" }],
-      findings: ["src/auth.ts:142 — refreshToken handler, needs rotation logic next"]
-    },
-    task_state: {
-      completed: ["access token generation", "middleware wiring"],
-      remaining: ["refresh token rotation", "logout blocklist"],
-      nextAction: "Edit src/auth.ts line 142 — implement rotation: invalidate old refresh token, issue new one, update DB row"
-    }
-  }
-```
-
-Veto generates `nextAction` as a **concrete, file+line instruction** the next AI can execute without re-reading any source files. On restore, the `resume_instructions` field tells the AI to trust this and start immediately.
-
-When MCP Sampling is unavailable (all platforms currently), returns an agentic template asking the host AI to generate the summary from the conversation and call back with filled-in fields — see v1.4.3.
-
----
-
-## New in v1.4.1
-
-### Council debate — decision-aware verdicts
-
-When your task presents a binary architectural choice ("should we X or Y", "A vs B"), every council agent now identifies which option it prefers and names it explicitly. The output includes a `🎯 Council leans toward:` line counting how many agents favour each option.
-
-Before — agents fired generic keyword-matched concerns unrelated to the choice:
-```
-Lead Dev: "Persistent memory stores grow unbounded..."  ← nothing to do with the question
-```
-
-After — agents address the specific choice:
-```
-Lead Dev:  [Express-bundled vs external-adapter] reason [WARN]
-           recommendation: Prefer "external-adapter" — "Express-bundled" adds new
-           infrastructure to maintain; validate real demand before building.
-🎯 Council leans toward: "external adapter pattern" (4 agents prefer it)
-```
-
-In the agentic loop (phase 2), the host AI is explicitly instructed to name the preferred option in its recommendation for each agent role.
-
-### `veto_session_restore` — resume instructions
-
-The restore response now includes a `resume_instructions` field that tells the AI exactly what to do:
-
-```
-veto_session_restore { session_id: "..." }
-→ {
-    resume_instructions: "Context restored. Trust the summary, context, and task_state
-      above. Do NOT re-read source files to orient yourself — only open a file if you
-      are about to EDIT it. Start immediately with: [nextAction from task_state].",
-    session_id: "...",
-    summary: "...",
-    context: { ... },
-    task_state: { nextAction: "Edit src/server.ts line 302, add zod validation..." },
-    ...
-  }
-```
-
-This fixes the core issue where AI sessions were re-reading the entire codebase on restore instead of trusting the saved context.
-
-### `veto_session_save` — input validation
-
-`summary`, `context`, and `task_state` now have enforced size limits. Oversized inputs are truncated with a warning rather than silently stored or crashing.
-
-| Field | Limit |
-|---|---|
-| `summary` | 2,000 chars |
-| `context` | 50,000 chars |
-| `task_state` | 20,000 chars |
-
-```
-veto_session_save { summary: "...(very long)..." }
-→ { success: true, truncation_warnings: ["summary truncated to 2000 chars (was 8432)"] }
-```
-
----
-
-## New in v1.4.0
-
-### `veto_metrics` — usage dashboard
-
-```
-veto_metrics {}
-→ {
-    sessions: { total: 45, today: 2, this_week: 8 },
-    council:  { total: 24, today: 1, by_verdict: { GREEN: 12, YELLOW: 9, RED: 3 } },
-    agents:   [ { agent: "coder", calls: 38, avg_quality: 86 }, ... ],
-    quality:  { overall_avg: 86, trend: [{ date: "2026-05-17", avg: 89, count: 5 }] },
-    knowledge:{ total_entries: 12, by_type: { solution: 6, decision: 4, pattern: 2 } },
-    patterns: { total: 10 }
-  }
-```
-
-### `veto_changelog` — git changelog
-
-```
-veto_changelog { project_dir: "/your/project" }
-→ {
-    since_tag: "v1.3.0",
-    total_commits: 23,
-    sections: [
-      { section: "Features",    items: [{ message: "Add council strictness param", hash: "a3f2b1c0", ... }] },
-      { section: "Bug Fixes",   items: [...] },
-      { section: "Refactoring", items: [...] }
-    ]
-  }
-```
-
-### `veto_git_blame` — ownership data
-
-```
-veto_git_blame { file_path: "/your/project/src/auth.ts" }
-→ {
-    path: "/your/project/src/auth.ts",
-    total_commits: 14,
-    contributors: [
-      { commits: 9, author: "Jigyasu Dham" },
-      { commits: 5, author: "contributor" }
-    ],
-    last_modified_at: "2026-05-16 18:30:00 +0530",
-    last_author: "Jigyasu Dham",
-    last_commit_message: "fix: JWT expiry check for clock skew"
-  }
-```
-
-### `veto_explain` — now accepts raw text
-
-```
-# Error message / stack trace
-veto_explain { text: "TypeError: Cannot read properties of undefined (reading 'id')\n  at auth.ts:42" }
-→ debugger agent explains the error and suggests root causes
-
-# Still works for files
-veto_explain { file_path: "/your/project/src/auth.ts", depth: "detailed" }
-```
-
-### Council `strictness` parameter
-
-```
-veto_council_debate { task: "...", strictness: "fast" }   # 3 agents, instant
-veto_council_debate { task: "...", strictness: "standard" } # 7 agents, default
-veto_council_debate { task: "...", strictness: "strict" }   # 7 + devil rebuttal
-```
+Token usage is manually reported — pass `token_count` to `veto_status` or `veto_session_save` and Veto stores it per platform per day. `veto_rate_status` shows what you've reported; nothing is counted automatically.
 
 ---
 
@@ -569,10 +291,13 @@ Open Gemini    →  veto_continue { resuming_as: "gemini" }
 Full context restored. Continue exactly where you stopped.
 ```
 
+Platform switching is manual — Veto surfaces which platform has budget remaining via `veto_rate_status`, you decide when to switch.
+
 | Platform | Support |
 |---|---|
 | Claude Code | ✅ Native MCP |
 | Gemini CLI | ✅ MCP support |
+| Antigravity CLI | ✅ MCP support |
 | Codex CLI | ✅ MCP support |
 | Cursor | ✅ MCP support |
 | Windsurf | ✅ MCP support |
@@ -580,76 +305,13 @@ Full context restored. Continue exactly where you stopped.
 
 ---
 
-## Roadmap
-
-| Phase | Status | Version |
-|---|---|---|
-| 1–12 — Foundation through CLI + Diff Review | ✅ Complete | v0.1.0 – v1.0.0 |
-| 13 — Developer Intelligence + Auto Docs | ✅ Complete | v1.1.0 |
-| 14 — Observability + Usage Stats + Audit Log | ✅ Complete | v1.2.0 |
-| 15 — CI/CD Gates + GitHub PR Review | ✅ Complete | v1.2.5 |
-| 16 — Workspace Discovery + Summarization + Doctor | ✅ Complete | v1.2.8 |
-| 17 — VS Code Extension + Token Budget + Risk Annotations | ✅ Complete | v1.2.14 |
-| 18 — Extension Upgrades | ✅ Complete | veto-vscode v0.6.0 |
-| 19 — Auto-Learning Hooks | ✅ Complete | v1.2.15 |
-| 20 — Auto-Store Memory on RED | ✅ Complete | v1.2.16 |
-| 21 — Closing the Loop (auto-thresholds, pre-commit hook, benchmark) | ✅ Complete | v1.2.18 |
-| 22 — LLM Council (MCP Sampling, per-model context windows) | ✅ Complete | v1.3.0 |
-| 23 — Quality + Features (TTL cache, metrics, git blame, changelog, Zed, session tags) | ✅ Complete | v1.4.0 |
-
----
-
-## Changelog
-
-### v1.4.0
-- **feat:** `veto_metrics` — live usage dashboard (sessions, council verdicts, top agents, quality trend, knowledge stats). Pure SQLite reads, zero cost.
-- **feat:** `veto_changelog` — structured changelog from git history since last tag, grouped by conventional commit type.
-- **feat:** `veto_git_blame` — file/directory ownership data from local git (contributors, commit counts, last-modified metadata).
-- **feat:** Council `strictness` param — `fast` (3 core agents, instant) / `standard` (7 agents, default) / `strict` (7 + Devil's Advocate rebuttal round on most critical blocker).
-- **feat:** Session tagging — `veto_session_save` accepts `tags: string[]`; `veto_sessions_list` accepts `query` for full-text search across summary, context, tags, and project_dir.
-- **feat:** Zed editor support — `veto init` now auto-configures Zed via `~/.config/zed/settings.json` (`context_servers` key).
-- **feat:** `veto_explain` accepts raw `text` — error messages, stack traces, and compiler output are auto-routed to the debugger agent.
-- **fix:** `task_plans` TTL — cached plans older than 7 days are no longer returned; `veto_task_parse` checks cache before running the planner agent.
-- **fix:** Complexity scorer — word-count cap raised from 20→25 pts; +5 bonus for tasks over 60 words.
-- **fix:** Path sanitization — `readProjectContext` now validates that the resolved path is a directory before running any `git` commands.
-- **refactor:** Tool definitions extracted from `server.ts` into `src/tools/definitions.ts` (49 tools, grouped by category). `server.ts` reduced from 2640 → 1907 lines.
-
-### v1.3.0
-- **feat:** Council agents are now LLM-backed via MCP Sampling — all 7 agents call the host LLM in parallel and return real reasoning, not deterministic templates. Deterministic fallback per agent if sampling is unavailable.
-- **feat:** Full agent reasoning returned — `votes` now includes each agent's complete `reason`, `concerns`, and `recommendation`.
-- **feat:** Knowledge retrieval pre-hook — council searches `knowledge_base` for similar past decisions before each debate.
-- **feat:** `veto_benchmark` runs two LLM council debates in parallel.
-- **feat:** Auto-store on YELLOW — significant YELLOW verdicts now stored in knowledge base with per-agent reasoning.
-- **feat:** Per-model context windows — `veto_status` and `veto_session_save` accept `model` param for exact window resolution.
-
-### v1.2.19
-- **fix:** `veto_session_save` accepts optional `session_id` — updates that row in-place instead of inserting a new one.
-
-### v1.2.18
-- **feat:** Auto-apply learned thresholds after every 20 `autoRecord()` calls.
-- **feat:** `veto hook install` / `veto hook remove` — pre-commit secrets scan hook.
-- **feat:** `veto check` — fast secrets scan on staged changes.
-- **feat:** `veto_benchmark` (tool #46) — two approaches → two parallel council debates → structured winner.
-
-### v1.2.17
-- **fix:** `veto version` no longer shows "Unknown command".
-- **fix:** Unknown commands show a short 2-line error.
-- **fix:** `veto help` is now ~50 lines; full troubleshooting moved to `veto help --troubleshoot`.
-- **feat:** Sessions track `save_type` (`manual` | `auto`); `veto sessions --clean` removes old auto-saves.
-
-### v1.2.15 – v1.2.16
-- Auto-learning hooks — `learning_data` fills automatically from every agent-producing tool.
-- Auto-store knowledge entries on RED council verdict and critical scan failures.
-
----
-
 ## Tech Stack
 
 - **Language:** TypeScript (strict mode)
 - **Runtime:** Node.js 22.5+ (built-in `node:sqlite` — no native compilation)
 - **Dependencies:** `@modelcontextprotocol/sdk` only — one package, zero native addons
 - **Memory:** Local SQLite — zero config, works offline, portable via JSON export
-- **Platforms:** Claude Code · Gemini CLI · Codex CLI · Cursor · Windsurf · Zed
+- **Platforms:** Claude Code · Gemini CLI · Antigravity CLI · Codex CLI · Cursor · Windsurf · Zed
 
 ---
 

package/dist/cli.js

@@ -307,7 +307,7 @@ async function initCommand() {
     console.log('');
     const VETO_GUIDE = `# Veto MCP Server
 
-Veto is active. 49 tools across 5 categories:
+Veto is active. 62 tools across 6 categories:
 
 **Session & Context** — veto_status · veto_session_save · veto_continue · veto_handoff
 Save work at 60–70% context capacity. veto_status triggers auto-save above 70%.
@@ -468,7 +468,7 @@ Recommended start sequence:
     }
     if (configured === 0 && skipped === 0) {
         console.log(c.yellow('  ⚠  No AI tools detected.'));
-        console.log('  Install Claude Code, Gemini CLI, or Codex CLI and run veto init again.');
+        console.log('  Install Claude Code, Gemini CLI, Antigravity CLI, or Codex CLI and run veto init again.');
         console.log('');
     }
     else {
@@ -484,6 +484,28 @@ Recommended start sequence:
         console.log(c.dim('  Tip: run `veto init` again anytime to install newly-added AI tools.'));
         console.log('');
     }
+    // ── Billing mode detection ──────────────────────────────────────────────────
+    // Check for API key env vars as a signal the user may be on pay-per-token billing.
+    const apiKeyEnvVars = ['ANTHROPIC_API_KEY', 'GEMINI_API_KEY', 'GOOGLE_API_KEY', 'OPENAI_API_KEY'];
+    const detectedKeys = apiKeyEnvVars.filter(k => !!process.env[k]);
+    const { setConfig: setVetoConfig } = await import('./memory/config.js');
+    if (detectedKeys.length > 0) {
+        setVetoConfig({ billing_mode: 'api' });
+        console.log(c.yellow('  ⚠  API key environment variables detected:') + c.dim(` ${detectedKeys.join(', ')}`));
+        console.log(c.yellow('     Veto has set billing_mode = api in ~/.veto/config.json.'));
+        console.log('');
+        console.log('  ' + c.bold('Important — cost warning:'));
+        console.log('  Veto\'s "zero cost" claim applies to subscription plans (Claude Max, Gemini');
+        console.log('  Advanced, etc.). On API/pay-per-token billing, any MCP Sampling calls made');
+        console.log('  by Veto agents will count toward your token usage and be billed accordingly.');
+        console.log('');
+        console.log(c.dim('  To silence this warning if you are on a subscription:'));
+        console.log(c.dim('  Edit ~/.veto/config.json and set "billing_mode": "subscription"'));
+        console.log('');
+    }
+    else {
+        setVetoConfig({ billing_mode: 'subscription' });
+    }
 }
 // ─── Doctor Command ─────────────────────────────────────────────────────────────
 async function doctorCommand() {
@@ -637,6 +659,23 @@ async function doctorCommand() {
             issues++;
         }
     }
+    // Billing mode
+    console.log('');
+    console.log('  ' + c.bold('Billing'));
+    console.log(c.dim('  ─────────────────────────────────────────────────────'));
+    const { getConfig: getVetoConfig } = await import('./memory/config.js');
+    const vetoConfig = getVetoConfig();
+    const apiKeyEnvVarsDoctor = ['ANTHROPIC_API_KEY', 'GEMINI_API_KEY', 'GOOGLE_API_KEY', 'OPENAI_API_KEY'];
+    const detectedKeysDoctor = apiKeyEnvVarsDoctor.filter(k => !!process.env[k]);
+    if (vetoConfig.billing_mode === 'api' || detectedKeysDoctor.length > 0) {
+        console.log(`  ${c.yellow('⚠')} billing_mode: ${c.yellow('api')} — MCP Sampling calls count toward your token usage`);
+        console.log(`  ${c.dim('  Veto\'s "zero cost" claim applies to subscription plans only.')}`);
+        console.log(`  ${c.dim('  To update: edit ~/.veto/config.json → "billing_mode": "subscription"')}`);
+        issues++;
+    }
+    else {
+        console.log(`  ${c.green('✓')} billing_mode: subscription — zero extra cost`);
+    }
     console.log('');
     if (issues === 0) {
         console.log(c.green('  ✓ All checks passed — Veto is healthy!'));
@@ -891,10 +930,10 @@ function troubleshootCommand() {
     console.log(`  ${c.dim('→')} Use ${c.cyan('veto_rate_status')} tool to check current usage`);
     console.log(`  ${c.dim('→')} Wait a moment, then retry — limits reset per minute`);
     console.log('');
-    console.log(`  ${c.yellow('veto init fails / API key not found')}`);
-    console.log(`  ${c.dim('→')} Set key in your shell: ${c.cyan('export ANTHROPIC_API_KEY=sk-...')}`);
-    console.log(`  ${c.dim('→')} Windows: ${c.cyan('$env:ANTHROPIC_API_KEY="sk-..."')}`);
-    console.log(`  ${c.dim('→')} Re-run ${c.cyan('veto init')} after setting the key`);
+    console.log(`  ${c.yellow('veto init fails on first run')}`);
+    console.log(`  ${c.dim('→')} Veto does not require an API key — it uses your existing AI subscriptions via MCP`);
+    console.log(`  ${c.dim('→')} Ensure Node.js >= 22 and run ${c.cyan('veto init')} from your project directory`);
+    console.log(`  ${c.dim('→')} Check that your AI client (Claude Code / Gemini / Codex / Antigravity) is installed`);
     console.log('');
     console.log(`  ${c.yellow('veto_health shows degraded / components failing')}`);
     console.log(`  ${c.dim('→')} Run ${c.cyan('veto status')} for a summary of all components`);