@jigyasudham/veto 1.2.19 → 1.4.1

package/README.md

@@ -1,8 +1,50 @@
 # veto
 
-> **50 agents. 46 tools. 3 AIs. Self-learning. Zero extra cost.**
+> **50 agents. 49 tools. 3 AIs. Self-learning. Zero extra cost.**
 
-An MCP server that runs locally on your machine, plugs into Claude Code, Codex CLI, and Gemini CLI using your existing subscriptions — giving every AI a council of specialist agents, persistent cross-platform memory, a self-learning router that improves automatically from every tool call, live usage tracking, CI/CD pipeline gates, workspace discovery, live documentation fetching, auto session save, and the ability to say no to bad decisions.
+An MCP server that runs locally on your machine, plugs into Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, and Zed using your existing subscriptions — giving every AI a council of specialist agents, persistent cross-platform memory, a self-learning router, CI/CD gates, workspace discovery, live docs, cross-platform handoff, usage metrics, and the ability to say no to bad decisions before any code is written.
+
+---
+
+## How the Agents Actually Work
+
+**This is the most important thing to understand about Veto.**
+
+Veto has two fundamentally different types of agents:
+
+### Council agents — real LLM reasoning (7 agents)
+
+The 7 council agents call your existing AI subscription via MCP Sampling — they do not use a separate API key or cost anything extra. Each agent gets a tight system prompt, reasons independently, and returns a structured JSON verdict.
+
+| Agent | Role |
+|---|---|
+| Lead Developer | Code quality, maintainability, implementation risk |
+| Product Manager | Scope, timeline, business value |
+| System Architect | Architecture fit, scalability, coupling |
+| UX Designer | User impact, accessibility, friction |
+| Devil's Advocate | Challenges assumptions, stress-tests the plan |
+| Legal & Compliance | License risks, data handling, regulatory exposure |
+| Security | OWASP, auth, injection, data leakage |
+
+Use `strictness` to control depth:
+- `fast` — 3 agents (Lead Dev + Architect + Security), instant
+- `standard` — all 7 agents, default
+- `strict` — all 7 agents + Devil's Advocate rebuttal round on the most critical blocker
+
+`veto_benchmark` also runs LLM council — two debates in parallel for side-by-side approach comparison.
+
+### Expert modules — deterministic, instant, zero tokens (42+ agents)
+
+Every other agent in Veto — coder, reviewer, tester, debugger, security scanner, secrets scanner, database, frontend, devops, and all 30+ others — is a **deterministic expert module**: structured templates, OWASP regex patterns, and domain heuristics compiled into code. They run offline, produce zero token cost, and return results in milliseconds.
+
+```
+veto_agent_plan  { agent: "coder", task: "..." }    ← deterministic plan, instant
+veto_code_review { code: "..." }                     ← regex + heuristic scanner, instant
+veto_secrets_scan{ text: "..." }                     ← pattern matching, instant
+veto_council_debate { task: "..." }                  ← 7 LLM calls via MCP Sampling
+```
+
+**Why this split?** LLM reasoning costs tokens and latency — it's only worth it for high-stakes decisions before architecture/security/migration work. Pattern-matching is MORE reliable than LLMs for secrets detection and OWASP scanning (no hallucinations). The deterministic agents are the workhorses; the council is the gatekeeper.
 
 ---
 
@@ -10,8 +52,8 @@ An MCP server that runs locally on your machine, plugs into Claude Code, Codex C
 
 | Requirement | Version | Notes |
 |---|---|---|
