@nerviq/cli 1.9.0 → 1.10.0

package/README.md

@@ -64,18 +64,26 @@ Nerviq scores your AI coding agent setup from 0 to 100, finds what's missing, an
   Next: nerviq setup
 ```
 
-## Quick Start
-
-```bash
-npx @nerviq/cli audit              # Quick scan: score + top 3 actions
-npx @nerviq/cli audit --full       # Full audit with all checks + badge
-npx @nerviq/cli setup              # Generate starter-safe baseline
-npx @nerviq/cli augment            # Improvement plan, no writes
-npx @nerviq/cli governance         # Permission profiles + policy packs
-npx @nerviq/cli benchmark          # Before/after in isolated copy
-```
-
-No install required. Zero dependencies.
+## Quick Start
+
+```bash
+npx @nerviq/cli --beginner         # Show only the 5 starter commands
+npx @nerviq/cli audit              # Quick scan: score + top 3 actions
+npx @nerviq/cli audit --full       # Full audit with all checks + badge
+npx @nerviq/cli audit --workspace packages/*  # Monorepo: root governance + workspace average/package scores
+npx @nerviq/cli setup              # Generate starter-safe baseline
+npx @nerviq/cli augment            # Improvement plan, no writes
+npx @nerviq/cli governance         # Permission profiles + policy packs
+npx @nerviq/cli benchmark          # Baseline vs projected score in isolated copy
+```
+
+No install required. Zero dependencies.
+
+If you want the shortest possible command list inside the terminal, start with:
+
+```bash
+npx @nerviq/cli --beginner
+```
 
 ## Get Started by Role
 
@@ -236,14 +244,14 @@ Levels:
 | `nerviq plan` | Export proposal bundles with previews |
 | `nerviq apply` | Apply proposals with rollback |
 | `nerviq governance` | Permission profiles, hooks, policy packs |
-| `nerviq benchmark` | Before/after in isolated temp copy |
+| `nerviq benchmark` | Baseline vs projected score in isolated temp copy |
 | `nerviq check-health` | Detect regressions between audit snapshots |
 | `nerviq deep-review` | AI-powered config review (opt-in) |
 | `nerviq interactive` | Step-by-step guided wizard |
 | `nerviq watch` | Live monitoring with score delta |
-| `nerviq history` | Score history from snapshots |
-| `nerviq compare` | Compare latest vs previous |
-| `nerviq trend` | Export trend report |
+| `nerviq history` | Audit snapshot history from saved snapshots |
+| `nerviq compare` | Compare latest vs previous audit snapshot |
+| `nerviq trend` | Export audit snapshot trend report |
 | `nerviq feedback` | Record recommendation outcomes |
 | `nerviq anti-patterns` | Detect anti-patterns in current project |
 | `nerviq freshness` | Show verification freshness for all checks |
@@ -281,7 +289,7 @@ Levels:
 | `--only A,B` | Limit apply to selected proposal IDs |
 | `--format sarif` | SARIF output for code scanning |
 | `--platform NAME` | Target platform (claude, codex, gemini, copilot, cursor, windsurf, aider, opencode) |
-| `--workspace GLOB` | Audit workspaces separately (e.g. packages/*) |
+| `--workspace GLOB` | Audit workspaces separately as package-level live audits (e.g. packages/*) |
 | `--external PATH` | Benchmark an external repo |
 
 ## Backed by Research
@@ -333,9 +341,9 @@ If Nerviq helped you, consider giving it a ⭐ on [GitHub](https://github.com/ne
 
 **Not designed for:** Deeply customized setups with 20+ skills, agent teams, and bespoke MCP integrations. If you've already built advanced agent workflows, you may not need this.
 
-**Strongest at:** Agent configuration, workflow governance, repo policy hygiene, cross-platform alignment, and setup standardization.
-
-**Not a replacement for:** Deep architectural review of business logic, runtime performance profiling, or security penetration testing. Nerviq focuses on how your AI coding agents are configured and governed — not on what your application code does.
+**Strongest at:** AI agent governance, configuration intelligence, workflow policy hygiene, cross-platform alignment, and setup standardization.
+
+**Not a replacement for:** Deep architectural review of business logic, runtime performance profiling, full SAST coverage, secret scanning, or security penetration testing. Nerviq focuses on how your AI coding agents are configured and governed — not on what your application code does.
 
 **Confidence levels:** Every check includes a `confidence` score (0.0–1.0) and a `sourceUrl` linking to primary documentation. Checks marked `heuristic` are pattern-based and may produce false positives on non-standard project structures.
 
@@ -347,16 +355,3 @@ If Nerviq helped you, consider giving it a ⭐ on [GitHub](https://github.com/ne
 | `BETA` | Works but has limited real-world testing. API may change |
 | `EXPERIMENTAL` | Early stage, static rules, results may vary |
 
-## Previously nerviq-cli
-
-Nerviq was previously published as `nerviq-cli`. If you were using it:
-
-```bash
-# Old
-npx nerviq-cli
-
-# New
-npx @nerviq/cli audit
-```
-
-All features are preserved and expanded.

package/bin/cli.js

@@ -61,9 +61,9 @@ function suggestCommand(input) {
   return bestDistance <= 3 ? best : null;
 }
 
-function parseArgs(rawArgs) {
-  const flags = [];
-  let command = 'audit';
+function parseArgs(rawArgs) {
+  const flags = [];
+  let command = 'audit';
   let threshold = null;
   let out = null;
   let planFile = null;
@@ -89,10 +89,11 @@ 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];
@@ -256,37 +257,47 @@ function parseArgs(rawArgs) {
       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);
+  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, external, repos, teamProfile, lang };
+}
+
+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`);
+  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('');
+  console.log('\x1b[1m  Workspace                  Audit  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}`);
   }
@@ -366,17 +377,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 root-vs-package score semantics
     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)
@@ -413,30 +425,30 @@ const HELP = `
   GOVERN
     nerviq governance             Permission profiles + hooks + policy packs
     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 history                Audit snapshot history from saved snapshots
+    nerviq compare                Latest vs previous audit snapshot diff
+    nerviq trend                  Audit snapshot trend over time
     nerviq trend --out report.md  Export trend report as markdown
     nerviq feedback               Record recommendation outcomes
 
@@ -469,26 +481,28 @@ const HELP = `
     --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)
+    --workspace GLOBS Audit workspaces separately and label root governance vs package scores
     --snapshot        Save snapshot artifact under .claude/nerviq/snapshots/
     --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 +519,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,22 +557,27 @@ 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);
-  }
+  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'),
@@ -746,9 +790,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 +800,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 +811,53 @@ 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 } = 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}`);
+        console.log(`  Previous snapshot: ${result.previous.score}/100 (${result.previous.date?.split('T')[0]})`);
+        console.log(`  Current snapshot:  ${result.current.score}/100 (${result.current.date?.split('T')[0]})`);
+        console.log(`  Snapshot 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);
-      }
+      }
+      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`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "The intelligent nervous system for AI coding agents — 2,438 checks (8 platforms × ~300 governance rules), 10 languages, 62 domain packs. Audit, align, and amplify.",
   "main": "src/index.js",
   "bin": {

package/src/activity.js

@@ -268,8 +268,9 @@ function compareLatest(dir) {
   }
 
   return {
-    current: { date: current.createdAt, score: current.summary?.score, passed: current.summary?.passed },
-    previous: { date: previous.createdAt, score: previous.summary?.score, passed: previous.summary?.passed },
+    scoreType: 'audit-snapshot-score',
+    current: { date: current.createdAt, score: current.summary?.score, passed: current.summary?.passed, scoreType: 'audit-snapshot-score' },
+    previous: { date: previous.createdAt, score: previous.summary?.score, passed: previous.summary?.passed, scoreType: 'audit-snapshot-score' },
     delta,
     regressions,
     improvements,
@@ -277,11 +278,60 @@ function compareLatest(dir) {
   };
 }
 
+function formatSnapshotBootstrap(dir, goal = 'history') {
+  const snapshotCount = getHistory(dir, 50).length;
+  const lines = [];
+  const snapshotLabel = snapshotCount === 1
+    ? '1 saved audit snapshot'
+    : `${snapshotCount} saved audit snapshots`;
+
+  if (goal === 'compare') {
+    lines.push(snapshotCount === 0
+      ? 'Compare needs 2 audit snapshots.'
+      : 'Compare needs one more audit snapshot.');
+  } else if (goal === 'trend') {
+    lines.push(snapshotCount === 0
+      ? 'Trend needs 2 audit snapshots to start.'
+      : 'Trend needs one more audit snapshot to become meaningful.');
+  } else {
+    lines.push(snapshotCount === 0
+      ? 'No audit snapshots found yet.'
+      : 'History is initialized, but compare/trend still need one more snapshot.');
+  }
+
+  lines.push(`  Current state: ${snapshotLabel}.`);
+
+  if (snapshotCount === 0) {
+    lines.push('  Bootstrap it with:');
+    lines.push('  1. Run `nerviq audit --snapshot` to save the baseline.');
+    lines.push('  2. Make a meaningful repo change (`nerviq setup --auto` or `nerviq fix --all-critical --auto`).');
+    lines.push('  3. Run `nerviq audit --snapshot` again to capture the next state.');
+  } else {
+    lines.push('  Next:');
+    lines.push('  1. Make a meaningful repo change (`nerviq setup --auto` or `nerviq fix --all-critical --auto`).');
+    lines.push('  2. Run `nerviq audit --snapshot` again.');
+  }
+
+  if (goal === 'compare') {
+    lines.push('  Then rerun `nerviq compare`.');
+  } else if (goal === 'trend') {
+    lines.push('  Then rerun `nerviq trend`.');
+  } else {
+    lines.push('  Then rerun `nerviq history`, `nerviq compare`, or `nerviq trend`.');
+  }
+
+  return lines.join('\n');
+}
+
 function formatHistory(dir) {
   const history = getHistory(dir, 10);
-  if (history.length === 0) return 'No snapshots found. Run `npx nerviq --snapshot` to save one.';
+  if (history.length === 0) return formatSnapshotBootstrap(dir, 'history');
 
-  const lines = ['Score history (most recent first):', ''];
+  const lines = [
+    'Audit snapshot history (most recent first):',
+    '  Score type: saved audit snapshot scores only (not live audits or benchmark projections).',
+    '',
+  ];
   for (const entry of history) {
     const dateStr = entry.createdAt || 'unknown';
     const date = dateStr.split('T')[0] || 'unknown';
@@ -290,14 +340,14 @@ function formatHistory(dir) {
     const score = entry.summary?.score ?? '?';
     const passed = entry.summary?.passed ?? '?';
     const total = entry.summary?.checkCount ?? '?';
-    lines.push(`  ${dateDisplay}  ${score}/100  (${passed}/${total} passing)`);
+    lines.push(`  ${dateDisplay}  snapshot ${score}/100  (${passed}/${total} checks passing)`);
   }
 
   const comparison = compareLatest(dir);
   if (comparison) {
     lines.push('');
     const sign = comparison.delta.score >= 0 ? '+' : '';
-    lines.push(`  Trend: ${comparison.trend} (${sign}${comparison.delta.score} since previous)`);
+    lines.push(`  Latest snapshot trend: ${comparison.trend} (${sign}${comparison.delta.score} since previous snapshot)`);
     if (comparison.improvements.length > 0) {
       lines.push(`  Fixed: ${comparison.improvements.join(', ')}`);
     }
@@ -306,6 +356,11 @@ function formatHistory(dir) {
     }
   }
 
+  if (history.length === 1) {
+    lines.push('');
+    lines.push(formatSnapshotBootstrap(dir, 'history'));
+  }
+
   return lines.join('\n');
 }
 
@@ -315,13 +370,13 @@ function exportTrendReport(dir) {
 
   const comparison = compareLatest(dir);
   const lines = [
-    '# Claude Code Setup Trend Report',
+    '# Nerviq Audit Snapshot Trend Report',
     '',
     `**Project:** ${path.basename(dir)}`,
     `**Generated:** ${new Date().toISOString().split('T')[0]}`,
-    `**Snapshots:** ${history.length}`,
+    `**Audit snapshots:** ${history.length}`,
     '',
-    '## Score History',
+    '## Audit Snapshot History',
     '',
     '| Date | Score | Passed | Checks |',
     '|------|-------|--------|--------|',
@@ -336,9 +391,9 @@ function exportTrendReport(dir) {
     lines.push('');
     lines.push('## Latest Comparison');
     lines.push('');
-    lines.push(`- **Previous:** ${comparison.previous.score}/100 (${comparison.previous.date?.split('T')[0]})`);
-    lines.push(`- **Current:** ${comparison.current.score}/100 (${comparison.current.date?.split('T')[0]})`);
-    lines.push(`- **Delta:** ${comparison.delta.score >= 0 ? '+' : ''}${comparison.delta.score} points`);
+    lines.push(`- **Previous snapshot score:** ${comparison.previous.score}/100 (${comparison.previous.date?.split('T')[0]})`);
+    lines.push(`- **Current snapshot score:** ${comparison.current.score}/100 (${comparison.current.date?.split('T')[0]})`);
+    lines.push(`- **Snapshot delta:** ${comparison.delta.score >= 0 ? '+' : ''}${comparison.delta.score} points`);
     lines.push(`- **Trend:** ${comparison.trend}`);
     if (comparison.improvements.length > 0) lines.push(`- **Fixed:** ${comparison.improvements.join(', ')}`);
     if (comparison.regressions.length > 0) lines.push(`- **New gaps:** ${comparison.regressions.join(', ')}`);
@@ -803,6 +858,7 @@ module.exports = {
   readSnapshotIndex,
   getHistory,
   compareLatest,
+  formatSnapshotBootstrap,
   formatHistory,
   exportTrendReport,
   readOutcomeIndex,