@vibecheckai/cli 3.2.5 → 3.3.0

package/bin/runners/lib/upsell.js

@@ -1,510 +1,658 @@
-/**
- * Upsell Copy Module - Central copy generator for tier upgrades
- * 
- * This is the SINGLE SOURCE OF TRUTH for all upsell/upgrade messaging.
- * All upgrade nudges flow through these functions.
- * 
- * Rules:
- * - Blunt, confident, minimal tone
- * - No cringe language ("please upgrade")
- * - Every upsell includes a free path if one exists
- * - No web links besides https://vibecheckai.dev/pricing
- * 
- * @module bin/runners/lib/upsell
- */
-
-"use strict";
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// ANSI STYLING
-// ═══════════════════════════════════════════════════════════════════════════════
-const SUPPORTS_COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
-
-const c = SUPPORTS_COLOR ? {
-  reset: "\x1b[0m",
-  bold: "\x1b[1m",
-  dim: "\x1b[2m",
-  red: "\x1b[31m",
-  green: "\x1b[32m",
-  yellow: "\x1b[33m",
-  cyan: "\x1b[36m",
-  magenta: "\x1b[35m",
-  white: "\x1b[37m",
-  gray: "\x1b[90m",
-} : {
-  reset: "", bold: "", dim: "", red: "", green: "", yellow: "",
-  cyan: "", magenta: "", white: "", gray: "",
-};
-
-const sym = {
-  lock: "🔒",
-  arrow: "→",
-  warning: "⚠",
-  check: "✓",
-  cross: "✗",
-  star: "★",
-  rocket: "🚀",
-  badge: "🏆",
-  lightning: "⚡",
-};
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// TIER CONFIGURATION
-// ═══════════════════════════════════════════════════════════════════════════════
-const TIER_LABELS = {
-  free: "FREE",
-  starter: "STARTER",
-  pro: "PRO",
-  complete: "COMPLETE",
-};
-
-const TIER_COLORS = {
-  free: c.green,
-  starter: c.cyan,
-  pro: c.magenta,
-  complete: c.yellow,
-};
-
-const PRICING_URL = "https://vibecheckai.dev";
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// DENIAL COPY - Command-specific reasons and alternatives
-// ═══════════════════════════════════════════════════════════════════════════════
-const DENIAL_COPY = {
-  ship: {
-    feature: "release gate",
-    why: "Full ship analysis with runtime verification",
-    freeAlt: "vibecheck scan",
-    freeAltDesc: "static analysis",
-  },
-  prove: {
-    feature: "proof loop",
-    why: "Complete ctx → reality → ship → fix cycle",
-    freeAlt: "vibecheck ship",
-    freeAltDesc: "static verdict",
-  },
-  permissions: {
-    feature: "auth boundary / IDOR detection",
-    why: "Deep authorization matrix and IDOR analysis",
-    freeAlt: "vibecheck reality --verify-auth",
-    freeAltDesc: "basic auth boundary check",
-  },
-  "fix.apply_patches": {
-    feature: "patch generator / PR-ready diff",
-    why: "Apply LLM-generated patches automatically",
-    freeAlt: "vibecheck fix",
-    freeAltDesc: "plan-only mode",
-  },
-  fix: {
-    feature: "auto-fix with patches",
-    why: "Generate and apply fixes to your codebase",
-    freeAlt: "vibecheck fix --plan-only",
-    freeAltDesc: "view fix plan without applying",
-  },
-  badge: {
-    feature: "status artifact",
-    why: "Verified ship badge for README",
-    freeAlt: "vibecheck report",
-    freeAltDesc: "HTML/MD report",
-  },
-  gate: {
-    feature: "CI/CD gate",
-    why: "Block deploys on verification failures",
-    freeAlt: "vibecheck ship --ci",
-    freeAltDesc: "exit codes for scripts",
-  },
-  pr: {
-    feature: "PR comment generator",
-    why: "Auto-generated PR comments with findings",
-    freeAlt: "vibecheck report --format md",
-    freeAltDesc: "markdown report",
-  },
-  launch: {
-    feature: "pre-launch checklist",
-    why: "Guided launch readiness wizard",
-    freeAlt: "vibecheck ship",
-    freeAltDesc: "verdict check",
-  },
-  mcp: {
-    feature: "MCP server for AI IDEs",
-    why: "Real-time AI IDE integration",
-    freeAlt: "vibecheck ctx",
-    freeAltDesc: "generate truthpack manually",
-  },
-  share: {
-    feature: "share pack generator",
-    why: "Shareable proof bundle for PRs/docs",
-    freeAlt: "vibecheck report",
-    freeAltDesc: "local report",
-  },
-  "ai-test": {
-    feature: "autonomous test generation",
-    why: "AI-generated test coverage",
-    freeAlt: "vibecheck scan",
-    freeAltDesc: "static analysis",
-  },
-  replay: {
-    feature: "session replay",
-    why: "Record and replay user sessions",
-    freeAlt: "vibecheck reality",
-    freeAltDesc: "one-time runtime proof",
-  },
-  graph: {
-    feature: "reality proof graph",
-    why: "Visual dependency and proof graph",
-    freeAlt: "vibecheck ctx",
-    freeAltDesc: "truthpack",
-  },
-};
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// CAPS COPY - Downgrade mode descriptions
-// ═══════════════════════════════════════════════════════════════════════════════
-const CAPS_COPY = {
-  "reality.preview": {
-    short: "5 pages, no auth boundary",
-    full: "Preview mode: 5 pages max, 20 clicks, no auth boundary verification",
-    upgradeBenefit: "Unlimited pages + full auth boundary testing",
-  },
-  "fix.plan_only": {
-    short: "plan-only, no apply",
-    full: "Plan mode: generates fix missions but cannot apply patches",
-    upgradeBenefit: "Apply patches automatically with --apply",
-  },
-  "report.html_md": {
-    short: "HTML/MD only",
-    full: "Basic formats: HTML and Markdown reports only",
-    upgradeBenefit: "SARIF, CSV, and compliance pack exports",
-  },
-  "ship.static": {
-    short: "static-only",
-    full: "Static analysis only, no runtime verification",
-    upgradeBenefit: "Full runtime + static verification",
-  },
-  "mcp.help_only": {
-    short: "help and print-config only",
-    full: "MCP server limited to help and config commands",
-    upgradeBenefit: "Full MCP server with all tools",
-  },
-};
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// formatDenied() - Hard denial message
-// ═══════════════════════════════════════════════════════════════════════════════
-/**
- * Format a denial message for a command that requires a higher tier.
- * 
- * @param {string} cmd - The command that was denied
- * @param {object} opts - Options
- * @param {string} opts.currentTier - User's current tier
- * @param {string} opts.requiredTier - Required tier for the command
- * @param {string} [opts.reason] - Additional context
- * @param {string} [opts.suggestedNext] - Suggested next command
- * @param {string} [opts.freeAlternative] - Free alternative command
- * @returns {string} Formatted denial message
- */
-function formatDenied(cmd, opts = {}) {
-  const { currentTier = "free", requiredTier = "pro" } = opts;
-  
-  const copy = DENIAL_COPY[cmd] || {
-    feature: cmd,
-    why: `${cmd} command`,
-    freeAlt: null,
-    freeAltDesc: null,
-  };
-  
-  const reqColor = TIER_COLORS[requiredTier] || c.yellow;
-  const reqLabel = TIER_LABELS[requiredTier] || requiredTier.toUpperCase();
-  const curLabel = TIER_LABELS[currentTier] || currentTier.toUpperCase();
-  
-  let msg = `
-${c.red}${c.bold}${sym.lock} LOCKED${c.reset}
-
-  ${c.bold}What:${c.reset}      ${c.yellow}${cmd}${c.reset} ${c.dim}(${copy.feature})${c.reset}
-  ${c.bold}Why:${c.reset}       ${copy.why}
-  ${c.bold}Requires:${c.reset}  ${reqColor}${reqLabel}${c.reset} plan
-  ${c.bold}You have:${c.reset}  ${c.dim}${curLabel}${c.reset}
-`;
-
-  // Free alternative
-  if (copy.freeAlt) {
-    msg += `
-  ${c.green}${sym.arrow} Free path:${c.reset} ${c.cyan}${copy.freeAlt}${c.reset} ${c.dim}(${copy.freeAltDesc})${c.reset}`;
-  }
-
-  // Upgrade CTA
-  msg += `
-  ${c.bold}${sym.arrow} Upgrade:${c.reset}   ${PRICING_URL}
-`;
-
-  return msg;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// formatDowngrade() - Caps/downgrade notice
-// ═══════════════════════════════════════════════════════════════════════════════
-/**
- * Format a downgrade notice for a command running in capped mode.
- * 
- * @param {string} cmd - The command being run
- * @param {object} opts - Options
- * @param {string} opts.currentTier - User's current tier
- * @param {string} opts.effectiveMode - The downgraded mode being used
- * @param {object} [opts.caps] - Specific caps applied
- * @returns {string} Formatted downgrade notice
- */
-function formatDowngrade(cmd, opts = {}) {
-  const { currentTier = "free", effectiveMode, caps } = opts;
-  
-  const copy = CAPS_COPY[effectiveMode] || {
-    short: effectiveMode || "limited mode",
-    full: `Running in ${effectiveMode || "limited"} mode`,
-    upgradeBenefit: "Full access",
-  };
-  
-  const curLabel = TIER_LABELS[currentTier] || currentTier.toUpperCase();
-  
-  // Single line notice for start of run
-  let shortNotice = `${c.yellow}${sym.warning}${c.reset} Running in ${c.yellow}${curLabel}${c.reset} mode: ${c.dim}${copy.short}${c.reset}`;
-  
-  return shortNotice;
-}
-
-/**
- * Format a cap-hit notice when user reaches a limit during execution.
- * 
- * @param {string} cmd - The command being run
- * @param {object} opts - Options
- * @param {string} opts.limitType - Type of limit hit (e.g., "pages", "clicks")
- * @param {number} opts.limitValue - The limit value
- * @param {string} opts.upgradeTier - Tier to upgrade to
- * @returns {string} Formatted cap-hit message
- */
-function formatCapHit(cmd, opts = {}) {
-  const { limitType = "limit", limitValue, upgradeTier = "pro" } = opts;
-  
-  const tierColor = TIER_COLORS[upgradeTier] || c.magenta;
-  const tierLabel = TIER_LABELS[upgradeTier] || upgradeTier.toUpperCase();
-  
-  return `${c.yellow}${sym.warning}${c.reset} Hit FREE ${limitType} cap (${limitValue}). Upgrade to ${tierColor}${tierLabel}${c.reset} ${sym.arrow} ${PRICING_URL}`;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// formatEarnedUpsell() - End-of-run upsell
-// ═══════════════════════════════════════════════════════════════════════════════
-/**
- * Format an earned upsell shown at end of run.
- * 
- * @param {object} opts - Options
- * @param {string} opts.cmd - The command that was run
- * @param {string} opts.verdict - The verdict (SHIP/WARN/BLOCK)
- * @param {Array} [opts.topIssues] - Top 3 issues to show
- * @param {string} [opts.withheldArtifact] - Artifact that was withheld (e.g., "badge")
- * @param {string} [opts.upgradeTier] - Tier to suggest upgrading to
- * @param {string} [opts.why] - Why this upsell is relevant
- * @returns {string} Formatted earned upsell message
- */
-function formatEarnedUpsell(opts = {}) {
-  const { 
-    cmd, 
-    verdict, 
-    topIssues = [], 
-    withheldArtifact, 
-    upgradeTier = "pro",
-    why,
-    currentTier = "free",
-    suggestedCmd,
-  } = opts;
-  
-  const tierColor = TIER_COLORS[upgradeTier] || c.magenta;
-  const tierLabel = TIER_LABELS[upgradeTier] || upgradeTier.toUpperCase();
-  
-  let msg = "";
-  
-  // Badge withheld case
-  if (withheldArtifact === "badge") {
-    msg += `
-${c.dim}─────────────────────────────────────────────────────────────${c.reset}
-${c.yellow}${sym.badge} Badge withheld${c.reset} ${c.dim}(verdict: ${verdict})${c.reset}
-`;
-    
-    if (topIssues.length > 0) {
-      msg += `\n${c.bold}Top blockers:${c.reset}\n`;
-      topIssues.slice(0, 3).forEach((issue, i) => {
-        const sev = issue.severity === "BLOCK" ? c.red : c.yellow;
-        msg += `  ${c.dim}${i + 1}.${c.reset} ${sev}${issue.severity}${c.reset} ${issue.message || issue.id || issue.type}\n`;
-      });
-    }
-    
-    if (suggestedCmd) {
-      msg += `\n${c.green}${sym.arrow} Fix:${c.reset} ${c.cyan}${suggestedCmd}${c.reset}`;
-    }
-    
-    msg += `\n${c.dim}Badge unlocks when verdict = SHIP${c.reset}\n`;
-    return msg;
-  }
-  
-  // Fix plan-only case
-  if (cmd === "fix" && withheldArtifact === "apply") {
-    msg += `
-${c.dim}─────────────────────────────────────────────────────────────${c.reset}
-${c.yellow}${sym.lightning} Fix plan generated${c.reset}
-
-  Patches ready but ${c.yellow}--apply${c.reset} requires ${tierColor}${tierLabel}${c.reset} plan.
-  
-  ${c.green}${sym.arrow} Review:${c.reset} .vibecheck/missions/
-  ${c.bold}${sym.arrow} Apply:${c.reset}  Upgrade ${sym.arrow} ${PRICING_URL}
-`;
-    return msg;
-  }
-  
-  // Reality cap hit case
-  if (cmd === "reality" && why === "cap_hit") {
-    msg += `
-${c.dim}─────────────────────────────────────────────────────────────${c.reset}
-${c.yellow}${sym.warning} Preview complete${c.reset}
-
-  Crawled ${topIssues.length || 5} pages (FREE limit).
-  ${tierColor}${tierLabel}${c.reset} unlocks unlimited pages + auth boundary testing.
-  
-  ${c.bold}${sym.arrow} Upgrade:${c.reset} ${PRICING_URL}
-`;
-    return msg;
-  }
-  
-  // Generic earned upsell
-  if (why) {
-    msg += `
-${c.dim}─────────────────────────────────────────────────────────────${c.reset}
-${c.cyan}${sym.star} ${why}${c.reset}
-
-  ${tierColor}${tierLabel}${c.reset} unlocks this feature.
-  ${c.bold}${sym.arrow} Upgrade:${c.reset} ${PRICING_URL}
-`;
-  }
-  
-  return msg;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// formatBadgeWithheld() - Specific badge denial
-// ═══════════════════════════════════════════════════════════════════════════════
-/**
- * Format badge withheld message with top issues.
- * 
- * @param {string} verdict - Current verdict
- * @param {Array} findings - All findings
- * @param {string} currentTier - User's tier
- * @returns {string} Formatted message
- */
-function formatBadgeWithheld(verdict, findings = [], currentTier = "free") {
-  const blockers = findings.filter(f => f.severity === "BLOCK").slice(0, 3);
-  const topIssues = blockers.length > 0 ? blockers : findings.slice(0, 3);
-  
-  let msg = `
-${c.yellow}${sym.badge} Badge withheld${c.reset}
-
-  ${c.bold}Verdict:${c.reset} ${verdict === "BLOCK" ? c.red : c.yellow}${verdict}${c.reset}
-  ${c.dim}Badge requires SHIP verdict${c.reset}
-`;
-
-  if (topIssues.length > 0) {
-    msg += `\n  ${c.bold}Fix these first:${c.reset}\n`;
-    topIssues.forEach((issue, i) => {
-      const sev = issue.severity === "BLOCK" ? c.red : c.yellow;
-      const label = issue.id || issue.type || issue.ruleId || "issue";
-      const desc = issue.message || issue.description || "";
-      msg += `    ${c.dim}${i + 1}.${c.reset} ${sev}[${issue.severity}]${c.reset} ${label}${desc ? `: ${c.dim}${desc.slice(0, 50)}${c.reset}` : ""}\n`;
-    });
-  }
-
-  // Suggest fix command if available
-  const canFix = currentTier !== "free";
-  if (canFix) {
-    msg += `\n  ${c.green}${sym.arrow} Run:${c.reset} ${c.cyan}vibecheck fix${c.reset}\n`;
-  } else {
-    msg += `\n  ${c.green}${sym.arrow} Run:${c.reset} ${c.cyan}vibecheck fix --plan-only${c.reset} ${c.dim}(view fix plan)${c.reset}\n`;
-  }
-
-  return msg;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// formatNextSteps() - Smart suggestions
-// ═══════════════════════════════════════════════════════════════════════════════
-/**
- * Format next step suggestions based on current command and result.
- * 
- * @param {string} cmd - Command just run
- * @param {string} verdict - Result/verdict
- * @param {string} currentTier - User's tier
- * @returns {string} Next step suggestion
- */
-function formatNextSteps(cmd, verdict, currentTier = "free") {
-  const steps = [];
-  
-  switch (cmd) {
-    case "scan":
-      if (currentTier === "free") {
-        steps.push({ cmd: "vibecheck ship", desc: "get verdict" });
-      } else {
-        steps.push({ cmd: "vibecheck ship", desc: "get verdict" });
-        steps.push({ cmd: "vibecheck prove --url <url>", desc: "full proof loop" });
-      }
-      break;
-      
-    case "ship":
-      if (verdict === "SHIP") {
-        if (currentTier !== "free") {
-          steps.push({ cmd: "vibecheck badge", desc: "generate badge" });
-        }
-        steps.push({ cmd: "vibecheck report", desc: "export report" });
-      } else {
-        if (currentTier === "free") {
-          steps.push({ cmd: "vibecheck fix --plan-only", desc: "view fix plan" });
-        } else {
-          steps.push({ cmd: "vibecheck fix", desc: "auto-fix issues" });
-        }
-      }
-      break;
-      
-    case "fix":
-      steps.push({ cmd: "vibecheck ship", desc: "verify fixes" });
-      break;
-      
-    case "reality":
-      steps.push({ cmd: "vibecheck ship", desc: "get verdict with runtime proof" });
-      break;
-  }
-  
-  if (steps.length === 0) return "";
-  
-  let msg = `\n${c.dim}Next:${c.reset} `;
-  msg += steps.map(s => `${c.cyan}${s.cmd}${c.reset} ${c.dim}(${s.desc})${c.reset}`).join(" or ");
-  
-  return msg;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// EXPORTS
-// ═══════════════════════════════════════════════════════════════════════════════
-module.exports = {
-  // Core formatters
-  formatDenied,
-  formatDowngrade,
-  formatCapHit,
-  formatEarnedUpsell,
-  formatBadgeWithheld,
-  formatNextSteps,
-  
-  // Copy data (for testing/docs)
-  DENIAL_COPY,
-  CAPS_COPY,
-  TIER_LABELS,
-  TIER_COLORS,
-  PRICING_URL,
-  
-  // Styling (for consistent use)
-  c,
-  sym,
-};
+/**
+ * Upsell Copy Module - Central copy generator for tier upgrades
+ * 
+ * This is the SINGLE SOURCE OF TRUTH for all upsell/upgrade messaging.
+ * All upgrade nudges flow through these functions.
+ * 
+ * Rules:
+ * - Blunt, confident, minimal tone
+ * - No cringe language ("please upgrade")
+ * - Every upsell includes a free path if one exists
+ * - No web links besides https://vibecheckai.dev/pricing
+ * 
+ * @module bin/runners/lib/upsell
+ */
+
+"use strict";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ANSI STYLING
+// ═══════════════════════════════════════════════════════════════════════════════
+const SUPPORTS_COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+
+const c = SUPPORTS_COLOR ? {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  magenta: "\x1b[35m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
+} : {
+  reset: "", bold: "", dim: "", red: "", green: "", yellow: "",
+  cyan: "", magenta: "", white: "", gray: "",
+};
+
+const sym = {
+  lock: "🔒",
+  arrow: "→",
+  warning: "⚠",
+  check: "✓",
+  cross: "✗",
+  star: "★",
+  rocket: "🚀",
+  badge: "🏆",
+  lightning: "⚡",
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TIER CONFIGURATION
+// ═══════════════════════════════════════════════════════════════════════════════
+const TIER_LABELS = {
+  free: "FREE",
+  starter: "STARTER",
+  pro: "PRO",
+  complete: "COMPLETE",
+};
+
+const TIER_COLORS = {
+  free: c.green,
+  starter: c.cyan,
+  pro: c.magenta,
+  complete: c.yellow,
+};
+
+const PRICING_URL = "https://vibecheckai.dev";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// DENIAL COPY - Command-specific reasons and alternatives
+// ═══════════════════════════════════════════════════════════════════════════════
+const DENIAL_COPY = {
+  ship: {
+    feature: "release gate",
+    why: "Full ship analysis with runtime verification",
+    freeAlt: "vibecheck scan",
+    freeAltDesc: "static analysis",
+  },
+  prove: {
+    feature: "proof loop",
+    why: "Complete ctx → reality → ship → fix cycle",
+    freeAlt: "vibecheck ship",
+    freeAltDesc: "static verdict",
+  },
+  permissions: {
+    feature: "auth boundary / IDOR detection",
+    why: "Deep authorization matrix and IDOR analysis",
+    freeAlt: "vibecheck reality --verify-auth",
+    freeAltDesc: "basic auth boundary check",
+  },
+  "fix.apply_patches": {
+    feature: "patch generator / PR-ready diff",
+    why: "Apply LLM-generated patches automatically",
+    freeAlt: "vibecheck fix",
+    freeAltDesc: "plan-only mode",
+  },
+  fix: {
+    feature: "auto-fix with patches",
+    why: "Generate and apply fixes to your codebase",
+    freeAlt: "vibecheck fix --plan-only",
+    freeAltDesc: "view fix plan without applying",
+  },
+  badge: {
+    feature: "status artifact",
+    why: "Verified ship badge for README",
+    freeAlt: "vibecheck report",
+    freeAltDesc: "HTML/MD report",
+  },
+  gate: {
+    feature: "CI/CD gate",
+    why: "Block deploys on verification failures",
+    freeAlt: "vibecheck ship --ci",
+    freeAltDesc: "exit codes for scripts",
+  },
+  pr: {
+    feature: "PR comment generator",
+    why: "Auto-generated PR comments with findings",
+    freeAlt: "vibecheck report --format md",
+    freeAltDesc: "markdown report",
+  },
+  launch: {
+    feature: "pre-launch checklist",
+    why: "Guided launch readiness wizard",
+    freeAlt: "vibecheck ship",
+    freeAltDesc: "verdict check",
+  },
+  mcp: {
+    feature: "MCP server for AI IDEs",
+    why: "Real-time AI IDE integration",
+    freeAlt: "vibecheck ctx",
+    freeAltDesc: "generate truthpack manually",
+  },
+  share: {
+    feature: "share pack generator",
+    why: "Shareable proof bundle for PRs/docs",
+    freeAlt: "vibecheck report",
+    freeAltDesc: "local report",
+  },
+  "ai-test": {
+    feature: "autonomous test generation",
+    why: "AI-generated test coverage",
+    freeAlt: "vibecheck scan",
+    freeAltDesc: "static analysis",
+  },
+  replay: {
+    feature: "session replay",
+    why: "Record and replay user sessions",
+    freeAlt: "vibecheck reality",
+    freeAltDesc: "one-time runtime proof",
+  },
+  graph: {
+    feature: "reality proof graph",
+    why: "Visual dependency and proof graph",
+    freeAlt: "vibecheck ctx",
+    freeAltDesc: "truthpack",
+  },
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CAPS COPY - Downgrade mode descriptions
+// ═══════════════════════════════════════════════════════════════════════════════
+const CAPS_COPY = {
+  "reality.preview": {
+    short: "5 pages, no auth boundary",
+    full: "Preview mode: 5 pages max, 20 clicks, no auth boundary verification",
+    upgradeBenefit: "Unlimited pages + full auth boundary testing",
+  },
+  "fix.plan_only": {
+    short: "plan-only, no apply",
+    full: "Plan mode: generates fix missions but cannot apply patches",
+    upgradeBenefit: "Apply patches automatically with --apply",
+  },
+  "report.html_md": {
+    short: "HTML/MD only",
+    full: "Basic formats: HTML and Markdown reports only",
+    upgradeBenefit: "SARIF, CSV, and compliance pack exports",
+  },
+  "ship.static": {
+    short: "static-only",
+    full: "Static analysis only, no runtime verification",
+    upgradeBenefit: "Full runtime + static verification",
+  },
+  "mcp.help_only": {
+    short: "help and print-config only",
+    full: "MCP server limited to help and config commands",
+    upgradeBenefit: "Full MCP server with all tools",
+  },
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// formatDenied() - Hard denial message
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Format a denial message for a command that requires a higher tier.
+ * 
+ * @param {string} cmd - The command that was denied
+ * @param {object} opts - Options
+ * @param {string} opts.currentTier - User's current tier
+ * @param {string} opts.requiredTier - Required tier for the command
+ * @param {string} [opts.reason] - Additional context
+ * @param {string} [opts.suggestedNext] - Suggested next command
+ * @param {string} [opts.freeAlternative] - Free alternative command
+ * @returns {string} Formatted denial message
+ */
+function formatDenied(cmd, opts = {}) {
+  const { currentTier = "free", requiredTier = "pro" } = opts;
+  
+  const copy = DENIAL_COPY[cmd] || {
+    feature: cmd,
+    why: `${cmd} command`,
+    freeAlt: null,
+    freeAltDesc: null,
+  };
+  
+  const reqColor = TIER_COLORS[requiredTier] || c.yellow;
+  const reqLabel = TIER_LABELS[requiredTier] || requiredTier.toUpperCase();
+  const curLabel = TIER_LABELS[currentTier] || currentTier.toUpperCase();
+  
+  let msg = `
+${c.red}${c.bold}${sym.lock} LOCKED${c.reset}
+
+  ${c.bold}What:${c.reset}      ${c.yellow}${cmd}${c.reset} ${c.dim}(${copy.feature})${c.reset}
+  ${c.bold}Why:${c.reset}       ${copy.why}
+  ${c.bold}Requires:${c.reset}  ${reqColor}${reqLabel}${c.reset} plan
+  ${c.bold}You have:${c.reset}  ${c.dim}${curLabel}${c.reset}
+`;
+
+  // Free alternative
+  if (copy.freeAlt) {
+    msg += `
+  ${c.green}${sym.arrow} Free path:${c.reset} ${c.cyan}${copy.freeAlt}${c.reset} ${c.dim}(${copy.freeAltDesc})${c.reset}`;
+  }
+
+  // Upgrade CTA
+  msg += `
+  ${c.bold}${sym.arrow} Upgrade:${c.reset}   ${PRICING_URL}
+`;
+
+  return msg;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// formatDowngrade() - Caps/downgrade notice
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Format a downgrade notice for a command running in capped mode.
+ * 
+ * @param {string} cmd - The command being run
+ * @param {object} opts - Options
+ * @param {string} opts.currentTier - User's current tier
+ * @param {string} opts.effectiveMode - The downgraded mode being used
+ * @param {object} [opts.caps] - Specific caps applied
+ * @returns {string} Formatted downgrade notice
+ */
+function formatDowngrade(cmd, opts = {}) {
+  const { currentTier = "free", effectiveMode, caps } = opts;
+  
+  const copy = CAPS_COPY[effectiveMode] || {
+    short: effectiveMode || "limited mode",
+    full: `Running in ${effectiveMode || "limited"} mode`,
+    upgradeBenefit: "Full access",
+  };
+  
+  const curLabel = TIER_LABELS[currentTier] || currentTier.toUpperCase();
+  
+  // Single line notice for start of run
+  let shortNotice = `${c.yellow}${sym.warning}${c.reset} Running in ${c.yellow}${curLabel}${c.reset} mode: ${c.dim}${copy.short}${c.reset}`;
+  
+  return shortNotice;
+}
+
+/**
+ * Format a cap-hit notice when user reaches a limit during execution.
+ * 
+ * @param {string} cmd - The command being run
+ * @param {object} opts - Options
+ * @param {string} opts.limitType - Type of limit hit (e.g., "pages", "clicks")
+ * @param {number} opts.limitValue - The limit value
+ * @param {string} opts.upgradeTier - Tier to upgrade to
+ * @returns {string} Formatted cap-hit message
+ */
+function formatCapHit(cmd, opts = {}) {
+  const { limitType = "limit", limitValue, upgradeTier = "pro" } = opts;
+  
+  const tierColor = TIER_COLORS[upgradeTier] || c.magenta;
+  const tierLabel = TIER_LABELS[upgradeTier] || upgradeTier.toUpperCase();
+  
+  return `${c.yellow}${sym.warning}${c.reset} Hit FREE ${limitType} cap (${limitValue}). Upgrade to ${tierColor}${tierLabel}${c.reset} ${sym.arrow} ${PRICING_URL}`;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// formatEarnedUpsell() - End-of-run upsell
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Format an earned upsell shown at end of run.
+ * 
+ * @param {object} opts - Options
+ * @param {string} opts.cmd - The command that was run
+ * @param {string} opts.verdict - The verdict (SHIP/WARN/BLOCK)
+ * @param {Array} [opts.topIssues] - Top 3 issues to show
+ * @param {string} [opts.withheldArtifact] - Artifact that was withheld (e.g., "badge")
+ * @param {string} [opts.upgradeTier] - Tier to suggest upgrading to
+ * @param {string} [opts.why] - Why this upsell is relevant
+ * @returns {string} Formatted earned upsell message
+ */
+function formatEarnedUpsell(opts = {}) {
+  const { 
+    cmd, 
+    verdict, 
+    topIssues = [], 
+    withheldArtifact, 
+    upgradeTier = "pro",
+    why,
+    currentTier = "free",
+    suggestedCmd,
+  } = opts;
+  
+  const tierColor = TIER_COLORS[upgradeTier] || c.magenta;
+  const tierLabel = TIER_LABELS[upgradeTier] || upgradeTier.toUpperCase();
+  
+  let msg = "";
+  
+  // Badge withheld case
+  if (withheldArtifact === "badge") {
+    msg += `
+${c.dim}─────────────────────────────────────────────────────────────${c.reset}
+${c.yellow}${sym.badge} Badge withheld${c.reset} ${c.dim}(verdict: ${verdict})${c.reset}
+`;
+    
+    if (topIssues.length > 0) {
+      msg += `\n${c.bold}Top blockers:${c.reset}\n`;
+      topIssues.slice(0, 3).forEach((issue, i) => {
+        const sev = issue.severity === "BLOCK" ? c.red : c.yellow;
+        msg += `  ${c.dim}${i + 1}.${c.reset} ${sev}${issue.severity}${c.reset} ${issue.message || issue.id || issue.type}\n`;
+      });
+    }
+    
+    if (suggestedCmd) {
+      msg += `\n${c.green}${sym.arrow} Fix:${c.reset} ${c.cyan}${suggestedCmd}${c.reset}`;
+    }
+    
+    msg += `\n${c.dim}Badge unlocks when verdict = SHIP${c.reset}\n`;
+    return msg;
+  }
+  
+  // Fix plan-only case
+  if (cmd === "fix" && withheldArtifact === "apply") {
+    msg += `
+${c.dim}─────────────────────────────────────────────────────────────${c.reset}
+${c.yellow}${sym.lightning} Fix plan generated${c.reset}
+
+  Patches ready but ${c.yellow}--apply${c.reset} requires ${tierColor}${tierLabel}${c.reset} plan.
+  
+  ${c.green}${sym.arrow} Review:${c.reset} .vibecheck/missions/
+  ${c.bold}${sym.arrow} Apply:${c.reset}  Upgrade ${sym.arrow} ${PRICING_URL}
+`;
+    return msg;
+  }
+  
+  // Reality cap hit case
+  if (cmd === "reality" && why === "cap_hit") {
+    msg += `
+${c.dim}─────────────────────────────────────────────────────────────${c.reset}
+${c.yellow}${sym.warning} Preview complete${c.reset}
+
+  Crawled ${topIssues.length || 5} pages (FREE limit).
+  ${tierColor}${tierLabel}${c.reset} unlocks unlimited pages + auth boundary testing.
+  
+  ${c.bold}${sym.arrow} Upgrade:${c.reset} ${PRICING_URL}
+`;
+    return msg;
+  }
+  
+  // Generic earned upsell
+  if (why) {
+    msg += `
+${c.dim}─────────────────────────────────────────────────────────────${c.reset}
+${c.cyan}${sym.star} ${why}${c.reset}
+
+  ${tierColor}${tierLabel}${c.reset} unlocks this feature.
+  ${c.bold}${sym.arrow} Upgrade:${c.reset} ${PRICING_URL}
+`;
+  }
+  
+  return msg;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// formatBadgeWithheld() - Specific badge denial
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Format badge withheld message with top issues.
+ * 
+ * @param {string} verdict - Current verdict
+ * @param {Array} findings - All findings
+ * @param {string} currentTier - User's tier
+ * @returns {string} Formatted message
+ */
+function formatBadgeWithheld(verdict, findings = [], currentTier = "free") {
+  const blockers = findings.filter(f => f.severity === "BLOCK").slice(0, 3);
+  const topIssues = blockers.length > 0 ? blockers : findings.slice(0, 3);
+  
+  let msg = `
+${c.yellow}${sym.badge} Badge withheld${c.reset}
+
+  ${c.bold}Verdict:${c.reset} ${verdict === "BLOCK" ? c.red : c.yellow}${verdict}${c.reset}
+  ${c.dim}Badge requires SHIP verdict${c.reset}
+`;
+
+  if (topIssues.length > 0) {
+    msg += `\n  ${c.bold}Fix these first:${c.reset}\n`;
+    topIssues.forEach((issue, i) => {
+      const sev = issue.severity === "BLOCK" ? c.red : c.yellow;
+      const label = issue.id || issue.type || issue.ruleId || "issue";
+      const desc = issue.message || issue.description || "";
+      msg += `    ${c.dim}${i + 1}.${c.reset} ${sev}[${issue.severity}]${c.reset} ${label}${desc ? `: ${c.dim}${desc.slice(0, 50)}${c.reset}` : ""}\n`;
+    });
+  }
+
+  // Suggest fix command if available
+  const canFix = currentTier !== "free";
+  if (canFix) {
+    msg += `\n  ${c.green}${sym.arrow} Run:${c.reset} ${c.cyan}vibecheck fix${c.reset}\n`;
+  } else {
+    msg += `\n  ${c.green}${sym.arrow} Run:${c.reset} ${c.cyan}vibecheck fix --plan-only${c.reset} ${c.dim}(view fix plan)${c.reset}\n`;
+  }
+
+  return msg;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// formatNextSteps() - Smart suggestions
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Format next step suggestions based on current command and result.
+ * 
+ * @param {string} cmd - Command just run
+ * @param {string} verdict - Result/verdict
+ * @param {string} currentTier - User's tier
+ * @returns {string} Next step suggestion
+ */
+function formatNextSteps(cmd, verdict, currentTier = "free") {
+  const steps = [];
+  
+  switch (cmd) {
+    case "scan":
+      if (currentTier === "free") {
+        steps.push({ cmd: "vibecheck ship", desc: "get verdict" });
+      } else {
+        steps.push({ cmd: "vibecheck ship", desc: "get verdict" });
+        steps.push({ cmd: "vibecheck prove --url <url>", desc: "full proof loop" });
+      }
+      break;
+      
+    case "ship":
+      if (verdict === "SHIP") {
+        if (currentTier !== "free") {
+          steps.push({ cmd: "vibecheck badge", desc: "generate badge" });
+        }
+        steps.push({ cmd: "vibecheck report", desc: "export report" });
+      } else {
+        if (currentTier === "free") {
+          steps.push({ cmd: "vibecheck fix --plan-only", desc: "view fix plan" });
+        } else {
+          steps.push({ cmd: "vibecheck fix", desc: "auto-fix issues" });
+        }
+      }
+      break;
+      
+    case "fix":
+      steps.push({ cmd: "vibecheck ship", desc: "verify fixes" });
+      break;
+      
+    case "reality":
+      steps.push({ cmd: "vibecheck ship", desc: "get verdict with runtime proof" });
+      break;
+  }
+  
+  if (steps.length === 0) return "";
+  
+  let msg = `\n${c.dim}Next:${c.reset} `;
+  msg += steps.map(s => `${c.cyan}${s.cmd}${c.reset} ${c.dim}(${s.desc})${c.reset}`).join(" or ");
+  
+  return msg;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// formatSoftUpsell() - Non-intrusive end-of-run upsell
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Format a soft upsell shown at end of any command.
+ * Less intrusive than formatEarnedUpsell - single line.
+ * 
+ * @param {string} cmd - The command that was run
+ * @param {object} opts - Options
+ * @param {string} opts.currentTier - User's current tier
+ * @param {string} opts.feature - Feature to upsell
+ * @param {string} opts.upgradeTier - Tier to suggest
+ * @returns {string} Formatted soft upsell (single line)
+ */
+function formatSoftUpsell(cmd, opts = {}) {
+  const { currentTier = "free", feature, upgradeTier = "starter" } = opts;
+  
+  // Don't show upsells to paid users for starter features
+  if (currentTier !== "free" && upgradeTier === "starter") return "";
+  if (currentTier === "pro" || currentTier === "complete") return "";
+  
+  const tierColor = TIER_COLORS[upgradeTier] || c.cyan;
+  const tierLabel = TIER_LABELS[upgradeTier] || upgradeTier.toUpperCase();
+  
+  // Command-specific soft upsells
+  const SOFT_UPSELLS = {
+    context: {
+      feature: "AI rule sync",
+      benefit: "sync rules across team + auto-update",
+      tier: "starter",
+    },
+    guard: {
+      feature: "advanced hallucination detection",
+      benefit: "deep claim verification + policy engine",
+      tier: "starter",
+    },
+    whoami: {
+      feature: "team dashboard",
+      benefit: "shared findings + team policies",
+      tier: "starter",
+    },
+    login: {
+      feature: "dashboard sync",
+      benefit: "findings sync to web dashboard",
+      tier: "starter",
+    },
+    logout: null, // No upsell on logout
+    validate: {
+      feature: "continuous validation",
+      benefit: "watch mode + CI integration",
+      tier: "starter",
+    },
+    truth: {
+      feature: "truthpack sync",
+      benefit: "team-shared truthpacks",
+      tier: "pro",
+    },
+    firewall: {
+      feature: "policy enforcement",
+      benefit: "custom rules + block patterns",
+      tier: "starter",
+    },
+    agent: {
+      feature: "agent firewall",
+      benefit: "real-time AI action blocking",
+      tier: "pro",
+    },
+  };
+  
+  const upsellCopy = feature ? { feature, benefit: feature, tier: upgradeTier } : SOFT_UPSELLS[cmd];
+  if (!upsellCopy) return "";
+  
+  const targetTier = upsellCopy.tier || upgradeTier;
+  const targetColor = TIER_COLORS[targetTier] || c.cyan;
+  const targetLabel = TIER_LABELS[targetTier] || targetTier.toUpperCase();
+  
+  return `${c.dim}${sym.star} ${targetColor}${targetLabel}${c.reset}${c.dim}: ${upsellCopy.benefit} ${sym.arrow} ${PRICING_URL}${c.reset}`;
+}
+
+/**
+ * Format a workflow upsell - suggests next command with tier context.
+ * 
+ * @param {string} completedCmd - Command just completed
+ * @param {string} currentTier - User's tier
+ * @returns {string} Formatted workflow suggestion with upsell
+ */
+function formatWorkflowUpsell(completedCmd, currentTier = "free") {
+  const WORKFLOWS = {
+    scan: {
+      next: "ship",
+      freeCmd: "vibecheck ship",
+      paidCmd: "vibecheck ship --runtime",
+      paidBenefit: "includes runtime verification",
+      tier: "starter",
+    },
+    context: {
+      next: "scan",
+      freeCmd: "vibecheck scan",
+      paidCmd: "vibecheck scan --autofix",
+      paidBenefit: "auto-fix findings",
+      tier: "starter",
+    },
+    guard: {
+      next: "scan",
+      freeCmd: "vibecheck scan",
+      paidCmd: "vibecheck prove",
+      paidBenefit: "full proof loop",
+      tier: "pro",
+    },
+    doctor: {
+      next: "scan",
+      freeCmd: "vibecheck scan",
+      paidCmd: "vibecheck fix",
+      paidBenefit: "auto-fix issues found",
+      tier: "starter",
+    },
+    checkpoint: {
+      next: "fix",
+      freeCmd: "vibecheck fix --plan-only",
+      paidCmd: "vibecheck fix --apply",
+      paidBenefit: "apply patches automatically",
+      tier: "starter",
+    },
+    validate: {
+      next: "ship",
+      freeCmd: "vibecheck ship",
+      paidCmd: "vibecheck prove",
+      paidBenefit: "verified proof artifacts",
+      tier: "pro",
+    },
+  };
+  
+  const workflow = WORKFLOWS[completedCmd];
+  if (!workflow) return "";
+  
+  const isPaid = currentTier !== "free";
+  const tierColor = TIER_COLORS[workflow.tier] || c.cyan;
+  const tierLabel = TIER_LABELS[workflow.tier] || workflow.tier.toUpperCase();
+  
+  if (isPaid) {
+    return `${c.dim}Next:${c.reset} ${c.cyan}${workflow.paidCmd}${c.reset}`;
+  }
+  
+  return `${c.dim}Next:${c.reset} ${c.cyan}${workflow.freeCmd}${c.reset} ${c.dim}or${c.reset} ${tierColor}${tierLabel}${c.reset}${c.dim}: ${workflow.paidCmd} (${workflow.paidBenefit})${c.reset}`;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+module.exports = {
+  // Core formatters
+  formatDenied,
+  formatDowngrade,
+  formatCapHit,
+  formatEarnedUpsell,
+  formatBadgeWithheld,
+  formatNextSteps,
+  formatSoftUpsell,
+  formatWorkflowUpsell,
+  
+  // Copy data (for testing/docs)
+  DENIAL_COPY,
+  CAPS_COPY,
+  TIER_LABELS,
+  TIER_COLORS,
+  PRICING_URL,
+  
+  // Styling (for consistent use)
+  c,
+  sym,
+};