-| **Node.js** | 22.5.0 or higher | Required — uses the built-in `node:sqlite` module (no native compilation). Download at [nodejs.org](https://nodejs.org). |
-| **At least one AI CLI** | Latest | Claude Code, Gemini CLI, or Codex CLI — whichever you use. Veto works with all three. |
+| **Node.js** | 22.5.0 or higher | Required — uses built-in `node:sqlite` (no native compilation). Download at [nodejs.org](https://nodejs.org). |
+| **At least one AI CLI** | Latest | Claude Code, Gemini CLI, or Codex CLI — whichever you use. Veto works with all. |
 
 ```bash
 node --version   # must be v22.5.0 or higher
@@ -33,18 +75,19 @@ npx @jigyasudham/veto@latest init
 claude mcp add veto -s user -- npx -y --package @jigyasudham/veto veto-server
 ```
 
-The `-s user` flag registers Veto at user scope so it is available in **every VS Code window and project** without re-running anything. `veto init` does this automatically.
+The `-s user` flag registers Veto at user scope so it is available in **every window and project** automatically.
 
 ### Other platforms
 
 | Platform | Config file written by `veto init` |
 |---|---|
 | **Gemini CLI** | `~/.gemini/settings.json` |
-| **Codex CLI** | `~/.codex/config.json` |
+| **Codex CLI** | `~/.codex/config.toml` |
 | **Cursor** | `~/.cursor/mcp.json` |
 | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
+| **Zed** | `~/.config/zed/settings.json` · Windows: `%APPDATA%\Zed\settings.json` (`context_servers` key) |
 
-All config files are home-directory relative — they apply globally across all projects and windows. Restart the AI client after `veto init` to pick up the new config.
+All config files are home-directory relative — they apply globally across all projects. Restart the AI client after `veto init`.
 
 ```json
 {
@@ -61,64 +104,73 @@ All config files are home-directory relative — they apply globally across all
 
 ## What Veto Does
 
-**Council** — Before any significant task, 7 specialist agents debate it in parallel and return a GREEN / YELLOW / RED / DEADLOCK verdict. Bad decisions get blocked before any code is written.
+**Council** — Before any significant task, 7 specialist agents (LLM-backed via MCP Sampling) debate it in parallel and return a GREEN / YELLOW / RED / DEADLOCK verdict. Bad decisions get blocked before any code is written. Use `strictness: "fast"` for quick checks or `"strict"` for a full rebuttal round.
+
+**Metrics** — `veto_metrics` gives you a live usage dashboard: sessions saved, council verdict breakdown, top agents by call count, 7-day quality trend, and knowledge base stats. Zero cost, pure SQLite.
+
+**Changelog** — `veto_changelog` reads your git history since the last tag, groups commits by conventional type (feat, fix, refactor...), and returns a structured changelog ready to publish.
 
-**Codebase-aware agents** — Pass `project_dir` to any tool and Veto auto-reads `package.json`, detects your tech stack, and injects recent `git diff` context. Every agent responds to your actual project, not generic templates.
+**Git blame** — `veto_git_blame` returns contribution history for any file or directory — total commits, contributor list with counts, and last-modified metadata. Instant, local, no network.
+
+**Codebase-aware agents** — Pass `project_dir` to any tool and Veto auto-reads `package.json`, detects your tech stack, and injects recent `git diff` context. Every agent responds to your actual project.
 
 **Structured output** — Every agent result carries `confidence`, `severity`, `recommendation`, `affected_files`, and `line_refs` — composable and actionable.
 
-**Router** — Every task is scored locally (zero tokens) and sent to the right model tier. Rate limits are tracked across all 3 platforms. The router self-adjusts from recorded outcomes and learns which agents perform best per file type.
+**Router** — Every task is scored locally (zero tokens) and sent to the right model tier. Rate limits are tracked across all platforms. The router self-adjusts from recorded outcomes and learns which agents perform best per file type.
 
-**50 Agents** — Domain experts for every task type. Each agent knows when it is the right tool and when to defer.
+**Memory** — Sessions, decisions, knowledge, and coding patterns persist across every conversation and platform. Sessions are searchable by summary, context, tags, or project path. Tag sessions with `tags: ["auth", "migration"]` and find them later with `query: "auth"`.
 
-**Memory** — Sessions, decisions, knowledge, and coding patterns persist across every conversation and every platform. Memory is automatically scoped to the active session's project directory — two instances working on different projects stay isolated without any extra configuration.
+**Workspace discovery** — `veto_discover` scans a project once and builds a rich context map: git state, tech stack, file tree, dependencies, and key config files.
 
-**Workspace discovery** — `veto_discover` scans a project once and builds a rich context map: git state, tech stack, file tree, dependencies, and key config files. Stored in Veto memory so every agent has accurate project context without re-reading files each time.
+**Project summarization** — `veto_summarize` generates a concise expert briefing of a project, directory, or file.
 
-**Project summarization** — `veto_summarize` generates a concise expert briefing of a project, directory, or file in seconds. Use it at the start of a session to orient yourself on unfamiliar code.
+**Explain anything** — `veto_explain` accepts a file path or raw text (error messages, stack traces, compiler output). Auto-routes to the right expert — file extension detection for source files, debugger agent for error-like content.
 
-**Diff review** — `veto_diff_review` runs code review, security scan, and secrets scan in parallel across a git diff. Returns a pass/warn/fail verdict with per-file findings — ready for CI and pre-commit hooks.
+**Diff review** — `veto_diff_review` runs code review, security scan, and secrets scan in parallel across a git diff. Returns a pass/warn/fail verdict ready for CI and pre-commit hooks.
 
 **File watching** — `veto_watch` monitors your project and tells you which agent to call when files change.
 
 **Sequential pipelines** — `veto_workflow` runs a chain of agents with pass/fail gates end to end.
 
-**File explanation** — `veto_explain` reads any file and routes it to the best-fit expert agent automatically.
+**Cross-platform handoff** — Claude hitting its rate limit? `veto_handoff` → open Gemini → `veto_continue`. Full context restored in seconds.
 
 **Plugin system** — Drop a `.js` file in `~/.veto/agents/` and it registers as a custom agent available in every tool.
 
-**MCP Resources + Prompts** — Read Veto's memory as MCP Resources. Use built-in Prompts as reusable task templates.
-
-**Cross-platform handoff** — Claude hitting its rate limit? `veto_handoff` → open Gemini → `veto_continue`. Full context restored in seconds.
-
 ---
 
 ## The 50 Agents
 
-### Council Layer (8) — runs before any code is written
+### Council Layer — LLM-backed via MCP Sampling (8)
+
+> These agents call your existing AI subscription. Real reasoning, real cost. Used exclusively by `veto_council_debate` and `veto_benchmark`.
+
 `Lead Developer` · `Product Manager` · `System Architect` · `UX Designer` · `Devil's Advocate` · `Legal & Compliance` · `Security` · `Decision Engine`
 
-### Development (12)
+### Expert Modules — deterministic, instant, zero tokens (42)
+
+> 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`
 
-### Security (6)
+**Security (6)**
 `Security Scanner` · `Auth Agent` · `Data Privacy` · `Secrets Agent` · `Dependency Audit` · `Penetration Tester`
 
-### Memory (5)
+**Memory (5)**
 `Context Manager` · `Decision Logger` · `Project Mapper` · `Pattern Learner` · `Knowledge Base`
 
-### Research (7)
+**Research (7)**
 `Researcher` · `Tech Advisor` · `Cost Analyzer` · `Competitor Analyzer` · `Risk Assessor` · `Estimator` · `Ethics & Bias`
 
-### Quality (5)
+**Quality (5)**
 `Code Quality` · `Documentation` · `Accessibility` · `Compatibility` · `Error Handling`
 
-### Workflow (7)
+**Workflow (7)**
 `Task Planner` · `Task Coordinator` · `File Manager` · `Git Agent` · `Search Agent` · `Reporter` · `Automation`
 
 ---
 
-## MCP Tools (46)
+## MCP Tools (49)
 
 | Category | Tools |
 |---|---|
@@ -133,9 +185,9 @@ All config files are home-directory relative — they apply globally across all
 | **Learning** | `veto_record_outcome` · `veto_learning_stats` · `veto_learning_apply` |
 | **Handoff** | `veto_handoff` · `veto_continue` · `veto_platform_setup` |
 | **Intelligence** | `veto_docs_fetch` · `veto_context_status` · `veto_task_parse` |
-| **Observability** | `veto_usage_status` · `veto_audit_log` · `veto_health` |
+| **Observability** | `veto_usage_status` · `veto_audit_log` · `veto_health` · `veto_metrics` |
 | **CI/CD** | `veto_ci_gate` · `veto_pr_review` |
-| **Discover** | `veto_discover` · `veto_summarize` |
+| **Discover** | `veto_discover` · `veto_summarize` · `veto_git_blame` · `veto_changelog` |
 | **Plugins** | `veto_plugins` |
 
 ## MCP Resources
@@ -160,10 +212,6 @@ All config files are home-directory relative — they apply globally across all
 
 ## CLI Commands
 
-Use these from any terminal to inspect Veto's brain without opening an AI session.
-
-After installing globally (`npm i -g @jigyasudham/veto`) or via npx:
-
 ```bash
 veto init                        # Configure all AI tools + scan project
 veto doctor                      # Check MCP registrations + system health
@@ -173,24 +221,17 @@ veto sessions                    # List last 20 saved sessions ([auto] badge on
 veto sessions --clean            # Remove auto-saves older than 7 days
 veto memory [query]              # Search knowledge base (blank = all entries)
 veto patterns [prefix]           # List learned agent/routing patterns
-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 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)
-
-# Without installing:
-npx @jigyasudham/veto help       # Same help output, no install needed
-npx @jigyasudham/veto status     # Check status from any machine
-npx @jigyasudham/veto doctor     # Diagnose MCP setup from any machine
 ```
 
-`veto help` shows all CLI commands, all 45 MCP tool names, MCP Resources, and MCP Prompts. `veto help --troubleshoot` shows the full troubleshooting guide.
+`veto help` shows all CLI commands, all 49 MCP tool names, MCP Resources, and MCP Prompts.
 
 ### `veto doctor`
 
-Diagnoses your full Veto setup in one command:
-
 ```
 veto doctor
 
@@ -206,203 +247,249 @@ veto doctor
   ✓ Claude Code — registered
   ✓ Gemini CLI — registered
   · Codex CLI — not installed
-  · Cursor — not installed
+  · Zed — not installed
 
   ✓ All checks passed — Veto is healthy!
 ```
 
-Run `veto init` to repair any failing check.
-
 ---
 
-## Workspace Discovery
-
-`veto_discover` scans a project once and stores a rich context map in Veto memory. Every subsequent agent call can read from this map instead of re-scanning files.
+## Council Debate
 
 ```
-veto_discover { "project_dir": "/your/project" }
+veto_council_debate {
+  task: "migrate auth from sessions to JWTs",
+  project_dir: "/your/project",
+  strictness: "standard"      ← fast | standard | strict
+}
 → {
-    git:        { branch: "main", commit: "a3f2b1", dirty_files: [], recent_commits: [...] },
-    ecosystems: { node: "my-app v2.1.0" },
-    tech_stack: ["TypeScript", "React", "Prisma"],
-    key_files:  ["tsconfig.json", "prisma/schema.prisma", ".env.example"],
-    total_files: 142,
-    structure:  ["src/", "  components/", "  api/", ...]
+    final_verdict: "YELLOW",
+    block_reasons: [],
+    warnings: ["JWT revocation requires a token blocklist — plan storage", "Clock skew between services can break expiry checks"],
+    votes: {
+      lead_dev:  { verdict: "warn",    reason: "Stateless JWTs complicate logout flows...", concerns: [...] },
+      architect: { verdict: "approve", reason: "Good fit for microservices...", concerns: [...] },
+      security:  { verdict: "warn",    reason: "Refresh token rotation must be atomic...", concerns: [...] },
+      ...
+    },
+    recommended: "Proceed with JWT migration. Implement a Redis blocklist for logout..."
   }
 ```
 
-Three depth levels: `quick` (git + package metadata only), `standard` (+ file tree, default), `full`.
+When the task presents a binary choice, agents name the option they prefer:
+
+```
+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...
+```
 
 ---
 
-## Project Summarization
+## Session Tagging + Search
 
-`veto_summarize` gives you a concise expert briefing on any project or file — useful when starting work on unfamiliar code.
+Tag sessions when saving to make them findable later:
 
 ```
-veto_summarize { "project_dir": "/your/project" }
-→ {
-    subject: "project",
-    tech_stack: ["TypeScript", "Next.js", "Prisma"],
-    summary: {
-      bullets: [
-        "Full-stack Next.js app with Prisma ORM and PostgreSQL",
-        "Auth via NextAuth — sessions stored in DB, not JWT",
-        "API routes under /src/app/api — RESTful, no tRPC",
-        "Background jobs via BullMQ with Redis",
-        "Deployed on Vercel — preview branches auto-deploy"
-      ]
-    }
-  }
-
-# File-level:
-veto_summarize { "file_path": "/your/project/src/auth.ts", "focus": "security" }
+veto_session_save {
+  summary: "Implemented JWT auth middleware",
+  context: "...",
+  tags: ["auth", "jwt", "middleware"]
+}
 
-# Detailed prose instead of bullets:
-veto_summarize { "project_dir": "/your/project", "format": "detailed" }
+# Find it weeks later:
+veto_sessions_list { query: "auth" }
+→ sessions matching "auth" in summary, context, tags, or project_dir
 ```
 
 ---
 
-## Codebase-Aware Agents
+## New in v1.4.1
 
-Pass `project_dir` to any agent tool — Veto auto-injects:
-- Project name, version, dependency list
-- Detected tech stack (React, Next.js, Prisma, Express, MCP, etc.)
-- Recent `git diff --stat` and last 5 commits
-- Config files present (tsconfig, vite.config, tailwind, etc.)
+### 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:
 ```
-veto_council_debate {
-  task: "migrate auth from sessions to JWTs",
-  project_dir: "/your/project"   ← agents now know your actual stack
-}
+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)
+```
 
-## Diff Review
+LLM-backed agents (when MCP Sampling is available) are now explicitly instructed to name the preferred option in their recommendation.
+
+### `veto_session_restore` — resume instructions
 
-Auto-reads `git diff HEAD` from `project_dir`, or pass a diff string directly:
+The restore response now includes a `resume_instructions` field that tells the AI exactly what to do:
 
 ```
