@vibecheckai/cli 3.0.4 → 3.0.7

package/bin/vibecheck.js

@@ -1,17 +1,26 @@
 #!/usr/bin/env node
-// bin/vibecheck.js
+// bin/vibecheck.js - World-Class CLI
+// ═══════════════════════════════════════════════════════════════════════════════
+// VibeCheck - Proves your app is real
+// Ship with confidence. Catch fake features before your users do.
+// ═══════════════════════════════════════════════════════════════════════════════
+
+"use strict";
+
 const readline = require("readline");
 const path = require("path");
 const fs = require("fs");
-const { routeArgv } = require("./_router");
-const { warnDeprecationOnce } = require("./_deprecations");
-const {
-  getApiKey,
-  checkEntitlement,
-  getEntitlements,
-} = require("./runners/lib/auth");
-
-// Read version from package.json
+const os = require("os");
+const { performance } = require("perf_hooks");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// PERFORMANCE: Track startup time
+// ═══════════════════════════════════════════════════════════════════════════════
+const STARTUP_TIME = performance.now();
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// VERSION & METADATA
+// ═══════════════════════════════════════════════════════════════════════════════
 function getVersion() {
   try {
     const pkgPath = path.join(__dirname, "..", "package.json");
@@ -22,813 +31,450 @@ function getVersion() {
   }
 }
 
-// Runners
-const { runScan } = require("./runners/runScan");
-const { runGate } = require("./runners/runGate");
-const { runContext } = require("./runners/runContext");
-const { runDashboard, runDemo } = require("./runners/runDashboard");
-const { runFix } = require("./runners/runFix");
-const { runShip } = require("./runners/runShip");
-const { runLaunch } = require("./runners/runLaunch");
-const { runAutopilot } = require("./runners/runAutopilot");
-const { runProof } = require("./runners/runProof");
-
-// Graceful loading for modules that may have syntax issues
-let runReality, runRealitySniff;
-try {
-  runReality = require("./runners/runReality").runReality;
-} catch (e) {
-  runReality = async () => { console.error("Reality runner unavailable:", e.message); return 1; };
-}
-try {
-  runRealitySniff = require("./runners/runRealitySniff").runRealitySniff;
-} catch (e) {
-  runRealitySniff = async () => { console.error("RealitySniff runner unavailable:", e.message); return 1; };
-}
-const { runValidate } = require("./runners/runValidate");
-const { runDoctor } = require("./runners/runDoctor");
-const { runInit } = require("./runners/runInit");
-const { runMcp } = require("./runners/runMcp");
-const { runLogin, runLogout, runWhoami } = require("./runners/runAuth");
-const {
-  runNaturalLanguage,
-  isNaturalLanguageCommand,
-} = require("./runners/runNaturalLanguage");
-const { runAIAgent } = require("./runners/runAIAgent");
-const { runBadge } = require("./runners/runBadge");
-const { runUpgrade } = require("./runners/runUpgrade");
-const { runCertify } = require("./runners/runCertify");
-const { runVerifyAgentOutput } = require("./runners/runVerifyAgentOutput");
-const { runFixPacks } = require("./runners/runFixPacks");
-const { runAudit } = require("./runners/runAudit");
-const { runMdc } = require("./runners/runMdc");
-const { runEnhancedShip } = require("./runners/runEnhancedShip");
-const { runPromptFirewall } = require("./runners/runPromptFirewall");
-
-// Route Truth v1 - ctx command
-const { runCtx } = require("./runners/runCtx");
-// Share command
-const { runShare } = require("./runners/runShare");
-// PR command
-const { runPR } = require("./runners/runPR");
-// Init GHA command
-const { runInitGha } = require("./runners/runInitGha");
-// Install command
-const { runInstall } = require("./runners/runInstall");
-// Prove command
-const { runProve } = require("./runners/runProve");
-// Watch command
-const { runWatch } = require("./runners/runWatch");
-// Status command
-const { runStatus } = require("./runners/runStatus");
-// Graph command - Reality Proof Graph
-const { runGraph } = require("./runners/runGraph");
-// Permissions command - AuthZ Matrix & IDOR
-const { runPermissions } = require("./runners/runPermissions");
-// Replay command - Record and replay user sessions
-const { runReplay } = require("./runners/runReplay");
-// Context Contracts commands
-const { runCtxSync } = require("./runners/runCtxSync");
-const { runCtxGuard } = require("./runners/runCtxGuard");
-
-// Truth Pack v1 - Core truth system
-let runTruthpack;
-try {
-  runTruthpack = require("./runners/runTruthpack").runTruthpack;
-} catch (e) {
-  runTruthpack = async () => { console.error("Truthpack runner unavailable:", e.message); return 1; };
-}
-
 const VERSION = getVersion();
-
-// ANSI colors
-const c = {
+const CLI_NAME = "vibecheck";
+const CONFIG_FILE = ".vibecheckrc";
+const CACHE_DIR = path.join(os.homedir(), ".vibecheck");
+const STATE_FILE = path.join(CACHE_DIR, "state.json");
+const UPDATE_CHECK_INTERVAL = 24 * 60 * 60 * 1000; // 24 hours
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ANSI STYLES - Premium terminal styling with gradient support
+// ═══════════════════════════════════════════════════════════════════════════════
+const SUPPORTS_COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+const SUPPORTS_TRUECOLOR = SUPPORTS_COLOR && (
+  process.env.COLORTERM === "truecolor" ||
+  process.env.TERM_PROGRAM === "iTerm.app" ||
+  process.env.TERM_PROGRAM === "Apple_Terminal" ||
+  process.env.WT_SESSION // Windows Terminal
+);
+
+const c = SUPPORTS_COLOR ? {
   reset: "\x1b[0m",
+  bold: "\x1b[1m",
   dim: "\x1b[2m",
-  cyan: "\x1b[36m",
+  italic: "\x1b[3m",
+  underline: "\x1b[4m",
+  blink: "\x1b[5m",
+  inverse: "\x1b[7m",
+  hidden: "\x1b[8m",
+  strikethrough: "\x1b[9m",
+  black: "\x1b[30m",
+  red: "\x1b[31m",
   green: "\x1b[32m",
   yellow: "\x1b[33m",
-  red: "\x1b[31m",
   blue: "\x1b[34m",
   magenta: "\x1b[35m",
-};
-
-// Detect CI/CD environment (non-interactive)
-function isCI() {
-  return !!(
-    process.env.CI ||
-    process.env.CONTINUOUS_INTEGRATION ||
-    process.env.RAILWAY_ENVIRONMENT ||
-    process.env.VERCEL ||
-    process.env.NETLIFY ||
-    process.env.GITHUB_ACTIONS ||
-    process.env.GITLAB_CI ||
-    process.env.CIRCLECI ||
-    process.env.TRAVIS ||
-    process.env.BUILDKITE ||
-    process.env.RENDER ||
-    process.env.HEROKU ||
-    !process.stdin.isTTY
-  );
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
+  brightRed: "\x1b[91m",
+  brightGreen: "\x1b[92m",
+  brightYellow: "\x1b[93m",
+  brightBlue: "\x1b[94m",
+  brightMagenta: "\x1b[95m",
+  brightCyan: "\x1b[96m",
+  brightWhite: "\x1b[97m",
+  bgRed: "\x1b[41m",
+  bgGreen: "\x1b[42m",
+  bgYellow: "\x1b[43m",
+  bgBlue: "\x1b[44m",
+  bgMagenta: "\x1b[45m",
+  bgCyan: "\x1b[46m",
+  bgWhite: "\x1b[47m",
+  bgGray: "\x1b[100m",
+  rgb: (r, g, b) => SUPPORTS_TRUECOLOR ? `\x1b[38;2;${r};${g};${b}m` : "",
+  bgRgb: (r, g, b) => SUPPORTS_TRUECOLOR ? `\x1b[48;2;${r};${g};${b}m` : "",
+} : Object.fromEntries([
+  "reset", "bold", "dim", "italic", "underline", "blink", "inverse", "hidden", "strikethrough",
+  "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "gray",
+  "brightRed", "brightGreen", "brightYellow", "brightBlue", "brightMagenta", "brightCyan", "brightWhite",
+  "bgRed", "bgGreen", "bgYellow", "bgBlue", "bgMagenta", "bgCyan", "bgWhite", "bgGray"
+].map(k => [k, ""]));
+
+// Gradient text generator (cyan → magenta → yellow)
+function gradient(text, colors = [[0, 255, 255], [255, 0, 255], [255, 255, 0]]) {
+  if (!SUPPORTS_TRUECOLOR) return `${c.cyan}${text}${c.reset}`;
+  const chars = [...text];
+  const len = chars.length;
+  if (len === 0) return text;
+  return chars.map((char, i) => {
+    const t = i / Math.max(len - 1, 1);
+    const segmentLen = colors.length - 1;
+    const segment = Math.min(Math.floor(t * segmentLen), segmentLen - 1);
+    const localT = (t * segmentLen) - segment;
+    const c1 = colors[segment];
+    const c2 = colors[segment + 1] || c1;
+    const r = Math.round(c1[0] + (c2[0] - c1[0]) * localT);
+    const g = Math.round(c1[1] + (c2[1] - c1[1]) * localT);
+    const b = Math.round(c1[2] + (c2[2] - c1[2]) * localT);
+    return `${c.rgb(r, g, b)}${char}`;
+  }).join("") + c.reset;
 }
 
-// ============================================================================
-// TIER-BASED COMMAND ACCESS
-// ============================================================================
-// FREE ($0) - No API key needed
-const FREE_COMMANDS = [
-  "help",
-  "version",
-  "doctor",
-  "init",
-  "login",
-  "logout",
-  "whoami",
-  "scan", // Route integrity + security analysis
-  "validate", // AI code validation
-  "badge", // Generate badges
-  "certify", // Certification badges (SEO fuel)
-  "context", // AI rules generator
-  "dashboard", // Real-time monitoring
-  "demo", // Interactive demo
-  "upgrade", // Subscription management
-  "verify-agent-output", // Verify AI agent output
-  "mdc", // MDC documentation generator
-  "prompt-firewall", // Prompt firewall (free tier with limited features)
-  "firewall", // Alias for prompt-firewall
-  "ctx", // Truth Pack generator
-  "truthpack", // Alias for ctx
-  "replay", // Record and replay user sessions
-  "graph", // Reality Proof Graph
-  "status", // Quick project status
-  "watch", // Continuous dev mode
-  "prove", // One command reality proof
-  "install", // Zero-friction onboarding
-  "pr", // PR comment generator
-  "share", // Share bundle generator
-  "reality", // Runtime UI verification
-];
-
-// STARTER ($19/mo) - Requires API key with starter+ plan
-const STARTER_COMMANDS = {
-  ship: "ship:audit", // Plain English audit
-  "enhanced-ship": "enhanced-ship:full", // Enhanced ship decision with all features
-  gate: "gate:ci", // CI/CD gate
-  reality: "reality:basic", // Browser testing
-  launch: "launch:checklist", // Pre-launch wizard
-};
-
-// PRO ($49/mo) - Requires API key with pro+ plan
-const PRO_COMMANDS = {
-  "ai-test": "ai:agent", // AI Agent testing
-  ai: "ai:agent",
-  agent: "ai:agent",
-  // fix: removed - handled specially to allow --plan-only on FREE tier
-  autopilot: "autopilot:enable", // Continuous protection
-};
-
-// Commands with FREE tier read-only modes
-const TIERED_COMMANDS = {
-  fix: {
-    freeArgs: ["--plan-only", "--help", "-h"], // Allow these args on FREE
-    requiredScope: "fix:apply",
-    tier: "pro",
-  },
-};
-
-// Special: proof command has sub-modes with different tiers
-const PROOF_COMMANDS = {
-  mocks: "proof:mocks", // Starter+
-  reality: "proof:reality", // Pro+
-};
-
-// Commands that always work (utilities)
-const UTILITY_COMMANDS = ["mcp", "rules", "api", "deps", "sbom", "fixpacks"];
-
-// Compliance tier commands
-const COMPLIANCE_COMMANDS = {
-  audit: "audit:full", // Full audit trail
+// ═══════════════════════════════════════════════════════════════════════════════
+// UNICODE SYMBOLS - Rich visual indicators
+// ═══════════════════════════════════════════════════════════════════════════════
+const SUPPORTS_UNICODE = process.platform !== "win32" || process.env.WT_SESSION || process.env.TERM_PROGRAM;
+
+const sym = SUPPORTS_UNICODE ? {
+  success: "✓", error: "✗", warning: "⚠", info: "ℹ", pending: "○", active: "●",
+  spinner: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+  progress: ["░", "▒", "▓", "█"],
+  arrow: "→", arrowRight: "▸", arrowDown: "▾", bullet: "•",
+  star: "★", starEmpty: "☆", heart: "♥", shield: "🛡️", rocket: "🚀",
+  fire: "🔥", sparkles: "✨", check: "☑", box: "☐", lock: "🔒",
+  key: "🔑", lightning: "⚡", clock: "⏱", folder: "📁", file: "📄",
+  gear: "⚙", chart: "📊",
+  boxTopLeft: "╭", boxTopRight: "╮", boxBottomLeft: "╰", boxBottomRight: "╯",
+  boxHorizontal: "─", boxVertical: "│", boxCross: "┼",
+  boxHorizontalDown: "┬", boxHorizontalUp: "┴",
+  boxVerticalRight: "├", boxVerticalLeft: "┤",
+  dblBoxTopLeft: "╔", dblBoxTopRight: "╗", dblBoxBottomLeft: "╚", dblBoxBottomRight: "╝",
+  dblBoxHorizontal: "═", dblBoxVertical: "║",
+} : {
+  success: "√", error: "×", warning: "!", info: "i", pending: "o", active: "*",
+  spinner: ["-", "\\", "|", "/"], progress: [".", ":", "#", "#"],
+  arrow: "->", arrowRight: ">", arrowDown: "v", bullet: "*",
+  star: "*", starEmpty: "o", heart: "<3", shield: "[#]", rocket: ">>",
+  fire: "(!)", sparkles: "*", check: "[x]", box: "[ ]", lock: "[L]",
+  key: "[K]", lightning: "!", clock: "[T]", folder: "[D]", file: "[F]",
+  gear: "[G]", chart: "[C]",
+  boxTopLeft: "+", boxTopRight: "+", boxBottomLeft: "+", boxBottomRight: "+",
+  boxHorizontal: "-", boxVertical: "|", boxCross: "+",
+  boxHorizontalDown: "+", boxHorizontalUp: "+",
+  boxVerticalRight: "+", boxVerticalLeft: "+",
+  dblBoxTopLeft: "+", dblBoxTopRight: "+", dblBoxBottomLeft: "+", dblBoxBottomRight: "+",
+  dblBoxHorizontal: "=", dblBoxVertical: "||",
 };
 
-async function prompt(question) {
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer.trim());
-    });
-  });
+// ═══════════════════════════════════════════════════════════════════════════════
+// SPINNER & PROGRESS
+// ═══════════════════════════════════════════════════════════════════════════════
+function isCI() {
+  return !!(process.env.CI || process.env.CONTINUOUS_INTEGRATION || process.env.RAILWAY_ENVIRONMENT ||
+    process.env.VERCEL || process.env.NETLIFY || process.env.GITHUB_ACTIONS || process.env.GITLAB_CI ||
+    process.env.CIRCLECI || process.env.TRAVIS || process.env.BUILDKITE || process.env.RENDER ||
+    process.env.HEROKU || process.env.CODEBUILD_BUILD_ID || process.env.JENKINS_URL ||
+    process.env.TEAMCITY_VERSION || process.env.TF_BUILD || !process.stdin.isTTY);
 }
 
