@vibecheckai/cli 3.2.5 → 3.3.0

package/bin/runners/runMcp.js

@@ -6,6 +6,7 @@
  */
 
 const path = require("path");
+const fs = require("fs");
 const http = require("http");
 const { URL } = require("url");
 
@@ -14,6 +15,8 @@ const { buildTruthpack, writeTruthpack } = require("./lib/truth");
 const { shipCore } = require("./runShip");
 const { generateRunId } = require("./lib/cli-output");
 const { enforceLimit, enforceFeature, trackUsage } = require("./lib/entitlements");
+const { EXIT } = require("./lib/exit-codes");
+const { parseGlobalFlags, shouldSuppressOutput, isJsonMode } = require("./lib/global-flags");
 
 // MCP Server class
 class VibecheckMCPServer {
@@ -642,8 +645,14 @@ class VibecheckMCPServer {
     });
     
     this.server.on("error", err => {
-      console.error("MCP Server failed to start:", err);
-      process.exit(1);
+      console.error("MCP Server failed to start:", err.message);
+      if (err.code === "EADDRINUSE") {
+        console.error(`  Port ${this.port} is already in use. Try a different port with --port`);
+      } else if (err.code === "EACCES") {
+        console.error(`  Permission denied for port ${this.port}. Use a port > 1024`);
+      }
+      // Emit error event for caller to handle
+      this.emit?.("error", err);
     });
   }
 
