vibecheck-ai 2.0.2 → 5.0.1

package/bin/vibecheck.js

@@ -0,0 +1,1617 @@
+#!/usr/bin/env node
+// bin/vibecheck.js - World-Class CLI (Refactored)
+// ═══════════════════════════════════════════════════════════════════════════════
+// VibeCheck - Proves your app is real
+// Ship with confidence. Catch fake features before your users do.
+// ═══════════════════════════════════════════════════════════════════════════════
+
+"use strict";
+
+const { performance } = require("perf_hooks");
+const STARTUP_TIME = performance.now();
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// LAZY LOADING - Defer all requires until needed for fast startup
+// ═══════════════════════════════════════════════════════════════════════════════
+const lazyModules = {};
+
+function lazy(name, loader) {
+  return () => {
+    if (!lazyModules[name]) {
+      lazyModules[name] = loader();
+    }
+    return lazyModules[name];
+  };
+}
+
+const getFs = lazy("fs", () => require("fs"));
+const getPath = lazy("path", () => require("path"));
+const getOs = lazy("os", () => require("os"));
+const getCrypto = lazy("crypto", () => require("crypto"));
+const getHttps = lazy("https", () => require("https"));
+const getReadline = lazy("readline", () => require("readline"));
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// VERSION & METADATA (lazy loaded)
+// ═══════════════════════════════════════════════════════════════════════════════
+let _version = null;
+function getVersion() {
+  if (_version) return _version;
+  try {
+    const fs = getFs();
+    const path = getPath();
+    const pkgPath = path.join(__dirname, "..", "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    _version = pkg.version || "0.0.0";
+  } catch {
+    _version = "0.0.0";
+  }
+  return _version;
+}
+
+const CLI_NAME = "vibecheck";
+const CONFIG_FILE = ".vibecheckrc";
+const UPDATE_CHECK_INTERVAL = 24 * 60 * 60 * 1000; // 24 hours
+
+// Cache/state paths (computed lazily)
+let _cacheDir = null;
+let _stateFile = null;
+function getCacheDir() {
+  if (!_cacheDir) {
+    const os = getOs();
+    const path = getPath();
+    _cacheDir = path.join(os.homedir(), ".vibecheck");
+  }
+  return _cacheDir;
+}
+function getStateFile() {
+  if (!_stateFile) {
+    const path = getPath();
+    _stateFile = path.join(getCacheDir(), "state.json");
+  }
+  return _stateFile;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 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
+);
+
+const c = SUPPORTS_COLOR ? {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  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",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  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, ""]));
+
+// Add no-op rgb functions for non-color mode
+if (!SUPPORTS_COLOR) {
+  c.rgb = () => "";
+  c.bgRgb = () => "";
+}
+
+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;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// UNICODE SYMBOLS
+// ═══════════════════════════════════════════════════════════════════════════════
+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: "||",
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CI DETECTION
+// ═══════════════════════════════════════════════════════════════════════════════
+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
+  );
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SPINNER CLASS
+// ═══════════════════════════════════════════════════════════════════════════════
+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;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// STATE MANAGEMENT (lazy file I/O)
+// ═══════════════════════════════════════════════════════════════════════════════
+function ensureCacheDir() {
+  const fs = getFs();
+  const cacheDir = getCacheDir();
+  if (!fs.existsSync(cacheDir)) {
+    fs.mkdirSync(cacheDir, { recursive: true });
+  }
+}
+
+function loadState() {
+  try {
+    const fs = getFs();
+    const stateFile = getStateFile();
+    if (fs.existsSync(stateFile)) {
+      return JSON.parse(fs.readFileSync(stateFile, "utf-8"));
+    }
+  } catch {}
+  return {
+    firstRun: Date.now(),
+    lastRun: null,
+    runCount: 0,
+    lastUpdateCheck: null,
+    latestVersion: null,
+    commandHistory: [],
+    favorites: [],
+  };
+}
+
+function saveState(state) {
+  try {
+    const fs = getFs();
+    ensureCacheDir();
+    fs.writeFileSync(getStateFile(), JSON.stringify(state, null, 2));
+  } catch {}
+}
+
+function loadConfig() {
+  const fs = getFs();
+  const path = getPath();
+  
+  const config = {
+    debug: false,
+    verbose: false,
+    quiet: false,
+    color: true,
+    analytics: true,
+    updateCheck: true,
+    timeout: 30000,
+    maxRetries: 3,
+    noBanner: false,
+  };
+
+  const projectConfigPath = path.join(process.cwd(), CONFIG_FILE);
+  if (fs.existsSync(projectConfigPath)) {
+    try {
+      Object.assign(config, JSON.parse(fs.readFileSync(projectConfigPath, "utf-8")));
+    } catch {}
+  }
+
+  // Environment overrides
+  if (process.env.VIBECHECK_DEBUG === "true") config.debug = true;
+  if (process.env.VIBECHECK_VERBOSE === "true") config.verbose = true;
+  if (process.env.VIBECHECK_QUIET === "true") config.quiet = true;
+  if (process.env.VIBECHECK_NO_BANNER === "true") config.noBanner = true;
+  if (process.env.NO_COLOR || process.env.VIBECHECK_NO_COLOR) config.color = false;
+
+  return config;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// UPDATE CHECKER - Actually implemented
+// ═══════════════════════════════════════════════════════════════════════════════
+async function checkForUpdates(state, config) {
+  if (!config.updateCheck) return null;
+  if (isCI()) return null;
+  
+  const now = Date.now();
+  if (state.lastUpdateCheck && (now - state.lastUpdateCheck) < UPDATE_CHECK_INTERVAL) {
+    // Use cached version if recent
+    if (state.latestVersion && state.latestVersion !== getVersion()) {
+      return state.latestVersion;
+    }
+    return null;
+  }
+
+  // Async check - don't block CLI startup
+  return new Promise((resolve) => {
+    const https = getHttps();
+    const timeout = setTimeout(() => resolve(null), 3000); // 3s timeout
+
+    const req = https.get(
+      "https://registry.npmjs.org/@vibecheck/cli/latest",
+      { headers: { "Accept": "application/json", "User-Agent": `vibecheck-cli/${getVersion()}` } },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => { data += chunk; });
+        res.on("end", () => {
+          clearTimeout(timeout);
+          try {
+            const pkg = JSON.parse(data);
+            const latest = pkg.version;
+            state.lastUpdateCheck = now;
+            state.latestVersion = latest;
+            saveState(state);
+            
+            if (latest && latest !== getVersion()) {
+              resolve(latest);
+            } else {
+              resolve(null);
+            }
+          } catch {
+            resolve(null);
+          }
+        });
+      }
+    );
+
+    req.on("error", () => {
+      clearTimeout(timeout);
+      resolve(null);
+    });
+
+    req.end();
+  });
+}
+
+function printUpdateNotice(latestVersion) {
+  const currentVersion = getVersion();
+  console.log();
+  console.log(`${c.yellow}${sym.sparkles}${c.reset} Update available: ${c.dim}${currentVersion}${c.reset} ${sym.arrow} ${c.green}${latestVersion}${c.reset}`);
+  console.log(`   Run ${c.cyan}npm update -g @vibecheck/cli${c.reset} to update`);
+  console.log();
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 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
+        );
+      }
+    }
+  }
+  return matrix[b.length][a.length];
+}
+
+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 [...new Set(matches.sort((a, b) => a.distance - b.distance).map(m => m.cmd))].slice(0, 3);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// COMMAND REGISTRY (lazy loaded)
+// ═══════════════════════════════════════════════════════════════════════════════
+let _registry = null;
+function getRegistry() {
+  if (!_registry) {
+    _registry = require("./registry");
+  }
+  return _registry;
+}
+
+function getRunner(cmd) {
+  const registry = getRegistry();
+  return registry.getRunner(cmd, { red: c.red, reset: c.reset, errorSymbol: sym.error });
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ENTITLEMENTS & UPSELL (lazy loaded)
+// ═══════════════════════════════════════════════════════════════════════════════
+let _entitlements = null;
+let _upsell = null;
+
+function getEntitlements() {
+  if (!_entitlements) {
+    _entitlements = require("./runners/lib/entitlements-v2");
+  }
+  return _entitlements;
+}
+
+function getUpsell() {
+  if (!_upsell) {
+    _upsell = require("./runners/lib/upsell");
+  }
+  return _upsell;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CLI OUTPUT UTILITIES (lazy loaded)
+// ═══════════════════════════════════════════════════════════════════════════════
+let _cliOutput = null;
+function getCliOutput() {
+  if (!_cliOutput) {
+    _cliOutput = require("./runners/lib/cli-output");
+  }
+  return _cliOutput;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// AUTH MODULE (lazy loaded)
+// ═══════════════════════════════════════════════════════════════════════════════
+let _authModule = null;
+function getAuthModule() {
+  if (!_authModule) {
+    _authModule = require("./runners/lib/auth");
+  }
+  return _authModule;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ACCESS CONTROL
+// ═══════════════════════════════════════════════════════════════════════════════
+async function checkCommandAccess(cmd, args, authInfo) {
+  const registry = getRegistry();
+  const def = registry.COMMANDS[cmd];
+  if (!def) return { allowed: true };
+
+  const entitlements = getEntitlements();
+  const result = await entitlements.enforce(cmd, {
+    apiKey: authInfo?.key,
+    projectPath: process.cwd(),
+    silent: true,
+  });
+
+  if (result.allowed) {
+    return {
+      allowed: true,
+      tier: result.tier,
+      downgrade: result.downgrade,
+      limits: result.limits,
+      caps: result.caps,
+    };
+  }
+
+  const upsell = getUpsell();
+  return {
+    allowed: false,
+    tier: result.tier,
+    requiredTier: result.requiredTier,
+    exitCode: result.exitCode,
+    reason: upsell.formatDenied(cmd, {
+      currentTier: result.tier,
+      requiredTier: result.requiredTier,
+    }),
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SHELL COMPLETIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+function generateBashCompletion() {
+  const registry = getRegistry();
+  const commands = Object.keys(registry.COMMANDS);
+  const aliases = Object.keys(registry.ALIAS_MAP);
+  const allCmds = [...commands, ...aliases].join(" ");
+
+  return `# vibecheck bash completion
+# Add to ~/.bashrc or ~/.bash_profile:
+#   eval "$(vibecheck completion bash)"
+
+_vibecheck_completions() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  local prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  
+  # Main commands
+  local commands="${allCmds}"
+  
+  # Global flags
+  local global_flags="--help --version --json --ci --quiet --verbose --debug --path --output --no-banner"
+  
+  case "\${prev}" in
+    vibecheck|vc)
+      COMPREPLY=($(compgen -W "\${commands} \${global_flags}" -- "\${cur}"))
+      return 0
+      ;;
+    --path|--output|-p|-o)
+      COMPREPLY=($(compgen -d -- "\${cur}"))
+      return 0
+      ;;
+    init)
+      COMPREPLY=($(compgen -W "--local --connect --quick --enterprise --ci --soc2 --hipaa --gdpr --team --mcp" -- "\${cur}"))
+      return 0
+      ;;
+    scan)
+      COMPREPLY=($(compgen -W "--fix --autofix --json --strict --path" -- "\${cur}"))
+      return 0
+      ;;
+    report)
+      COMPREPLY=($(compgen -W "--format --output html md json sarif csv" -- "\${cur}"))
+      return 0
+      ;;
+    completion)
+      COMPREPLY=($(compgen -W "bash zsh fish" -- "\${cur}"))
+      return 0
+      ;;
+  esac
+  
+  if [[ "\${cur}" == -* ]]; then
+    COMPREPLY=($(compgen -W "\${global_flags}" -- "\${cur}"))
+  fi
+}
+
+complete -F _vibecheck_completions vibecheck
+complete -F _vibecheck_completions vc
+`;
+}
+
+function generateZshCompletion() {
+  const registry = getRegistry();
+  const commands = Object.entries(registry.COMMANDS);
+  
+  let cmdList = commands.map(([cmd, def]) => {
+    const desc = (def.description || "").replace(/'/g, "\\'").replace(/"/g, '\\"');
+    return `    '${cmd}:${desc}'`;
+  }).join(" \\\n");
+
+  return `#compdef vibecheck vc
+# vibecheck zsh completion
+# Add to ~/.zshrc:
+#   eval "$(vibecheck completion zsh)"
+
+_vibecheck() {
+  local -a commands
+  commands=(
+${cmdList}
+  )
+
+  local -a global_opts
+  global_opts=(
+    '--help[Show help]'
+    '--version[Show version]'
+    '--json[Output as JSON]'
+    '--ci[CI mode]'
+    '--quiet[Suppress output]'
+    '--verbose[Verbose output]'
+    '--debug[Debug mode]'
+    '--path[Project path]:directory:_directories'
+    '--output[Output directory]:directory:_directories'
+    '--no-banner[Hide banner]'
+  )
+
+  _arguments -C \\
+    "1: :->command" \\
+    "*::arg:->args"
+
+  case "\$state" in
+    command)
+      _describe -t commands 'vibecheck commands' commands
+      _describe -t options 'options' global_opts
+      ;;
+    args)
+      case "\$words[1]" in
+        init)
+          _arguments \\
+            '--local[Local setup only]' \\
+            '--connect[GitHub integration]' \\
+            '--quick[Quick setup]' \\
+            '--enterprise[Enterprise mode]' \\
+            '--ci[Setup CI/CD]' \\
+            '--soc2[SOC2 compliance]' \\
+            '--hipaa[HIPAA compliance]'
+          ;;
+        scan)
+          _arguments \\
+            '--fix[Apply fixes]' \\
+            '--autofix[Auto-fix issues]' \\
+            '--json[JSON output]' \\
+            '--strict[Strict mode]'
+          ;;
+        report)
+          _arguments \\
+            '--format[Output format]:format:(html md json sarif csv)' \\
+            '--output[Output file]:file:_files'
+          ;;
+        completion)
+          _arguments '1:shell:(bash zsh fish)'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+compdef _vibecheck vibecheck
+compdef _vibecheck vc
+`;
+}
+
+function generateFishCompletion() {
+  const registry = getRegistry();
+  const commands = Object.entries(registry.COMMANDS);
+
+  let completions = `# vibecheck fish completion
+# Add to ~/.config/fish/completions/vibecheck.fish
+# Or run: vibecheck completion fish > ~/.config/fish/completions/vibecheck.fish
+
+# Disable file completion by default
+complete -c vibecheck -f
+complete -c vc -f
+
+# Global flags
+complete -c vibecheck -l help -d 'Show help'
+complete -c vibecheck -l version -d 'Show version'
+complete -c vibecheck -l json -d 'Output as JSON'
+complete -c vibecheck -l ci -d 'CI mode'
+complete -c vibecheck -l quiet -d 'Suppress output'
+complete -c vibecheck -l verbose -d 'Verbose output'
+complete -c vibecheck -l debug -d 'Debug mode'
+complete -c vibecheck -l path -d 'Project path' -r -a '(__fish_complete_directories)'
+complete -c vibecheck -l output -d 'Output directory' -r -a '(__fish_complete_directories)'
+complete -c vibecheck -l no-banner -d 'Hide banner'
+
+# Commands
+`;
+
+  for (const [cmd, def] of commands) {
+    const desc = (def.description || "").replace(/'/g, "\\'");
+    completions += `complete -c vibecheck -n '__fish_use_subcommand' -a '${cmd}' -d '${desc}'\n`;
+    completions += `complete -c vc -n '__fish_use_subcommand' -a '${cmd}' -d '${desc}'\n`;
+  }
+
+  // Add aliases
+  for (const [alias, target] of Object.entries(registry.ALIAS_MAP)) {
+    const def = registry.COMMANDS[target];
+    if (def) {
+      const desc = `Alias for ${target}`;
+      completions += `complete -c vibecheck -n '__fish_use_subcommand' -a '${alias}' -d '${desc}'\n`;
+      completions += `complete -c vc -n '__fish_use_subcommand' -a '${alias}' -d '${desc}'\n`;
+    }
+  }
+
+  completions += `
+# init subcommand options
+complete -c vibecheck -n '__fish_seen_subcommand_from init' -l local -d 'Local setup only'
+complete -c vibecheck -n '__fish_seen_subcommand_from init' -l connect -d 'GitHub integration'
+complete -c vibecheck -n '__fish_seen_subcommand_from init' -l quick -d 'Quick setup'
+complete -c vibecheck -n '__fish_seen_subcommand_from init' -l enterprise -d 'Enterprise mode'
+
+# scan subcommand options
+complete -c vibecheck -n '__fish_seen_subcommand_from scan' -l fix -d 'Apply fixes'
+complete -c vibecheck -n '__fish_seen_subcommand_from scan' -l autofix -d 'Auto-fix issues'
+complete -c vibecheck -n '__fish_seen_subcommand_from scan' -l strict -d 'Strict mode'
+
+# report subcommand options
+complete -c vibecheck -n '__fish_seen_subcommand_from report' -l format -d 'Output format' -r -a 'html md json sarif csv'
+
+# completion subcommand
+complete -c vibecheck -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish' -d 'Shell type'
+`;
+
+  return completions;
+}
+
+function runCompletion(args) {
+  const shell = args[0];
+  
+  if (!shell || shell === "--help" || shell === "-h") {
+    console.log(`
+${c.bold}Usage:${c.reset} vibecheck completion <shell>
+
+${c.bold}Shells:${c.reset}
+  bash    Generate bash completions
+  zsh     Generate zsh completions  
+  fish    Generate fish completions
+
+${c.bold}Installation:${c.reset}
+  ${c.dim}# Bash (add to ~/.bashrc)${c.reset}
+  eval "$(vibecheck completion bash)"
+  
+  ${c.dim}# Zsh (add to ~/.zshrc)${c.reset}
+  eval "$(vibecheck completion zsh)"
+  
+  ${c.dim}# Fish${c.reset}
+  vibecheck completion fish > ~/.config/fish/completions/vibecheck.fish
+`);
+    return 0;
+  }
+
+  switch (shell.toLowerCase()) {
+    case "bash":
+      console.log(generateBashCompletion());
+      return 0;
+    case "zsh":
+      console.log(generateZshCompletion());
+      return 0;
+    case "fish":
+      console.log(generateFishCompletion());
+      return 0;
+    default:
+      console.error(`${c.red}${sym.error}${c.reset} Unknown shell: ${shell}`);
+      console.error(`Supported shells: bash, zsh, fish`);
+      return 1;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELP SYSTEM - World-Class CLI Experience
+// ═══════════════════════════════════════════════════════════════════════════════
+function printBanner() {
+  const VERSION = getVersion();
+  console.log(`
+${c.dim}${sym.boxTopLeft}${sym.boxHorizontal.repeat(64)}${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(64 - 13 - VERSION.length - 4)}${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}                                                                ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}  ${c.bold}Catch AI hallucinations before your users do.${c.reset}                 ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}                                                                ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}  ${c.cyan}${sym.check}${c.reset} Detects routes that look real but don't work             ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}  ${c.cyan}${sym.check}${c.reset} Finds env vars used but never declared                   ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}  ${c.cyan}${sym.check}${c.reset} Flags auth endpoints with no protection                  ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}                                                                ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}  ${c.dim}SHIP = proof your code works. Not a vibe check.${c.reset}               ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxBottomLeft}${sym.boxHorizontal.repeat(64)}${sym.boxBottomRight}${c.reset}
+`);
+}
+
+/**
+ * Print command-specific help with rich examples
+ */
+function printCommandHelp(cmd) {
+  const registry = getRegistry();
+  const def = registry.COMMANDS[cmd];
+  if (!def) return false;
+  
+  // Build reverse alias map
+  const reverseAliases = {};
+  for (const [alias, target] of Object.entries(registry.ALIAS_MAP)) {
+    if (!reverseAliases[target]) reverseAliases[target] = [];
+    reverseAliases[target].push(alias);
+  }
+  
+  const aliases = reverseAliases[cmd] || [];
+  
+  // Tier badge (2-tier: FREE / PRO)
+  const tierBadge = def.tier === "free" ? `${c.green}[FREE]${c.reset}` :
+                    def.tier === "pro" ? `${c.magenta}[PRO]${c.reset}` : "";
+  
+  console.log(`
+  ${c.bold}${sym.arrowRight} vibecheck ${cmd}${c.reset} ${tierBadge}
+  ${aliases.length > 0 ? `${c.dim}Aliases: ${aliases.join(", ")}${c.reset}` : ""}
+  
+  ${def.longDescription || def.description}
+`);
+
+  // Examples
+  if (def.examples && def.examples.length > 0) {
+    console.log(`  ${c.bold}${sym.star} EXAMPLES${c.reset}\n`);
+    for (const ex of def.examples) {
+      const exTier = ex.tier === "pro" ? `${c.magenta}[PRO]${c.reset} ` : "";
+      console.log(`    ${c.dim}#${c.reset} ${ex.description} ${exTier}`);
+      console.log(`    ${c.cyan}${ex.command}${c.reset}`);
+      console.log();
+    }
+  }
+  
+  // Related commands
+  if (def.related && def.related.length > 0) {
+    console.log(`  ${c.bold}${sym.arrowRight} RELATED COMMANDS${c.reset}\n`);
+    for (const relCmd of def.related) {
+      const relDef = registry.COMMANDS[relCmd];
+      if (relDef) {
+        const relTier = relDef.tier === "pro" ? `${c.magenta}[PRO]${c.reset} ` : "";
+        console.log(`    ${c.cyan}vibecheck ${relCmd}${c.reset} ${relTier}${c.dim}${relDef.description}${c.reset}`);
+      }
+    }
+    console.log();
+  }
+  
+  // Documentation link
+  if (def.docsUrl) {
+    console.log(`  ${c.dim}${sym.boxHorizontal.repeat(56)}${c.reset}`);
+    console.log(`  ${c.dim}Documentation: ${c.underline}${def.docsUrl}${c.reset}`);
+  }
+  
+  console.log(`  ${c.dim}Run 'vibecheck --help' for all commands.${c.reset}\n`);
+  
+  return true;
+}
+
+function printHelp(showBanner = true) {
+  if (showBanner) printBanner();
+
+  const registry = getRegistry();
+  const { COMMANDS } = registry;
+
+  // Categories — clean story: Start → Core → Evidence → Automation
+  const categoryOrder = ["start", "core", "output", "verify", "enforce", "automation"];
+  const categories = {
+    start:      { name: "GETTING STARTED", color: c.yellow, icon: sym.rocket },
+    core:       { name: "CORE LOOP", color: c.green, icon: sym.shield },
+    output:     { name: "EVIDENCE", color: c.blue, icon: sym.file },
+    verify:     { name: "VERIFICATION", color: c.cyan, icon: sym.check },
+    enforce:    { name: "ENFORCEMENT", color: c.magenta, icon: sym.lock },
+    automation: { name: "AUTOMATION", color: c.brightBlue, icon: sym.gear },
+  };
+
+  // Group commands by category
+  const grouped = {};
+  for (const [cmd, def] of Object.entries(COMMANDS)) {
+    const cat = def.category || "automation";
+    if (!grouped[cat]) grouped[cat] = [];
+    grouped[cat].push({ cmd, ...def });
+  }
+
+  // Print each category
+  for (const catKey of categoryOrder) {
+    const commands = grouped[catKey];
+    if (!commands || commands.length === 0) continue;
+
+    const cat = categories[catKey];
+    console.log(`\n${cat.color}${cat.icon} ${cat.name}${c.reset}\n`);
+
+    for (const { cmd, description, tier, subcommands } of commands) {
+      // Tier badge
+      const tierBadge = tier === "pro" ? `${c.magenta}[PRO]${c.reset} ` : `${c.green}[FREE]${c.reset} `;
+
+      // Subcommand hint
+      let subHint = "";
+      if (subcommands && subcommands.length > 0) {
+        const subNames = subcommands.map(s => s.name).join(", ");
+        subHint = ` ${c.dim}(${subNames})${c.reset}`;
+      }
+
+      console.log(`  ${c.cyan}${cmd.padEnd(12)}${c.reset} ${tierBadge}${description}${subHint}`);
+    }
+  }
+
+  console.log(`
+${c.dim}${sym.boxHorizontal.repeat(64)}${c.reset}
+
+${c.green}${sym.star} PRODUCT STORY${c.reset}
+
+  ${c.bold}Scan${c.reset} ${c.dim}→${c.reset} ${c.bold}Ship${c.reset} ${c.dim}→${c.reset} ${c.bold}Certify${c.reset}     ${c.dim}That's it. Three steps to proven code.${c.reset}
+
+${c.green}${sym.rocket} QUICK START${c.reset}
+
+  ${c.bold}One command:${c.reset}
+  ${c.cyan}vibecheck kickoff${c.reset}          ${c.dim}60-second first run experience${c.reset}
+
+  ${c.bold}Step by step:${c.reset}
+  ${c.bold}1.${c.reset} ${c.cyan}vibecheck scan${c.reset}           ${c.dim}Find what's broken${c.reset}
+  ${c.bold}2.${c.reset} ${c.cyan}vibecheck fix --apply${c.reset}   ${c.dim}Fix it with AI${c.reset}
+  ${c.bold}3.${c.reset} ${c.cyan}vibecheck ship${c.reset}           ${c.dim}Get verdict: SHIP / WARN / BLOCK${c.reset}
+
+${c.green}${sym.lightning} COMMON WORKFLOWS${c.reset}
+
+  ${c.cyan}vibecheck scan secrets${c.reset}         ${c.dim}Scan for leaked secrets${c.reset}
+  ${c.cyan}vibecheck firewall on${c.reset}          ${c.dim}Enable agent firewall${c.reset}
+  ${c.cyan}vibecheck certify --badge${c.reset}      ${c.dim}Full proof + badge${c.reset}
+  ${c.cyan}vibecheck report sarif${c.reset}         ${c.dim}SARIF for GitHub CI${c.reset}
+  ${c.cyan}vibecheck ship preflight${c.reset}       ${c.dim}Pre-release checklist${c.reset}
+
+${c.green}${sym.star} PRICING${c.reset}
+
+  ${c.green}FREE${c.reset}  ${c.dim}$0${c.reset}       kickoff, scan, report, ci, config, doctor
+  ${c.magenta}PRO${c.reset}   ${c.dim}$49/mo${c.reset}   + ship, fix, certify, reality, firewall, mcp
+
+${c.bold}GLOBAL OPTIONS${c.reset}
+
+  ${c.cyan}--help, -h${c.reset}           Show help for any command
+  ${c.cyan}--json${c.reset}               Machine-readable JSON output
+  ${c.cyan}--quiet, -q${c.reset}          Suppress non-essential output
+  ${c.cyan}--verbose${c.reset}            Detailed output for debugging
+  ${c.cyan}--ci${c.reset}                 CI mode (quiet + no-banner)
+  ${c.cyan}--offline${c.reset}            Run without API connection
+  ${c.cyan}--path, -p <dir>${c.reset}     Run in specified directory
+
+${c.dim}${sym.boxHorizontal.repeat(64)}${c.reset}
+${c.dim}Run 'vibecheck <command> --help' for subcommands and options.${c.reset}
+${c.dim}Docs: https://docs.vibecheckai.dev${c.reset}
+`);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELP VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Self-test function to verify help output matches actual commands
+ * Run with: node bin/vibecheck.js --self-test
+ */
+function validateHelpOutput() {
+  const registry = getRegistry();
+  const { COMMANDS, ALIAS_MAP } = registry;
+  
+  // Extract commands from help text (simplified - just check registry)
+  const actualCommands = Object.keys(COMMANDS);
+  const actualAliases = Object.keys(ALIAS_MAP);
+  const allActualCommands = [...actualCommands, ...actualAliases];
+  
+  // Check for obvious issues
+  const issues = [];
+  
+  // Check that all commands have runners
+  for (const [cmd, def] of Object.entries(COMMANDS)) {
+    if (!def.runner) {
+      issues.push(`Command '${cmd}' missing runner`);
+    }
+  }
+  
+  // Check that aliases point to valid commands
+  for (const [alias, target] of Object.entries(ALIAS_MAP)) {
+    if (!COMMANDS[target]) {
+      issues.push(`Alias '${alias}' points to non-existent command '${target}'`);
+    }
+  }
+  
+  if (issues.length > 0) {
+    console.error('Help output validation failed:');
+    issues.forEach(issue => console.error(`  - ${issue}`));
+    return false;
+  }
+  
+  return true;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 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;
+}
+
+function hasFlag(args, flags) {
+  for (const flag of flags) {
+    if (args.includes(flag)) return true;
+  }
+  return false;
+}
+
+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");
+}
+
+/**
+ * Map error to standardized exit code
+ * @param {Error} error - Error object
+ * @param {boolean} json - Whether JSON output is requested
+ * @returns {number} Exit code
+ */
+function mapErrorToExitCode(error, json = false) {
+  const EXIT_CODES = {
+    'AUTH_REQUIRED': 5,
+    'AUTH_FAILED': 6,
+    'TIER_REQUIRED': 7,
+    'RATE_LIMITED': 8,
+    'NOT_FOUND': 4,
+    'VALIDATION_ERROR': 3,
+    'USER_ERROR': 3,
+    'NETWORK_ERROR': 9,
+  };
+  
+  // Check error.code first
+  if (error.code && EXIT_CODES[error.code]) {
+    return EXIT_CODES[error.code];
+  }
+  
+  // Check error.exitCode
+  if (error.exitCode !== undefined) {
+    return error.exitCode;
+  }
+  
+  // Check error message for common patterns
+  const message = error.message?.toLowerCase() || '';
+  if (message.includes('not found') || message.includes('not exist')) {
+    return 4; // NOT_FOUND
+  }
+  if (message.includes('auth') || message.includes('login')) {
+    return 5; // AUTH_REQUIRED
+  }
+  if (message.includes('network') || message.includes('connection')) {
+    return 9; // NETWORK_ERROR
+  }
+  
+  // Default to internal error
+  return 10; // INTERNAL_ERROR
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// FLAG PARSING
+// ═══════════════════════════════════════════════════════════════════════════════
+function parseGlobalFlags(rawArgs) {
+  const flags = {
+    help: false,
+    version: false,
+    json: false,
+    ci: false,
+    quiet: false,
+    verbose: false,
+    debug: false,
+    strict: false,
+    noBanner: false,
+    offline: false,
+    path: process.cwd(),
+    output: null,
+  };
+
+  const cleanArgs = [];
+  let i = 0;
+
+  while (i < rawArgs.length) {
+    const arg = rawArgs[i];
+
+    switch (arg) {
+      case "--help":
+      case "-h":
+        flags.help = true;
+        break;
+      case "--version":
+      case "-v":
+        flags.version = true;
+        break;
+      case "--json":
+        flags.json = true;
+        break;
+      case "--ci":
+        flags.ci = true;
+        break;
+      case "--quiet":
+      case "-q":
+        flags.quiet = true;
+        break;
+      case "--verbose":
+        flags.verbose = true;
+        break;
+      case "--debug":
+        flags.debug = true;
+        break;
+      case "--strict":
+        flags.strict = true;
+        break;
+      case "--no-banner":
+        flags.noBanner = true;
+        break;
+      case "--offline":
+      case "--local":
+        flags.offline = true;
+        break;
+      case "--path":
+      case "-p":
+        flags.path = rawArgs[++i] || process.cwd();
+        break;
+      case "--output":
+      case "-o":
+        flags.output = rawArgs[++i] || null;
+        break;
+      default:
+        if (arg.startsWith("--path=")) {
+          flags.path = arg.split("=")[1];
+        } else if (arg.startsWith("--output=")) {
+          flags.output = arg.split("=")[1];
+        } else {
+          cleanArgs.push(arg);
+        }
+    }
+    i++;
+  }
+
+  return { flags, cleanArgs };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MAIN ENTRY POINT
+// ═══════════════════════════════════════════════════════════════════════════════
+async function main() {
+  const startTime = performance.now();
+  const rawArgs = process.argv.slice(2);
+
+  // Parse global flags
+  const { flags: globalFlags, cleanArgs } = parseGlobalFlags(rawArgs);
+
+  // Handle version (fast path - no config loading)
+  if (globalFlags.version) {
+    console.log(`vibecheck v${getVersion()}`);
+    process.exit(0);
+  }
+
+  // Handle self-test flag (for CI validation)
+  if (cleanArgs.includes('--self-test')) {
+    const registry = getRegistry();
+    if (!validateHelpOutput()) {
+      process.exit(1);
+    }
+    console.log('Self-test passed: Help output matches command registry');
+    process.exit(0);
+  }
+
+  // Load config and state
+  const config = loadConfig();
+  const state = loadState();
+
+  // Apply flag overrides to config
+  if (globalFlags.debug) config.debug = true;
+  if (globalFlags.verbose) config.verbose = true;
+  if (globalFlags.quiet) config.quiet = true;
+  if (globalFlags.noBanner) config.noBanner = true;
+  if (globalFlags.ci) {
+    config.quiet = true;
+    config.noBanner = true;
+  }
+
+  // Handle no command
+  if (!cleanArgs[0]) {
+    printHelp(!config.noBanner);
+    process.exit(0);
+  }
+
+  // Handle global help
+  if (globalFlags.help && !cleanArgs[0]) {
+    printHelp(!config.noBanner);
+    process.exit(0);
+  }
+
+  // Handle completion command (special - doesn't need registry loaded normally)
+  if (cleanArgs[0] === "completion") {
+    process.exit(runCompletion(cleanArgs.slice(1)));
+  }
+
+  // Load registry for command resolution
+  const registry = getRegistry();
+  const { COMMANDS, ALIAS_MAP, ALL_COMMANDS, HIDDEN_COMMANDS, SUBCOMMAND_MAP, DEPRECATION_MAP } = registry;
+
+  let cmd = cleanArgs[0];
+  const originalCmd = cmd; // Save original for deprecation warning
+  let subcommandRunner = null; // Will be set if a subcommand route matches
+  
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // COMMAND RESOLUTION (3-pass)
+  //   1. Exact match in 12 top-level COMMANDS
+  //   2. Alias resolution (old names → new 12)
+  //   3. Hidden command fallback (power-user / legacy)
+  // ═══════════════════════════════════════════════════════════════════════════════
+  let resolvedViaAlias = false;
+  let resolvedViaHidden = false;
+
+  if (!COMMANDS[cmd]) {
+    if (ALIAS_MAP[cmd]) {
+      resolvedViaAlias = true;
+      cmd = ALIAS_MAP[cmd];
+    } else if (HIDDEN_COMMANDS && HIDDEN_COMMANDS[cmd]) {
+      resolvedViaHidden = true;
+      // Hidden commands run directly — skip subcommand logic
+    }
+  }
+
+  let cmdArgs = cleanArgs.slice(1);
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // SUBCOMMAND ROUTING
+  // If the first arg matches a known subcommand, route to its dedicated runner.
+  // e.g. "vibecheck scan secrets" → SUBCOMMAND_MAP["scan:secrets"]
+  //      "vibecheck ship preflight" → SUBCOMMAND_MAP["ship:preflight"]
+  //      "vibecheck firewall on" → SUBCOMMAND_MAP["firewall:on"]
+  // ═══════════════════════════════════════════════════════════════════════════════
+  if (COMMANDS[cmd] && cmdArgs.length > 0 && !resolvedViaHidden) {
+    const subKey = `${cmd}:${cmdArgs[0]}`;
+    if (SUBCOMMAND_MAP[subKey]) {
+      try {
+        const subDef = SUBCOMMAND_MAP[subKey];
+        subcommandRunner = subDef.runner();
+        const prependArgs = subDef.prependArgs || [];
+        // Drop the subcommand name from args, prepend any mapped args
+        cmdArgs = [...prependArgs, ...cmdArgs.slice(1)];
+      } catch (e) {
+        // Fall through to default runner if subcommand runner fails to load
+        subcommandRunner = null;
+      }
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // SPECIAL ALIAS ROUTING
+  // When old top-level commands that are now subcommands are used via alias,
+  // route them to the correct subcommand runner.
+  // e.g. "vibecheck launch" → alias to "ship" → route to ship:preflight runner
+  //      "vibecheck login"  → alias to "config" → route to config:auth runner
+  // ═══════════════════════════════════════════════════════════════════════════════
+  if (resolvedViaAlias && !subcommandRunner) {
+    const aliasRoutes = {
+      // Auth aliases → config:auth
+      "login": "config:auth", "logout": "config:auth", "whoami": "config:auth",
+      "me": "config:auth", "signin": "config:auth", "signout": "config:auth",
+      // launch → ship:preflight
+      "launch": "ship:preflight", "gate": "ship:preflight",
+      "ci-gate": "ship:preflight", "preflight": "ship:preflight", "prelaunch": "ship:preflight",
+      // shield/guard → firewall (default runner is fine)
+      // prove/verify/seal/badge → certify subcommands
+      "prove": "certify:prove", "verify": "certify:verify",
+      "seal": "certify:seal", "badge": "certify:seal", "attest": "certify:seal",
+      "truth": "certify:truth", "truthpack": "certify:truth",
+      // safelist/allowlist → config:safelist
+      "safelist": "config:safelist", "allowlist": "config:safelist",
+      "al": "config:safelist", "suppress": "config:safelist",
+      // context → config:context
+      "context": "config:context", "ctx": "config:context",
+      // forge → firewall:rules
+      "rules": "firewall:rules", "ai-rules": "firewall:rules",
+      "mdc": "firewall:rules", "brain": "firewall:rules",
+      // intent/approve → firewall subcommands
+      "intent": "firewall:intent", "approve": "firewall:approve",
+      // checkpoint shortcuts → fix:checkpoint
+      "checkpoint": "fix:checkpoint", "cp": "fix:checkpoint",
+      "snap": "fix:checkpoint", "snapshot": "fix:checkpoint",
+      "timemachine": "fix:checkpoint", "rollback": "fix:checkpoint",
+      // polish → fix:polish
+      "prod": "fix:polish", "final": "fix:polish",
+      // missions → fix:missions
+      "missions": "fix:missions",
+      // packs → report (default runner)
+      // evidence-pack → report:evidence
+      "evidence-pack": "report:evidence",
+      "permissions-pack": "report:permissions",
+      "proof-graph": "report:graph",
+    };
+
+    const subKey = aliasRoutes[originalCmd];
+    if (subKey && SUBCOMMAND_MAP[subKey]) {
+      try {
+        const subDef = SUBCOMMAND_MAP[subKey];
+        subcommandRunner = subDef.runner();
+        const prependArgs = subDef.prependArgs || [];
+        // For auth aliases, prepend the original command as subcommand
+        const authAliases = ['login', 'logout', 'whoami', 'me', 'signin', 'signout'];
+        if (authAliases.includes(originalCmd)) {
+          const mapped = originalCmd === 'signin' ? 'login' : originalCmd === 'signout' ? 'logout' : originalCmd;
+          cmdArgs = [mapped, ...cmdArgs];
+        }
+        cmdArgs = [...prependArgs, ...cmdArgs];
+      } catch (e) {
+        subcommandRunner = null;
+      }
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // DEPRECATION WARNING
+  // Show one-line hint when user uses an old command name
+  // ═══════════════════════════════════════════════════════════════════════════════
+  if (resolvedViaAlias && DEPRECATION_MAP && DEPRECATION_MAP[originalCmd]) {
+    const dep = DEPRECATION_MAP[originalCmd];
+    if (!globalFlags.json && !globalFlags.quiet) {
+      console.log(`${c.yellow}${sym.warning}${c.reset} ${c.dim}${dep.message} — use '${c.cyan}vibecheck ${dep.target}${c.reset}${c.dim}' instead${c.reset}`);
+    }
+  }
+
+  // Handle command-specific help (vibecheck <cmd> --help)
+  if (globalFlags.help && cmd && (COMMANDS[cmd] || (HIDDEN_COMMANDS && HIDDEN_COMMANDS[cmd]))) {
+    // Try our rich help first, then fall back to runner's --help
+    if (COMMANDS[cmd] && printCommandHelp(cmd)) {
+      process.exit(0);
+    }
+  }
+  
+  // Pass --help to runner if specified with command
+  if (globalFlags.help) cmdArgs = ["--help", ...cmdArgs];
+
+  // Pass standard flags to runners
+  if (globalFlags.json) cmdArgs.push("--json");
+  if (globalFlags.ci) cmdArgs.push("--ci");
+  if (globalFlags.noBanner) cmdArgs.push("--no-banner");
+  if (globalFlags.quiet) cmdArgs.push("--quiet");
+  if (globalFlags.path && globalFlags.path !== process.cwd()) {
+    cmdArgs.push("--path", globalFlags.path);
+  }
+  if (globalFlags.output) {
+    cmdArgs.push("--output", globalFlags.output);
+  }
+  if (globalFlags.verbose) cmdArgs.push("--verbose");
+  if (globalFlags.strict) cmdArgs.push("--strict");
+  if (globalFlags.offline) cmdArgs.push("--offline");
+
+  // Unknown command
+  if (!COMMANDS[cmd] && !resolvedViaHidden) {
+    const suggestions = findSimilarCommands(cmd, [...Object.keys(COMMANDS)]);
+    console.log(`\n${c.red}${sym.error}${c.reset} Unknown command: ${c.yellow}${originalCmd}${c.reset}`);
+
+    if (suggestions.length > 0) {
+      console.log(`\n${c.dim}Did you mean:${c.reset}`);
+      suggestions.forEach((s) => {
+        const def = COMMANDS[s];
+        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(4);
+  }
+
+  // Generate runId
+  const cliOutput = getCliOutput();
+  const runId = cliOutput.generateRunId();
+  const runStart = new Date().toISOString();
+
+  const cmdDef = COMMANDS[cmd] || (HIDDEN_COMMANDS && HIDDEN_COMMANDS[cmd]) || {};
+  let authInfo = { key: null };
+
+  // Check for offline/dev mode (via flag or env var)
+  // SECURITY: VIBECHECK_DEV_PRO only works in non-production to prevent auth bypass
+  const isDevProAllowed = process.env.NODE_ENV !== 'production' && 
+                          process.env.CI !== 'true' && 
+                          process.env.CI !== '1' &&
+                          process.env.VIBECHECK_DEV_PRO === '1';
+  const isOffline = globalFlags.offline || 
+                    process.env.VIBECHECK_OFFLINE === '1' || 
+                    process.env.VIBECHECK_LOCAL === '1' ||
+                    isDevProAllowed;
+
+  // Auth check (unless skipAuth or offline mode)
+  // Auth-exempt: config (has auth subcommand), doctor, kickoff, plus direct auth aliases
+  const authExemptCommands = ['auth', 'config', 'login', 'logout', 'whoami', 'me', 'signin', 'signout', 'help', '--help', '-h', 'version', '--version', 'doctor', 'kickoff'];
+  const needsAuth = !authExemptCommands.includes(cmd) && !cmdDef.skipAuth && !isOffline;
+  
+  if (needsAuth) {
+    const auth = getAuthModule();
+    const { key } = auth.getApiKey();
+    authInfo.key = key;
+
+    // If no API key, prompt for login
+    if (!key) {
+      console.log(`\n  ${c.red}❌ Authentication Required${c.reset}`);
+      console.log(`  Please log in to use vibecheck.\n`);
+      console.log(`  ${c.cyan}Options:${c.reset}`);
+      console.log(`  1. Press ${c.yellow}Enter${c.reset} to open browser and sign up`);
+      console.log(`  2. Visit ${c.underline}https://vibecheckai.dev${c.reset} directly`);
+      console.log(`  3. Run ${c.cyan}vibecheck login${c.reset} after getting your API key\n`);
+      
+      // Wait for Enter key
+      const readline = getReadline();
+      readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+      }).question('', async () => {
+        try {
+          const https = getHttps();
+          const url = 'https://vibecheckai.dev';
+          console.log(`\n  Opening ${c.underline}${url}${c.reset} in your browser...\n`);
+          
+          // Try to open browser
+          const start = process.platform === 'darwin' ? 'open' : 
+                       process.platform === 'win32' ? 'start' : 'xdg-open';
+          require('child_process').exec(`${start} ${url}`);
+        } catch (e) {
+          console.log(`  Could not open browser. Please visit: ${c.underline}https://vibecheckai.dev${c.reset}`);
+        }
+        process.exit(0);
+      });
+      
+      // Keep process alive
+      return new Promise(() => {});
+    }
+
+    const access = await checkCommandAccess(cmd, cmdArgs, authInfo);
+
+    if (!access.allowed) {
+      console.log(access.reason);
+      
+      // Show upgrade prompt if tier insufficient
+      if (access.upgradeUrl) {
+        console.log(`\n  ${c.cyan}Upgrade:${c.reset} ${access.upgradeUrl}`);
+      }
+      
+      return 1;
+    }
+
+    authInfo.access = access;
+  } else if (isOffline) {
+    // Offline mode - provide basic access info
+    // Suppress message if JSON/SARIF output is requested (check both global flags and command args)
+    const hasJsonOutput = globalFlags.json || cmdArgs.includes('--json') || cmdArgs.includes('--sarif');
+    if (!config.quiet && !config.noBanner && !hasJsonOutput) {
+      console.log(`${c.cyan}${sym.arrowRight} OFFLINE${c.reset} ${c.dim}mode - local scanning without API${c.reset}`);
+    }
+    authInfo.access = {
+      allowed: true,
+      tier: 'free',
+      caps: { maxFiles: 100, maxDepth: 3 },
+      offline: true
+    };
+  }
+
+  // Update state
+  state.runCount++;
+  state.lastRun = Date.now();
+  state.commandHistory = [...(state.commandHistory || []).slice(-99), { cmd, timestamp: Date.now() }];
+  saveState(state);
+
+  // Check for updates (async, non-blocking for startup)
+  let updatePromise = null;
+  if (!config.quiet && !config.noBanner && !isCI()) {
+    updatePromise = checkForUpdates(state, config);
+  }
+
+  let exitCode = 0;
+
+  try {
+    // Use subcommand runner if resolved, otherwise default command runner
+    const runner = subcommandRunner || getRunner(cmd);
+    if (!runner) {
+      console.error(`${c.red}${sym.error}${c.reset} Failed to load runner for: ${cmd}`);
+      process.exit(4); // NOT_FOUND
+    }
+
+    const context = {
+      repoRoot: globalFlags.path,
+      config,
+      state,
+      authInfo,
+      version: getVersion(),
+      isCI: isCI(),
+      runId,
+      runStart,
+    };
+
+    // Execute command - all commands use consistent runner signature
+    const result = await runner(cmdArgs, context);
+    
+    // Ensure result has standardized exit code
+    if (typeof result === 'object' && result.exitCode !== undefined) {
+      exitCode = result.exitCode;
+    } else if (typeof result === 'number') {
+      exitCode = result;
+    } else {
+      exitCode = 0; // SUCCESS
+    }
+  } catch (error) {
+    // Map errors to exit codes
+    exitCode = mapErrorToExitCode(error, globalFlags.json);
+    
+    if (globalFlags.json) {
+      console.log(JSON.stringify({
+        success: false,
+        error: {
+          code: error.code || 'INTERNAL_ERROR',
+          message: error.message,
+        },
+        exitCode,
+      }, null, 2));
+    } else {
+      console.error(formatError(error, config));
+    }
+  }
+
+  // Create receipt for paid commands
+  if (cmdDef.tier !== "free" && runId) {
+    try {
+      const { createManifestAndReceipt } = require("./runners/lib/receipts");
+      await createManifestAndReceipt({
+        runId,
+        command: cmd,
+        args: cmdArgs,
+        tier: authInfo.access?.tier || "free",
+        exitCode,
+        startTime: runStart,
+        endTime: new Date().toISOString(),
+        projectPath: globalFlags.path,
+      });
+    } catch (e) {
+      if (config.debug) console.error(`Failed to create receipt: ${e.message}`);
+    }
+  }
+
+  // Show update notice after command (if available)
+  if (updatePromise) {
+    const latestVersion = await updatePromise;
+    if (latestVersion) {
+      printUpdateNotice(latestVersion);
+    }
+  }
+
+  // Debug timing
+  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);
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// RUN
+// ═══════════════════════════════════════════════════════════════════════════════
+main().catch((error) => {
+  console.error(`\n${c.red}${sym.error} Fatal:${c.reset} ${error.message}`);
+  process.exit(1);
+});