-veto_diff_review { project_dir: "/your/project" }
+veto_session_restore { session_id: "..." }
 → {
-    verdict: "warn",
-    files_changed: 4,
-    code_review:   { score: 78, critical: 0, high: 2, findings: [...] },
-    security:      { score: 91, critical: 0, high: 0, findings: [...] },
-    secrets:       { findings: [] },
-    summary: "⚠️  WARN — 4 file(s) changed\nCode: approved_with_warnings (78/100)\n..."
+    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..." },
+    ...
   }
 ```
 
-Works as a pre-commit hook or CI step. The `summary` field is a single string ready to post as a PR comment.
+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)"] }
+```
 
 ---
 
-## GitHub PR Review
+## New in v1.4.0
 
-Pass a PR URL — Veto fetches the diff and runs the full triple-scan automatically:
+### `veto_metrics` — usage dashboard
 
 ```
-veto_pr_review { pr_url: "https://github.com/owner/repo/pull/42" }
+veto_metrics {}
 → {
-    verdict: "warn",
-    pr: { title: "Add auth middleware", author: "jigyasudham", changed_files: 6, ... },
-    checks: {
-      code_review: { score: 78, critical: 0, high: 2 },
-      security:    { score: 91, critical: 0, high: 0 },
-      secrets:     { clean: true }
-    },
-    review_comment: "## ⚠️ Veto Review — WARN\n...",  ← paste directly into GitHub
-    blocking_issues: []
+    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 }
   }
 ```
 