@@ -658,54 +667,77 @@ class VibecheckMCPServer {
 // CLI handler
 async function runMcp(args) {
   const opts = parseArgs(args);
+  const { flags: globalFlags } = parseGlobalFlags(args);
+  const quiet = shouldSuppressOutput(globalFlags);
+  const json = isJsonMode(globalFlags);
   
   // Check if we're in free tier and only showing help/config
   const isFreeTier = process.env.VIBECHECK_TIER === "free" || !process.env.VIBECHECK_API_KEY;
   const isHelpOrConfig = opts.help || opts.printConfig || opts.status || opts.test;
   
   if (isFreeTier && !isHelpOrConfig) {
-    // This will be handled by entitlements system
-    // But we can show a helpful message
-    console.log("\n🔌 MCP Server requires STARTER plan or higher");
-    console.log("Use --help to see available options or");
-    console.log("Upgrade: https://vibecheckai.dev/pricing\n");
-    return 3; // EXIT_FEATURE_NOT_ALLOWED
+    if (json) {
+      console.log(JSON.stringify({ success: false, error: "MCP Server requires STARTER plan or higher" }));
+    } else if (!quiet) {
+      console.log("\n🔌 MCP Server requires STARTER plan or higher");
+      console.log("Use --help to see available options or");
+      console.log("Upgrade: https://vibecheckai.dev/pricing\n");
+    }
+    return EXIT.TIER_REQUIRED;
   }
   
   if (opts.help) {
     printHelp();
-    return 0;
+    return EXIT.SUCCESS;
   }
   
   if (opts.printConfig) {
     printClientConfig(opts);
-    return 0;
+    return EXIT.SUCCESS;
   }
   
   if (opts.status) {
     // Check server status
     try {
-      const response = await fetch(`http://${opts.host}:${opts.port}/status`);
+      const host = opts.host || "127.0.0.1";
+      const port = opts.port || 3000;
+      const response = await fetch(`http://${host}:${port}/status`);
       const status = await response.json();
       console.log(JSON.stringify(status, null, 2));
-      return 0;
+      return EXIT.SUCCESS;
     } catch (err) {
-      console.error("Server not running or not reachable");
-      return 1;
+      if (json) {
+        console.log(JSON.stringify({ success: false, error: "Server not running or not reachable" }));
+      } else {
+        console.error("Server not running or not reachable");
+        console.error("  Start the server with: vibecheck mcp");
+      }
+      return EXIT.NETWORK_ERROR;
     }
   }
   
   if (opts.test) {
     // Test connection
     try {
-      const response = await fetch(`http://${opts.host}:${opts.port}/tools`);
+      const host = opts.host || "127.0.0.1";
+      const port = opts.port || 3000;
+      const response = await fetch(`http://${host}:${port}/tools`);
       const tools = await response.json();
-      console.log("✅ Connection successful");
-      console.log(`📋 Available tools: ${tools.tools.length}`);
-      return 0;
+      if (json) {
+        console.log(JSON.stringify({ success: true, toolCount: tools.tools?.length || 0 }));
+      } else {
+        console.log("✅ Connection successful");
+        console.log(`📋 Available tools: ${tools.tools?.length || 0}`);
+      }
+      return EXIT.SUCCESS;
     } catch (err) {
-      console.error("❌ Connection failed:", err.message);
-      return 1;
+      if (json) {
+        console.log(JSON.stringify({ success: false, error: err.message }));
+      } else {
+        console.error("❌ Connection failed:", err.message);
+        console.error("  Ensure the MCP server is running");
+      }
+      return EXIT.NETWORK_ERROR;
     }
   }
   
@@ -713,42 +745,88 @@ async function runMcp(args) {
   let config = {};
   if (opts.config) {
     const configPath = path.resolve(opts.config);
-    if (require("fs").existsSync(configPath)) {
-      config = JSON.parse(require("fs").readFileSync(configPath, "utf8"));
-    } else {
-      console.error(`Config file not found: ${configPath}`);
-      return 1;
+    if (!fs.existsSync(configPath)) {
+      if (json) {
+        console.log(JSON.stringify({ success: false, error: `Config file not found: ${configPath}` }));
+      } else {
+        console.error(`Config file not found: ${configPath}`);
+      }
+      return EXIT.NOT_FOUND;
+    }
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    } catch (parseErr) {
+      if (json) {
+        console.log(JSON.stringify({ success: false, error: `Invalid JSON in config: ${parseErr.message}` }));
+      } else {
+        console.error(`Invalid JSON in config file: ${parseErr.message}`);
+      }
+      return EXIT.USER_ERROR;
     }
   }
   
-  // Create and start server
-  const server = new VibecheckMCPServer({
-    host: opts.host || config.server?.host || "127.0.0.1",
-    port: opts.port || config.server?.port || 3000,
-    allowRemote: opts.allowRemote || config.server?.allowRemote || false,
-    requireApiKey: opts.requireApiKey !== false,
-    apiKey: opts.apiKey || config.auth?.apiKey,
-    logLevel: opts.logLevel || config.logging?.level || "info",
-    auditLog: opts.auditLog || config.logging?.auditFile
-  });
-  
-  server.start();
-  
-  // Handle shutdown
-  process.on("SIGINT", () => {
-    console.log("\nShutting down MCP server...");
-    server.stop();
-    process.exit(0);
-  });
-  
-  process.on("SIGTERM", () => {
-    console.log("\nShutting down MCP server...");
-    server.stop();
-    process.exit(0);
-  });
+  // Validate port
+  const port = opts.port || config.server?.port || 3000;
+  if (isNaN(port) || port < 1 || port > 65535) {
+    if (json) {
+      console.log(JSON.stringify({ success: false, error: `Invalid port: ${port}` }));
+    } else {
+      console.error(`Invalid port: ${port}`);
+      console.error("  Port must be a number between 1 and 65535");
+    }
+    return EXIT.USER_ERROR;
+  }
   
-  // Keep process alive
-  return new Promise(() => {});
+  try {
+    // Create and start server
+    const server = new VibecheckMCPServer({
+      host: opts.host || config.server?.host || "127.0.0.1",
+      port: port,
+      allowRemote: opts.allowRemote || config.server?.allowRemote || false,
+      requireApiKey: opts.requireApiKey !== false,
+      apiKey: opts.apiKey || config.auth?.apiKey,
+      logLevel: opts.logLevel || config.logging?.level || "info",
+      auditLog: opts.auditLog || config.logging?.auditFile
+    });
+    
+    // Track if server started successfully
+    let serverStarted = false;
+    let serverError = null;
+    
+    // Listen for server errors before starting
+    server.server?.on?.("error", (err) => {
+      serverError = err;
+    });
+    
+    server.start();
+    serverStarted = true;
+    
+    // Handle shutdown gracefully
+    const cleanup = () => {
+      if (!quiet) console.log("\nShutting down MCP server...");
+      server.stop();
+    };
+    
+    process.on("SIGINT", () => {
+      cleanup();
+      process.exit(EXIT.SUCCESS);
+    });
+    
+    process.on("SIGTERM", () => {
+      cleanup();
+      process.exit(EXIT.SUCCESS);
+    });
+    
+    // Keep process alive
+    return new Promise(() => {});
+  } catch (error) {
+    if (json) {
+      console.log(JSON.stringify({ success: false, error: error.message }));
+    } else {
+      console.error(`Failed to start MCP server: ${error.message}`);
+    }
+    return EXIT.INTERNAL_ERROR;
+  }
 }
 
 // Argument parsing

package/bin/runners/runPolish.js

@@ -24,6 +24,8 @@
 
 const fs = require("fs");
 const path = require("path");
+const { EXIT } = require("./lib/exit-codes");
+const { parseGlobalFlags, shouldSuppressOutput, isJsonMode } = require("./lib/global-flags");
 
 // ═══════════════════════════════════════════════════════════════════════════════
 // TERMINAL STYLING
@@ -2856,26 +2858,35 @@ function getCategoryIcon(category) {
 
 async function runPolish(args) {
   const opts = parseArgs(args);
+  const { flags: globalFlags } = parseGlobalFlags(args);
+  const quiet = shouldSuppressOutput(globalFlags);
+  const json = isJsonMode(globalFlags) || opts.json;
   
   if (opts.help) {
     printHelp();
-    return 0;
+    return EXIT.SUCCESS;
   }
   
   const projectPath = path.resolve(opts.path);
   
   // Verify project exists
   if (!await pathExists(projectPath)) {
-    console.error(`${c.red}${icons.cross} Project path does not exist: ${projectPath}${c.reset}`);
-    return 1;
+    if (json) {
+      console.log(JSON.stringify({ success: false, error: `Project path does not exist: ${projectPath}` }));
+    } else {
+      console.error(`${c.red}${icons.cross} Project path does not exist: ${projectPath}${c.reset}`);
+      console.error(`  Verify the path and try again.`);
+    }
+    return EXIT.NOT_FOUND;
   }
   
-  // JSON mode
-  if (opts.json) {
-    const report = await analyzeProject(projectPath, opts);
-    console.log(JSON.stringify(report, null, 2));
-    return report.critical > 0 ? 1 : 0;
-  }
+  try {
+    // JSON mode
+    if (json) {
+      const report = await analyzeProject(projectPath, opts);
+      console.log(JSON.stringify(report, null, 2));
+      return report.critical > 0 ? EXIT.BLOCKING : EXIT.SUCCESS;
+    }
   
   // Interactive mode
   console.log(`
@@ -2914,8 +2925,10 @@ ${c.bold}╔══════════════════════
   console.log(`            ${icons.critical} ${report.critical} critical  ${icons.high} ${report.high} high  ${icons.medium} ${report.medium} medium  ${icons.low} ${report.low} low\n`);
   
   if (report.issues.length === 0) {
-    console.log(`\n${c.green}${c.bold}${icons.check} Perfect!${c.reset} No polish issues found. Your project is production-ready! ${icons.rocket}\n`);
-    return 0;
+    if (!quiet) {
+      console.log(`\n${c.green}${c.bold}${icons.check} Perfect!${c.reset} No polish issues found. Your project is production-ready! ${icons.rocket}\n`);
+    }
+    return EXIT.SUCCESS;
   }
   
   // Group by category
@@ -3016,16 +3029,26 @@ ${c.bold}╔══════════════════════
   }
   
   // Next steps
-  console.log(`${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}`);
-  console.log(`${c.bold}${icons.rocket} NEXT STEPS${c.reset}`);
-  console.log(`${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}\n`);
-  console.log(`   1. Fix ${c.red}critical${c.reset} and ${c.yellow}high${c.reset} severity issues first`);
-  console.log(`   2. Use ${c.cyan}vibecheck polish --prompts${c.reset} to get AI-ready fixes`);
-  console.log(`   3. Copy prompts to your AI assistant (Cursor, Copilot, Claude)`);
-  console.log(`   4. Re-run ${c.cyan}vibecheck polish${c.reset} to verify fixes`);
-  console.log(`   5. Run ${c.cyan}vibecheck ship${c.reset} when score is 80+\n`);
+  if (!quiet) {
+    console.log(`${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}`);
+    console.log(`${c.bold}${icons.rocket} NEXT STEPS${c.reset}`);
+    console.log(`${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}\n`);
+    console.log(`   1. Fix ${c.red}critical${c.reset} and ${c.yellow}high${c.reset} severity issues first`);
+    console.log(`   2. Use ${c.cyan}vibecheck polish --prompts${c.reset} to get AI-ready fixes`);
+    console.log(`   3. Copy prompts to your AI assistant (Cursor, Copilot, Claude)`);
+    console.log(`   4. Re-run ${c.cyan}vibecheck polish${c.reset} to verify fixes`);
+    console.log(`   5. Run ${c.cyan}vibecheck ship${c.reset} when score is 80+\n`);
+  }
   
-  return report.critical > 0 ? 1 : 0;
+  return report.critical > 0 ? EXIT.BLOCKING : EXIT.SUCCESS;
+  } catch (error) {
+    if (json) {
+      console.log(JSON.stringify({ success: false, error: error.message }));
+    } else {
+      console.error(`${c.red}${icons.cross} Polish analysis failed: ${error.message}${c.reset}`);
+    }
+    return EXIT.INTERNAL_ERROR;
+  }
 }
 
 module.exports = { runPolish };

package/bin/runners/runProve.js

@@ -26,10 +26,9 @@ const {
   generateRunId, 
   createJsonOutput, 
   writeJsonOutput, 
-  exitCodeToVerdict,
-  verdictToExitCode,
   saveArtifact 
 } = require("./lib/cli-output");
+const { EXIT, verdictToExitCode, exitCodeToVerdict } = require("./lib/exit-codes");
 const { parseGlobalFlags, shouldShowBanner } = require("./lib/global-flags");
 const upsell = require("./lib/upsell");
 

package/bin/runners/runReport.js

@@ -18,6 +18,7 @@
 const path = require("path");
 const fs = require("fs");
 const { parseGlobalFlags, shouldShowBanner } = require("./lib/global-flags");
+const { EXIT } = require("./lib/exit-codes");
 
 // Entitlements enforcement
 let entitlements;
@@ -264,11 +265,11 @@ async function runReport(args) {
       default:
         spinner.fail(`Unknown format: ${format}`);
         console.log(`  ${ansi.dim}Supported: html, md, json, sarif, csv, pdf${ansi.reset}`);
-        return 1;
+        return EXIT.USER_ERROR;
     }
   } catch (err) {
     spinner.fail(`Failed to generate report: ${err.message}`);
-    return 1;
+    return EXIT.INTERNAL_ERROR;
   }
 
   // Determine output path

package/bin/runners/runScan.js

@@ -18,6 +18,14 @@ const { withErrorHandling, createUserError } = require("./lib/error-handler");
 const { enforceLimit, trackUsage } = require("./lib/entitlements");
 const { emitScanStart, emitScanComplete } = require("./lib/audit-bridge");
 const { parseGlobalFlags, shouldShowBanner } = require("./lib/global-flags");
+const { 
+  createScan, 
+  updateScanProgress, 
+  submitScanResults, 
+  reportScanError, 
+  isApiAvailable 
+} = require("./lib/api-client");
+const { EXIT, verdictToExitCode } = require("./lib/exit-codes");
 
 // ═══════════════════════════════════════════════════════════════════════════════
 // ENHANCED TERMINAL UI & OUTPUT MODULES
@@ -163,57 +171,75 @@ function printHelp(showBanner = true) {
     console.log(BANNER);
   }
   console.log(`
-  ${ansi.bold}Usage:${ansi.reset} vibecheck scan ${ansi.dim}(s)${ansi.reset} [path] [options]
+  ${ansi.bold}USAGE${ansi.reset}
+    ${colors.accent}vibecheck scan${ansi.reset} [path] [options]
   
-  ${ansi.bold}Aliases:${ansi.reset} ${ansi.dim}s${ansi.reset}
-
-  ${ansi.bold}Scan Modes:${ansi.reset}
-    ${colors.accent}(default)${ansi.reset}       Layer 1: AST static analysis ${ansi.dim}(fast)${ansi.reset}
-    ${colors.accent}--truth, -t${ansi.reset}     Layer 1+2: Include build manifest verification ${ansi.dim}(CI/ship)${ansi.reset}
-    ${colors.accent}--reality, -r${ansi.reset}   Layer 1+2+3: Include Playwright runtime proof ${ansi.dim}(full)${ansi.reset}
-    ${colors.accent}--reality-sniff${ansi.reset} Include Reality Sniff AI artifact detection ${ansi.dim}(recommended)${ansi.reset}
-
-  ${ansi.bold}Fix Mode:${ansi.reset}
-    ${colors.accent}--autofix, -f${ansi.reset}   Apply safe fixes + generate AI missions ${ansi.rgb(0, 200, 255)}[STARTER]${ansi.reset}
-
-  ${ansi.bold}Allowlist (suppress false positives):${ansi.reset}
-    ${colors.accent}--allowlist list${ansi.reset}                 Show all allowlist entries
-    ${colors.accent}--allowlist add${ansi.reset}                  Add entry to allowlist
-      ${ansi.dim}--id <finding-id>${ansi.reset}             Finding ID to allowlist
-      ${ansi.dim}--pattern <regex>${ansi.reset}             Pattern to match
-      ${ansi.dim}--reason <text>${ansi.reset}               Reason (required)
-      ${ansi.dim}--scope <global|file|line>${ansi.reset}    Scope (default: global)
-      ${ansi.dim}--expires <days>${ansi.reset}              Auto-expire after N days
-    ${colors.accent}--allowlist remove --id <id>${ansi.reset}     Remove entry from allowlist
-    ${colors.accent}--allowlist check --id <id>${ansi.reset}      Check if finding is allowlisted
-
-  ${ansi.bold}Options:${ansi.reset}
-    ${colors.accent}--url, -u${ansi.reset}       Base URL for reality testing (e.g., http://localhost:3000)
-    ${colors.accent}--verbose, -v${ansi.reset}   Show detailed progress
-    ${colors.accent}--json${ansi.reset}          Output results as JSON
-    ${colors.accent}--sarif${ansi.reset}         Output in SARIF format (GitHub code scanning)
-    ${colors.accent}--no-save${ansi.reset}       Don't save results to .vibecheck/results/
-    ${colors.accent}--help, -h${ansi.reset}      Show this help
-
-  ${ansi.bold}Examples:${ansi.reset}
-    ${ansi.dim}# Quick scan (AST only)${ansi.reset}
+  ${ansi.dim}Aliases: s, check${ansi.reset}
+
+  The core analysis engine. Scans your codebase for route integrity issues,
+  security vulnerabilities, code quality problems, and more.
+
+  ${ansi.bold}SCAN LAYERS${ansi.reset}
+    ${colors.accent}(default)${ansi.reset}         Layer 1: AST static analysis ${ansi.dim}(fast, ~2s)${ansi.reset}
+    ${colors.accent}--truth, -t${ansi.reset}       Layer 1+2: + build manifest verification ${ansi.dim}(CI/ship)${ansi.reset}
+    ${colors.accent}--reality, -r${ansi.reset}     Layer 1+2+3: + Playwright runtime proof ${ansi.dim}[PRO]${ansi.reset}
+    ${colors.accent}--reality-sniff${ansi.reset}   Include Reality Sniff AI artifact detection
+
+  ${ansi.bold}FIX MODE${ansi.reset} ${ansi.cyan}[STARTER]${ansi.reset}
+    ${colors.accent}--autofix, -f${ansi.reset}     Generate AI fix missions for detected issues
+
+  ${ansi.bold}BASELINE TRACKING${ansi.reset}
+    ${colors.accent}--baseline${ansi.reset}        Compare against previous scan ${ansi.dim}(default: on)${ansi.reset}
+    ${colors.accent}--no-baseline${ansi.reset}     Skip baseline comparison
+    ${colors.accent}--update-baseline${ansi.reset} Save current findings as new baseline
+
+  ${ansi.bold}ALLOWLIST (suppress false positives)${ansi.reset}
+    ${colors.accent}--allowlist list${ansi.reset}                   Show all suppressed findings
+    ${colors.accent}--allowlist add --id <id> --reason "..."${ansi.reset}
+    ${colors.accent}--allowlist remove --id <id>${ansi.reset}       Remove suppression
+    ${colors.accent}--allowlist check --id <id>${ansi.reset}        Check if suppressed
+
+  ${ansi.bold}OUTPUT OPTIONS${ansi.reset}
+    ${colors.accent}--json${ansi.reset}            Output as JSON ${ansi.dim}(machine-readable)${ansi.reset}
+    ${colors.accent}--sarif${ansi.reset}           SARIF format ${ansi.dim}(GitHub code scanning)${ansi.reset}
+    ${colors.accent}--no-save${ansi.reset}         Don't save results to .vibecheck/results/
+    ${colors.accent}--verbose, -v${ansi.reset}     Show detailed progress
+
+  ${ansi.bold}GLOBAL OPTIONS${ansi.reset}
+    ${colors.accent}--path, -p <dir>${ansi.reset}  Run in specified directory
+    ${colors.accent}--quiet, -q${ansi.reset}       Suppress non-essential output
+    ${colors.accent}--ci${ansi.reset}              CI mode ${ansi.dim}(quiet + no-banner)${ansi.reset}
+    ${colors.accent}--help, -h${ansi.reset}        Show this help
+
+  ${ansi.bold}💡 EXAMPLES${ansi.reset}
+
+    ${ansi.dim}# Quick scan (most common)${ansi.reset}
     vibecheck scan
 
-    ${ansi.dim}# Scan + autofix with missions${ansi.reset}
+    ${ansi.dim}# Scan with AI fix missions${ansi.reset}
     vibecheck scan --autofix
 
-    ${ansi.dim}# Add false positive to allowlist${ansi.reset}
-    vibecheck scan --allowlist add --id R_DEAD_abc123 --reason "Known toggle"
+    ${ansi.dim}# Suppress a false positive${ansi.reset}
+    vibecheck scan --allowlist add --id R_DEAD_abc123 --reason "Feature toggle"
 
-    ${ansi.dim}# List allowlist entries${ansi.reset}
-    vibecheck scan --allowlist list
+    ${ansi.dim}# CI pipeline (JSON output, strict)${ansi.reset}
+    vibecheck scan --ci --json > results.json
 
-    ${ansi.dim}# Full proof with Playwright${ansi.reset}
+    ${ansi.dim}# Full reality proof (requires running app)${ansi.reset}
     vibecheck scan --reality --url http://localhost:3000
 
-  ${ansi.bold}Output:${ansi.reset}
-    Results saved to: .vibecheck/results/latest.json
-    Missions saved to: .vibecheck/missions/ ${ansi.dim}(with --autofix)${ansi.reset}
+  ${ansi.bold}📄 OUTPUT${ansi.reset}
+    Results:   .vibecheck/results/latest.json
+    Missions:  .vibecheck/missions/ ${ansi.dim}(with --autofix)${ansi.reset}
+    History:   .vibecheck/results/history/
+
+  ${ansi.bold}🔗 RELATED COMMANDS${ansi.reset}
+    ${colors.accent}vibecheck ship${ansi.reset}       Get final SHIP/WARN/BLOCK verdict
+    ${colors.accent}vibecheck fix${ansi.reset}        Apply AI-generated fixes ${ansi.cyan}[STARTER]${ansi.reset}
+    ${colors.accent}vibecheck prove${ansi.reset}      Full proof pipeline with evidence ${ansi.magenta}[PRO]${ansi.reset}
+
+  ${ansi.dim}─────────────────────────────────────────────────────────────${ansi.reset}
+  ${ansi.dim}Documentation: https://docs.vibecheckai.dev/cli/scan${ansi.reset}
   `);
 }
 
@@ -703,6 +729,27 @@ async function runScan(args) {
   emitScanStart(projectPath, args);
   const projectName = path.basename(projectPath);
 
+  // Initialize API integration
+  let apiScan = null;
+  let apiConnected = false;
+  
+  // Try to connect to API for dashboard integration
+  try {
+    apiConnected = await isApiAvailable();
+    if (apiConnected) {
+      // Create scan record in dashboard
+      apiScan = await createScan({
+        localPath: projectPath,
+        branch: opts.branch || 'main',
+        enableLLM: opts.llm || false,
+      });
+      console.log(`${colors.info}📡${ansi.reset} Connected to dashboard (Scan ID: ${apiScan.scanId})`);
+    }
+  } catch (err) {
+    // API connection is optional, continue without it
+    console.log(`${colors.dim}ℹ${ansi.reset} Dashboard integration unavailable`);
+  }
+
   // Validate project path
   if (!fs.existsSync(projectPath)) {
     throw createUserError(`Project path does not exist: ${projectPath}`, "ValidationError");
@@ -733,7 +780,7 @@ async function runScan(args) {
     console.log(`  ${colors.warning}⚠${ansi.reset} ${ansi.bold}Reality layer requires --url${ansi.reset}`);
     console.log(`  ${ansi.dim}Example: vibecheck scan --reality --url http://localhost:3000${ansi.reset}`);
     console.log();
-    return 1;
+    return EXIT.USER_ERROR;
   }
 
   // Initialize spinner outside try block for error handling
@@ -1228,6 +1275,28 @@ async function runScan(args) {
       durationMs: timings.total,
     });
 
+    // Submit results to dashboard if connected
+    if (apiConnected && apiScan) {
+      try {
+        await submitScanResults(apiScan.scanId, {
+          verdict: verdict.verdict,
+          score: report.score?.overall || 0,
+          findings: report.findings || [],
+          filesScanned: report.stats?.filesScanned || 0,
+          linesScanned: report.stats?.linesScanned || 0,
+          durationMs: timings.total,
+          metadata: {
+            layers,
+            profile: opts.profile,
+            version: require('../../package.json').version,
+          },
+        });
+        console.log(`${colors.success}✓${ansi.reset} Results sent to dashboard`);
+      } catch (err) {
+        console.log(`${colors.warning}⚠${ansi.reset} Failed to send results to dashboard: ${err.message}`);
+      }
+    }
+
     return getExitCodeFromUnified ? getExitCodeFromUnified(verdict) : getExitCode(verdict);
     } else {
       // Legacy fallback output when unified output system isn't available
@@ -1316,8 +1385,30 @@ async function runScan(args) {
         issueCount: criticalCount + warningCount,
         durationMs: timings.total,
       });
+
+      // Submit results to dashboard if connected
+      if (apiConnected && apiScan) {
+        try {
+          await submitScanResults(apiScan.scanId, {
+            verdict,
+            score: verdict === 'SHIP' ? 100 : verdict === 'WARN' ? 70 : 40,
+            findings: normalizedLegacyFindings,
+            filesScanned: result.stats?.filesScanned || 0,
+            linesScanned: result.stats?.linesScanned || 0,
+            durationMs: timings.total,
+            metadata: {
+              layers,
+              profile: opts.profile,
+              version: require('../../package.json').version,
+            },
+          });
+          console.log(`${colors.success}✓${ansi.reset} Results sent to dashboard`);
+        } catch (err) {
+          console.log(`${colors.warning}⚠${ansi.reset} Failed to send results to dashboard: ${err.message}`);
+        }
+      }
       
-      return verdict === 'SHIP' ? 0 : verdict === 'WARN' ? 1 : 2;
+      return verdictToExitCode(verdict);
     }
 
   } catch (error) {
@@ -1334,6 +1425,16 @@ async function runScan(args) {
       errorMessage: error.message,
       durationMs: Date.now() - startTime,
     });
+
+    // Report error to dashboard if connected
+    if (apiConnected && apiScan) {
+      try {
+        await reportScanError(apiScan.scanId, error);
+        console.log(`${colors.info}📡${ansi.reset} Error reported to dashboard`);
+      } catch (err) {
+        console.log(`${colors.warning}⚠${ansi.reset} Failed to report error to dashboard: ${err.message}`);
+      }
+    }
     
     return exitCode;
   }