-async function showWelcomeAndPromptLogin() {
-  console.log(`
-${c.cyan}╔════════════════════════════════════════════════════════════╗
-║  ${c.reset}🛡️  VIBECHECK${c.cyan}                                              ║
-╚════════════════════════════════════════════════════════════╝${c.reset}
-
-${c.dim}Ship with confidence. Catch fake features before your users do.${c.reset}
+class Spinner {
+  constructor(text = "") {
+    this.text = text; this.frame = 0; this.interval = null;
+    this.stream = process.stderr; this.isCI = isCI();
+  }
+  start(text) {
+    if (text) this.text = text;
+    if (this.isCI) { this.stream.write(`${c.dim}${sym.pending}${c.reset} ${this.text}\n`); return this; }
+    this.interval = setInterval(() => {
+      const spinner = sym.spinner[this.frame % sym.spinner.length];
+      this.stream.write(`\r${c.cyan}${spinner}${c.reset} ${this.text}`);
+      this.frame++;
+    }, 80);
+    return this;
+  }
+  update(text) { this.text = text; if (this.isCI) this.stream.write(`  ${c.dim}${sym.arrowRight}${c.reset} ${text}\n`); return this; }
+  succeed(text) { this.stop(); this.stream.write(`\r${c.green}${sym.success}${c.reset} ${text || this.text}\n`); return this; }
+  fail(text) { this.stop(); this.stream.write(`\r${c.red}${sym.error}${c.reset} ${text || this.text}\n`); return this; }
+  warn(text) { this.stop(); this.stream.write(`\r${c.yellow}${sym.warning}${c.reset} ${text || this.text}\n`); return this; }
+  info(text) { this.stop(); this.stream.write(`\r${c.blue}${sym.info}${c.reset} ${text || this.text}\n`); return this; }
+  stop() { if (this.interval) { clearInterval(this.interval); this.interval = null; this.stream.write("\r\x1b[K"); } return this; }
+}
 
-`);
+function stripAnsi(str) { return str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, ""); }
 