-Set `GITHUB_TOKEN` in your environment for private repos. Public repos need no auth.
+### `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: [...] }
+    ]
+  }
+```
 
-## Sequential Pipelines
+### `veto_git_blame` — ownership data
 
 ```
-veto_workflow {
-  steps: [
-    { id: "code",     agent: "coder",    task: "implement auth middleware", gate: 70 },
-    { id: "review",   agent: "reviewer", task: "review the implementation", gate: 75 },
-    { id: "security", agent: "security-scanner", task: "scan for vulnerabilities", gate: 80 },
-    { id: "test",     agent: "tester",   task: "write test cases" }
-  ],
-  project_dir: "/your/project"
-}
-→ { verdict: "passed", steps_passed: 4, steps_failed: 0, results: [...] }
+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"
+  }
 ```
 
-If any step's confidence falls below its gate, the pipeline halts and returns `partial` with the exact failure point.
+### `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
 
-## Reactive File Watching
+# Still works for files
+veto_explain { file_path: "/your/project/src/auth.ts", depth: "detailed" }
+```
 
-```bash
-veto_watch { project_dir: "/your/project" }
-→ { watch_id: "a3f2b1c0" }
+### Council `strictness` parameter
 
-# make some changes, then:
-veto_watch_poll { watch_id: "a3f2b1c0" }
-→ [
-    { file: "src/auth.ts",  recommended_agent: "code-quality", suggested_tool: "veto_code_review" },
-    { file: "package.json", recommended_agent: "dependency-audit", suggested_tool: "veto_agent_plan" },
-    { file: ".env",         recommended_agent: "secrets", suggested_tool: "veto_secrets_scan" }
-  ]
+```
+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
 ```
 
 ---
 
