@vibgrate/cli 1.0.52 → 1.0.54

package/dist/{baseline-FRBISJ66.js → baseline-5ZOILNXB.js}

@@ -1,8 +1,8 @@
 import {
   baselineCommand,
   runBaseline
-} from "./chunk-TCYJSLL2.js";
-import "./chunk-TYAGUEXG.js";
+} from "./chunk-CQMW6PVB.js";
+import "./chunk-PQEUNAVK.js";
 import "./chunk-RNVZIZNL.js";
 export {
   baselineCommand,

package/dist/{chunk-TCYJSLL2.js → chunk-CQMW6PVB.js}

@@ -1,6 +1,6 @@
 import {
   runScan
-} from "./chunk-TYAGUEXG.js";
+} from "./chunk-PQEUNAVK.js";
 import {
   writeJsonFile
 } from "./chunk-RNVZIZNL.js";

package/dist/{chunk-TYAGUEXG.js → chunk-PQEUNAVK.js}

@@ -469,6 +469,17 @@ function formatExtended(ext) {
       if (bc.peerConflictsDetected) {
         lines.push(`    ${chalk.red("\u26A0")} Peer dependency conflicts detected`);
       }
+      lines.push(`    Recommendation: ${chalk.bold(bc.overallRecommendation)}`);
+      const projectsWithPlans = bc.projectIntelligence.filter((p) => p.packages.length > 0).slice(0, 3);
+      if (projectsWithPlans.length > 0) {
+        lines.push("    Major Upgrade Intelligence:");
+        for (const p of projectsWithPlans) {
+          lines.push(`      - ${p.project} (${p.recommendation})`);
+          for (const pkg2 of p.packages.slice(0, 2)) {
+            lines.push(`        \xB7 ${pkg2.package} ${pkg2.currentVersion ?? "?"} \u2192 ${pkg2.targetVersion ?? "?"} | touched ~${pkg2.usage.touchedPercent}% | ${pkg2.automatable}`);
+          }
+        }
+      }
       lines.push("");
     }
   }
@@ -1197,7 +1208,7 @@ var pushCommand = new Command2("push").description("Push scan results to Vibgrat
 });
 
 // src/commands/scan.ts
-import * as path22 from "path";
+import * as path23 from "path";
 import { Command as Command3 } from "commander";
 import chalk6 from "chalk";
 
@@ -4945,307 +4956,253 @@ async function scanTsModernity(rootDir, cache) {
 }
 
 // src/scanners/breaking-change.ts
+import * as path16 from "path";
+import * as semver9 from "semver";
 var DEPRECATED_PACKAGES2 = /* @__PURE__ */ new Set([
-  // Fully deprecated / archived
   "request",
-  // deprecated 2020, use undici/node fetch
   "request-promise",
-  // deprecated with request
   "request-promise-native",
-  // deprecated with request
   "moment",
-  // deprecated, use date-fns / luxon / Temporal
   "node-sass",
-  // deprecated, use sass (Dart Sass)
   "tslint",
-  // archived, use eslint + typescript-eslint
   "aws-sdk",
-  // AWS SDK v2 EOL, use @aws-sdk/* v3
   "babel-core",
-  // replaced by @babel/core
   "babel-preset-env",
-  // replaced by @babel/preset-env
   "babel-preset-react",
-  // replaced by @babel/preset-react
   "babel-loader",
-  // 7.x deprecated, must pair with @babel/core
   "core-js",
-  // v2 deprecated (v3 ok but signals old config)
   "istanbul",
-  // replaced by nyc / c8
   "istanbul-instrumenter-loader",
-  // deprecated with istanbul
   "left-pad",
-  // meme package, use String.padStart
   "popper.js",
-  // deprecated, use @popperjs/core
   "create-react-class",
-  // deprecated React pattern
   "react-addons-css-transition-group",
-  // deprecated React addon
   "react-addons-test-utils",
-  // use react-dom/test-utils
   "@types/express-serve-static-core",
-  // now shipped with express
   "enzyme",
-  // unmaintained, use Testing Library or Vitest
   "enzyme-adapter-react-16",
-  // unmaintained
   "enzyme-adapter-react-17",
-  // unmaintained
   "react-hot-loader",
-  // deprecated, use React Fast Refresh
   "react-loadable",
-  // unmaintained, use React.lazy
   "react-router-dom-v5-compat",
-  // migration shim
   "redux-thunk",
-  // bundled into @reduxjs/toolkit since v1.5
   "redux-saga",
-  // declining, consider RTK Query
   "recompose",
-  // archived, use hooks
   "classnames",
-  // works but clsx is faster & smaller
   "glamor",
-  // deprecated CSS-in-JS
   "radium",
-  // deprecated CSS-in-JS
   "material-ui",
-  // replaced by @mui/material
   "@material-ui/core",
-  // replaced by @mui/material
-  // Unmaintained / abandoned
   "bower",
-  // dead package manager
   "grunt",
-  // superseded by npm scripts / modern bundlers
   "gulp",
-  // declining, modern bundlers preferred
   "browserify",
-  // superseded by modern bundlers
   "coffee-script",
-  // CoffeeScript 1.x deprecated
   "coffeescript",
-  // declining
   "jade",
-  // renamed to pug
   "nomnom",
-  // deprecated CLI parser
   "optimist",
-  // deprecated CLI parser, use yargs/commander
   "minimist",
-  // unmaintained, use mri or parseArgs
   "colors",
-  // supply chain compromised, use chalk/picocolors
   "faker",
-  // supply chain compromised, use @faker-js/faker
   "event-stream",
-  // supply chain incident
   "ua-parser-js",
-  // had supply chain incident
   "caniuse-db",
-  // replaced by caniuse-lite
   "circular-json",
-  // deprecated, use flatted
   "mkdirp",
-  // Node has fs.mkdir recursive since v10
   "rimraf",
-  // Node has fs.rm recursive since v14
   "glob",
-  // consider fast-glob or Node fs.glob
   "swig",
-  // abandoned template engine
   "dustjs-linkedin",
-  // abandoned template engine
   "hogan.js",
-  // abandoned template engine
   "passport-local-mongoose",
-  // low maintenance
-  // Known breaking-change magnets
   "@angular/http",
-  // removed in Angular 15+
   "rxjs-compat",
-  // migration shim for RxJS 5→6
   "protractor",
-  // deprecated by Angular team
   "karma",
-  // deprecated, Vitest/Jest preferred
   "karma-jasmine",
-  // deprecated with Karma
   "jasmine"
-  // declining in usage
 ]);
 var LEGACY_POLYFILLS = /* @__PURE__ */ new Set([
-  // Built-in fetch & web APIs (Node 18+)
   "node-fetch",
-  // native fetch since Node 18
   "cross-fetch",
-  // native fetch since Node 18
   "isomorphic-fetch",
-  // native fetch since Node 18
   "whatwg-fetch",
-  // native fetch since Node 18
   "abort-controller",
-  // native AbortController since Node 15
   "form-data",
-  // native FormData since Node 18
   "formdata-polyfill",
-  // native FormData since Node 18
   "web-streams-polyfill",
-  // native ReadableStream since Node 18
   "whatwg-url",
-  // native URL since Node 10
   "url-parse",
-  // native URL since Node 10
   "domexception",
-  // native DOMException since Node 17
   "abortcontroller-polyfill",
-  // native since Node 15
-  // Built-in Node modules shimmed for browser
   "querystring",
-  // URLSearchParams preferred, native in Node
   "string_decoder",
-  // native TextDecoder preferred
   "buffer",
-  // native Buffer in Node, Uint8Array in browser
   "events",
-  // native EventTarget preferred
   "path-browserify",
-  // browser shim
   "stream-browserify",
-  // browser shim
   "stream-http",
-  // browser shim
   "https-browserify",
-  // browser shim
   "os-browserify",
-  // browser shim
   "crypto-browserify",
-  // native Web Crypto API
   "assert",
-  // native assert in Node, console.assert in browser
   "util",
-  // Node native, deprecations in browser bundles
   "process",
-  // shimmed, usually unnecessary
   "timers-browserify",
-  // native timers
   "tty-browserify",
-  // rarely needed
   "vm-browserify",
-  // rarely needed
   "domain-browser",
-  // domains deprecated in Node
   "punycode",
-  // native in URL since Node 10
   "readable-stream",
-  // Node streams polyfill, usually unnecessary
-  // ES / language polyfills for ES2015+ (Node 18+ has all)
   "es6-promise",
-  // native Promise since Node 4
   "promise-polyfill",
-  // native Promise
   "es6-symbol",
-  // native Symbol since Node 4
   "es6-map",
-  // native Map since Node 4
   "es6-set",
-  // native Set since Node 4
   "es6-weak-map",
-  // native WeakMap since Node 4
   "es6-iterator",
-  // native iterators
   "object-assign",
-  // native Object.assign since Node 4
   "object.assign",
-  // same
   "array.prototype.find",
-  // native since ES2015
   "array.prototype.findindex",
-  // native since ES2015
   "array.prototype.flat",
-  // native since Node 11
   "array.prototype.flatmap",
-  // native since Node 11
   "array-includes",
-  // native Array.includes since Node 6
   "string.prototype.startswith",
-  // native since ES2015
   "string.prototype.endswith",
-  // native since ES2015
   "string.prototype.includes",
-  // native since ES2015
   "string.prototype.padstart",
-  // native since Node 8
   "string.prototype.padend",
-  // native since Node 8
   "string.prototype.matchall",
-  // native since Node 12
   "string.prototype.replaceall",
-  // native since Node 15
   "string.prototype.trimstart",
-  // native since Node 10
   "string.prototype.trimend",
-  // native since Node 10
   "string.prototype.at",
-  // native since Node 16.6
   "object.entries",
-  // native since Node 7
   "object.values",
-  // native since Node 7
   "object.fromentries",
-  // native since Node 12
   "globalthis",
-  // native globalThis since Node 12
   "symbol-observable",
-  // TC39 withdrawn
   "setimmediate",
-  // Node-only, setTimeout(fn, 0) preferred
   "regenerator-runtime",
-  // async/await native since Node 8
   "@babel/polyfill",
-  // deprecated, use core-js directly
   "whatwg-encoding",
-  // native TextEncoder/TextDecoder
   "text-encoding",
-  // native TextEncoder/TextDecoder since Node 11
   "encoding",
-  // native TextEncoder/TextDecoder
   "unorm",
-  // native String.normalize since Node 0.12
   "number.isnan",
-  // native Number.isNaN since Node 0.12
   "is-nan",
-  // native Number.isNaN
   "has-symbols",
-  // native Symbol detection
   "has",
-  // native Object.hasOwn since Node 16.9
   "hasown",
-  // shim for Object.hasOwn
   "safe-buffer",
-  // Buffer.from available since Node 5.10
   "safer-buffer"
-  // Buffer.from available since Node 5.10
 ]);