-  const { key, source } = getApiKey();
-
-  if (!key) {
-    // In CI/CD environments, skip interactive prompts
-    if (isCI()) {
-      console.log(`${c.yellow}⚠ No API key found${c.reset}`);
-      console.log(
-        `${c.dim}Running in CI mode with FREE tier features.${c.reset}`,
-      );
-      console.log(
-        `${c.dim}Set VIBECHECK_API_KEY env var to unlock more features.${c.reset}\n`,
-      );
-      return { key: null, entitlements: null };
-    }
+function ensureCacheDir() { if (!fs.existsSync(CACHE_DIR)) fs.mkdirSync(CACHE_DIR, { recursive: true }); }
 
-    console.log(`${c.yellow}⚠ No API key found${c.reset}`);
-    console.log(`
-${c.dim}To unlock all features, you need a vibecheck API key.${c.reset}
+function loadState() {
+  try { if (fs.existsSync(STATE_FILE)) return JSON.parse(fs.readFileSync(STATE_FILE, "utf-8")); } catch {}
+  return { firstRun: Date.now(), lastRun: null, runCount: 0, lastUpdateCheck: null, latestVersion: null, commandHistory: [], favorites: [] };
+}
 
-  ${c.green}FREE${c.reset}     scan, validate, badge, doctor, init
-  ${c.cyan}STARTER${c.reset}  ship, gate, reality, launch, proof mocks  ${c.dim}($29/mo)${c.reset}
-  ${c.magenta}PRO${c.reset}      ai-test, fix, autopilot, proof reality  ${c.dim}($99/mo)${c.reset}
+function saveState(state) { try { ensureCacheDir(); fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2)); } catch {} }
 
-${c.dim}Get your API key at: ${c.cyan}https://vibecheckai.dev/settings/keys${c.reset}
-`);
+function loadConfig() {
+  const config = { debug: false, verbose: false, quiet: false, color: true, analytics: true, updateCheck: true, timeout: 30000, maxRetries: 3 };
+  const projectConfigPath = path.join(process.cwd(), CONFIG_FILE);
+  if (fs.existsSync(projectConfigPath)) { try { Object.assign(config, JSON.parse(fs.readFileSync(projectConfigPath, "utf-8"))); } catch {} }
+  if (process.env.VIBECHECK_DEBUG === "true") config.debug = true;
+  if (process.env.VIBECHECK_VERBOSE === "true") config.verbose = true;
+  if (process.env.NO_COLOR || process.env.VIBECHECK_NO_COLOR) config.color = false;
+  return config;
+}
 
-    const answer = await prompt(
-      `${c.cyan}?${c.reset} Do you have an API key? (y/N) `,
-    );
-
-    if (answer.toLowerCase() === "y") {
-      const apiKey = await prompt(`${c.cyan}?${c.reset} Paste your API key: `);
-      if (apiKey) {
-        const { saveApiKey } = require("./runners/lib/auth");
-        console.log(`\n${c.dim}Verifying...${c.reset}`);
-
-        const entitlements = await getEntitlements(apiKey);
-        if (entitlements) {
-          saveApiKey(apiKey);
-          console.log(
-            `\n${c.green}✓${c.reset} Logged in as ${entitlements.user?.name || "User"}`,
-          );
-          console.log(
-            `${c.dim}Plan: ${entitlements.plan?.toUpperCase() || "FREE"}${c.reset}\n`,
-          );
-          return { key: apiKey, entitlements };
-        } else {
-          console.log(`\n${c.red}✗${c.reset} Invalid API key\n`);
-        }
-      }
+// ═══════════════════════════════════════════════════════════════════════════════
+// FUZZY MATCHING
+// ═══════════════════════════════════════════════════════════════════════════════
+function levenshtein(a, b) {
+  const matrix = [];
+  for (let i = 0; i <= b.length; i++) matrix[i] = [i];
+  for (let j = 0; j <= a.length; j++) matrix[0][j] = j;
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) matrix[i][j] = matrix[i - 1][j - 1];
+      else matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
     }
-
-    console.log(`
-${c.dim}Continuing in FREE mode. Some features will be limited.${c.reset}
-${c.dim}Run ${c.cyan}vibecheck login${c.dim} anytime to upgrade.${c.reset}
-`);
-    return { key: null, entitlements: null };
   }
-
-  // User has API key, get entitlements
-  const entitlements = await getEntitlements(key);
-  return { key, entitlements };
+  return matrix[b.length][a.length];
 }
 