-## Self-Learning Router
+## Workspace Discovery
 
-The router improves automatically — no manual steps needed.
+```
+veto_discover { "project_dir": "/your/project" }
+→ {
+    git:        { branch: "main", commit: "a3f2b1", dirty_files: [], recent_commits: [...] },
+    ecosystems: { node: "my-app v2.1.0" },
+    tech_stack: ["TypeScript", "React", "Prisma"],
+    key_files:  ["tsconfig.json", "prisma/schema.prisma", ".env.example"],
+    total_files: 142
+  }
+```
 
-Every tool that runs an agent auto-records a `learning_data` row when it completes. After any normal working session, `veto_learning_stats` will show live data and `veto_learning_apply` will start producing meaningful threshold adjustments after ~20 tool calls.
+---
 
-**What auto-records (all of these, without any extra call):**
+## Diff Review
 
-| Tool | Quality signal used |
-|---|---|
-| `veto_council_debate` | Verdict: GREEN → 90, YELLOW → 60, RED → 20, DEADLOCK → 50 |
-| `veto_workflow` | Per-step confidence score |
-| `veto_execute_parallel` | Per-task confidence score |
-| `veto_route_task` | Routing registered (tier distribution) |
-| `veto_agent_plan` | Agent confidence |
-| `veto_code_review` | Analysis score |
-| `veto_security_scan` | Analysis score |
-| `veto_secrets_scan` | Clean = 100, findings found = score |
-| `veto_diff_review` | Average of code + security scores |
-| `veto_ci_gate` | Average of code + security scores |
-| `veto_pr_review` | Average of code + security scores |
-| `veto_explain` | Agent confidence |
-| `veto_task_parse` | Planner confidence |
-| `veto_summarize` | Agent confidence |
-
-You can still record manually for custom signals:
+```
+veto_diff_review { project_dir: "/your/project" }
+→ {
+    verdict: "warn",
+    files_changed: 4,
+    code_review: { score: 78, critical: 0, high: 2, findings: [...] },
+    security:    { score: 91, critical: 0, high: 0, findings: [...] },
+    secrets:     { findings: [] },
+    summary: "⚠️  WARN — 4 file(s) changed..."
+  }
+```
 
