@nerviq/cli 1.9.0 → 1.11.0

package/src/audit.js

@@ -24,16 +24,18 @@ const { AiderProjectContext } = require('./aider/context');
 const { OPENCODE_TECHNIQUES } = require('./opencode/techniques');
 const { OpenCodeProjectContext } = require('./opencode/context');
 const { getBadgeMarkdown } = require('./badge');
-const { sendInsights, getLocalInsights } = require('./insights');
-const { getRecommendationOutcomeSummary, getRecommendationAdjustment } = require('./activity');
-const { getFeedbackSummary } = require('./feedback');
-const { formatSarif } = require('./formatters/sarif');
-const { formatOtelMetrics } = require('./formatters/otel');
-const { loadPlugins, mergePluginChecks } = require('./plugins');
-const { hasWorkspaceConfig, detectWorkspaceGlobs, detectWorkspaces } = require('./workspace');
-const { detectDeprecationWarnings } = require('./deprecation');
-const { version: packageVersion } = require('../package.json');
-const { t } = require('./i18n');
+const { sendInsights, getLocalInsights } = require('./insights');
+const { getRecommendationOutcomeSummary, getRecommendationAdjustment } = require('./activity');
+const { getFeedbackSummary } = require('./feedback');
+const { formatSarif } = require('./formatters/sarif');
+const { formatOtelMetrics } = require('./formatters/otel');
+const { collectAuditTerminology, formatTerminologyLines } = require('./terminology');
+const { loadPlugins, mergePluginChecks } = require('./plugins');
+const { hasWorkspaceConfig, detectWorkspaceGlobs, detectWorkspaces } = require('./workspace');
+const { detectDeprecationWarnings } = require('./deprecation');
+const { estimateTokenCount } = require('./token-estimate');
+const { version: packageVersion } = require('../package.json');
+const { t } = require('./i18n');
 
 const COLORS = {
   reset: '\x1b[0m',
@@ -64,8 +66,8 @@ function formatLocation(file, line) {
 
 const IMPACT_ORDER = { critical: 3, high: 2, medium: 1, low: 0 };
 const WEIGHTS = { critical: 15, high: 10, medium: 5, low: 2 };
-const LARGE_INSTRUCTION_WARN_BYTES = 50 * 1024;
-const LARGE_INSTRUCTION_SKIP_BYTES = 1024 * 1024;
+const LARGE_INSTRUCTION_WARN_TOKENS = 12000;
+const LARGE_INSTRUCTION_SKIP_TOKENS = 240000;
 const CATEGORY_MODULES = {
   memory: 'CLAUDE.md',
   quality: 'verification',
@@ -358,9 +360,13 @@ function getAuditSpec(platform = 'claude') {
   };
 }
 
-function normalizeRelativePath(filePath) {
-  return String(filePath || '').replace(/\\/g, '/').replace(/^\.\//, '');
-}
+function normalizeRelativePath(filePath) {
+  return String(filePath || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function formatCount(value) {
+  return Number(value || 0).toLocaleString('en-US');
+}
 
 function addPath(target, filePath) {
   if (!filePath || typeof filePath !== 'string') return;
@@ -454,25 +460,27 @@ function instructionFileCandidates(spec, ctx) {
   return [...candidates];
 }
 
-function inspectInstructionFiles(spec, ctx) {
-  const warnings = [];
-
-  for (const filePath of instructionFileCandidates(spec, ctx)) {
-    const byteCount = typeof ctx.fileSizeBytes === 'function' ? ctx.fileSizeBytes(filePath) : null;
-    if (!Number.isFinite(byteCount) || byteCount <= LARGE_INSTRUCTION_WARN_BYTES) continue;
-
-    const content = typeof ctx.fileContent === 'function' ? ctx.fileContent(filePath) : null;
-    warnings.push({
-      file: normalizeRelativePath(filePath),
-      byteCount,
-      lineCount: typeof content === 'string' ? content.split(/\r?\n/).length : null,
-      skipped: byteCount > LARGE_INSTRUCTION_SKIP_BYTES,
-      severity: byteCount > LARGE_INSTRUCTION_SKIP_BYTES ? 'critical' : 'warning',
-      message: byteCount > LARGE_INSTRUCTION_SKIP_BYTES
-        ? 'Instruction file exceeds 1MB and will be skipped during audit.'
-        : 'Instruction file exceeds 50KB. Audit will continue, but this file may reduce runtime clarity.',
-    });
-  }
+function inspectInstructionFiles(spec, ctx) {
+  const warnings = [];
+
+  for (const filePath of instructionFileCandidates(spec, ctx)) {
+    const content = typeof ctx.fileContent === 'function' ? ctx.fileContent(filePath) : null;
+    const byteCount = typeof ctx.fileSizeBytes === 'function' ? ctx.fileSizeBytes(filePath) : null;
+    const tokenCount = typeof content === 'string' ? estimateTokenCount(content) : null;
+    if (!Number.isFinite(tokenCount) || tokenCount <= LARGE_INSTRUCTION_WARN_TOKENS) continue;
+
+    warnings.push({
+      file: normalizeRelativePath(filePath),
+      byteCount,
+      tokenCount,
+      lineCount: typeof content === 'string' ? content.split(/\r?\n/).length : null,
+      skipped: tokenCount > LARGE_INSTRUCTION_SKIP_TOKENS,
+      severity: tokenCount > LARGE_INSTRUCTION_SKIP_TOKENS ? 'critical' : 'warning',
+      message: tokenCount > LARGE_INSTRUCTION_SKIP_TOKENS
+        ? 'Instruction file exceeds ~240,000 tokens and will be skipped during audit.'
+        : 'Instruction file exceeds ~12,000 tokens. Audit will continue, but this file may reduce runtime clarity.',
+    });
+  }
 
   return warnings;
 }
@@ -882,7 +890,7 @@ function printLiteAudit(result, dir) {
     console.log(colorize(`  Found: ${result.detectedConfigFiles.join(', ')}`, 'dim'));
   }
   console.log('');
-  console.log(`  ${t('audit.score', { score: colorize(`${result.score}/100`, 'bold'), passed: result.passed, total: result.passed + result.failed })}`);
+  console.log(`  ${t('audit.score', { score: colorize(`${result.score}/100`, 'bold'), passed: result.passed, total: result.passed + result.failed })}`);
 
   // Score explanation line (lite mode only)
   const _critCount = (result.results || []).filter(r => r.passed === false && r.impact === 'critical').length;
@@ -905,10 +913,11 @@ function printLiteAudit(result, dir) {
     scoreExplanation = t('audit.basic', { category: weakestCategory });
   } else {
     scoreExplanation = t('audit.early');
-  }
-  console.log(colorize(`  ${scoreExplanation}`, 'dim'));
-
-  if (result.platformScopeNote) {
+  }
+  console.log(colorize(`  ${scoreExplanation}`, 'dim'));
+  console.log(colorize('  Score type: live repo audit (current files only, not snapshot history or benchmark projection).', 'dim'));
+
+  if (result.platformScopeNote) {
     console.log(colorize(`  Scope: ${result.platformScopeNote.message}`, 'dim'));
   }
   if (result.workspaceHint && result.workspaceHint.workspaces.length > 0) {
@@ -920,11 +929,11 @@ function printLiteAudit(result, dir) {
       console.log(colorize(`     - ${item.title}: ${item.message}`, 'dim'));
     });
   }
-  if (result.largeInstructionFiles && result.largeInstructionFiles.length > 0) {
-    result.largeInstructionFiles.slice(0, 2).forEach((item) => {
-      console.log(colorize(`  Large file: ${item.file} (${Math.round(item.byteCount / 1024)}KB)`, 'yellow'));
-    });
-  }
+  if (result.largeInstructionFiles && result.largeInstructionFiles.length > 0) {
+    result.largeInstructionFiles.slice(0, 2).forEach((item) => {
+      console.log(colorize(`  Large file: ${item.file} (~${formatCount(item.tokenCount)} tokens)`, 'yellow'));
+    });
+  }
   console.log('');
 
   if (result.failed === 0) {
@@ -956,15 +965,23 @@ function printLiteAudit(result, dir) {
   console.log('');
   let usagePatterns;
   try { usagePatterns = require('./usage-patterns'); } catch { usagePatterns = null; }
-  result.liteSummary.topNextActions.forEach((item, index) => {
-    const tier = item.impact === 'critical' ? '🔴' : item.impact === 'high' ? '🟡' : '🔵';
-    const suppressed = usagePatterns && usagePatterns.getPriorityAdjustment(dir, item.key) === 'suppress';
-    const suffix = suppressed ? colorize(' (suppressed)', 'dim') : '';
-    console.log(`  ${index + 1}. ${tier} ${colorize(item.name, 'bold')}${suffix}`);
-    console.log(colorize(`     ${item.fix}`, 'dim'));
-  });
-  console.log('');
-  console.log(`  Ready? Run: ${colorize(result.suggestedNextCommand, 'bold')}`);
+  result.liteSummary.topNextActions.forEach((item, index) => {
+    const tier = item.impact === 'critical' ? '🔴' : item.impact === 'high' ? '🟡' : '🔵';
+    const suppressed = usagePatterns && usagePatterns.getPriorityAdjustment(dir, item.key) === 'suppress';
+    const suffix = suppressed ? colorize(' (suppressed)', 'dim') : '';
+    console.log(`  ${index + 1}. ${tier} ${colorize(item.name, 'bold')}${suffix}`);
+    console.log(colorize(`     ${item.fix}`, 'dim'));
+  });
+  console.log('');
+  const liteTerminology = formatTerminologyLines(collectAuditTerminology(result));
+  if (liteTerminology.length > 0) {
+    liteTerminology.forEach((line) => {
+      const color = line.startsWith('  Terms used here:') ? 'blue' : 'dim';
+      console.log(colorize(line, color));
+    });
+    console.log('');
+  }
+  console.log(`  Ready? Run: ${colorize(result.suggestedNextCommand, 'bold')}`);
   if (result.platform === 'codex') {
     console.log(colorize('  Note: Codex now supports no-write advisory flows via augment and suggest-only before setup/apply.', 'dim'));
   }
@@ -1053,12 +1070,12 @@ async function audit(options) {
       key: 'largeInstructionFile',
       id: null,
       name: 'Large instruction file warning',
-      category: 'performance',
-      impact: 'medium',
-      rating: null,
-      fix: 'Split oversized instruction files so they stay under 50KB, and keep any single instruction file below 1MB.',
-      sourceUrl: null,
-      confidence: 'high',
+      category: 'performance',
+      impact: 'medium',
+      rating: null,
+      fix: 'Split oversized instruction files so they stay under ~12,000 tokens, and keep any single instruction file below ~240,000 tokens.',
+      sourceUrl: null,
+      confidence: 'high',
       file: largeInstructionFiles[0].file,
       line: null,
       passed: null,
@@ -1126,12 +1143,13 @@ async function audit(options) {
     ...largeInstructionFiles.map((item) => ({
       kind: 'large-instruction-file',
       severity: item.severity,
-      message: item.message,
-      file: item.file,
-      lineCount: item.lineCount,
-      byteCount: item.byteCount,
-      skipped: item.skipped,
-    })),
+      message: item.message,
+      file: item.file,
+      lineCount: item.lineCount,
+      byteCount: item.byteCount,
+      tokenCount: item.tokenCount,
+      skipped: item.skipped,
+    })),
     ...deprecationWarnings.map((item) => ({
       kind: 'deprecated-feature',
       severity: 'warning',
@@ -1259,13 +1277,13 @@ async function audit(options) {
     console.log('');
   }
 
-  if (largeInstructionFiles.length > 0) {
-    console.log(colorize('  Large instruction files', 'yellow'));
-    for (const item of largeInstructionFiles) {
-      const sizeKb = Math.round(item.byteCount / 1024);
-      console.log(colorize(`     ${item.file} (${sizeKb}KB, ${item.lineCount || '?'} lines)`, 'bold'));
-      console.log(colorize(`     → ${item.message}`, 'dim'));
-    }
+  if (largeInstructionFiles.length > 0) {
+    console.log(colorize('  Large instruction files', 'yellow'));
+    for (const item of largeInstructionFiles) {
+      const sizeKb = Number.isFinite(item.byteCount) ? Math.round(item.byteCount / 1024) : '?';
+      console.log(colorize(`     ${item.file} (~${formatCount(item.tokenCount)} tokens, ${item.lineCount || '?'} lines, ${sizeKb}KB)`, 'bold'));
+      console.log(colorize(`     → ${item.message}`, 'dim'));
+    }
     console.log('');
   }
 
@@ -1365,8 +1383,8 @@ async function audit(options) {
   }
 
   // Top next actions
-  if (topNextActions.length > 0) {
-    console.log(colorize('  ⚡ Top 5 Next Actions', 'magenta'));
+  if (topNextActions.length > 0) {
+    console.log(colorize('  ⚡ Top 5 Next Actions', 'magenta'));
     for (let i = 0; i < topNextActions.length; i++) {
       const item = topNextActions[i];
       console.log(`     ${i + 1}. ${colorize(item.name, 'bold')}`);
@@ -1382,11 +1400,20 @@ async function audit(options) {
         console.log(colorize(`        Feedback: accepted ${item.feedback.accepted}, rejected ${item.feedback.rejected}, positive ${item.feedback.positive}, negative ${item.feedback.negative}${avgDelta}`, 'dim'));
       }
       console.log(colorize(`        Fix: ${item.fix}`, 'dim'));
-    }
-    console.log('');
-  }
-
-  // Summary
+    }
+    console.log('');
+  }
+
+  const terminology = formatTerminologyLines(collectAuditTerminology(result));
+  if (terminology.length > 0) {
+    terminology.forEach((line) => {
+      const color = line.startsWith('  Terms used here:') ? 'blue' : 'dim';
+      console.log(colorize(line, color));
+    });
+    console.log('');
+  }
+
+  // Summary
   console.log(colorize('  ─────────────────────────────────────', 'dim'));
   const deprecatedNote = deprecated.length > 0 ? colorize(`, ${deprecated.length} deprecated`, 'dim') : '';
   console.log(`  ${colorize(`${passed.length}/${applicable.length}`, 'bold')} checks passing${skipped.length > 0 ? colorize(` (${skipped.length} not applicable${deprecatedNote})`, 'dim') : (deprecatedNote ? colorize(` (${deprecatedNote})`, 'dim') : '')}`);

package/src/auto-suggest.js

@@ -52,23 +52,72 @@ function analyzeSuggestions(dir) {
     .sort((a, b) => b[1] - a[1])
     .map(([key, count]) => ({ key, failCount: count, auditCount: auditSnapshots.length }));
 
-  return { totalEvents, auditCount: auditSnapshots.length, suggestedRules, suggestedSuppressions, suggestedPriorities };
+  const hasSuggestions = suggestedRules.length > 0 || suggestedSuppressions.length > 0 || suggestedPriorities.length > 0;
+  let bootstrap = { ready: true, state: 'ready', message: null, steps: [] };
+
+  if (totalEvents === 0 && auditSnapshots.length === 0) {
+    bootstrap = {
+      ready: false,
+      state: 'empty',
+      message: 'No local usage or snapshot history exists yet.',
+      steps: [
+        'Run `nerviq audit --snapshot` to save the baseline.',
+        'Use `nerviq fix`, `nerviq fix --all-critical`, or `nerviq feedback` to record recommendation outcomes.',
+        'Run `nerviq audit --snapshot` again after a meaningful repo change.',
+        'Re-run `nerviq suggest-rules`.',
+      ],
+    };
+  } else if (!hasSuggestions && totalEvents === 0 && auditSnapshots.length > 0) {
+    bootstrap = {
+      ready: false,
+      state: 'snapshots-only',
+      message: `${auditSnapshots.length} audit snapshot(s) exist, but no recommendation outcomes have been recorded yet.`,
+      steps: [
+        'Run `nerviq fix` or `nerviq feedback` so Nerviq can learn which recommendations you accept or reject.',
+        'Re-run `nerviq suggest-rules` after another fix cycle.',
+      ],
+    };
+  } else if (!hasSuggestions && totalEvents > 0 && auditSnapshots.length === 0) {
+    bootstrap = {
+      ready: false,
+      state: 'patterns-only',
+      message: `${totalEvents} usage event(s) exist, but no audit snapshots have been saved yet.`,
+      steps: [
+        'Run `nerviq audit --snapshot` to save the baseline.',
+        'Run it again after changes so repeated failures can be prioritized.',
+        'Re-run `nerviq suggest-rules`.',
+      ],
+    };
+  } else if (!hasSuggestions) {
+    bootstrap = {
+      ready: false,
+      state: 'warming-up',
+      message: `Nerviq has some local history (${totalEvents} pattern events, ${auditSnapshots.length} audit snapshots), but not enough repeated signals yet.`,
+      steps: [
+        'Keep saving snapshots with `nerviq audit --snapshot`.',
+        'Keep recording outcomes with `nerviq fix` or `nerviq feedback`.',
+        'Re-run `nerviq suggest-rules` after another change cycle.',
+      ],
+    };
+  }
+
+  return { totalEvents, auditCount: auditSnapshots.length, suggestedRules, suggestedSuppressions, suggestedPriorities, bootstrap };
 }
 
 /**
  * Format suggestions for CLI output.
  */
 function formatSuggestions(suggestions) {
-  const { totalEvents, auditCount, suggestedRules, suggestedSuppressions, suggestedPriorities } = suggestions;
-
-  if (totalEvents === 0 && auditCount === 0) {
-    return '  No usage data yet. Run nerviq fix or nerviq audit to build pattern history.';
-  }
+  const { totalEvents, auditCount, suggestedRules, suggestedSuppressions, suggestedPriorities, bootstrap } = suggestions;
 
   const sources = [];
   if (totalEvents > 0) sources.push(`${totalEvents} pattern events`);
   if (auditCount > 0) sources.push(`${auditCount} audit snapshots`);
-  const lines = [`  Auto-Suggested Rules (based on ${sources.join(', ')}):`];
+  const lines = [
+    sources.length > 0
+      ? `  Auto-Suggested Rules (based on ${sources.join(', ')}):`
+      : '  Auto-Suggested Rules:',
+  ];
 
   if (suggestedRules.length > 0) {
     lines.push('', '  Suggested as required (always accepted):');
@@ -91,8 +140,12 @@ function formatSuggestions(suggestions) {
     }
   }
 
-  if (suggestedRules.length === 0 && suggestedSuppressions.length === 0 && suggestedPriorities.length === 0) {
-    lines.push('', '  No strong patterns detected yet. Keep using nerviq fix and audit to build history.');
+  if (suggestedRules.length === 0 && suggestedSuppressions.length === 0 && suggestedPriorities.length === 0 && bootstrap && !bootstrap.ready) {
+    lines.push('', `  ${bootstrap.message}`);
+    lines.push('  Bootstrap it with:');
+    for (let i = 0; i < bootstrap.steps.length; i++) {
+      lines.push(`  ${i + 1}. ${bootstrap.steps[i]}`);
+    }
   }
 
   return lines.join('\n');

package/src/benchmark.js

@@ -2,11 +2,12 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
-const { version } = require('../package.json');
-const { audit } = require('./audit');
-const { setup } = require('./setup');
-const { analyzeProject } = require('./analyze');
-const { getGovernanceSummary } = require('./governance');
+const { version } = require('../package.json');
+const { audit } = require('./audit');
+const { setup } = require('./setup');
+const { analyzeProject } = require('./analyze');
+const { getGovernanceSummary } = require('./governance');
+const { formatTerminologyLines } = require('./terminology');
 
 function copyProject(sourceDir, targetDir) {
   fs.mkdirSync(targetDir, { recursive: true });
@@ -201,31 +202,36 @@ function buildCaseStudy(before, after, applyResult) {
   };
 }
 
-function renderBenchmarkMarkdown(report) {
-  return [
-    '# NERVIQ CLI Benchmark Report',
-    '',
-    `- Generated by: ${report.generatedBy}`,
-    `- Created at: ${report.createdAt}`,
-    `- Source repo: ${report.directory}`,
-    '',
-    '## Methodology',
-    ...report.methodology.map(item => `- ${item}`),
-    '',
-    '## Before',
-    `- Score: ${report.before.score}/100`,
-    `- Organic score: ${report.before.organicScore}/100`,
-    `- Passing checks: ${report.before.passed}/${report.before.checkCount}`,
-    '',
-    '## After',
-    `- Score: ${report.after.score}/100`,
-    `- Organic score: ${report.after.organicScore}/100`,
-    `- Passing checks: ${report.after.passed}/${report.after.checkCount}`,
-    '',
-    '## Delta',
-    `- Score delta: ${report.delta.score}`,
-    `- Organic score delta: ${report.delta.organicScore}`,
-    `- Passed checks delta: ${report.delta.passed}`,
+function renderBenchmarkMarkdown(report) {
+  return [
+    '# NERVIQ CLI Benchmark Report',
+    '',
+    `- Generated by: ${report.generatedBy}`,
+    `- Created at: ${report.createdAt}`,
+    `- Source repo: ${report.directory}`,
+    '',
+    '## Score Semantics',
+    `- Baseline live audit score: ${report.scoreSemantics.baseline}`,
+    `- Projected benchmark score: ${report.scoreSemantics.projected}`,
+    `- Organic score: ${report.scoreSemantics.organic}`,
+    '',
+    '## Methodology',
+    ...report.methodology.map(item => `- ${item}`),
+    '',
+    '## Baseline (Live Repo)',
+    `- Live audit score: ${report.before.score}/100`,
+    `- Organic live score: ${report.before.organicScore}/100`,
+    `- Passing checks: ${report.before.passed}/${report.before.checkCount}`,
+    '',
+    '## Projected (Isolated Benchmark Copy)',
+    `- Projected benchmark score: ${report.after.score}/100`,
+    `- Projected organic score: ${report.after.organicScore}/100`,
+    `- Passing checks: ${report.after.passed}/${report.after.checkCount}`,
+    '',
+    '## Delta',
+    `- Projected score delta: ${report.delta.score}`,
+    `- Projected organic score delta: ${report.delta.organicScore}`,
+    `- Passed checks delta: ${report.delta.passed}`,
     '',
     '## Executive Summary',
     `- ${report.executiveSummary.headline}`,
@@ -285,9 +291,14 @@ async function runBenchmark(options) {
       schemaVersion: 1,
       generatedBy: `nerviq@${version}`,
       createdAt: new Date().toISOString(),
-      directory: sourceDir,
-      platform,
-      methodology: [
+      directory: sourceDir,
+      platform,
+      scoreSemantics: {
+        baseline: 'current repo state before benchmark runs',
+        projected: 'starter-safe post-setup score measured on an isolated temp copy',
+        organic: 'repo-owned config quality excluding starter-generated Nerviq assets',
+      },
+      methodology: [
         'Run a baseline audit on the source repo.',
         'Copy the repo into a temporary isolated workspace.',
         `Apply starter-safe ${platform === 'codex' ? 'Codex' : 'Claude'} artifacts only on the isolated copy.`,
@@ -316,24 +327,29 @@ function printBenchmark(report, options = {}) {
     return;
   }
 
-  console.log('');
-  console.log('  nerviq benchmark');
-  console.log('  ═══════════════════════════════════════');
-  console.log('  Runs in an isolated temp copy. Your current repo is not modified.');
-  console.log('');
-  const orgDeltaSign = report.delta.organicScore >= 0 ? '+' : '';
-  const totalDeltaSign = report.delta.score >= 0 ? '+' : '';
-  console.log(`  Organic improvement: \x1b[1m${orgDeltaSign}${report.delta.organicScore} points\x1b[0m (your actual config quality)`);
-  console.log(`  Total with nerviq setup: ${totalDeltaSign}${report.delta.score} points`);
-  console.log('');
-  console.log(`  Before:  organic ${report.before.organicScore}/100, total ${report.before.score}/100`);
-  console.log(`  After:   organic ${report.after.organicScore}/100, total ${report.after.score}/100`);
-  console.log('');
-  console.log(`  ${report.executiveSummary.headline}`);
-  console.log(`  Recommendation: ${report.executiveSummary.decisionGuidance}`);
-  console.log(`  Workflow evidence: ${report.workflowEvidence.summary.passed}/${report.workflowEvidence.summary.total} tasks (${report.workflowEvidence.summary.coverageScore}%)`);
-  console.log('');
-}
+  console.log('');
+  console.log('  nerviq benchmark');
+  console.log('  ═══════════════════════════════════════');
+  console.log('  Runs in an isolated temp copy. Your current repo is not modified.');
+  console.log('  Score type: baseline = live repo audit, projected = isolated post-setup benchmark.');
+  console.log('');
+  const orgDeltaSign = report.delta.organicScore >= 0 ? '+' : '';
+  const totalDeltaSign = report.delta.score >= 0 ? '+' : '';
+  console.log(`  Projected organic delta: \x1b[1m${orgDeltaSign}${report.delta.organicScore} points\x1b[0m (repo-owned config quality)`);
+  console.log(`  Projected total delta with nerviq setup: ${totalDeltaSign}${report.delta.score} points`);
+  console.log('');
+  console.log(`  Baseline live audit:      organic ${report.before.organicScore}/100, total ${report.before.score}/100`);
+  console.log(`  Projected after setup:    organic ${report.after.organicScore}/100, total ${report.after.score}/100`);
+  console.log('');
+  console.log(`  ${report.executiveSummary.headline}`);
+  console.log(`  Recommendation: ${report.executiveSummary.decisionGuidance}`);
+  console.log(`  Workflow evidence: ${report.workflowEvidence.summary.passed}/${report.workflowEvidence.summary.total} tasks (${report.workflowEvidence.summary.coverageScore}%)`);
+  console.log('');
+  for (const line of formatTerminologyLines(['governance', 'hooks', 'mcp'])) {
+    console.log(line);
+  }
+  console.log('');
+}
 
 function writeBenchmarkReport(report, outFile) {
   fs.mkdirSync(path.dirname(outFile), { recursive: true });

package/src/dashboard.js

@@ -68,7 +68,7 @@ function buildScoreOverTimeSvg(history) {
 
   return `
   <div class="card">
-    <h2>Score Over Time</h2>
+    <h2>Audit Snapshot Score Over Time</h2>
     <svg viewBox="0 0 ${w} ${h}" width="100%" style="max-width:${w}px">
       ${yLabels}
       <polyline points="${polyline}" fill="none" stroke="${COLORS.blue}" stroke-width="2"/>
@@ -119,11 +119,28 @@ function buildCategoryBreakdownSvg(results) {
   </div>`;
 }
 
+function getDashboardScoreMeta(history) {
+  if (history && history.length > 0) {
+    return {
+      label: 'Latest audit snapshot score',
+      note: 'Dashboard is anchored to the most recent saved audit snapshot. Trend and drift sections use audit snapshots only.',
+      consoleSource: 'latest audit snapshot',
+    };
+  }
+
+  return {
+    label: 'Live audit score',
+    note: 'No saved audit snapshots found, so this dashboard ran a live audit of the current repo. Run `nerviq audit --snapshot` to build history.',
+    consoleSource: 'live audit (no snapshots yet)',
+  };
+}
+
 function buildHtml(projectName, auditPayload, history) {
   const score = auditPayload.score ?? 0;
   const platform = auditPayload.platform || 'unknown';
   const results = auditPayload.results || [];
   const timestamp = new Date().toISOString();
+  const scoreMeta = getDashboardScoreMeta(history);
 
   // Top 5 failed checks sorted by impact severity
   const impactOrder = { critical: 0, high: 1, medium: 2, low: 3 };
@@ -184,7 +201,8 @@ function buildHtml(projectName, auditPayload, history) {
 
   <div class="card score-card">
     <div class="score-number" style="color:${scoreColor(score)}">${score}</div>
-    <div class="score-label">out of 100</div>
+    <div class="score-label">${escapeHtml(scoreMeta.label)}</div>
+    <div style="color:${COLORS.textDim};font-size:.85rem;margin-top:.75rem;max-width:520px;margin-left:auto;margin-right:auto">${escapeHtml(scoreMeta.note)}</div>
   </div>
 
   <div class="card">
@@ -238,6 +256,7 @@ async function generateDashboard(dir, flags = {}) {
     auditPayload = await audit({ dir, silent: true, platform: flags.platform || 'claude' });
   }
 
+  const scoreMeta = getDashboardScoreMeta(history);
   const html = buildHtml(projectName, auditPayload, history);
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
   fs.writeFileSync(outputPath, html, 'utf8');
@@ -247,8 +266,9 @@ async function generateDashboard(dir, flags = {}) {
     console.log('');
     console.log('  nerviq dashboard');
     console.log('  \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550');
-    console.log(`  Score: ${auditPayload.score ?? '?'}/100`);
-    console.log(`  Snapshots: ${history.length}`);
+    console.log(`  Dashboard score: ${auditPayload.score ?? '?'}/100`);
+    console.log(`  Score source: ${scoreMeta.consoleSource}`);
+    console.log(`  Audit snapshots: ${history.length}`);
     console.log(`  Output: ${relPath}`);
     console.log('');
   }
@@ -261,7 +281,7 @@ async function generateDashboard(dir, flags = {}) {
     exec(cmd);
   }
 
-  return { outputPath, relativePath: relPath, score: auditPayload.score };
+  return { outputPath, relativePath: relPath, score: auditPayload.score, scoreSource: scoreMeta.consoleSource };
 }
 
 /**
@@ -274,13 +294,15 @@ function detectDrifts(history, threshold = 5) {
   for (let i = 0; i < history.length - 1; i++) {
     const current = history[i];
     const previous = history[i + 1];
-    if (current.score != null && previous.score != null) {
-      const delta = current.score - previous.score;
+    const currentScore = current.summary?.score;
+    const previousScore = previous.summary?.score;
+    if (currentScore != null && previousScore != null) {
+      const delta = currentScore - previousScore;
       if (Math.abs(delta) >= threshold) {
         drifts.push({
-          date: current.date || current.timestamp,
-          from: previous.score,
-          to: current.score,
+          date: current.createdAt || current.date || current.timestamp,
+          from: previousScore,
+          to: currentScore,
           delta,
         });
       }
@@ -307,8 +329,8 @@ function buildDriftAlertsHtml(drifts) {
 
   return `
     <div style="margin-top:32px">
-      <h2 style="color:${COLORS.text};font-size:18px;margin-bottom:12px">⚠ Score Drift Alerts</h2>
-      <p style="color:${COLORS.textDim};font-size:13px;margin-bottom:12px">Changes of 5+ points between consecutive snapshots</p>
+      <h2 style="color:${COLORS.text};font-size:18px;margin-bottom:12px">⚠ Audit Snapshot Drift Alerts</h2>
+      <p style="color:${COLORS.textDim};font-size:13px;margin-bottom:12px">Changes of 5+ points between consecutive audit snapshots</p>
       <table style="width:100%;border-collapse:collapse;background:${COLORS.surface};border-radius:8px;overflow:hidden">
         <thead><tr style="background:${COLORS.border}">
           <th style="padding:8px 12px;text-align:left;color:${COLORS.textDim};font-size:12px">Date</th>
@@ -375,7 +397,7 @@ function buildPortfolioHtml(repoResults) {
 
   <div class="card score-card">
     <div class="score-number" style="color:${scoreColor(avgScore)}">${avgScore}</div>
-    <div class="score-label">average score across ${repoResults.length} repos</div>
+    <div class="score-label">average live audit score across ${repoResults.length} repos</div>
   </div>
 
   <div class="highlights">
@@ -452,7 +474,7 @@ async function generatePortfolioDashboard(repoPaths, flags = {}) {
     console.log('  nerviq portfolio dashboard');
     console.log('  \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550');
     console.log(`  Repos: ${repoResults.length}`);
-    console.log(`  Average score: ${avgScore}/100`);
+    console.log(`  Average live audit score: ${avgScore}/100`);
     console.log(`  Output: ${outputPath}`);
     console.log('');
   }