-async function checkCommandAccess(cmd, entitlements, args = []) {
-  // Free commands always work (no API key needed)
-  if (FREE_COMMANDS.includes(cmd)) {
-    return { allowed: true, tier: "free" };
+function findSimilarCommands(input, commands, maxDistance = 3) {
+  const matches = [];
+  for (const cmd of commands) {
+    const distance = levenshtein(input.toLowerCase(), cmd.toLowerCase());
+    if (distance <= maxDistance) matches.push({ cmd, distance });
+    if (cmd.toLowerCase().startsWith(input.toLowerCase()) && input.length >= 2) matches.push({ cmd, distance: 0.5 });
   }
+  return matches.sort((a, b) => a.distance - b.distance).map(m => m.cmd).slice(0, 3);
+}
 
-  // Utility commands always work
-  if (UTILITY_COMMANDS.includes(cmd)) {
-    return { allowed: true, tier: "utility" };
-  }
+// ═══════════════════════════════════════════════════════════════════════════════
+// COMMAND REGISTRY
+// ═══════════════════════════════════════════════════════════════════════════════
+const COMMANDS = {
+  scan: { description: "Static truth - routes, contracts, secrets, coverage", tier: "free", category: "proof", aliases: ["s", "check"], runner: () => require("./runners/runScan").runScan },
+  ship: { description: "Verdict engine - SHIP / WARN / BLOCK decision", tier: "free", category: "proof", aliases: ["verdict"], runner: () => require("./runners/runShip").runShip },
+  reality: { description: "Runtime proof - Playwright clicks every button", tier: "free", category: "proof", aliases: ["r", "test", "e2e"], runner: () => { try { return require("./runners/runReality").runReality; } catch (e) { return async () => { console.error("Reality runner unavailable:", e.message); return 1; }; } } },
+  fix: { description: "Mission-based repair - targeted fixes with proof", tier: "pro", category: "proof", freeArgs: ["--plan-only", "--help", "-h"], aliases: ["f", "repair"], runner: () => require("./runners/runFix").runFix },
+  prove: { description: "One command - runs the full loop, fixes issues, proves SHIP", tier: "free", category: "proof", aliases: ["p", "full", "all"], runner: () => require("./runners/runProve").runProve },
+  report: { description: "HTML artifact - shareable proof of what shipped", tier: "free", category: "proof", aliases: ["html", "artifact"], runner: () => require("./runners/runReport").runReport },
+  init: { description: "Set up vibecheck (--gha for GitHub Actions)", tier: "free", category: "setup", aliases: ["setup", "configure"], runner: () => require("./runners/runInit").runInit },
+  install: { description: "Zero-friction onboarding - auto-detects everything", tier: "free", category: "setup", aliases: ["i", "bootstrap"], runner: () => require("./runners/runInstall").runInstall },
+  doctor: { description: "Environment + project diagnostics", tier: "free", category: "setup", aliases: ["health", "diag"], runner: () => require("./runners/runDoctor").runDoctor },
+  watch: { description: "Continuous mode - re-runs on file changes", tier: "free", category: "setup", aliases: ["w", "dev"], runner: () => require("./runners/runWatch").runWatch },
+  ctx: { description: "Generate truthpack - ground truth for AI agents", tier: "free", category: "truth", aliases: ["truthpack", "tp"], subcommands: ["build", "diff", "guard", "sync", "search"], runner: () => require("./runners/runCtx").runCtx },
+  guard: { description: "Trust boundaries - validates AI claims + prompt injection", tier: "free", category: "truth", aliases: ["validate", "trust"], runner: () => require("./runners/runGuard").runGuard },
+  context: { description: "Generate AI rules (.cursorrules, .windsurf/rules, etc.)", tier: "free", category: "truth", aliases: ["rules", "ai-rules"], runner: () => require("./runners/runContext").runContext },
+  mcp: { description: "Start MCP server for AI coding agents", tier: "free", category: "extras", aliases: [], runner: () => require("./runners/runMcp").runMcp },
+  badge: { description: "Generate ship badge for README/PR", tier: "free", category: "extras", aliases: ["b"], runner: () => require("./runners/runBadge").runBadge },
+  pr: { description: "Generate PR comment with findings", tier: "free", category: "extras", aliases: ["pull-request"], runner: () => require("./runners/runPR").runPR },
+  labs: { description: "Experimental features", tier: "free", category: "extras", aliases: ["experimental", "beta"], runner: () => require("./runners/runLabs").runLabs },
+  gate: { description: "CI/CD gate - blocks deploys on failures", tier: "starter", category: "ci", aliases: ["ci", "block"], scope: "gate:ci", runner: () => require("./runners/runGate").runGate },
+  "ai-test": { description: "AI Agent testing - autonomous test generation", tier: "pro", category: "automation", aliases: ["ai", "agent"], scope: "ai:agent", runner: () => require("./runners/runAIAgent").runAIAgent },
+  login: { description: "Authenticate with API key", tier: "free", category: "account", aliases: ["auth", "signin"], runner: () => require("./runners/runAuth").runLogin, skipAuth: true },
+  logout: { description: "Remove stored credentials", tier: "free", category: "account", aliases: ["signout"], runner: () => require("./runners/runAuth").runLogout, skipAuth: true },
+  whoami: { description: "Show current user and plan", tier: "free", category: "account", aliases: ["me", "user"], runner: () => require("./runners/runAuth").runWhoami, skipAuth: true },
+  mdc: { description: "Generate MDC specifications", tier: "free", category: "truth", aliases: [], runner: () => require("./runners/runMdc").runMdc },
+  status: { description: "Project status dashboard", tier: "free", category: "setup", aliases: ["st"], runner: () => require("./runners/runStatus").runStatus },
+  share: { description: "Generate share pack for PR/docs", tier: "free", category: "extras", aliases: [], runner: () => require("./runners/runShare").runShare },
+};
 
-  // Tiered commands with FREE read-only modes
-  if (TIERED_COMMANDS[cmd]) {
-    const config = TIERED_COMMANDS[cmd];
-    // Check if using a FREE tier argument
-    const hasFreeArg = args.some(arg => config.freeArgs.includes(arg));
-    // Also allow if no fix pack specified (shows help)
-    const hasNoFixPack = cmd === "fix" && !args.some(arg => !arg.startsWith("-"));
-    
-    if (hasFreeArg || hasNoFixPack) {
-      return { allowed: true, tier: "free" };
-    }
-    
-    // Requires paid tier
-    if (!entitlements) {
-      return {
-        allowed: false,
-        reason: `${c.yellow}${cmd}${c.reset} requires a ${c.magenta}PRO${c.reset} plan.\n\n  Run ${c.cyan}vibecheck login${c.reset} to authenticate.\n  Get your API key at: ${c.cyan}https://vibecheckai.dev/settings/keys${c.reset}`,
-      };
-    }
-    
-    if (
-      entitlements.scopes?.includes(config.requiredScope) ||
-      entitlements.scopes?.includes("*")
-    ) {
-      return { allowed: true, tier: config.tier };
-    }
-    
-    return {
-      allowed: false,
-      reason: `Your ${c.yellow}${entitlements.plan?.toUpperCase()}${c.reset} plan doesn't include this feature.\n\n  Required: ${config.requiredScope}\n  Upgrade to ${c.magenta}PRO${c.reset} at: ${c.cyan}https://vibecheckai.dev/pricing${c.reset}`,
-    };
-  }
+const ALIAS_MAP = {};
+for (const [cmd, def] of Object.entries(COMMANDS)) { for (const alias of def.aliases || []) ALIAS_MAP[alias] = cmd; }
+const ALL_COMMANDS = [...Object.keys(COMMANDS), ...Object.values(COMMANDS).flatMap(c => c.aliases || [])];
 
-  // Special handling for proof command (has sub-modes with different tiers)
-  if (cmd === "proof") {
-    const subMode = args[0]; // mocks or reality
-    if (subMode === "mocks") {
-      // Starter+ required
-      if (!entitlements) {
-        return {
-          allowed: false,
-          reason: `${c.yellow}proof mocks${c.reset} requires a ${c.cyan}STARTER${c.reset} plan or higher.\n\n  Run ${c.cyan}vibecheck login${c.reset} to authenticate.\n  Get your API key at: ${c.cyan}https://vibecheckai.dev/settings/keys${c.reset}`,
-        };
-      }
-      if (
-        entitlements.scopes?.includes("proof:mocks") ||
-        entitlements.scopes?.includes("*")
-      ) {
-        return { allowed: true, tier: "starter" };
-      }
-      return {
-        allowed: false,
-        reason: `Your ${c.yellow}${entitlements.plan?.toUpperCase()}${c.reset} plan doesn't include mock detection.\n\n  Upgrade to ${c.cyan}STARTER${c.reset} at: ${c.cyan}https://vibecheckai.dev/pricing${c.reset}`,
-      };
-    } else if (subMode === "reality") {
-      // Pro+ required
-      if (!entitlements) {
-        return {
-          allowed: false,
-          reason: `${c.yellow}proof reality${c.reset} requires a ${c.magenta}PRO${c.reset} plan.\n\n  Run ${c.cyan}vibecheck login${c.reset} to authenticate.\n  Get your API key at: ${c.cyan}https://vibecheckai.dev/settings/keys${c.reset}`,
-        };
-      }
-      if (
-        entitlements.scopes?.includes("proof:reality") ||
-        entitlements.scopes?.includes("*")
-      ) {
-        return { allowed: true, tier: "pro" };
-      }
-      return {
-        allowed: false,
-        reason: `Your ${c.yellow}${entitlements.plan?.toUpperCase()}${c.reset} plan doesn't include runtime verification.\n\n  Upgrade to ${c.magenta}PRO${c.reset} at: ${c.cyan}https://vibecheckai.dev/pricing${c.reset}`,
-      };
-    }
-    // No submode - show help
-    return { allowed: true };
-  }
+function getRunner(cmd) {
+  const def = COMMANDS[cmd];
+  if (!def) return null;
+  try { return def.runner(); } catch (e) { return async () => { console.error(`${c.red}${sym.error}${c.reset} Failed to load ${cmd}: ${e.message}`); return 1; }; }
+}
 
-  // STARTER tier commands
-  if (STARTER_COMMANDS[cmd]) {
-    const requiredScope = STARTER_COMMANDS[cmd];
+// ═══════════════════════════════════════════════════════════════════════════════
+// AUTH & ACCESS CONTROL
+// ═══════════════════════════════════════════════════════════════════════════════
+let authModule = null;
+function getAuthModule() { if (!authModule) authModule = require("./runners/lib/auth"); return authModule; }
+
+async function checkCommandAccess(cmd, args, entitlements) {
+  const def = COMMANDS[cmd];
+  if (!def) return { allowed: true };
+  if (def.tier === "free") return { allowed: true, tier: "free" };
+  if (!entitlements) return { allowed: false, tier: def.tier, reason: formatAccessDenied(cmd, def.tier, null) };
+  const hasAccess = entitlements.scopes?.includes(def.scope) || entitlements.scopes?.includes("*");
+  if (!hasAccess) return { allowed: false, tier: def.tier, reason: formatAccessDenied(cmd, def.tier, entitlements.plan) };
+  return { allowed: true, tier: def.tier };
+}
 
-    if (!entitlements) {
-      return {
-        allowed: false,
-        reason: `${c.yellow}${cmd}${c.reset} requires a ${c.cyan}STARTER${c.reset} plan or higher.\n\n  Run ${c.cyan}vibecheck login${c.reset} to authenticate.\n  Get your API key at: ${c.cyan}https://vibecheckai.dev/settings/keys${c.reset}`,
-      };
-    }
+function formatAccessDenied(cmd, requiredTier, currentPlan) {
+  const tierColors = { starter: c.cyan, pro: c.magenta, enterprise: c.yellow };
+  const tierColor = tierColors[requiredTier] || c.white;
+  let msg = `${c.yellow}${cmd}${c.reset} requires a ${tierColor}${requiredTier.toUpperCase()}${c.reset} plan.\n\n`;
+  if (!currentPlan) { msg += `  Run ${c.cyan}vibecheck login${c.reset} to authenticate.\n  Get your API key at: ${c.cyan}https://vibecheckai.dev/settings/keys${c.reset}`; }
+  else { msg += `  Your current plan: ${c.yellow}${currentPlan.toUpperCase()}${c.reset}\n  Upgrade at: ${c.cyan}https://vibecheckai.dev/pricing${c.reset}`; }
+  return msg;
+}
 
-    if (
-      entitlements.scopes?.includes(requiredScope) ||
-      entitlements.scopes?.includes("*")
-    ) {
-      return { allowed: true, tier: "starter" };
-    }
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELP SYSTEM
+// ═══════════════════════════════════════════════════════════════════════════════
+function printBanner() {
+  console.log(`
+${c.dim}${sym.boxTopLeft}${sym.boxHorizontal.repeat(60)}${sym.boxTopRight}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}  ${gradient("VIBECHECK", [[0, 255, 255], [138, 43, 226], [255, 20, 147]])} ${c.dim}v${VERSION}${c.reset}${" ".repeat(60 - 13 - VERSION.length - 4)}${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}  ${c.dim}Ship with confidence. Catch fake features before users do.${c.reset}  ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxBottomLeft}${sym.boxHorizontal.repeat(60)}${sym.boxBottomRight}${c.reset}
+`);
+}
 
-    return {
-      allowed: false,
-      reason: `Your ${c.yellow}${entitlements.plan?.toUpperCase()}${c.reset} plan doesn't include this feature.\n\n  Required: ${requiredScope}\n  Upgrade to ${c.cyan}STARTER${c.reset} at: ${c.cyan}https://vibecheckai.dev/pricing${c.reset}`,
-    };
+function printHelp() {
+  printBanner();
+  const categories = {
+    proof: { name: "THE PROOF LOOP", color: c.green, icon: sym.shield },
+    setup: { name: "SETUP & DIAGNOSTICS", color: c.yellow, icon: sym.gear },
+    truth: { name: "TRUTH SYSTEM", color: c.magenta, icon: sym.lightning },
+    extras: { name: "EXTRAS", color: c.dim, icon: sym.star },
+    ci: { name: "CI/CD", color: c.cyan, icon: sym.rocket },
+    automation: { name: "AUTOMATION", color: c.blue, icon: sym.fire },
+    account: { name: "ACCOUNT", color: c.dim, icon: sym.key },
+  };
+  const grouped = {};
+  for (const [cmd, def] of Object.entries(COMMANDS)) {
+    const cat = def.category || "extras";
+    if (!grouped[cat]) grouped[cat] = [];
+    grouped[cat].push({ cmd, ...def });
   }
-
-  // PRO tier commands
-  if (PRO_COMMANDS[cmd]) {
-    const requiredScope = PRO_COMMANDS[cmd];
-
-    if (!entitlements) {
-      return {
-        allowed: false,
-        reason: `${c.yellow}${cmd}${c.reset} requires a ${c.magenta}PRO${c.reset} plan.\n\n  Run ${c.cyan}vibecheck login${c.reset} to authenticate.\n  Get your API key at: ${c.cyan}https://vibecheckai.dev/settings/keys${c.reset}`,
-      };
-    }
-
-    if (
-      entitlements.scopes?.includes(requiredScope) ||
-      entitlements.scopes?.includes("*")
-    ) {
-      return { allowed: true, tier: "pro" };
+  for (const [catKey, commands] of Object.entries(grouped)) {
+    const cat = categories[catKey] || { name: catKey.toUpperCase(), color: c.white, icon: sym.bullet };
+    console.log(`\n${cat.color}${cat.icon} ${cat.name}${c.reset}\n`);
+    for (const { cmd, description, tier, aliases } of commands) {
+      const tierBadge = tier === "starter" ? `${c.cyan}[STARTER]${c.reset} ` : tier === "pro" ? `${c.magenta}[PRO]${c.reset} ` : "";
+      const aliasStr = aliases?.length ? `${c.dim}(${aliases.join(", ")})${c.reset}` : "";
+      console.log(`  ${c.cyan}${cmd.padEnd(12)}${c.reset} ${tierBadge}${description} ${aliasStr}`);
     }
-
-    return {
-      allowed: false,
-      reason: `Your ${c.yellow}${entitlements.plan?.toUpperCase()}${c.reset} plan doesn't include this feature.\n\n  Required: ${requiredScope}\n  Upgrade to ${c.magenta}PRO${c.reset} at: ${c.cyan}https://vibecheckai.dev/pricing${c.reset}`,
-    };
   }
+  console.log(`
+${c.dim}${sym.boxHorizontal.repeat(64)}${c.reset}
 
-  return { allowed: true };
-}
-
-function printHelp() {
-  console.log(
-    `
-${c.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}
-${c.cyan}  VIBECHECK${c.reset} - Ship with confidence
-${c.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}
-
-${c.green}🚀 QUICK START${c.reset}
-
-  ${c.cyan}ship${c.reset}              "Is my app ready?" - Plain English, traffic light score
-  ${c.cyan}ship --fix${c.reset}        Same + auto-fix problems
-
-${c.yellow}🧪 TESTING${c.reset} (each does something different!)
-
-  ${c.cyan}scan${c.reset}              ${c.dim}Route Integrity${c.reset} - dead links, orphans, coverage, security 🗺️
-  ${c.cyan}scan --truth${c.reset}      ${c.dim}+ Build manifest${c.reset} verification (CI/ship ready)
-  ${c.cyan}scan --reality${c.reset}    ${c.dim}+ Playwright${c.reset} runtime proof (best-in-class)
-  ${c.cyan}reality${c.reset}           ${c.dim}Browser testing${c.reset} - clicks buttons, fills forms, finds broken UI
-  ${c.cyan}ai-test${c.reset}           ${c.dim}AI Agent${c.reset} - autonomous testing + generates fix prompts 🤖
-
-${c.magenta}🚦 CI/CD & GATES${c.reset}
-
-  ${c.cyan}gate${c.reset}              Block bad deploys - pass/fail for CI pipelines
-  ${c.cyan}proof mocks${c.reset}       Block mock/demo code from reaching production
-  ${c.cyan}proof reality${c.reset}     Runtime GO/NO-GO verification with Playwright
-
-${c.blue}🔧 FIX & AUTOMATE${c.reset}
-
-  ${c.cyan}fix${c.reset}               Auto-fix detected issues (--plan first, then --apply)
-  ${c.cyan}autopilot${c.reset}         Continuous protection - weekly reports, auto-PRs
-  ${c.cyan}badge${c.reset}             Generate Ship Badge for your README/PR
-  ${c.cyan}certify${c.reset}           Generate vibecheck Certified badge with verification link
-
-${c.dim}📦 TRUTH SYSTEM${c.reset}
-
-  ${c.cyan}ctx${c.reset}               Generate Truth Pack - ground truth for AI agents
-  ${c.cyan}ctx --snapshot${c.reset}    Save snapshot to .vibecheck/truth/snapshots/
-  ${c.cyan}graph${c.reset}             Build Reality Proof Graph - end-to-end causal chains
-
-${c.dim}📦 EXTRAS${c.reset}
-
-  ${c.cyan}audit${c.reset}             View/export audit trail (Compliance+ tier)
-  ${c.cyan}context${c.reset}           Generate AI rules files (.cursorrules, .windsurf/rules, etc.)
-  ${c.cyan}dashboard${c.reset}         Real-time monitoring dashboard with live metrics
-  ${c.cyan}demo${c.reset}              Interactive terminal features showcase
-  ${c.cyan}launch${c.reset}            Pre-launch checklist wizard
-  ${c.cyan}validate${c.reset}          Check AI-generated code for hallucinations
-  ${c.cyan}init${c.reset}              Set up vibecheck in your project
-  ${c.cyan}doctor${c.reset}            Debug environment issues
-  ${c.cyan}mcp${c.reset}               Start MCP server for AI editors
-
-${c.dim}🔑 ACCOUNT${c.reset}
-
-  ${c.cyan}login${c.reset}             Sign in with API key
-  ${c.cyan}logout${c.reset}            Sign out
-  ${c.cyan}whoami${c.reset}            Show current user & plan
-  ${c.cyan}upgrade${c.reset}           Manage subscription & view usage
+${c.green}QUICK START${c.reset}
 
-${c.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}
+  ${c.bold}"Check my repo"${c.reset}     ${c.cyan}vibecheck scan${c.reset}
+  ${c.bold}"Can I ship?"${c.reset}       ${c.cyan}vibecheck prove --url http://localhost:3000${c.reset}
+  ${c.bold}"Why did it fail?"${c.reset}  ${c.cyan}vibecheck report${c.reset}    ${c.dim}(then: vibecheck fix)${c.reset}
 
-${c.green}Examples:${c.reset}
+${c.dim}Run 'vibecheck <command> --help' for command-specific help.${c.reset}
+`);
+}
 
-  vibecheck ship                      ${c.dim}# Quick health check${c.reset}
-  vibecheck scan                      ${c.dim}# Route integrity + security analysis${c.reset}
-  vibecheck scan --truth              ${c.dim}# + Build manifest verification${c.reset}
-  vibecheck scan --reality --url http://localhost:3000  ${c.dim}# Full proof${c.reset}
-  vibecheck reality --url https://... ${c.dim}# Test live app${c.reset}
-  vibecheck ai-test --url https://... ${c.dim}# AI explores your app${c.reset}
-  vibecheck gate                      ${c.dim}# Block bad deploy in CI${c.reset}
-  vibecheck badge                     ${c.dim}# Generate ship badge${c.reset}
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+function getArgValue(args, flags) {
+  for (const flag of flags) {
+    const idx = args.indexOf(flag);
+    if (idx !== -1 && idx < args.length - 1) return args[idx + 1];
+  }
+  return undefined;
+}
 
-${c.dim}Run 'vibecheck <command> --help' for details.${c.reset}
-`.trim(),
-  );
+function formatError(error, config) {
+  const lines = [`${c.red}${sym.error} Error:${c.reset} ${error.message}`];
+  if (config.debug && error.stack) { lines.push("", `${c.dim}Stack trace:${c.reset}`, c.dim + error.stack.split("\n").slice(1).join("\n") + c.reset); }
+  return lines.join("\n");
 }
 
-(async function main() {
+// ═══════════════════════════════════════════════════════════════════════════════
+// MAIN ENTRY POINT
+// ═══════════════════════════════════════════════════════════════════════════════
+async function main() {
+  const startTime = performance.now();
   const rawArgs = process.argv.slice(2);
-
-  // Check if the first argument looks like a natural language command
-  // Natural language commands are typically quoted strings or multi-word phrases
-  const firstArg = rawArgs[0];
-  if (firstArg && isNaturalLanguageCommand(firstArg)) {
-    // Join all args as the natural language input
-    const nlInput = rawArgs.join(" ");
-    const exitCode = await runNaturalLanguage(nlInput);
-    process.exit(exitCode);
-  }
-
-  const { legacyFrom, routed } = routeArgv(process.argv);
-
-  const cmd = routed[0];
-  const args = routed.slice(1);
-
-  // Commands that skip auth check entirely
-  const skipAuthCommands = [
-    "help",
-    "-h",
-    "--help",
-    "version",
-    "login",
-    "logout",
-    "whoami",
-    "doctor",
-  ];
-
-  if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
-    printHelp();
+  const config = loadConfig();
+  const state = loadState();
+  
+  const globalFlags = {
+    debug: rawArgs.includes("--debug") || rawArgs.includes("-d"),
+    verbose: rawArgs.includes("--verbose") || rawArgs.includes("-v"),
+    quiet: rawArgs.includes("--quiet") || rawArgs.includes("-q"),
+    help: rawArgs.includes("--help") || rawArgs.includes("-h"),
+    version: rawArgs.includes("--version") || rawArgs.includes("-V"),
+  };
+  
+  if (globalFlags.debug) config.debug = true;
+  if (globalFlags.verbose) config.verbose = true;
+  if (globalFlags.quiet) config.quiet = true;
+  
+  const args = rawArgs.filter(a => !["--debug", "-d", "--verbose", "-v", "--quiet", "-q", "--help", "-h", "--version", "-V"].includes(a));
+  
+  if (globalFlags.version || args[0] === "version") {
+    console.log(`vibecheck v${VERSION}`);
     process.exit(0);
   }
-
-  // Check for first run (no API key) - only for non-skip commands
-  let authInfo = { key: null, entitlements: null };
-
-  if (!skipAuthCommands.includes(cmd)) {
-    // Check if this is a free command or utility - if so, skip entitlement checks
-    const isFreeCommand = FREE_COMMANDS.includes(cmd) || UTILITY_COMMANDS.includes(cmd);
-    const isKnownCommand = isFreeCommand || 
-      STARTER_COMMANDS[cmd] || 
-      PRO_COMMANDS[cmd] || 
-      TIERED_COMMANDS[cmd] || 
-      PROOF_COMMANDS[cmd] ||
-      COMPLIANCE_COMMANDS[cmd];
-    
-    // For unknown commands, skip auth and let them fail with "Unknown command" message
-    if (!isKnownCommand) {
-      // Skip authentication for unknown commands - they'll show help/error message
-      authInfo = { key: null, entitlements: null };
-    } else {
-      const { key } = getApiKey();
-
-      // First run without API key - show welcome and prompt
-      if (!key && !process.env.VIBECHECK_SKIP_AUTH) {
-        authInfo = await showWelcomeAndPromptLogin();
-      } else if (key && !isFreeCommand) {
-        // Has API key and command requires auth - get entitlements silently
-        // For free commands, we don't need to check entitlements
-        try {
-          const entitlements = await getEntitlements(key);
-          authInfo = { key, entitlements };
-        } catch (error) {
-          // If API is unavailable, allow free commands to proceed
-          // Paid commands will be blocked in checkCommandAccess
-          if (isFreeCommand) {
-            authInfo = { key, entitlements: null };
-          } else {
-            throw error;
-          }
-        }
-      } else if (key && isFreeCommand) {
-        // Free command with key - no need to fetch entitlements
-        authInfo = { key, entitlements: null };
-      }
-    }
-
-    // Check if user has access to this command (only for known commands)
-    if (isKnownCommand) {
-      const access = await checkCommandAccess(cmd, authInfo.entitlements, args);
-
-      if (!access.allowed) {
-        console.log(`\n${c.red}✗ Access Denied${c.reset}\n`);
-        console.log(access.reason);
-        console.log("");
-        process.exit(1);
-      }
-
-      // Show tier info for paid features
-      if (access.tier === "starter") {
-        console.log(`${c.cyan}▸ STARTER${c.reset} ${c.dim}feature${c.reset}\n`);
-      } else if (access.tier === "pro") {
-        console.log(`${c.magenta}▸ PRO${c.reset} ${c.dim}feature${c.reset}\n`);
-      }
+  
+  if (!args[0]) { printHelp(); process.exit(0); }
+  
+  // Handle command-specific help (vibecheck <cmd> --help)
+  if (globalFlags.help && args[0] && COMMANDS[args[0]]) {
+    // Pass --help to the command runner
+  } else if (globalFlags.help && !args[0]) {
+    printHelp(); process.exit(0);
+  }
+  
+  let cmd = args[0];
+  if (ALIAS_MAP[cmd]) { cmd = ALIAS_MAP[cmd]; }
+  let cmdArgs = args.slice(1);
+  
+  // Add --help back to cmdArgs if it was passed with a command
+  if (globalFlags.help) cmdArgs = ["--help", ...cmdArgs];
+  
+  if (!COMMANDS[cmd]) {
+    const suggestions = findSimilarCommands(cmd, ALL_COMMANDS);
+    console.log(`\n${c.red}${sym.error}${c.reset} Unknown command: ${c.yellow}${cmd}${c.reset}`);
+    if (suggestions.length > 0) {
+      console.log(`\n${c.dim}Did you mean:${c.reset}`);
+      suggestions.forEach(s => { const actual = ALIAS_MAP[s] || s; const def = COMMANDS[actual]; console.log(`  ${c.cyan}vibecheck ${s}${c.reset}  ${c.dim}${def?.description || ""}${c.reset}`); });
     }
+    console.log(`\n${c.dim}Run 'vibecheck --help' for available commands.${c.reset}\n`);
+    process.exit(1);
   }
-
-  // Deprecation suggestions
-  if (legacyFrom) {
-    const suggestion = routed.slice(0, 2).join(" ");
-    warnDeprecationOnce(legacyFrom, suggestion, VERSION);
+  
+  const cmdDef = COMMANDS[cmd];
+  let authInfo = { key: null, entitlements: null };
+  
+  if (!cmdDef.skipAuth) {
+    const auth = getAuthModule();
+    const { key } = auth.getApiKey();
+    
+    if (key && cmdDef.tier !== "free") {
+      try { authInfo.key = key; authInfo.entitlements = await auth.getEntitlements(key); } catch (e) { if (config.verbose) console.log(`${c.yellow}${sym.warning}${c.reset} ${c.dim}Could not verify credentials${c.reset}`); }
+    } else { authInfo.key = key; }
+    
+    const access = await checkCommandAccess(cmd, cmdArgs, authInfo.entitlements);
+    if (!access.allowed) { console.log(`\n${c.red}${sym.error} Access Denied${c.reset}\n`); console.log(access.reason); console.log(""); process.exit(1); }
+    if (access.tier === "starter" && !config.quiet) console.log(`${c.cyan}${sym.arrowRight} STARTER${c.reset} ${c.dim}feature${c.reset}`);
+    else if (access.tier === "pro" && !config.quiet) console.log(`${c.magenta}${sym.arrowRight} PRO${c.reset} ${c.dim}feature${c.reset}`);
   }
-
+  
+  state.runCount++; state.lastRun = Date.now();
+  state.commandHistory = [...(state.commandHistory || []).slice(-99), { cmd, timestamp: Date.now() }];
+  saveState(state);
+  
+  let exitCode = 0;
   try {
-    let exitCode = 0;
+    const runner = getRunner(cmd);
+    if (!runner) { console.error(`${c.red}${sym.error}${c.reset} Failed to load runner for: ${cmd}`); process.exit(1); }
+    
+    const context = { repoRoot: process.cwd(), config, state, authInfo, version: VERSION, isCI: isCI() };
+    
     switch (cmd) {
-      case "scan":
-        exitCode = await runScan(args);
-        break;
-      case "gate":
-        exitCode = await runGate(args);
-        break;
-      case "ship":
-        exitCode = await runShip(args);
-        break;
-      case "enhanced-ship":
-        exitCode = await runEnhancedShip(args);
-        break;
-      case "prompt-firewall":
-      case "firewall":
-        exitCode = await runPromptFirewall(args);
-        break;
-      case "launch":
-        exitCode = await runLaunch(args);
-        break;
-      case "autopilot":
-        exitCode = await runAutopilot(args);
-        break;
-      case "fix":
-        exitCode = await runFix(args);
-        break;
-      case "share":
-        exitCode = await runShare({
-          repoRoot: process.cwd(),
-          missionDir: args.find((a, i) => args[i-1] === '--mission-dir'),
-          outputDir: args.find((a, i) => args[i-1] === '--output-dir'),
-          prComment: args.includes('--pr-comment')
-        });
-        break;
-      case "pr":
-        exitCode = await runPR({
-          repoRoot: process.cwd(),
-          fastifyEntry: args.find((a, i) => args[i-1] === '--fastify-entry'),
-          out: args.find((a, i) => args[i-1] === '--out'),
-          failOnWarn: args.includes('--fail-on-warn'),
-          maxFindings: Number(args.find((a, i) => args[i-1] === '--max-findings')) || 12
-        });
-        break;
-      case "install":
-        exitCode = await runInstall({ repoRoot: process.cwd() });
-        break;
-      case "prove":
-        exitCode = await runProve({
-          repoRoot: process.cwd(),
-          url: args.find((a, i) => args[i-1] === '--url' || args[i-1] === '-u'),
-          auth: args.find((a, i) => args[i-1] === '--auth'),
-          storageState: args.find((a, i) => args[i-1] === '--storage-state'),
-          fastifyEntry: args.find((a, i) => args[i-1] === '--fastify-entry'),
-          maxFixRounds: Number(args.find((a, i) => args[i-1] === '--max-fix-rounds')) || 3,
-          maxMissions: Number(args.find((a, i) => args[i-1] === '--max-missions')) || 8,
-          maxSteps: Number(args.find((a, i) => args[i-1] === '--max-steps')) || 10,
-          skipReality: args.includes('--skip-reality'),
-          skipFix: args.includes('--skip-fix'),
-          headed: args.includes('--headed'),
-          danger: args.includes('--danger'),
-          maxPages: Number(args.find((a, i) => args[i-1] === '--max-pages')) || 18,
-          maxDepth: Number(args.find((a, i) => args[i-1] === '--max-depth')) || 2,
-          timeoutMs: Number(args.find((a, i) => args[i-1] === '--timeout-ms')) || 15000
-        });
-        break;
-      case "watch":
-        exitCode = await runWatch({
-          repoRoot: process.cwd(),
-          fastifyEntry: args.find((a, i) => args[i-1] === '--fastify-entry'),
-          debounceMs: Number(args.find((a, i) => args[i-1] === '--debounce')) || 500,
-          clearScreen: !args.includes('--no-clear')
-        });
-        break;
-      case "status":
-        exitCode = await runStatus({
-          repoRoot: process.cwd(),
-          json: args.includes('--json')
-        });
-        break;
-      case "proof":
-        exitCode = await runProof(args);
-        break;
-      case "reality":
-        exitCode = await runReality({
-          repoRoot: process.cwd(),
-          url: args.find((a, i) => args[i-1] === '--url' || args[i-1] === '-u'),
-          auth: args.find((a, i) => args[i-1] === '--auth'),
-          storageState: args.find((a, i) => args[i-1] === '--storage-state'),
-          saveStorageState: args.find((a, i) => args[i-1] === '--save-storage-state'),
-          truthpack: args.find((a, i) => args[i-1] === '--truthpack'),
-          verifyAuth: args.includes('--verify-auth'),
-          headed: args.includes('--headed'),
-          maxPages: Number(args.find((a, i) => args[i-1] === '--max-pages')) || 18,
-          maxDepth: Number(args.find((a, i) => args[i-1] === '--max-depth')) || 2,
-          danger: args.includes('--danger'),
-          timeoutMs: Number(args.find((a, i) => args[i-1] === '--timeout-ms')) || 15000
-        });
-        break;
-      case "reality-sniff":
-      case "sniff":
-        exitCode = await runRealitySniff(args);
-        break;
-      case "ai-test":
-      case "ai":
-      case "agent":
-        exitCode = await runAIAgent(args);
-        break;
-      case "validate":
-        exitCode = await runValidate(args);
-        break;
-      case "doctor":
-        exitCode = runDoctor(args);
-        break;
-      case "init":
-        // Enterprise init handles all flags including --gha, --gitlab, --compliance, etc.
-        exitCode = await runInit(args);
-        break;
-      case "mcp":
-        exitCode = runMcp(args);
-        break;
-      case "login":
-        exitCode = await runLogin(args);
-        break;
-      case "logout":
-        exitCode = await runLogout(args);
-        break;
-      case "whoami":
-        exitCode = await runWhoami(args);
-        break;
-      case "badge":
-        exitCode = await runBadge(args);
-        break;
-      case "context":
-      case "rules":
-        exitCode = await runContext(args);
-        break;
-      case "dashboard":
-        exitCode = await runDashboard(args);
-        break;
-      case "demo":
-        exitCode = await runDemo(args);
-        break;
-      case "upgrade":
-        exitCode = await runUpgrade(args);
-        break;
-      case "certify":
-        exitCode = await runCertify(args, process.cwd());
-        break;
-      case "verify-agent-output":
-        exitCode = await runVerifyAgentOutput(args);
-        break;
-      case "fixpacks":
-        exitCode = await runFixPacks(args);
-        break;
-      case "audit":
-        exitCode = await runAudit(args);
-        break;
-      case "mdc":
-        exitCode = await runMdc(args);
-        break;
-      case "graph":
-        exitCode = await runGraph(args);
-        break;
-      case "permissions":
-      case "authz":
-        exitCode = await runPermissions(args);
-        break;
-      case "ctx":
-      case "truthpack":
-        // Check for subcommands
-        if (args[0] === "sync") {
-          exitCode = await runCtxSync({
-            repoRoot: process.cwd(),
-            fastifyEntry: args.find((a, i) => args[i-1] === '--fastify-entry')
-          });
-          break;
-        }
-        if (args[0] === "guard") {
-          exitCode = await runCtxGuard.main(args.slice(1));
-          break;
-        }
-        // Parse args for ctx command - use Route Truth v1
-        const fastifyEntryIdx = args.indexOf('--fastify-entry');
-        const fastifyEntry = fastifyEntryIdx !== -1 ? args[fastifyEntryIdx + 1] : undefined;
-        await runCtx({
-          repoRoot: process.cwd(),
-          fastifyEntry,
-          print: args.includes('--print'),
-        });
-        exitCode = 0;
-        break;
-      case "version":
-        console.log(`vibecheck v${VERSION}`);
-        break;
-      default:
-        // Try natural language parsing as fallback for unknown commands
-        const nlInput = [cmd, ...args].join(" ");
-        if (isNaturalLanguageCommand(nlInput)) {
-          exitCode = await runNaturalLanguage(nlInput);
-        } else {
-          process.stderr.write(`Unknown command: ${cmd}\n\n`);
-          printHelp();
-          exitCode = 1;
-        }
+      case "prove": exitCode = await runner({ ...context, url: getArgValue(cmdArgs, ["--url", "-u"]), auth: getArgValue(cmdArgs, ["--auth"]), storageState: getArgValue(cmdArgs, ["--storage-state"]), fastifyEntry: getArgValue(cmdArgs, ["--fastify-entry"]), maxFixRounds: parseInt(getArgValue(cmdArgs, ["--max-fix-rounds"]) || "3", 10), skipReality: cmdArgs.includes("--skip-reality"), skipFix: cmdArgs.includes("--skip-fix"), headed: cmdArgs.includes("--headed"), danger: cmdArgs.includes("--danger") }); break;
+      case "reality": exitCode = await runner({ ...context, url: getArgValue(cmdArgs, ["--url", "-u"]), auth: getArgValue(cmdArgs, ["--auth"]), storageState: getArgValue(cmdArgs, ["--storage-state"]), saveStorageState: getArgValue(cmdArgs, ["--save-storage-state"]), truthpack: getArgValue(cmdArgs, ["--truthpack"]), verifyAuth: cmdArgs.includes("--verify-auth"), headed: cmdArgs.includes("--headed"), danger: cmdArgs.includes("--danger") }); break;
+      case "watch": exitCode = await runner({ ...context, fastifyEntry: getArgValue(cmdArgs, ["--fastify-entry"]), debounceMs: parseInt(getArgValue(cmdArgs, ["--debounce"]) || "500", 10), clearScreen: !cmdArgs.includes("--no-clear") }); break;
+      case "ctx": case "truthpack":
+        if (cmdArgs[0] === "sync") { const { runCtxSync } = require("./runners/runCtxSync"); exitCode = await runCtxSync({ ...context, fastifyEntry: getArgValue(cmdArgs, ["--fastify-entry"]) }); }
+        else if (cmdArgs[0] === "guard") { const { runCtxGuard } = require("./runners/runCtxGuard"); exitCode = await runCtxGuard.main(cmdArgs.slice(1)); }
+        else if (cmdArgs[0] === "diff") { const { main: ctxDiffMain } = require("./runners/runCtxDiff"); exitCode = await ctxDiffMain(cmdArgs.slice(1)); }
+        else if (cmdArgs[0] === "search") { const { runContext } = require("./runners/runContext"); exitCode = await runContext(["--search", ...cmdArgs.slice(1)]); }
+        else { exitCode = await runner({ ...context, fastifyEntry: getArgValue(cmdArgs, ["--fastify-entry"]), print: cmdArgs.includes("--print") }); }
+        break;
+      case "install": exitCode = await runner(context); break;
+      case "status": exitCode = await runner({ ...context, json: cmdArgs.includes("--json") }); break;
+      case "pr": exitCode = await runner({ ...context, fastifyEntry: getArgValue(cmdArgs, ["--fastify-entry"]), out: getArgValue(cmdArgs, ["--out"]), failOnWarn: cmdArgs.includes("--fail-on-warn"), maxFindings: parseInt(getArgValue(cmdArgs, ["--max-findings"]) || "12", 10) }); break;
+      case "share": exitCode = await runner({ ...context, missionDir: getArgValue(cmdArgs, ["--mission-dir"]), outputDir: getArgValue(cmdArgs, ["--output-dir"]), prComment: cmdArgs.includes("--pr-comment") }); break;
+      default: exitCode = await runner(cmdArgs);
     }
-    process.exit(exitCode);
-  } catch (err) {
-    process.stderr.write(
-      err && err.stack ? err.stack + "\n" : String(err) + "\n",
-    );
-    process.exit(1);
-  }
-})();
+  } catch (error) { console.error(formatError(error, config)); exitCode = 1; }
+  
+  if (config.debug) console.log(`\n${c.dim}${sym.clock} Total: ${(performance.now() - startTime).toFixed(0)}ms${c.reset}`);
+  process.exit(exitCode);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// GRACEFUL SHUTDOWN
+// ═══════════════════════════════════════════════════════════════════════════════
+process.on("SIGINT", () => { console.log(`\n${c.yellow}${sym.warning}${c.reset} Interrupted`); process.exit(130); });
+process.on("SIGTERM", () => { console.log(`\n${c.yellow}${sym.warning}${c.reset} Terminated`); process.exit(143); });
+process.on("uncaughtException", (error) => { console.error(`\n${c.red}${sym.error} Uncaught Exception:${c.reset} ${error.message}`); if (process.env.VIBECHECK_DEBUG === "true") console.error(c.dim + error.stack + c.reset); process.exit(1); });
+process.on("unhandledRejection", (reason) => { console.error(`\n${c.red}${sym.error} Unhandled Rejection:${c.reset} ${reason}`); process.exit(1); });
+
+main().catch((error) => { console.error(`\n${c.red}${sym.error} Fatal:${c.reset} ${error.message}`); process.exit(1); });