-```bash
-veto_record_outcome {
-  task_type: "fix-auth-bug",
-  complexity: 45,
-  model_tier: 2,
-  output_quality: 88,
-  agent: "debugger",
-  file_ext: ".ts"         # ← teaches which agent works best for .ts files
+---
+
+## Sequential Pipelines
+
+```
+veto_workflow {
+  steps: [
+    { id: "code",     agent: "coder",           task: "implement auth middleware", gate: 70 },
+    { id: "review",   agent: "reviewer",         task: "review the implementation", gate: 75 },
+    { id: "security", agent: "security-scanner", task: "scan for vulnerabilities",  gate: 80 },
+    { id: "test",     agent: "tester",           task: "write test cases" }
+  ],
+  project_dir: "/your/project"
 }
+→ { verdict: "passed", steps_passed: 4, steps_failed: 0, results: [...] }
 ```
 
-```bash
-# After 20+ outcomes (auto or manual):
-veto_learning_apply       # adjusts tier thresholds from your actual data
+---
+
+## Self-Learning Router
+
+Every agent tool auto-records a quality signal when it completes. After any working session, `veto_learning_stats` shows live data and `veto_learning_apply` adjusts tier thresholds automatically after ~20 calls.
 
-# Next route_task call:
+```bash
 veto_route_task { task: "debug auth issue", file_ext: ".ts" }
 → { ..., recommended_agent: "debugger" }   # ← predicted from history
 ```
@@ -411,15 +498,11 @@ veto_route_task { task: "debug auth issue", file_ext: ".ts" }
 
 ## Plugin System
 
