@nerviq/cli 1.9.0 → 1.11.0

package/bin/cli.js

@@ -47,7 +47,7 @@ function levenshtein(a, b) {
   return matrix[a.length][b.length];
 }
 
-function suggestCommand(input) {
+function suggestCommand(input) {
   const candidates = [...KNOWN_COMMANDS, ...Object.keys(COMMAND_ALIASES)];
   let best = null;
   let bestDistance = Infinity;
@@ -58,12 +58,33 @@ function suggestCommand(input) {
       bestDistance = distance;
     }
   }
-  return bestDistance <= 3 ? best : null;
-}
-
-function parseArgs(rawArgs) {
-  const flags = [];
-  let command = 'audit';
+  return bestDistance <= 3 ? best : null;
+}
+
+function parseNonNegativeIntegerFlag(value, flagName) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${flagName} requires a non-negative integer`);
+  }
+  return parsed;
+}
+
+function parseWebhookHeader(rawValue) {
+  const separator = rawValue.indexOf(':');
+  if (separator <= 0) {
+    throw new Error('--webhook-header requires NAME: VALUE');
+  }
+  const name = rawValue.slice(0, separator).trim();
+  const value = rawValue.slice(separator + 1).trim();
+  if (!name || !value) {
+    throw new Error('--webhook-header requires NAME: VALUE');
+  }
+  return { name, value };
+}
+
+function parseArgs(rawArgs) {
+  const flags = [];
+  let command = 'audit';
   let threshold = null;
   let out = null;
   let planFile = null;
@@ -79,9 +100,12 @@ function parseArgs(rawArgs) {
   let feedbackScoreDelta = null;
   let platform = 'claude';
   let format = null;
-  let port = null;
-  let workspace = null;
-  let webhookUrl = null;
+  let port = null;
+  let workspace = null;
+  let webhookUrl = null;
+  let webhookHeaders = [];
+  let webhookRetries = null;
+  let snapshotTags = [];
   let commandSet = false;
   let extraArgs = [];
   let convertFrom = null;
@@ -89,19 +113,20 @@ function parseArgs(rawArgs) {
   let migrateFrom = null;
   let migrateTo = null;
   let checkVersion = null;
-  let external = null;
-  let repos = [];
-  let teamProfile = null;
-  let lang = null;
+  let external = null;
+  let repos = [];
+  let teamProfile = null;
+  let lang = null;
+  let commandExplicit = false;
 
   for (let i = 0; i < rawArgs.length; i++) {
     const arg = rawArgs[i];
 
-    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack' || arg === '--require' || arg === '--key' || arg === '--status' || arg === '--effect' || arg === '--notes' || arg === '--source' || arg === '--score-delta' || arg === '--platform' || arg === '--format' || arg === '--from' || arg === '--to' || arg === '--port' || arg === '--workspace' || arg === '--check-version' || arg === '--webhook' || arg === '--external' || arg === '--team-profile' || arg === '--lang') {
-      const value = rawArgs[i + 1];
-      if (!value || value.startsWith('--')) {
-        throw new Error(`${arg} requires a value`);
-      }
+    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack' || arg === '--require' || arg === '--key' || arg === '--status' || arg === '--effect' || arg === '--notes' || arg === '--source' || arg === '--score-delta' || arg === '--platform' || arg === '--format' || arg === '--from' || arg === '--to' || arg === '--port' || arg === '--workspace' || arg === '--check-version' || arg === '--webhook' || arg === '--webhook-header' || arg === '--webhook-retries' || arg === '--external' || arg === '--team-profile' || arg === '--lang' || arg === '--tag') {
+      const value = rawArgs[i + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error(`${arg} requires a value`);
+      }
       if (arg === '--threshold') threshold = value;
       if (arg === '--out') out = value;
       if (arg === '--plan') planFile = value;
@@ -120,15 +145,18 @@ function parseArgs(rawArgs) {
       if (arg === '--from') { convertFrom = value.trim(); migrateFrom = value.trim(); }
       if (arg === '--to') { convertTo = value.trim(); migrateTo = value.trim(); }
       if (arg === '--port') port = value.trim();
-      if (arg === '--workspace') workspace = value.trim();
-      if (arg === '--check-version') checkVersion = value.trim();
-      if (arg === '--webhook') webhookUrl = value.trim();
-      if (arg === '--external') external = value.trim();
-      if (arg === '--team-profile') teamProfile = value.trim();
-      if (arg === '--lang') lang = value.trim().toLowerCase();
-      i++;
-      continue;
-    }
+      if (arg === '--workspace') workspace = value.trim();
+      if (arg === '--check-version') checkVersion = value.trim();
+      if (arg === '--webhook') webhookUrl = value.trim();
+      if (arg === '--webhook-header') webhookHeaders.push(parseWebhookHeader(value));
+      if (arg === '--webhook-retries') webhookRetries = parseNonNegativeIntegerFlag(value.trim(), '--webhook-retries');
+      if (arg === '--external') external = value.trim();
+      if (arg === '--team-profile') teamProfile = value.trim();
+      if (arg === '--lang') lang = value.trim().toLowerCase();
+      if (arg === '--tag') snapshotTags.push(value.trim());
+      i++;
+      continue;
+    }
 
     if (arg.startsWith('--lang=')) {
       lang = arg.split('=').slice(1).join('=').trim().toLowerCase();
@@ -140,10 +168,15 @@ function parseArgs(rawArgs) {
       continue;
     }
 
-    if (arg.startsWith('--external=')) {
-      external = arg.split('=').slice(1).join('=').trim();
-      continue;
-    }
+    if (arg.startsWith('--external=')) {
+      external = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--tag=')) {
+      snapshotTags.push(arg.split('=').slice(1).join('=').trim());
+      continue;
+    }
 
     if (arg === '--repos') {
       // Collect all following non-flag args as repo paths (supports comma-separated too)
@@ -246,54 +279,100 @@ function parseArgs(rawArgs) {
       continue;
     }
 
-    if (arg.startsWith('--check-version=')) {
-      checkVersion = arg.split('=').slice(1).join('=').trim();
-      continue;
+    if (arg.startsWith('--check-version=')) {
+      checkVersion = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--webhook=')) {
+      webhookUrl = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--webhook-header=')) {
+      webhookHeaders.push(parseWebhookHeader(arg.split('=').slice(1).join('=')));
+      continue;
+    }
+
+    if (arg.startsWith('--webhook-retries=')) {
+      webhookRetries = parseNonNegativeIntegerFlag(arg.split('=').slice(1).join('=').trim(), '--webhook-retries');
+      continue;
+    }
+
+    if (arg.startsWith('--')) {
+      flags.push(arg);
+      continue;
     }
 
-    if (arg.startsWith('--')) {
-      flags.push(arg);
-      continue;
-    }
-
-    if (!commandSet) {
-      command = arg;
-      commandSet = true;
-    } else {
-      extraArgs.push(arg);
-    }
-  }
+    if (!commandSet) {
+      command = arg;
+      commandSet = true;
+      commandExplicit = true;
+    } else {
+      extraArgs.push(arg);
+    }
+  }
 
   const normalizedCommand = COMMAND_ALIASES[command] || command;
 
-  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, feedbackKey, feedbackStatus, feedbackEffect, feedbackNotes, feedbackSource, feedbackScoreDelta, platform, format, port, workspace, extraArgs, convertFrom, convertTo, migrateFrom, migrateTo, checkVersion, webhookUrl, external, repos, teamProfile, lang };
-}
-
-function printWorkspaceSummary(summary, options) {
-  if (options.json) {
-    console.log(JSON.stringify(summary, null, 2));
-    return;
-  }
-
-  console.log('');
-  console.log('\x1b[1m  nerviq workspace audit\x1b[0m');
-  console.log('\x1b[2m  ═══════════════════════════════════════\x1b[0m');
-  console.log(`  Root: ${summary.rootDir}`);
-  console.log(`  Platform: ${summary.platform}`);
-  console.log(`  Workspaces: ${summary.workspaceCount}`);
-  console.log(`  Average score: \x1b[1m${summary.averageScore}/100\x1b[0m`);
-  console.log('');
-  console.log('\x1b[1m  Workspace                  Score  Pass  Total  Top action\x1b[0m');
-  console.log('  ' + '─'.repeat(72));
-  for (const item of summary.workspaces) {
-    const score = item.score === null ? 'ERR' : String(item.score);
-    const topAction = item.error || item.topAction || '-';
-    console.log(`  ${item.workspace.padEnd(26)} ${score.padStart(5)} ${String(item.passed).padStart(5)} ${String(item.total).padStart(6)}  ${topAction}`);
-  }
-  console.log('');
-}
-
-function printScanDetail(summary, options) {
+  return { flags, command, commandExplicit, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, feedbackKey, feedbackStatus, feedbackEffect, feedbackNotes, feedbackSource, feedbackScoreDelta, platform, format, port, workspace, extraArgs, convertFrom, convertTo, migrateFrom, migrateTo, checkVersion, webhookUrl, webhookHeaders, webhookRetries, external, repos, teamProfile, lang, snapshotTags };
+}
+
+function printWorkspaceSummary(summary, options) {
+  if (options.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+
+  const rootScore = summary.rootGovernance?.score === null ? 'ERR' : `${summary.rootGovernance?.score ?? 0}/100`;
+  const workspaceAverage = summary.workspaceAggregate?.score ?? summary.averageScore;
+
+  console.log('');
+  console.log('\x1b[1m  nerviq workspace audit\x1b[0m');
+  console.log('\x1b[2m  ═══════════════════════════════════════\x1b[0m');
+  console.log(`  Root: ${summary.rootDir}`);
+  console.log(`  Platform: ${summary.platform}`);
+  console.log(`  Workspaces: ${summary.workspaceCount}`);
+  if (summary.patterns?.length > 0) {
+    console.log(`  Selection: ${summary.patterns.join(', ')}`);
+  }
+  console.log(`  Root governance audit: \x1b[1m${rootScore}\x1b[0m`);
+  console.log(`  Workspace audit average: \x1b[1m${workspaceAverage}/100\x1b[0m`);
+  if (summary.profileBreakdown?.length > 0) {
+    const profileLine = summary.profileBreakdown
+      .map((item) => `${item.profileLabel} (${item.workspaceCount})`)
+      .join(', ');
+    console.log(`  Workspace profiles: ${profileLine}`);
+  }
+  console.log('  Score semantics: root governance shows shared repo policy health; workspace average shows package-level coverage across the selected workspaces.');
+  console.log('  Aggregate vs package: per-workspace scores can legitimately trail the root repo score in a monorepo.');
+  console.log('  Stack-specific checks: Go, Python, Node, and other workspace types can have different applicable totals.');
+  console.log('');
+  console.log('\x1b[1m  Workspace                  Profile              Audit  Pass  Total  Top action\x1b[0m');
+  console.log('  ' + '─'.repeat(96));
+  for (const item of summary.workspaces) {
+    const score = item.score === null ? 'ERR' : String(item.score);
+    const topAction = item.error || item.topAction || '-';
+    const profile = (item.workspaceProfile?.label || 'General workspace').slice(0, 20);
+    console.log(`  ${item.workspace.padEnd(26)} ${profile.padEnd(20)} ${score.padStart(5)} ${String(item.passed).padStart(5)} ${String(item.total).padStart(6)}  ${topAction}`);
+    if (item.stackLabels?.length > 0) {
+      console.log(`\x1b[2m     Stacks: ${item.stackLabels.join(', ')}\x1b[0m`);
+    }
+  }
+  console.log('');
+}
+
+function printCompareCheckSection(title, items, prefix) {
+  if (!Array.isArray(items) || items.length === 0) return;
+  console.log(`  ${title} (${items.length}):`);
+  for (const item of items) {
+    const impact = item.impact ? ` [${item.impact}]` : '';
+    const category = item.category ? ` — ${item.category}` : '';
+    console.log(`    ${prefix} ${item.key}${impact}: ${item.name}${category}`);
+  }
+}
+
+function printScanDetail(summary, options) {
   if (options.json) {
     console.log(JSON.stringify(summary, null, 2));
     return;
@@ -366,17 +445,18 @@ function printOrgSummary(summary, options) {
   console.log('');
 }
 
-const HELP = `
-  nerviq v${version}
-  The intelligent nervous system for AI coding agents.
-  Audit, align, and amplify every platform on every project.
-
-  DISCOVER
-    nerviq audit                  Quick scan: score + top 3 gaps (default)
-    nerviq audit --full           Full audit with all checks, weakest areas, badge
-    nerviq audit --platform X     Audit specific platform (claude|codex|cursor|copilot|gemini|windsurf|aider|opencode)
-    nerviq audit --json           Machine-readable JSON output (for CI)
-    nerviq audit --workspace packages/*     Audit each workspace in a monorepo
+const HELP = `
+  nerviq v${version}
+  The intelligent nervous system for AI coding agents.
+  Audit, align, and amplify every platform on every project.
+  New here? Run: nerviq --beginner
+
+  DISCOVER
+    nerviq audit                  Quick scan: score + top 3 gaps (default)
+    nerviq audit --full           Full audit with all checks, weakest areas, badge
+    nerviq audit --platform X     Audit specific platform (claude|codex|cursor|copilot|gemini|windsurf|aider|opencode)
+    nerviq audit --json           Machine-readable JSON output (for CI)
+    nerviq audit --workspace packages/*     Audit monorepo workspaces with stack-specific package profiles
     nerviq scan dir1 dir2         Compare multiple repos side-by-side
     nerviq org scan dir1 dir2     Aggregate multiple repos into one score table
     nerviq catalog                Full check catalog (all 8 platforms)
@@ -411,34 +491,35 @@ const HELP = `
     nerviq apply --dry-run        Preview changes without writing
 
   GOVERN
-    nerviq governance             Permission profiles + hooks + policy packs
+    nerviq governance             Permission profiles + hooks + policy packs (the rollout safety layer)
     nerviq governance --json      Machine-readable governance summary
-    nerviq benchmark              Before/after score in isolated temp copy
+    nerviq benchmark              Baseline vs projected score in isolated temp copy
     nerviq benchmark --external /path  Benchmark an external repo
     nerviq freshness              Show verification freshness for all checks
     nerviq certify                Generate certification badge for your project
 
   CROSS-PLATFORM
-    nerviq harmony-audit          Drift detection across all active platforms
-    nerviq harmony-sync           Preview cross-platform sync (dry run)
-    nerviq harmony-sync --fix     Apply cross-platform sync (write files)
-    nerviq harmony-sync --json    JSON output for CI/automation
-    nerviq harmony-add <platform>  Add a new platform to the project
-    nerviq synergy-report         Multi-agent amplification opportunities
+    nerviq harmony-audit          Drift detection across all active platforms (GA)
+    nerviq harmony-sync           Preview cross-platform sync (dry run, GA)
+    nerviq harmony-sync --fix     Apply cross-platform sync (write files, GA)
+    nerviq harmony-sync --json    JSON output for CI/automation
+    nerviq harmony-add <platform>  Add a new platform to the project
+    nerviq synergy-report         [EXPERIMENTAL] Static-rule multi-agent amplification report
     nerviq convert --from X --to Y   Convert configs between platforms
     nerviq migrate --platform X   Platform version migration helper
     nerviq migrate --platform cursor --from v2 --to v3
 
   MONITOR
-    nerviq dashboard              Generate static HTML dashboard report
+    nerviq dashboard              Generate static dashboard from latest audit snapshot (or live audit if none)
     nerviq dashboard --out F      Save dashboard to custom file
     nerviq dashboard --open       Open dashboard in browser after generating
     nerviq watch                  Live config monitoring (re-audits on file change)
-    nerviq history                Score history from saved snapshots
-    nerviq compare                Latest vs previous snapshot diff
-    nerviq trend                  Score trend over time
-    nerviq trend --out report.md  Export trend report as markdown
-    nerviq feedback               Record recommendation outcomes
+    nerviq history                Audit snapshot history from saved snapshots
+    nerviq compare                Detailed per-check diff between latest two audit snapshots
+    nerviq trend                  Audit snapshot trend over time
+    nerviq trend --out report.md  Export trend report as markdown
+    nerviq audit --snapshot --tag "pre-refactor"  Save a named audit snapshot
+    nerviq feedback               Record recommendation outcomes
 
   TEAM PROFILES
     nerviq profile save <name>    Save current preferences as a named profile
@@ -448,7 +529,7 @@ const HELP = `
 
   ADVANCED
     nerviq deep-review            AI-powered config review (opt-in, uses API key)
-    nerviq serve --port 3000      Start local Nerviq REST API server
+    nerviq serve --port 3000      Start local Nerviq REST API server + OpenAPI contract
     nerviq badge                  Generate shields.io badge markdown
     nerviq rules-export           Export recommendation rules as JSON
     nerviq rules-export --out F   Save rules to file
@@ -463,32 +544,37 @@ const HELP = `
     --only A,B        Limit plan/apply to selected proposal IDs
     --profile NAME    Permission profile: read-only | suggest-only | safe-write | power-user
     --team-profile N  Load a saved team profile for audit (overrides threshold/platform)
-    --mcp-pack A,B    Merge MCP packs into setup (e.g. context7-docs,next-devtools)
-    --check-version V Pin catalog to a specific version (warn on mismatch)
-    --format NAME     Output format: json | sarif | otel
-    --webhook URL     Send audit results to a webhook (Slack/Discord/generic JSON)
-    --external PATH   Benchmark an external repo instead of cwd
-    --port N          Port for \`serve\` (default: 3000)
-    --workspace GLOBS Audit workspaces separately (e.g. packages/* or apps/web,apps/api)
-    --snapshot        Save snapshot artifact under .claude/nerviq/snapshots/
-    --full            Show full audit output (all checks, weakest areas, badge)
+    --mcp-pack A,B    Merge MCP packs into setup (live tool connectors; e.g. context7-docs,next-devtools)
+    --check-version V Pin catalog to a specific version (warn on mismatch)
+    --format NAME     Output format: json | sarif | otel
+    --webhook URL     Send audit results to a webhook (Slack/Discord/generic JSON)
+    --webhook-header H Add a custom webhook header (repeat; format: Name: Value)
+    --webhook-retries N Retry transient webhook failures N times (default: 2)
+    --external PATH   Benchmark an external repo instead of cwd
+    --port N          Port for \`serve\` (default: 3000)
+    --workspace GLOBS Audit workspaces separately with root/package score semantics and stack-specific profiles
+    --snapshot        Save snapshot artifact under .claude/nerviq/snapshots/
+    --tag LABEL       Tag the saved snapshot (use with --snapshot; repeat or comma-separate for more)
+    --full            Show full audit output (all checks, weakest areas, badge)
     --lite            Short top-3 scan (default behavior since v1.5.2)
     --dry-run         Preview changes without writing files
     --config-only     Only write config files (.claude/, rules, hooks) — never source code
     --verbose         Full audit + medium-priority recommendations
-    --show-deprecated Show deprecated checks (excluded from scoring)
-    --json            Output as JSON
-    --auto            Apply all generated files without prompting
-    --key NAME        Feedback: recommendation key (e.g. permissionDeny)
+    --show-deprecated Show deprecated checks (excluded from scoring)
+    --json            Output as JSON
+    --auto            Apply all generated files without prompting
+    --beginner        Show only the 5 starter commands for first-time users
+    --key NAME        Feedback: recommendation key (e.g. permissionDeny)
     --status VALUE    Feedback: accepted | rejected | deferred
     --effect VALUE    Feedback: positive | neutral | negative
     --score-delta N   Feedback: observed score delta
     --help            Show this help
     --version         Show version
 
-  EXAMPLES
-    npx nerviq
-    npx nerviq --lite
+  EXAMPLES
+    npx nerviq --beginner
+    npx nerviq
+    npx nerviq --lite
     npx nerviq --platform cursor
     npx nerviq audit --workspace packages/*
     npx nerviq --platform codex augment
@@ -505,9 +591,34 @@ const HELP = `
     npx nerviq feedback --key permissionDeny --status accepted --effect positive
 
   EXIT CODES
-    0  Success
-    1  Error, unknown command, or score below --threshold
-`;
+    0  Success
+    1  Error, unknown command, or score below --threshold
+`;
+
+const BEGINNER_HELP = `
+  nerviq v${version}
+  Start here.
+
+  If this is your first time, learn just these 5 commands:
+
+  STARTER COMMANDS
+    nerviq audit      Score the repo and show the top gaps
+    nerviq setup      Generate a starter-safe baseline
+    nerviq fix        Fix what can be fixed or show manual fix guidance
+    nerviq augment    Show an improvement plan without writing
+    nerviq doctor     Check install health, freshness, and platform detection
+
+  SIMPLE PATH
+    1. nerviq audit
+    2. nerviq setup --auto
+    3. nerviq fix --all-critical --auto
+    4. nerviq augment
+    5. nerviq doctor
+
+  WHEN YOU ARE READY
+    nerviq --help     Show the full command set
+    Docs: https://nerviq.net/docs/getting-started
+`;
 
 async function main() {
   let parsed;
@@ -518,24 +629,29 @@ async function main() {
     process.exit(1);
   }
 
-  const { flags, command, normalizedCommand } = parsed;
+  const { flags, command, commandExplicit, normalizedCommand } = parsed;
 
   // Initialize i18n with --lang flag or NERVIQ_LANG env var
   if (parsed.lang) {
     initI18n(parsed.lang);
   }
 
-  if (flags.includes('--help') || command === 'help') {
-    console.log(HELP);
-    process.exit(0);
-  }
-
-  if (flags.includes('--version') || command === 'version') {
-    console.log(version);
-    process.exit(0);
-  }
-
-  const options = {
+  if (flags.includes('--version') || command === 'version') {
+    console.log(version);
+    process.exit(0);
+  }
+
+  if (flags.includes('--beginner') && (!commandExplicit || flags.includes('--help') || command === 'help')) {
+    console.log(BEGINNER_HELP);
+    process.exit(0);
+  }
+
+  if (flags.includes('--help') || command === 'help') {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  const options = {
     verbose: flags.includes('--verbose'),
     json: flags.includes('--json'),
     auto: flags.includes('--auto'),
@@ -557,13 +673,21 @@ async function main() {
     require: parsed.requireChecks,
     platform: parsed.platform || 'claude',
     format: parsed.format || null,
-    port: parsed.port !== null ? Number(parsed.port) : null,
-    workspace: parsed.workspace || null,
-    webhookUrl: parsed.webhookUrl || null,
-    lang: parsed.lang || null,
-    external: parsed.external || null,
-    dir: process.cwd()
-  };
+    port: parsed.port !== null ? Number(parsed.port) : null,
+    workspace: parsed.workspace || null,
+    webhookUrl: parsed.webhookUrl || null,
+    webhookHeaders: Object.fromEntries((parsed.webhookHeaders || []).map((entry) => [entry.name, entry.value])),
+    webhookRetries: parsed.webhookRetries ?? 2,
+    lang: parsed.lang || null,
+    external: parsed.external || null,
+    snapshotTags: parsed.snapshotTags || [],
+    dir: process.cwd()
+  };
+
+  if (options.snapshotTags.length > 0 && !options.snapshot) {
+    console.error('\n  Error: --tag requires --snapshot.\n');
+    process.exit(1);
+  }
 
   if (parsed.checkVersion) {
     if (parsed.checkVersion !== version) {
@@ -746,9 +870,9 @@ async function main() {
         process.exit(1);
       }
       process.exit(0);
-    } else if (normalizedCommand === 'history') {
-      const { formatHistory, readSnapshotIndex } = require('../src/activity');
-      // Handle --prune N
+    } else if (normalizedCommand === 'history') {
+      const { formatHistory, readSnapshotIndex } = require('../src/activity');
+      // Handle --prune N
       const pruneIdx = flags.indexOf('--prune');
       if (pruneIdx >= 0) {
         const keepCount = parseInt(flags[pruneIdx + 1] || parsed.extraArgs[0], 10) || 10;
@@ -756,7 +880,7 @@ async function main() {
         const pathMod = require('path');
         const entries = readSnapshotIndex(options.dir);
         if (entries.length <= keepCount) {
-          console.log(`\n  Nothing to prune (${entries.length} snapshots, keeping ${keepCount}).\n`);
+          console.log(`\n  Nothing to prune (${entries.length} audit snapshots, keeping ${keepCount}).\n`);
         } else {
           const toRemove = entries.slice(0, entries.length - keepCount);
           let removed = 0;
@@ -767,42 +891,78 @@ async function main() {
           const kept = entries.slice(entries.length - keepCount);
           const indexPath = pathMod.join(options.dir, '.nerviq', 'snapshots', 'index.json');
           try { fsMod.writeFileSync(indexPath, JSON.stringify(kept, null, 2), 'utf8'); } catch {}
-          console.log(`\n  Pruned ${removed} snapshots, kept ${kept.length}.\n`);
+          console.log(`\n  Pruned ${removed} audit snapshots, kept ${kept.length}.\n`);
         }
         process.exit(0);
       }
       console.log('');
-      console.log(formatHistory(options.dir));
-      console.log('');
-      process.exit(0);
-    } else if (normalizedCommand === 'compare') {
-      const { compareLatest } = require('../src/activity');
-      const result = compareLatest(options.dir);
-      if (!result) {
-        console.log('\n  Need at least 2 snapshots to compare. Run `npx nerviq --snapshot` twice.\n');
-        process.exit(0);
-      }
+      console.log(formatHistory(options.dir));
+      console.log('');
+      process.exit(0);
+    } else if (normalizedCommand === 'compare') {
+      const { compareLatest, formatSnapshotBootstrap, formatSnapshotTags } = require('../src/activity');
+      const result = compareLatest(options.dir);
+      if (!result) {
+        console.log('');
+        console.log(formatSnapshotBootstrap(options.dir, 'compare'));
+        console.log('');
+        process.exit(0);
+      }
       if (options.json) {
         console.log(JSON.stringify(result, null, 2));
-      } else {
-        const sign = result.delta.score >= 0 ? '+' : '';
-        console.log('');
-        console.log(`  Previous: ${result.previous.score}/100 (${result.previous.date?.split('T')[0]})`);
-        console.log(`  Current:  ${result.current.score}/100 (${result.current.date?.split('T')[0]})`);
-        console.log(`  Delta:    ${sign}${result.delta.score} points`);
-        console.log(`  Trend:    ${result.trend}`);
-        if (result.improvements.length > 0) console.log(`  Fixed:    ${result.improvements.join(', ')}`);
-        if (result.regressions.length > 0) console.log(`  New gaps: ${result.regressions.join(', ')}`);
-        console.log('');
-      }
-      process.exit(0);
-    } else if (normalizedCommand === 'trend') {
-      const { exportTrendReport } = require('../src/activity');
-      const report = exportTrendReport(options.dir);
-      if (!report) {
-        console.log('\n  No snapshots found. Run `npx nerviq --snapshot` to start tracking.\n');
-        process.exit(0);
-      }
+      } else {
+        const sign = result.delta.score >= 0 ? '+' : '';
+        console.log('');
+        console.log(`  Previous snapshot: ${result.previous.score}/100 (${result.previous.date?.split('T')[0]})${formatSnapshotTags(result.previous.tags)}`);
+        console.log(`  Current snapshot:  ${result.current.score}/100 (${result.current.date?.split('T')[0]})${formatSnapshotTags(result.current.tags)}`);
+        console.log(`  Snapshot delta:    ${sign}${result.delta.score} points`);
+        console.log(`  Trend:    ${result.trend}`);
+        if (result.detailedDiffAvailable) {
+          console.log('');
+          console.log('  Detailed check diff:');
+          printCompareCheckSection('Regressions', result.regressionDetails, '🔴');
+          printCompareCheckSection('Improvements', result.improvementDetails, '✅');
+          printCompareCheckSection('Newly applicable', result.newlyApplicableDetails, '🆕');
+          printCompareCheckSection('No longer applicable', result.noLongerApplicableDetails, '↩');
+          if (Array.isArray(result.newChecks) && result.newChecks.length > 0) {
+            printCompareCheckSection('New checks', result.newChecks, '➕');
+          }
+          if (Array.isArray(result.removedChecks) && result.removedChecks.length > 0) {
+            printCompareCheckSection('Removed checks', result.removedChecks, '➖');
+          }
+          if (
+            result.regressionDetails.length === 0 &&
+            result.improvementDetails.length === 0 &&
+            result.newlyApplicableDetails.length === 0 &&
+            result.noLongerApplicableDetails.length === 0 &&
+            result.newChecks.length === 0 &&
+            result.removedChecks.length === 0
+          ) {
+            console.log('  No per-check state changes detected.');
+          }
+        } else {
+          if (result.improvements.length > 0) console.log(`  Fixed:    ${result.improvements.join(', ')}`);
+          if (result.regressions.length > 0) console.log(`  New gaps: ${result.regressions.join(', ')}`);
+        }
+        console.log('');
+      }
+      process.exit(0);
+    } else if (normalizedCommand === 'trend') {
+      const { exportTrendReport, getHistory, formatSnapshotBootstrap } = require('../src/activity');
+      const auditHistory = getHistory(options.dir, 2);
+      if (auditHistory.length < 2) {
+        console.log('');
+        console.log(formatSnapshotBootstrap(options.dir, 'trend'));
+        console.log('');
+        process.exit(0);
+      }
+      const report = exportTrendReport(options.dir);
+      if (!report) {
+        console.log('');
+        console.log(formatSnapshotBootstrap(options.dir, 'trend'));
+        console.log('');
+        process.exit(0);
+      }
       if (options.out) {
         require('fs').writeFileSync(options.out, report, 'utf8');
         console.log(`\n  Trend report exported to ${options.out}\n`);
@@ -904,9 +1064,10 @@ async function main() {
       process.exit(0);
     } else if (normalizedCommand === 'augment' || normalizedCommand === 'suggest-only') {
       const report = await analyzeProject({ ...options, mode: normalizedCommand });
-      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, normalizedCommand, report, {
-        sourceCommand: normalizedCommand,
-      }) : null;
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, normalizedCommand, report, {
+        tags: options.snapshotTags,
+        sourceCommand: normalizedCommand,
+      }) : null;
       if (options.out && !options.json) {
         const fs = require('fs');
         const md = exportMarkdown(report);
@@ -1037,9 +1198,10 @@ async function main() {
         fs.writeFileSync(options.out, content, 'utf8');
       }
       printGovernanceSummary(summary, options);
-      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'governance', summary, {
-        sourceCommand: normalizedCommand,
-      }) : null;
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'governance', summary, {
+        tags: options.snapshotTags,
+        sourceCommand: normalizedCommand,
+      }) : null;
       if (options.out && !options.json) {
         console.log(`  Governance report written to ${options.out}`);
         console.log('');
@@ -1051,9 +1213,10 @@ async function main() {
       }
     } else if (normalizedCommand === 'benchmark') {
       const report = await runBenchmark(options);
-      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'benchmark', report, {
-        sourceCommand: normalizedCommand,
-      }) : null;
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'benchmark', report, {
+        tags: options.snapshotTags,
+        sourceCommand: normalizedCommand,
+      }) : null;
       if (options.out) {
         writeBenchmarkReport(report, options.out);
       }
@@ -1147,9 +1310,10 @@ async function main() {
       const address = server.address();
       const resolvedPort = address && typeof address === 'object' ? address.port : options.port;
       console.log('');
-      console.log(`  nerviq API listening on http://127.0.0.1:${resolvedPort}`);
-      console.log('  Endpoints: /api/health, /api/catalog, /api/audit, /api/harmony');
-      console.log('');
+      console.log(`  nerviq API listening on http://127.0.0.1:${resolvedPort}`);
+      console.log('  Endpoints: /api/openapi.json, /api/health, /api/catalog, /api/audit, /api/harmony');
+      console.log(`  Contract: http://127.0.0.1:${resolvedPort}/api/openapi.json`);
+      console.log('');
 
       const closeServer = () => {
         server.close(() => process.exit(0));
@@ -1927,14 +2091,15 @@ async function main() {
       process.exit(0);
     } else if (normalizedCommand === 'setup') {
       await setup(options);
-      if (options.snapshot) {
-        const postSetupResult = await audit({ dir: options.dir, silent: true, platform: options.platform });
-        const snapshot = writeSnapshotArtifact(options.dir, 'audit', postSetupResult, {
-          sourceCommand: 'setup',
-        });
-        if (!options.json) {
-          console.log(`  Snapshot saved: ${snapshot.relativePath}`);
-        }
+      if (options.snapshot) {
+        const postSetupResult = await audit({ dir: options.dir, silent: true, platform: options.platform });
+        const snapshot = writeSnapshotArtifact(options.dir, 'audit', postSetupResult, {
+          tags: options.snapshotTags,
+          sourceCommand: 'setup',
+        });
+        if (!options.json) {
+          console.log(`  Snapshot saved: ${snapshot.relativePath}`);
+        }
       }
     } else {
       if (options.workspace) {
@@ -1972,18 +2137,26 @@ async function main() {
             // Generic webhook: send full JSON audit result
             payload = { platform: result.platform, score: result.score, passed: result.passed, failed: result.failed, results: result.results };
           }
-          const webhookResp = await sendWebhook(options.webhookUrl, payload);
-          if (!options.json) {
-            if (webhookResp.ok) {
-              console.log(`  Webhook sent: ${options.webhookUrl} (${webhookResp.status})`);
-            } else {
-              console.error(`  Webhook failed: ${webhookResp.status} — ${webhookResp.body.slice(0, 200)}`);
-            }
-          }
-        } catch (webhookErr) {
-          if (!options.json) console.error(`  Webhook error: ${webhookErr.message}`);
-        }
-      }
+          const webhookResp = await sendWebhook(options.webhookUrl, payload, {
+            headers: options.webhookHeaders,
+            retries: options.webhookRetries,
+          });
+          if (!options.json) {
+            if (webhookResp.ok) {
+              const retryNote = webhookResp.attempts > 1 ? ` after ${webhookResp.attempts} attempts` : '';
+              console.log(`  Webhook sent${retryNote}: ${options.webhookUrl} (${webhookResp.status})`);
+            } else {
+              const retryNote = webhookResp.attempts > 1 ? ` after ${webhookResp.attempts} attempts` : '';
+              console.error(`  Webhook failed${retryNote}: ${webhookResp.status} — ${webhookResp.body.slice(0, 200)}`);
+            }
+          }
+        } catch (webhookErr) {
+          if (!options.json) {
+            const retryNote = webhookErr.attempts > 1 ? ` after ${webhookErr.attempts} attempts` : '';
+            console.error(`  Webhook error${retryNote}: ${webhookErr.message}`);
+          }
+        }
+      }
       if (options.feedback && !options.json && options.format === null) {
         const feedbackTargets = options.lite
           ? (result.liteSummary?.topNextActions || [])
@@ -2003,9 +2176,10 @@ async function main() {
           console.log('');
         }
       }
-      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'audit', result, {
-        sourceCommand: normalizedCommand,
-      }) : null;
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'audit', result, {
+        tags: options.snapshotTags,
+        sourceCommand: normalizedCommand,
+      }) : null;
       if (snapshot && !options.json) {
         console.log(`  Snapshot saved: ${snapshot.relativePath}`);
         console.log(`  Snapshot index: ${snapshot.indexPath}`);