-function scanBreakingChangeExposure(projects) {
+var BREAKING_SIGNAL_PHRASES = [
+  "BREAKING",
+  "Breaking Change",
+  "Removed",
+  "Deprecated",
+  "Migration",
+  "Rename",
+  "Drop support"
+];
+var PACKAGE_PLAYBOOKS = {
+  vue: {
+    impactedFeatures: ["Options API-heavy components", "Deprecated hooks", "Template filters", "$listeners / $attrs merge behavior", "Mixin-heavy architecture"],
+    usagePatterns: [/\bexport\s+default\s*\{/, /\bmixins\s*:/, /\bfilters\s*:/, /\$listeners\b/, /beforeDestroy\b/, /destroyed\b/],
+    automation: "manual"
+  },
+  "react-router-dom": {
+    impactedFeatures: ["Switch/Route v5 patterns", "history prop mutation flows", "withRouter HOC usage"],
+    usagePatterns: [/\bSwitch\b/, /\bwithRouter\b/, /\bhistory\./, /<Route\s+component=/],
+    automation: "deterministic-recipe"
+  },
+  eslint: {
+    impactedFeatures: ["Flat config migration", ".eslintrc plugin resolution", "legacy parser/plugin options"],
+    usagePatterns: [/\.eslintrc/, /eslintConfig/, /module\.exports\s*=\s*\[/, /extends\s*:/],
+    automation: "deterministic-recipe"
+  },
+  typescript: {
+    impactedFeatures: ["Stricter type checks", "tsconfig option removals", "moduleResolution defaults changes"],
+    usagePatterns: [/tsconfig\.json/, /strictNullChecks/, /noImplicitAny/, /moduleResolution/],
+    automation: "manual"
+  },
+  "@angular/core": {
+    impactedFeatures: ["NgModule bootstrap assumptions", "Standalone component migration", "Deprecated lifecycle signatures"],
+    usagePatterns: [/@NgModule\b/, /ngOnInit\(/, /providers\s*:/],
+    automation: "codemod-available",
+    codemod: "ng update"
+  }
+};
+function detectDecision(majorItems, manualHotspots, codemodItems) {
+  if (majorItems === 0) return "do-nothing";
+  if (codemodItems > 0 && manualHotspots === 0) return "codemod-available";
+  if (manualHotspots > 0) return "manual-hotspots";
+  if (majorItems <= 2) return "upgrade-safely-now";
+  return "plan-major-upgrade";
+}
+function normalizeMajor(version) {
+  if (!version) return null;
+  const parsed = semver9.coerce(version);
+  return parsed?.major ?? null;
+}
+function resolveCurrentVersion(dep) {
+  if (dep.resolvedVersion && semver9.valid(semver9.coerce(dep.resolvedVersion))) return semver9.coerce(dep.resolvedVersion)?.version ?? null;
+  const min = semver9.minVersion(dep.currentSpec);
+  return min?.version ?? null;
+}
+function listInterimMajorTargets(current, target) {
+  if (target <= current + 1) return [];
+  const out = [];
+  for (let m = current + 1; m < target; m++) out.push(`${m}.x`);
+  return out;
+}
+async function buildProjectUsageIndex(project, rootDir, fileCache, candidatePackages) {
+  const index = /* @__PURE__ */ new Map();
+  for (const pkg2 of candidatePackages) index.set(pkg2, { importSites: 0, filesTouched: 0, patternHits: 0 });
+  const entries = await fileCache.walkDir(rootDir);
+  const projectPrefix = project.path.replace(/\\/g, "/").replace(/^\.\//, "");
+  const projectEntries = entries.filter((e) => e.isFile && e.relPath.replace(/\\/g, "/").startsWith(projectPrefix));
+  const codeEntries = projectEntries.filter((e) => /\.(ts|tsx|js|jsx|vue|mjs|cjs|json)$/.test(e.name));
+  for (const file of codeEntries) {
+    let content = "";
+    try {
+      content = await fileCache.readTextFile(path16.join(rootDir, file.relPath));
+    } catch {
+      continue;
+    }
+    for (const pkg2 of candidatePackages) {
+      const current = index.get(pkg2);
+      if (!current) continue;
+      const escaped = pkg2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const importRegex = new RegExp(`(?:from\\s+['"]${escaped}['"]|require\\(\\s*['"]${escaped}['"]\\s*\\)|import\\(\\s*['"]${escaped}['"]\\s*\\))`, "g");
+      const importMatches = content.match(importRegex) ?? [];
+      if (importMatches.length > 0) {
+        current.importSites += importMatches.length;
+        current.filesTouched += 1;
+      }
+      const playbook = PACKAGE_PLAYBOOKS[pkg2];
+      if (playbook) {
+        for (const pattern of playbook.usagePatterns) {
+          const matches = content.match(new RegExp(pattern.source, "g"));
+          if (matches) current.patternHits += matches.length;
+        }
+      }
+    }
+  }
+  return index;
+}
+async function scanBreakingChangeExposure(projects, rootDir, fileCache) {
   const deprecated = /* @__PURE__ */ new Set();
   const legacyPolyfills = /* @__PURE__ */ new Set();
   let peerConflictsDetected = false;
-  const allDeps = /* @__PURE__ */ new Set();
   for (const project of projects) {
     for (const dep of project.dependencies) {
-      allDeps.add(dep.package);
-      if (DEPRECATED_PACKAGES2.has(dep.package)) {
-        deprecated.add(dep.package);
-      }
-      if (LEGACY_POLYFILLS.has(dep.package)) {
-        legacyPolyfills.add(dep.package);
-      }
-      if (dep.section === "peerDependencies" && dep.majorsBehind !== null && dep.majorsBehind >= 2) {
-        peerConflictsDetected = true;
-      }
+      if (DEPRECATED_PACKAGES2.has(dep.package)) deprecated.add(dep.package);
+      if (LEGACY_POLYFILLS.has(dep.package)) legacyPolyfills.add(dep.package);
+      if (dep.section === "peerDependencies" && dep.majorsBehind !== null && dep.majorsBehind >= 2) peerConflictsDetected = true;
     }
   }
   let score = 0;
@@ -5253,17 +5210,94 @@ function scanBreakingChangeExposure(projects) {
   score += Math.min(legacyPolyfills.size * 5, 30);
   score += peerConflictsDetected ? 20 : 0;
   score = Math.min(score, 100);
+  const projectIntelligence = [];
+  const solutionRollup = /* @__PURE__ */ new Map();
+  let majorPackageCount = 0;
+  let manualHotspots = 0;
+  let codemodCandidates = 0;
+  for (const project of projects) {
+    const majorDeps = project.dependencies.filter((d) => (d.majorsBehind ?? 0) >= 1 && d.latestStable);
+    if (majorDeps.length === 0) {
+      projectIntelligence.push({
+        project: project.name,
+        projectPath: project.path,
+        packages: [],
+        recommendation: "do-nothing"
+      });
+      continue;
+    }
+    const usageIndex = await buildProjectUsageIndex(project, rootDir, fileCache, majorDeps.map((d) => d.package));
+    const packages = majorDeps.map((dep) => {
+      const currentVersion = resolveCurrentVersion(dep);
+      const targetVersion = dep.latestStable;
+      const currentMajor = normalizeMajor(currentVersion);
+      const targetMajor = normalizeMajor(targetVersion);
+      const interimMajors = currentMajor !== null && targetMajor !== null ? listInterimMajorTargets(currentMajor, targetMajor) : [];
+      const usage = usageIndex.get(dep.package) ?? { importSites: 0, filesTouched: 0, patternHits: 0 };
+      const fileCount = Math.max(1, project.fileCount ?? 1);
+      const touchedPercent = Math.min(100, Math.round((usage.filesTouched + usage.patternHits) / fileCount * 100));
+      const playbook = PACKAGE_PLAYBOOKS[dep.package];
+      const impactedFeatures = playbook?.impactedFeatures ?? ["Public API usage patterns", "Configuration surface", "Runtime compatibility expectations"];
+      const automatable = playbook?.automation ?? (usage.patternHits > 0 ? "manual" : "deterministic-recipe");
+      majorPackageCount++;
+      if (automatable === "manual") manualHotspots++;
+      if (automatable === "codemod-available") codemodCandidates++;
+      return {
+        package: dep.package,
+        currentVersion,
+        targetVersion,
+        majorJumpCount: dep.majorsBehind ?? 0,
+        interimMajors,
+        releaseNoteSources: ["GitHub Releases", "Repository tags", "CHANGELOG.md"],
+        parsedSignals: [...BREAKING_SIGNAL_PHRASES],
+        impactedFeatures,
+        usage: {
+          importSites: usage.importSites,
+          filesTouchedEstimate: usage.filesTouched,
+          functionsTouchedEstimate: usage.patternHits,
+          touchedPercent
+        },
+        automatable,
+        codemod: playbook?.codemod
+      };
+    });
+    const rec = detectDecision(packages.length, packages.filter((p) => p.automatable === "manual").length, packages.filter((p) => p.automatable === "codemod-available").length);
+    projectIntelligence.push({
+      project: project.name,
+      projectPath: project.path,
+      packages,
+      recommendation: rec
+    });
+    if (project.solutionId) {
+      const key = project.solutionId;
+      const existing = solutionRollup.get(key) ?? {
+        solutionId: key,
+        solutionName: project.solutionName ?? key,
+        projectCount: 0,
+        majorPackages: 0,
+        recommendation: "do-nothing"
+      };
+      existing.projectCount += 1;
+      existing.majorPackages += packages.length;
+      existing.recommendation = detectDecision(existing.majorPackages, manualHotspots, codemodCandidates);
+      solutionRollup.set(key, existing);
+    }
+  }
+  const overallRecommendation = detectDecision(majorPackageCount, manualHotspots, codemodCandidates);
   return {
     deprecatedPackages: [...deprecated].sort(),
     legacyPolyfills: [...legacyPolyfills].sort(),
     peerConflictsDetected,
-    exposureScore: score
+    exposureScore: score,
+    projectIntelligence,
+    solutionIntelligence: [...solutionRollup.values()],
+    overallRecommendation
   };
 }
 
 // src/scanners/file-hotspots.ts
 import * as fs4 from "fs/promises";
-import * as path16 from "path";
+import * as path17 from "path";
 var SKIP_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
   ".git",
@@ -5308,9 +5342,9 @@ async function scanFileHotspots(rootDir, cache) {
     const entries = await cache.walkDir(rootDir);
     for (const entry of entries) {
       if (!entry.isFile) continue;
-      const ext = path16.extname(entry.name).toLowerCase();
+      const ext = path17.extname(entry.name).toLowerCase();
       if (SKIP_EXTENSIONS.has(ext)) continue;
-      const depth = entry.relPath.split(path16.sep).length - 1;
+      const depth = entry.relPath.split(path17.sep).length - 1;
       if (depth > maxDepth) maxDepth = depth;
       extensionCounts[ext] = (extensionCounts[ext] ?? 0) + 1;
       try {
@@ -5339,15 +5373,15 @@ async function scanFileHotspots(rootDir, cache) {
       for (const e of entries) {
         if (e.isDirectory) {
           if (SKIP_DIRS.has(e.name)) continue;
-          await walk(path16.join(dir, e.name), depth + 1);
+          await walk(path17.join(dir, e.name), depth + 1);
         } else if (e.isFile) {
-          const ext = path16.extname(e.name).toLowerCase();
+          const ext = path17.extname(e.name).toLowerCase();
           if (SKIP_EXTENSIONS.has(ext)) continue;
           extensionCounts[ext] = (extensionCounts[ext] ?? 0) + 1;
           try {
-            const stat3 = await fs4.stat(path16.join(dir, e.name));
+            const stat3 = await fs4.stat(path17.join(dir, e.name));
             allFiles.push({
-              path: path16.relative(rootDir, path16.join(dir, e.name)),
+              path: path17.relative(rootDir, path17.join(dir, e.name)),
               bytes: stat3.size
             });
           } catch {
@@ -5370,7 +5404,7 @@ async function scanFileHotspots(rootDir, cache) {
 }
 
 // src/scanners/security-posture.ts
-import * as path17 from "path";
+import * as path18 from "path";
 var LOCKFILES = {
   "pnpm-lock.yaml": "pnpm",
   "package-lock.json": "npm",
@@ -5391,14 +5425,14 @@ async function scanSecurityPosture(rootDir, cache) {
   const _readTextFile = cache ? (p) => cache.readTextFile(p) : readTextFile;
   const foundLockfiles = [];
   for (const [file, type] of Object.entries(LOCKFILES)) {
-    if (await _pathExists(path17.join(rootDir, file))) {
+    if (await _pathExists(path18.join(rootDir, file))) {
       foundLockfiles.push(type);
     }
   }
   result.lockfilePresent = foundLockfiles.length > 0;
   result.multipleLockfileTypes = foundLockfiles.length > 1;
   result.lockfileTypes = foundLockfiles.sort();
-  const gitignorePath = path17.join(rootDir, ".gitignore");
+  const gitignorePath = path18.join(rootDir, ".gitignore");
   if (await _pathExists(gitignorePath)) {
     try {
       const content = await _readTextFile(gitignorePath);
@@ -5413,7 +5447,7 @@ async function scanSecurityPosture(rootDir, cache) {
     }
   }
   for (const envFile of [".env", ".env.local", ".env.development", ".env.production"]) {
-    if (await _pathExists(path17.join(rootDir, envFile))) {
+    if (await _pathExists(path18.join(rootDir, envFile))) {
       if (!result.gitignoreCoversEnv) {
         result.envFilesTracked = true;
         break;
@@ -5425,7 +5459,7 @@ async function scanSecurityPosture(rootDir, cache) {
 
 // src/scanners/security-scanners.ts
 import { spawn as spawn3 } from "child_process";
-import * as path18 from "path";
+import * as path19 from "path";
 var TOOL_MATRIX = [
   { key: "semgrep", category: "sast", command: "semgrep", versionArgs: ["--version"], minRecommendedVersion: "1.75.0" },
   { key: "gitleaks", category: "secrets", command: "gitleaks", versionArgs: ["version"], minRecommendedVersion: "8.20.0" },
@@ -5520,7 +5554,7 @@ async function detectSecretHeuristics(rootDir, cache) {
   const findings = [];
   for (const entry of entries) {
     if (!entry.isFile) continue;
-    const ext = path18.extname(entry.name).toLowerCase();
+    const ext = path19.extname(entry.name).toLowerCase();
     if (ext && [".png", ".jpg", ".jpeg", ".gif", ".zip", ".pdf"].includes(ext)) continue;
     const content = await cache.readTextFile(entry.absPath);
     if (!content || content.length > 3e5) continue;
@@ -5543,9 +5577,9 @@ async function scanSecurityScanners(rootDir, cache, runner = defaultRunner) {
   const [semgrep, gitleaks, trufflehog] = await Promise.all(TOOL_MATRIX.map((tool) => assessTool(tool, runner)));
   const heuristicFindings = await detectSecretHeuristics(rootDir, cache);
   const configFiles = {
-    semgrep: await cache.pathExists(path18.join(rootDir, ".semgrep.yml")) || await cache.pathExists(path18.join(rootDir, ".semgrep.yaml")),
-    gitleaks: await cache.pathExists(path18.join(rootDir, ".gitleaks.toml")),
-    trufflehog: await cache.pathExists(path18.join(rootDir, ".trufflehog.yml")) || await cache.pathExists(path18.join(rootDir, ".trufflehog.yaml"))
+    semgrep: await cache.pathExists(path19.join(rootDir, ".semgrep.yml")) || await cache.pathExists(path19.join(rootDir, ".semgrep.yaml")),
+    gitleaks: await cache.pathExists(path19.join(rootDir, ".gitleaks.toml")),
+    trufflehog: await cache.pathExists(path19.join(rootDir, ".trufflehog.yml")) || await cache.pathExists(path19.join(rootDir, ".trufflehog.yaml"))
   };
   return {
     semgrep,
@@ -5970,7 +6004,7 @@ function scanServiceDependencies(projects) {
 }
 
 // src/scanners/architecture.ts
-import * as path19 from "path";
+import * as path20 from "path";
 import * as fs5 from "fs/promises";
 var ARCHETYPE_SIGNALS = [
   // Meta-frameworks (highest priority — they imply routing patterns)
@@ -6269,9 +6303,9 @@ async function walkSourceFiles(rootDir, cache) {
     const entries = await cache.walkDir(rootDir);
     return entries.filter((e) => {
       if (!e.isFile) return false;
-      const name = path19.basename(e.absPath);
+      const name = path20.basename(e.absPath);
       if (name.startsWith(".") && name !== ".") return false;
-      const ext = path19.extname(name);
+      const ext = path20.extname(name);
       return SOURCE_EXTENSIONS.has(ext);
     }).map((e) => e.relPath);
   }
@@ -6285,15 +6319,15 @@ async function walkSourceFiles(rootDir, cache) {
     }
     for (const entry of entries) {
       if (entry.name.startsWith(".") && entry.name !== ".") continue;
-      const fullPath = path19.join(dir, entry.name);
+      const fullPath = path20.join(dir, entry.name);
       if (entry.isDirectory()) {
         if (!IGNORE_DIRS.has(entry.name)) {
           await walk(fullPath);
         }
       } else if (entry.isFile()) {
-        const ext = path19.extname(entry.name);
+        const ext = path20.extname(entry.name);
         if (SOURCE_EXTENSIONS.has(ext)) {
-          files.push(path19.relative(rootDir, fullPath));
+          files.push(path20.relative(rootDir, fullPath));
         }
       }
     }
@@ -6317,7 +6351,7 @@ function classifyFile(filePath, archetype) {
     }
   }
   if (!bestMatch || bestMatch.confidence < 0.7) {
-    const baseName = path19.basename(filePath, path19.extname(filePath));
+    const baseName = path20.basename(filePath, path20.extname(filePath));
     const cleanBase = baseName.replace(/\.(test|spec)$/, "");
     for (const rule of SUFFIX_RULES) {
       if (cleanBase.endsWith(rule.suffix)) {
@@ -6426,7 +6460,7 @@ function generateLayerFlowMermaid(layers) {
   return lines.join("\n");
 }
 async function buildProjectArchitectureMermaid(rootDir, project, archetype, cache) {
-  const projectRoot = path19.resolve(rootDir, project.path || ".");
+  const projectRoot = path20.resolve(rootDir, project.path || ".");
   const allFiles = await walkSourceFiles(projectRoot, cache);
   const layerSet = /* @__PURE__ */ new Set();
   for (const rel of allFiles) {
@@ -6552,7 +6586,7 @@ async function scanArchitecture(rootDir, projects, tooling, services, cache) {
 }
 
 // src/scanners/code-quality.ts
-import * as path20 from "path";
+import * as path21 from "path";
 import * as ts from "typescript";
 var SOURCE_EXTENSIONS2 = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 var DEFAULT_RESULT = {
@@ -6583,9 +6617,9 @@ async function scanCodeQuality(rootDir, cache) {
       continue;
     }
     if (!raw.trim()) continue;
-    const rel = normalizeModuleId(path20.relative(rootDir, filePath));
+    const rel = normalizeModuleId(path21.relative(rootDir, filePath));
     const source = ts.createSourceFile(filePath, raw, ts.ScriptTarget.Latest, true);
-    const imports = collectLocalImports(source, path20.dirname(filePath), rootDir);
+    const imports = collectLocalImports(source, path21.dirname(filePath), rootDir);
     depGraph.set(rel, imports);
     const fileMetrics = computeFileMetrics(source, raw);
     totalFunctions += fileMetrics.functionsAnalyzed;
@@ -6619,9 +6653,9 @@ async function scanCodeQuality(rootDir, cache) {
 async function findSourceFiles(rootDir, cache) {
   if (cache) {
     const entries = await cache.walkDir(rootDir);
-    return entries.filter((entry) => entry.isFile && SOURCE_EXTENSIONS2.has(path20.extname(entry.name).toLowerCase())).map((entry) => entry.absPath);
+    return entries.filter((entry) => entry.isFile && SOURCE_EXTENSIONS2.has(path21.extname(entry.name).toLowerCase())).map((entry) => entry.absPath);
   }
-  const files = await findFiles(rootDir, (name) => SOURCE_EXTENSIONS2.has(path20.extname(name).toLowerCase()));
+  const files = await findFiles(rootDir, (name) => SOURCE_EXTENSIONS2.has(path21.extname(name).toLowerCase()));
   return files;
 }
 function collectLocalImports(source, fileDir, rootDir) {
@@ -6642,8 +6676,8 @@ function collectLocalImports(source, fileDir, rootDir) {
 }
 function resolveLocalImport(specifier, fileDir, rootDir) {
   if (!specifier.startsWith(".")) return null;
-  const rawTarget = path20.resolve(fileDir, specifier);
-  const normalized = path20.relative(rootDir, rawTarget).replace(/\\/g, "/");
+  const rawTarget = path21.resolve(fileDir, specifier);
+  const normalized = path21.relative(rootDir, rawTarget).replace(/\\/g, "/");
   if (!normalized || normalized.startsWith("..")) return null;
   return normalizeModuleId(normalized);
 }
@@ -6785,7 +6819,7 @@ function visitEach(node, cb) {
 
 // src/scanners/owasp-category-mapping.ts
 import { spawn as spawn4 } from "child_process";
-import * as path21 from "path";
+import * as path22 from "path";
 var OWASP_CONFIG = "p/owasp-top-ten";
 var DEFAULT_EXTENSIONS = /* @__PURE__ */ new Set([
   ".js",
@@ -6864,7 +6898,7 @@ function parseFindings(results, rootDir) {
     const metadata = r.extra?.metadata;
     return {
       ruleId: r.check_id ?? "unknown",
-      path: r.path ? path21.relative(rootDir, path21.resolve(rootDir, r.path)) : "",
+      path: r.path ? path22.relative(rootDir, path22.resolve(rootDir, r.path)) : "",
       line: r.start?.line ?? 1,
       endLine: r.end?.line,
       message: r.extra?.message ?? "Potential security issue",
@@ -6924,7 +6958,7 @@ async function scanOwaspCategoryMapping(rootDir, cache, options = {}, runner = r
     }
   }
   const entries = cache ? await cache.walkDir(rootDir) : [];
-  const files = entries.filter((e) => e.isFile && DEFAULT_EXTENSIONS.has(path21.extname(e.name).toLowerCase()));
+  const files = entries.filter((e) => e.isFile && DEFAULT_EXTENSIONS.has(path22.extname(e.name).toLowerCase()));
   const findings = [];
   const errors = [];
   let scannedFiles = 0;
@@ -7372,17 +7406,17 @@ async function discoverSolutions(rootDir, fileCache) {
   for (const solutionFile of solutionFiles) {
     try {
       const content = await fileCache.readTextFile(solutionFile);
-      const dir = path22.dirname(solutionFile);
-      const relSolutionPath = path22.relative(rootDir, solutionFile).replace(/\\/g, "/");
+      const dir = path23.dirname(solutionFile);
+      const relSolutionPath = path23.relative(rootDir, solutionFile).replace(/\\/g, "/");
       const projectPaths = /* @__PURE__ */ new Set();
       const projectRegex = /Project\("[^"]*"\)\s*=\s*"([^"]*)",\s*"([^"]+\.csproj)"/g;
       let match;
       while ((match = projectRegex.exec(content)) !== null) {
         const projectRelative = match[2];
-        const absProjectPath = path22.resolve(dir, projectRelative.replace(/\\/g, "/"));
-        projectPaths.add(path22.relative(rootDir, absProjectPath).replace(/\\/g, "/"));
+        const absProjectPath = path23.resolve(dir, projectRelative.replace(/\\/g, "/"));
+        projectPaths.add(path23.relative(rootDir, absProjectPath).replace(/\\/g, "/"));
       }
-      const solutionName = path22.basename(solutionFile, path22.extname(solutionFile));
+      const solutionName = path23.basename(solutionFile, path23.extname(solutionFile));
       parsed.push({
         path: relSolutionPath,
         name: solutionName,
@@ -7575,7 +7609,7 @@ async function runScan(rootDir, opts) {
     project.drift = computeDriftScore([project]);
     project.projectId = computeProjectId(project.path, project.name, workspaceId);
   }
-  const solutionsManifestPath = path22.join(rootDir, ".vibgrate", "solutions.json");
+  const solutionsManifestPath = path23.join(rootDir, ".vibgrate", "solutions.json");
   const persistedSolutionIds = /* @__PURE__ */ new Map();
   if (await pathExists(solutionsManifestPath)) {
     try {
@@ -7650,8 +7684,8 @@ async function runScan(rootDir, opts) {
     if (scannerPolicy.breakingChangeExposure && scanners?.breakingChangeExposure?.enabled !== false) {
       progress.startStep("breaking");
       scannerTasks.push(
-        Promise.resolve().then(() => {
-          extended.breakingChangeExposure = scanBreakingChangeExposure(allProjects);
+        Promise.resolve().then(async () => {
+          extended.breakingChangeExposure = await scanBreakingChangeExposure(allProjects, rootDir, fileCache);
           const bc = extended.breakingChangeExposure;
           const bcTotal = bc.deprecatedPackages.length + bc.legacyPolyfills.length;
           progress.completeStep(
@@ -7885,7 +7919,7 @@ async function runScan(rootDir, opts) {
     schemaVersion: "1.0",
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     vibgrateVersion: VERSION,
-    rootPath: path22.basename(rootDir),
+    rootPath: path23.basename(rootDir),
     ...vcs.type !== "unknown" ? { vcs } : {},
     repository,
     projects: allProjects,
@@ -7899,7 +7933,7 @@ async function runScan(rootDir, opts) {
     relationshipDiagram
   };
   if (opts.baseline) {
-    const baselinePath = path22.resolve(opts.baseline);
+    const baselinePath = path23.resolve(opts.baseline);
     if (await pathExists(baselinePath)) {
       try {
         const baseline = await readJsonFile(baselinePath);
@@ -7911,10 +7945,10 @@ async function runScan(rootDir, opts) {
     }
   }
   if (!opts.noLocalArtifacts && !maxPrivacyMode) {
-    const vibgrateDir = path22.join(rootDir, ".vibgrate");
+    const vibgrateDir = path23.join(rootDir, ".vibgrate");
     await ensureDir(vibgrateDir);
-    await writeJsonFile(path22.join(vibgrateDir, "scan_result.json"), artifact);
-    await writeJsonFile(path22.join(vibgrateDir, "solutions.json"), {
+    await writeJsonFile(path23.join(vibgrateDir, "scan_result.json"), artifact);
+    await writeJsonFile(path23.join(vibgrateDir, "solutions.json"), {
       scannedAt: artifact.timestamp,
       solutions: solutions.map((solution) => ({
         solutionId: solution.solutionId,
@@ -7935,10 +7969,10 @@ async function runScan(rootDir, opts) {
   if (!opts.noLocalArtifacts && !maxPrivacyMode) {
     for (const project of allProjects) {
       if (project.drift && project.path) {
-        const projectDir = path22.resolve(rootDir, project.path);
-        const projectVibgrateDir = path22.join(projectDir, ".vibgrate");
+        const projectDir = path23.resolve(rootDir, project.path);
+        const projectVibgrateDir = path23.join(projectDir, ".vibgrate");
         await ensureDir(projectVibgrateDir);
-        await writeJsonFile(path22.join(projectVibgrateDir, "project_score.json"), {
+        await writeJsonFile(path23.join(projectVibgrateDir, "project_score.json"), {
           projectId: project.projectId,
           name: project.name,
           type: project.type,
@@ -7958,7 +7992,7 @@ async function runScan(rootDir, opts) {
   if (opts.format === "json") {
     const jsonStr = JSON.stringify(artifact, null, 2);
     if (opts.out) {
-      await writeTextFile(path22.resolve(opts.out), jsonStr);
+      await writeTextFile(path23.resolve(opts.out), jsonStr);
       console.log(chalk6.green("\u2714") + ` JSON written to ${opts.out}`);
     } else {
       console.log(jsonStr);
@@ -7967,7 +8001,7 @@ async function runScan(rootDir, opts) {
     const sarif = formatSarif(artifact);
     const sarifStr = JSON.stringify(sarif, null, 2);
     if (opts.out) {
-      await writeTextFile(path22.resolve(opts.out), sarifStr);
+      await writeTextFile(path23.resolve(opts.out), sarifStr);
       console.log(chalk6.green("\u2714") + ` SARIF written to ${opts.out}`);
     } else {
       console.log(sarifStr);
@@ -7976,20 +8010,20 @@ async function runScan(rootDir, opts) {
     const markdown = formatMarkdown(artifact);
     console.log(markdown);
     if (opts.out) {
-      await writeTextFile(path22.resolve(opts.out), markdown);
+      await writeTextFile(path23.resolve(opts.out), markdown);
     }
   } else {
     const text = formatText(artifact);
     console.log(text);
     if (opts.out) {
-      await writeTextFile(path22.resolve(opts.out), text);
+      await writeTextFile(path23.resolve(opts.out), text);
     }
   }
   return artifact;
 }
 async function buildRepositoryInfo(rootDir, remoteUrl, ciSystems) {
-  const packageJsonPath = path22.join(rootDir, "package.json");
-  let name = path22.basename(rootDir);
+  const packageJsonPath = path23.join(rootDir, "package.json");
+  let name = path23.basename(rootDir);
   let version;
   if (await pathExists(packageJsonPath)) {
     try {
@@ -8081,7 +8115,7 @@ function parseNonNegativeNumber(value, label) {
   return parsed;
 }
 var scanCommand = new Command3("scan").description("Scan a project for upgrade drift").argument("[path]", "Path to scan", ".").option("--out <file>", "Output file path").option("--format <format>", "Output format (text|json|sarif|md)", "text").option("--fail-on <level>", "Fail on warn or error").option("--baseline <file>", "Compare against baseline").option("--changed-only", "Only scan changed files").option("--concurrency <n>", "Max concurrent npm calls", "8").option("--push", "Auto-push results to Vibgrate API after scan").option("--dsn <dsn>", "DSN token for push (or use VIBGRATE_DSN env)").option("--region <region>", "Override data residency region for push (us, eu)").option("--strict", "Fail on push errors").option("--install-tools", "Auto-install missing security scanners via Homebrew").option("--ui-purpose", "Enable optional UI purpose evidence extraction (slower)").option("--no-local-artifacts", "Do not write .vibgrate JSON artifacts to disk").option("--max-privacy", "Enable strongest privacy mode (minimal scanners, no local artifacts)").option("--offline", "Run without network calls; do not upload results").option("--package-manifest <file>", "Use local package-version manifest JSON/ZIP (for offline mode)").option("--drift-budget <score>", "Fail if drift score is above budget (0-100)").option("--drift-worsening <percent>", "Fail if drift worsens by more than % since baseline").action(async (targetPath, opts) => {
-  const rootDir = path22.resolve(targetPath);
+  const rootDir = path23.resolve(targetPath);
   if (!await pathExists(rootDir)) {
     console.error(chalk6.red(`Path does not exist: ${rootDir}`));
     process.exit(1);

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   baselineCommand
-} from "./chunk-TCYJSLL2.js";
+} from "./chunk-CQMW6PVB.js";
 import {
   VERSION,
   dsnCommand,
@@ -10,7 +10,7 @@ import {
   pushCommand,
   scanCommand,
   writeDefaultConfig
-} from "./chunk-TYAGUEXG.js";
+} from "./chunk-PQEUNAVK.js";
 import {
   ensureDir,
   pathExists,
@@ -19,8 +19,8 @@ import {
 } from "./chunk-RNVZIZNL.js";
 
 // src/cli.ts
-import { Command as Command5 } from "commander";
-import chalk5 from "chalk";
+import { Command as Command6 } from "commander";
+import chalk6 from "chalk";
 
 // src/commands/init.ts
 import * as path from "path";
@@ -39,7 +39,7 @@ var initCommand = new Command("init").description("Initialize vibgrate in a proj
     console.log(chalk.green("\u2714") + ` Created ${chalk.bold("vibgrate.config.ts")}`);
   }
   if (opts.baseline) {
-    const { runBaseline } = await import("./baseline-FRBISJ66.js");
+    const { runBaseline } = await import("./baseline-5ZOILNXB.js");
     await runBaseline(rootDir);
   }
   console.log("");
@@ -409,9 +409,239 @@ var deltaCommand = new Command4("delta").description("Show SBOM delta between tw
 });
 var sbomCommand = new Command4("sbom").description("SBOM export and delta reports for dependency drift tracking").addCommand(exportCommand).addCommand(deltaCommand);
 
+// src/commands/help.ts
+import { Command as Command5 } from "commander";
+import chalk5 from "chalk";
+var HELP_URL = "https://vibgrate.com/help";
+function printFooter() {
+  console.log("");
+  console.log(chalk5.dim(`See ${HELP_URL} for more guidance`));
+}
+var detailedHelp = {
+  scan: () => {
+    console.log("");
+    console.log(chalk5.bold.underline("vibgrate scan") + chalk5.dim(" \u2014 Scan a project for upgrade drift"));
+    console.log("");
+    console.log(chalk5.bold("Usage:"));
+    console.log("  vibgrate scan [path] [options]");
+    console.log("");
+    console.log(chalk5.bold("Arguments:"));
+    console.log(`  ${chalk5.cyan("[path]")}                       Path to scan (default: current directory)`);
+    console.log("");
+    console.log(chalk5.bold("Output options:"));
+    console.log(`  ${chalk5.cyan("--format <format>")}           Output format: ${chalk5.white("text")} | json | sarif | md  (default: text)`);
+    console.log(`  ${chalk5.cyan("--out <file>")}                Write output to a file instead of stdout`);
+    console.log("");
+    console.log(chalk5.bold("Baseline & gating:"));
+    console.log(`  ${chalk5.cyan("--baseline <file>")}           Compare results against a saved baseline`);
+    console.log(`  ${chalk5.cyan("--drift-budget <score>")}      Fail if drift score exceeds this value (0\u2013100)`);
+    console.log(`  ${chalk5.cyan("--drift-worsening <percent>")} Fail if drift worsens by more than % since baseline`);
+    console.log(`  ${chalk5.cyan("--fail-on <level>")}           Fail exit code on warn or error findings`);
+    console.log("");
+    console.log(chalk5.bold("Performance:"));
+    console.log(`  ${chalk5.cyan("--concurrency <n>")}           Max concurrent registry calls (default: 8)`);
+    console.log(`  ${chalk5.cyan("--changed-only")}              Only scan files changed since last git commit`);
+    console.log("");
+    console.log(chalk5.bold("Privacy & offline:"));
+    console.log(`  ${chalk5.cyan("--offline")}                   Run without any network calls; skip result upload`);
+    console.log(`  ${chalk5.cyan("--package-manifest <file>")}   Use a local package-version manifest (JSON or ZIP) for offline mode`);
+    console.log(`  ${chalk5.cyan("--no-local-artifacts")}        Do not write .vibgrate JSON artifacts to disk`);
+    console.log(`  ${chalk5.cyan("--max-privacy")}               Strongest privacy mode: minimal scanners + no local artifacts`);
+    console.log("");
+    console.log(chalk5.bold("Tooling:"));
+    console.log(`  ${chalk5.cyan("--install-tools")}             Auto-install missing security scanners via Homebrew`);
+    console.log(`  ${chalk5.cyan("--ui-purpose")}                Enable UI purpose evidence extraction (slower)`);
+    console.log("");
+    console.log(chalk5.bold("Uploading results:"));
+    console.log(`  ${chalk5.cyan("--push")}                      Auto-push results to Vibgrate API after scan`);
+    console.log(`  ${chalk5.cyan("--dsn <dsn>")}                 DSN token for push (or set VIBGRATE_DSN env var)`);
+    console.log(`  ${chalk5.cyan("--region <region>")}           Data residency region: us | eu  (default: us)`);
+    console.log(`  ${chalk5.cyan("--strict")}                    Fail if the upload to Vibgrate API fails`);
+    console.log("");
+    console.log(chalk5.bold("Examples:"));
+    console.log(`  ${chalk5.dim("# Scan the current directory and display a text report")}`);
+    console.log("  vibgrate scan .");
+    console.log("");
+    console.log(`  ${chalk5.dim("# Scan, fail if drift score > 40, and write SARIF for GitHub Actions")}`);
+    console.log("  vibgrate scan . --drift-budget 40 --format sarif --out drift.sarif");
+    console.log("");
+    console.log(`  ${chalk5.dim("# Scan and automatically upload results via a DSN")}`);
+    console.log("  vibgrate scan . --push --dsn $VIBGRATE_DSN");
+    console.log("");
+    console.log(`  ${chalk5.dim("# Offline scan using a pre-downloaded package manifest")}`);
+    console.log("  vibgrate scan . --offline --package-manifest ./manifest.zip");
+  },
+  init: () => {
+    console.log("");
+    console.log(chalk5.bold.underline("vibgrate init") + chalk5.dim(" \u2014 Initialise vibgrate in a project directory"));
+    console.log("");
+    console.log(chalk5.bold("Usage:"));
+    console.log("  vibgrate init [path] [options]");
+    console.log("");
+    console.log(chalk5.bold("Arguments:"));
+    console.log(`  ${chalk5.cyan("[path]")}          Directory to initialise (default: current directory)`);
+    console.log("");
+    console.log(chalk5.bold("Options:"));
+    console.log(`  ${chalk5.cyan("--baseline")}      Create an initial drift baseline after init`);
+    console.log(`  ${chalk5.cyan("--yes")}           Skip all confirmation prompts`);
+    console.log("");
+    console.log(chalk5.bold("What it does:"));
+    console.log("  \u2022 Creates a .vibgrate/ directory");
+    console.log("  \u2022 Writes a vibgrate.config.ts starter config");
+    console.log("  \u2022 Optionally runs an initial baseline scan (--baseline)");
+    console.log("");
+    console.log(chalk5.bold("Examples:"));
+    console.log("  vibgrate init");
+    console.log("  vibgrate init ./my-project --baseline");
+  },
+  baseline: () => {
+    console.log("");
+    console.log(chalk5.bold.underline("vibgrate baseline") + chalk5.dim(" \u2014 Save a drift baseline snapshot"));
+    console.log("");
+    console.log(chalk5.bold("Usage:"));
+    console.log("  vibgrate baseline [path]");
+    console.log("");
+    console.log(chalk5.bold("Arguments:"));
+    console.log(`  ${chalk5.cyan("[path]")}   Path to baseline (default: current directory)`);
+    console.log("");
+    console.log(chalk5.bold("What it does:"));
+    console.log("  Runs a full scan and saves the result as .vibgrate/baseline.json.");
+    console.log("  Future scans can compare against this file using --baseline.");
+    console.log("");
+    console.log(chalk5.bold("Examples:"));
+    console.log("  vibgrate baseline .");
+    console.log("  vibgrate scan . --baseline .vibgrate/baseline.json --drift-worsening 10");
+  },
+  report: () => {
+    console.log("");
+    console.log(chalk5.bold.underline("vibgrate report") + chalk5.dim(" \u2014 Generate a report from a saved scan artifact"));
+    console.log("");
+    console.log(chalk5.bold("Usage:"));
+    console.log("  vibgrate report [options]");
+    console.log("");
+    console.log(chalk5.bold("Options:"));
+    console.log(`  ${chalk5.cyan("--in <file>")}        Input artifact file (default: .vibgrate/scan_result.json)`);
+    console.log(`  ${chalk5.cyan("--format <format>")}  Output format: ${chalk5.white("text")} | md | json  (default: text)`);
+    console.log("");
+    console.log(chalk5.bold("Examples:"));
+    console.log("  vibgrate report");
+    console.log("  vibgrate report --format md > DRIFT-REPORT.md");
+    console.log("  vibgrate report --in ./ci/scan_result.json --format json");
+  },
+  sbom: () => {
+    console.log("");
+    console.log(chalk5.bold.underline("vibgrate sbom") + chalk5.dim(" \u2014 Export a Software Bill of Materials from a scan artifact"));
+    console.log("");
+    console.log(chalk5.bold("Usage:"));
+    console.log("  vibgrate sbom [options]");
+    console.log("");
+    console.log(chalk5.bold("Options:"));
+    console.log(`  ${chalk5.cyan("--in <file>")}        Input artifact (default: .vibgrate/scan_result.json)`);
+    console.log(`  ${chalk5.cyan("--format <format>")}  SBOM format: ${chalk5.white("cyclonedx")} | spdx  (default: cyclonedx)`);
+    console.log(`  ${chalk5.cyan("--out <file>")}       Write SBOM to file instead of stdout`);
+    console.log("");
+    console.log(chalk5.bold("Examples:"));
+    console.log("  vibgrate sbom --format cyclonedx --out sbom.json");
+    console.log("  vibgrate sbom --format spdx --out sbom.spdx.json");
+  },
+  push: () => {
+    console.log("");
+    console.log(chalk5.bold.underline("vibgrate push") + chalk5.dim(" \u2014 Upload a scan artifact to the Vibgrate API"));
+    console.log("");
+    console.log(chalk5.bold("Usage:"));
+    console.log("  vibgrate push [options]");
+    console.log("");
+    console.log(chalk5.bold("Options:"));
+    console.log(`  ${chalk5.cyan("--dsn <dsn>")}        DSN token (or set VIBGRATE_DSN env var)`);
+    console.log(`  ${chalk5.cyan("--file <file>")}      Artifact to upload (default: .vibgrate/scan_result.json)`);
+    console.log(`  ${chalk5.cyan("--region <region>")}  Override data residency region: us | eu`);
+    console.log(`  ${chalk5.cyan("--strict")}           Fail with non-zero exit code on upload error`);
+    console.log("");
+    console.log(chalk5.bold("Examples:"));
+    console.log("  vibgrate push --dsn $VIBGRATE_DSN");
+    console.log("  vibgrate push --file ./ci/scan_result.json --strict");
+  },
+  dsn: () => {
+    console.log("");
+    console.log(chalk5.bold.underline("vibgrate dsn") + chalk5.dim(" \u2014 Manage DSN tokens for API authentication"));
+    console.log("");
+    console.log(chalk5.bold("Subcommands:"));
+    console.log(`  ${chalk5.cyan("vibgrate dsn create")}   Generate a new DSN token`);
+    console.log("");
+    console.log(chalk5.bold("dsn create options:"));
+    console.log(`  ${chalk5.cyan("--workspace <id>")}   Workspace ID ${chalk5.red("(required)")}`);
+    console.log(`  ${chalk5.cyan("--region <region>")}  Data residency region: us | eu  (default: us)`);
+    console.log(`  ${chalk5.cyan("--ingest <url>")}     Override ingest API URL`);
+    console.log(`  ${chalk5.cyan("--write <path>")}     Write the DSN to a file (add to .gitignore!)`);
+    console.log("");
+    console.log(chalk5.bold("Examples:"));
+    console.log("  vibgrate dsn create --workspace abc123");
+    console.log("  vibgrate dsn create --workspace abc123 --region eu --write .vibgrate/.dsn");
+  },
+  update: () => {
+    console.log("");
+    console.log(chalk5.bold.underline("vibgrate update") + chalk5.dim(" \u2014 Update the vibgrate CLI to the latest version"));
+    console.log("");
+    console.log(chalk5.bold("Usage:"));
+    console.log("  vibgrate update [options]");
+    console.log("");
+    console.log(chalk5.bold("Options:"));
+    console.log(`  ${chalk5.cyan("--check")}         Check for a newer version without installing`);
+    console.log(`  ${chalk5.cyan("--pm <manager>")} Force a package manager: npm | pnpm | yarn | bun`);
+    console.log("");
+    console.log(chalk5.bold("Examples:"));
+    console.log("  vibgrate update");
+    console.log("  vibgrate update --check");
+    console.log("  vibgrate update --pm pnpm");
+  }
+};
+function printSummaryHelp() {
+  console.log("");
+  console.log(chalk5.bold("vibgrate") + chalk5.dim(" \u2014 Continuous Drift Intelligence"));
+  console.log("");
+  console.log(chalk5.bold("Usage:"));
+  console.log("  vibgrate <command> [options]");
+  console.log("  vibgrate help [command]     Show detailed help for a command");
+  console.log("");
+  console.log(chalk5.bold("Getting started:"));
+  console.log(`  ${chalk5.cyan("init")}       Initialise vibgrate in a project (creates config & .vibgrate/ dir)`);
+  console.log("");
+  console.log(chalk5.bold("Core scanning:"));
+  console.log(`  ${chalk5.cyan("scan")}       Scan a project for upgrade drift and generate a report`);
+  console.log(`  ${chalk5.cyan("baseline")}   Save a baseline snapshot to compare future scans against`);
+  console.log("");
+  console.log(chalk5.bold("Reporting & export:"));
+  console.log(`  ${chalk5.cyan("report")}     Re-generate a report from a previously saved scan artifact`);
+  console.log(`  ${chalk5.cyan("sbom")}       Export a Software Bill of Materials (CycloneDX or SPDX)`);
+  console.log("");
+  console.log(chalk5.bold("CI/CD integration:"));
+  console.log(`  ${chalk5.cyan("push")}       Upload a scan artifact to the Vibgrate API`);
+  console.log(`  ${chalk5.cyan("dsn")}        Create and manage DSN tokens for API authentication`);
+  console.log("");
+  console.log(chalk5.bold("Maintenance:"));
+  console.log(`  ${chalk5.cyan("update")}     Update the vibgrate CLI to the latest version`);
+  console.log("");
+  console.log(chalk5.dim("Run") + ` ${chalk5.cyan("vibgrate help <command>")} ` + chalk5.dim("for detailed options, e.g.") + ` ${chalk5.cyan("vibgrate help scan")}`);
+}
+var helpCommand = new Command5("help").description("Show help for vibgrate commands").argument("[command]", "Command to show detailed help for").helpOption(false).action((cmd) => {
+  const name = cmd?.toLowerCase().trim();
+  if (name && detailedHelp[name]) {
+    detailedHelp[name]();
+  } else if (name) {
+    console.log("");
+    console.log(chalk5.red(`Unknown command: ${name}`));
+    console.log(chalk5.dim(`Available commands: ${Object.keys(detailedHelp).join(", ")}`));
+    printSummaryHelp();
+  } else {
+    printSummaryHelp();
+  }
+  printFooter();
+});
+
 // src/cli.ts
-var program = new Command5();
-program.name("vibgrate").description("Continuous Drift Intelligence for Node & .NET").version(VERSION);
+var program = new Command6();
+program.name("vibgrate").description("Continuous Drift Intelligence").version(VERSION).addHelpText("after", "\nSee https://vibgrate.com/help for more guidance");
+program.addCommand(helpCommand);
 program.addCommand(initCommand);
 program.addCommand(scanCommand);
 program.addCommand(baselineCommand);
@@ -424,8 +654,8 @@ function notifyIfUpdateAvailable() {
   void checkForUpdate().then((update) => {
     if (!update?.updateAvailable) return;
     console.error("");
-    console.error(chalk5.yellow(`  Update available: ${update.current} \u2192 ${update.latest}`));
-    console.error(chalk5.dim('  Run "vibgrate update" to install the latest version.'));
+    console.error(chalk6.yellow(`  Update available: ${update.current} \u2192 ${update.latest}`));
+    console.error(chalk6.dim('  Run "vibgrate update" to install the latest version.'));
     console.error("");
   }).catch(() => {
   });

package/dist/index.d.ts

@@ -287,11 +287,46 @@ interface TsModernityResult {
     moduleType: 'esm' | 'cjs' | 'mixed' | null;
     exportsField: boolean;
 }
+type UpgradeRecommendation = 'do-nothing' | 'upgrade-safely-now' | 'plan-major-upgrade' | 'codemod-available' | 'manual-hotspots';
+interface BreakingChangePackageIntelligence {
+    package: string;
+    currentVersion: string | null;
+    targetVersion: string | null;
+    majorJumpCount: number;
+    interimMajors: string[];
+    releaseNoteSources: string[];
+    parsedSignals: string[];
+    impactedFeatures: string[];
+    usage: {
+        importSites: number;
+        filesTouchedEstimate: number;
+        functionsTouchedEstimate: number;
+        touchedPercent: number;
+    };
+    automatable: 'codemod-available' | 'deterministic-recipe' | 'manual';
+    codemod?: string;
+}
+interface BreakingChangeProjectIntelligence {
+    project: string;
+    projectPath: string;
+    packages: BreakingChangePackageIntelligence[];
+    recommendation: UpgradeRecommendation;
+}
+interface BreakingChangeSolutionIntelligence {
+    solutionId: string;
+    solutionName: string;
+    projectCount: number;
+    majorPackages: number;
+    recommendation: UpgradeRecommendation;
+}
 interface BreakingChangeExposureResult {
     deprecatedPackages: string[];
     legacyPolyfills: string[];
     peerConflictsDetected: boolean;
     exposureScore: number;
+    projectIntelligence: BreakingChangeProjectIntelligence[];
+    solutionIntelligence: BreakingChangeSolutionIntelligence[];
+    overallRecommendation: UpgradeRecommendation;
 }
 interface FileHotspot {
     path: string;

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   formatText,
   generateFindings,
   runScan
-} from "./chunk-TYAGUEXG.js";
+} from "./chunk-PQEUNAVK.js";
 import "./chunk-RNVZIZNL.js";
 export {
   computeDriftScore,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibgrate/cli",
-  "version": "1.0.52",
+  "version": "1.0.54",
   "description": "CLI for measuring upgrade drift across Node, .NET, Python & Java projects",
   "type": "module",
   "bin": {