-Register custom agents without forking:
-
 ```js
 // ~/.veto/agents/my-agent.js
 export function plan(task, context) {
   return {
-    agent: 'my-agent',
-    task,
-    tier: 2,
+    agent: 'my-agent', task, tier: 2,
     approach: 'Your custom approach...',
     steps: ['Step 1', 'Step 2'],
     checklist: ['[ ] Check 1'],
@@ -430,31 +513,16 @@ export function plan(task, context) {
 }
 ```
 
-Veto loads it on start. Use it in `veto_agent_plan { agent: "my-agent" }` or `veto_execute_parallel`.
-
 ---
 
 ## Cross-Platform Handoff
 
-**Rate limit mid-task:**
 ```
 Claude at 90%  →  veto_handoff { summary, context }
 Open Gemini    →  veto_continue { resuming_as: "gemini" }
 Full context restored. Continue exactly where you stopped.
 ```
 
-Every session tracks two fields:
-- `created_by` — which AI originally saved the session
-- `active_client` — which AI last resumed it (updated on every `veto_continue` or `veto_session_restore`)
-
-**Multiple AIs on different projects simultaneously:** Each MCP server process is independent. Sessions are always separate. Memory is automatically scoped to each process's active project — no cross-contamination.
-
-**Switch machines:**
-```
-Machine A  →  veto_memory_export  →  veto-export.json
-Machine B  →  veto_memory_import  →  veto_session_restore
-```
-
 | Platform | Support |
 |---|---|
 | Claude Code | ✅ Native MCP |
@@ -462,6 +530,7 @@ Machine B  →  veto_memory_import  →  veto_session_restore
 | Codex CLI | ✅ MCP support |
 | Cursor | ✅ MCP support |
 | Windsurf | ✅ MCP support |
+| Zed | ✅ MCP support (`context_servers`) |
 
 ---
 
@@ -469,79 +538,62 @@ Machine B  →  veto_memory_import  →  veto_session_restore
 
 | Phase | Status | Version |
 |---|---|---|
-| 1 — Foundation | ✅ Complete | v0.1.0 |
-| 2 — Router | ✅ Complete | v0.2.0 |
-| 3 — Council | ✅ Complete | v0.3.0 |
-| 4 — Core Agents | ✅ Complete | v0.4.0 |
-| 5 — Memory System | ✅ Complete | v0.5.0 |
-| 6 — Self-Learning | ✅ Complete | v0.6.0 |
-| 7 — Cross-Platform | ✅ Complete | v0.7.0 |
-| 8 — All 50 Agents | ✅ Complete | v0.8.0 |
-| 9 — Codebase Context + Structured Output + MCP Resources/Prompts | ✅ Complete | v0.9.0 |
-| 10 — Watch, Workflow, Explain, Plugins | ✅ Complete | v0.10.0 |
-| 11 — Smarter Council + Predictive Routing + Auto Project Map | ✅ Complete | v0.11.0 |
-| 12 — CLI Subcommands + Diff Review | ✅ Complete | v1.0.0 |
+| 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 (status bar, PR review, Learning Stats panel, secrets trigger) | ✅ Complete | veto-vscode v0.6.0 |
-| 19 — Auto-Learning Hooks (every agent tool auto-records outcomes) | ✅ Complete | v1.2.15 |
-| 20 — Auto-Store Memory (RED verdict + critical scan findings → Memory panel) | ✅ Complete | v1.2.16 |
-| CLI Polish — `veto version`, short help, session transparency, TAGLINE constant | ✅ Complete | v1.2.17 |
-| 21 — Closing the Loop (#42 auto-thresholds, #43 pre-commit hook, #44 veto_benchmark) | ✅ Complete | v1.2.18 |
+| 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, preventing session inflation when refreshing mid-conversation
+- **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 the router thresholds update automatically, no manual `veto_learning_apply` needed
-- **feat:** `veto hook install` / `veto hook remove` — writes a `.git/hooks/pre-commit` that blocks commits containing critical/high secrets
-- **feat:** `veto check` — fast secrets scan on staged changes (used by the hook, also runnable standalone)
-- **feat:** `veto_benchmark` tool (tool #46) — two approaches → two parallel council debates → structured winner with verdict, confidence, warning delta, and per-agent votes
+- **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` (and `veto v`) no longer shows "Unknown command" — now an alias for `veto status`
-- **fix:** Unknown commands show a short 2-line error instead of the full 100-line help wall
-- **fix:** `veto help` is now ~50 lines (commands + tools + resources). Full troubleshooting guide moved to `veto help --troubleshoot`
-- **fix:** Tagline `"50 agents. 45 tools. 3 AIs."` extracted to a single `TAGLINE` constant in `cli.ts` — only one place to update when tool count changes
-- **feat:** Sessions now track `save_type` (`manual` | `auto`) — auto-saves show a dim `[auto]` badge in `veto sessions` output
-- **feat:** `veto sessions --clean` removes auto-saves older than 7 days (keeps all manual saves)
-
-### v1.2.16
-- **feat:** Auto-store knowledge entries on RED council verdict and critical scan failures — entries appear in the VS Code Memory panel immediately without any manual `veto_memory_store` call. RED verdict stores block reasons + warnings + recommended action. Critical findings from `veto_diff_review`, `veto_ci_gate`, and `veto_pr_review` store the blocking issue list when verdict is `fail`.
-
-### v1.2.15
-- **feat:** Auto-learning hooks — `learning_data` now fills automatically from every agent-producing tool. No manual `veto_record_outcome` calls needed. Hooks fire on `veto_council_debate` (verdict → quality score), `veto_workflow` (per-step confidence), `veto_execute_parallel` (per-task confidence), `veto_route_task` (tier distribution), plus `veto_agent_plan`, `veto_code_review`, `veto_security_scan`, `veto_secrets_scan`, `veto_diff_review`, `veto_ci_gate`, `veto_pr_review`, `veto_explain`, `veto_task_parse`, and `veto_summarize`. After any working session, `veto_learning_stats` shows live data and `veto_learning_apply` starts producing real threshold adjustments after ~20 calls.
-
-### v1.2.14
-- **feat:** Token budget per operation — `max_tokens` optional param on `veto_council_debate` and `veto_execute_parallel`; warns if estimated output exceeds budget; all calls logged to new `usage_log` table; `veto_usage_status` now includes `operation_budget_log`
-- **feat:** MCP tool risk annotations — all 45 tools annotated with `readOnlyHint`, `destructiveHint`, `openWorldHint` using the official MCP SDK annotation fields; 23 read-only, 3 destructive, 2 open-world
-
-### v1.2.13
-- **feat:** Real token tracking for Rate Status — `tokens_today` and `budget_used_pct` per platform; `veto_usage_status` accepts `set_budget` to configure daily token limits (defaults: Claude 500K, Gemini 1M, Codex 200K)
-
-### v1.2.12
-- **feat:** `veto_pr_review` — pass a GitHub PR URL, Veto fetches the diff via GitHub API and runs the full triple-scan (code review + security + secrets). Returns a structured verdict and ready-to-post GitHub review comment. Set `GITHUB_TOKEN` for private repos.
-
-### v1.2.11
-- **fix:** `veto init` now registers Codex CLI via `codex mcp add` (writes to `~/.codex/config.toml`) instead of `config.json` — Codex CLI ignores `mcpServers` in JSON entirely
-- **fix:** `veto doctor` checks `codex mcp list` / `config.toml` for Codex registration instead of the wrong `config.json` key
-- **fix:** `veto_platform_setup` for Codex now shows the correct TOML-based config path, `codex mcp add` install command, and a Windows `npx.cmd` note
-- **fix:** Windows — `veto init` passes `npx.cmd` to `codex mcp add` so the Codex Rust binary can resolve the command
-
-### v1.2.10
-- **fix:** `veto init` writes `npx.cmd` (not `npx`) for all platform configs on Windows — Node's `child_process.spawn` cannot resolve bare `npx` on Windows
+- **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.8 — v1.2.9
-- `veto_summarize` tool — compress any session into a portable summary
-- `veto doctor` CLI command — full system health check with per-platform registration status
-- Shared `discover` module powering both `veto_discover` and `veto init` project scanning
+### 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.
 
 ---
 
@@ -551,7 +603,7 @@ Machine B  →  veto_memory_import  →  veto_session_restore
 - **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
+- **Platforms:** Claude Code · Gemini CLI · Codex CLI · Cursor · Windsurf · Zed
 
 ---