@rune-kit/rune 2.18.1 → 2.20.0

package/compiler/__tests__/governance-collector.test.js

@@ -0,0 +1,376 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import { assembleGovernance } from '../governance-collector.js';
+
+// ─── Test Helpers ───
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function sessionEntry(overrides = {}) {
+  return {
+    id: `s-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+    date: today(),
+    duration_min: 10,
+    tool_calls: 20,
+    skill_invocations: 3,
+    skills_used: ['cook', 'plan', 'scout'],
+    primary_skill: 'cook',
+    models_used: { sonnet: 2 },
+    ...overrides,
+  };
+}
+
+async function setupMetrics(tmpDir, sessions = [], skillTotals = null) {
+  const metricsDir = path.join(tmpDir, '.rune', 'metrics');
+  await mkdir(metricsDir, { recursive: true });
+
+  if (sessions.length > 0) {
+    const lines = `${sessions.map((s) => JSON.stringify(s)).join('\n')}\n`;
+    await writeFile(path.join(metricsDir, 'sessions.jsonl'), lines);
+  }
+
+  if (skillTotals) {
+    await writeFile(
+      path.join(metricsDir, 'skills.json'),
+      JSON.stringify({ version: 1, updated: new Date().toISOString(), skills: skillTotals }),
+    );
+  }
+}
+
+// ─── Tests ───
+
+describe('assembleGovernance — empty state', () => {
+  let tmpDir;
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(path.join(os.tmpdir(), 'rune-gov-test-'));
+  });
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns a valid object shape when no metrics exist', async () => {
+    const result = await assembleGovernance(tmpDir, 30);
+
+    assert.ok(typeof result === 'object' && result !== null, 'should return an object');
+    assert.ok(typeof result.generated_at === 'string', 'generated_at should be a string');
+    assert.ok(Array.isArray(result.gates), 'gates should be an array');
+    assert.ok(Array.isArray(result.signals), 'signals should be an array');
+    assert.ok(Array.isArray(result.compliance), 'compliance should be an array');
+    assert.ok(Array.isArray(result.decisions), 'decisions should be an array');
+  });
+
+  it('generated_at is a valid ISO date-time string', async () => {
+    const result = await assembleGovernance(tmpDir, 30);
+    const parsed = new Date(result.generated_at);
+    assert.ok(!Number.isNaN(parsed.getTime()), 'generated_at must be parseable as a date');
+  });
+
+  it('window_days reflects the days parameter', async () => {
+    const result = await assembleGovernance(tmpDir, 14);
+    assert.equal(result.window_days, 14);
+  });
+
+  it('returns empty arrays when no data exists', async () => {
+    const result = await assembleGovernance(tmpDir, 30);
+    assert.deepEqual(result.gates, []);
+    assert.deepEqual(result.decisions, []);
+  });
+});
+
+describe('assembleGovernance — gate skill counting', () => {
+  let tmpDir;
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(path.join(os.tmpdir(), 'rune-gov-test-'));
+  });
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('counts sentinel invocations from sessions', async () => {
+    await setupMetrics(tmpDir, [
+      sessionEntry({ skills_used: ['cook', 'sentinel', 'plan'] }),
+      sessionEntry({ skills_used: ['sentinel', 'preflight'] }),
+      sessionEntry({ skills_used: ['cook', 'debug'] }),
+    ]);
+
+    const result = await assembleGovernance(tmpDir, 30);
+    const sentinelGate = result.gates.find((g) => g.name === 'sentinel');
+    assert.ok(sentinelGate, 'sentinel gate should be in gates[]');
+    assert.equal(sentinelGate.fired, 2);
+  });
+
+  it('counts preflight invocations correctly', async () => {
+    await setupMetrics(tmpDir, [
+      sessionEntry({ skills_used: ['preflight', 'cook'] }),
+      sessionEntry({ skills_used: ['preflight'] }),
+    ]);
+
+    const result = await assembleGovernance(tmpDir, 30);
+    const preflightGate = result.gates.find((g) => g.name === 'preflight');
+    assert.ok(preflightGate, 'preflight gate should be in gates[]');
+    assert.equal(preflightGate.fired, 2);
+  });
+
+  it('includes multiple gate skills in one result', async () => {
+    await setupMetrics(tmpDir, [
+      sessionEntry({
+        skills_used: ['sentinel', 'preflight', 'completion-gate', 'logic-guardian', 'cook'],
+      }),
+    ]);
+
+    const result = await assembleGovernance(tmpDir, 30);
+    const gateNames = result.gates.map((g) => g.name);
+    assert.ok(gateNames.includes('sentinel'), 'sentinel should appear');
+    assert.ok(gateNames.includes('preflight'), 'preflight should appear');
+    assert.ok(gateNames.includes('completion-gate'), 'completion-gate should appear');
+    assert.ok(gateNames.includes('logic-guardian'), 'logic-guardian should appear');
+  });
+
+  it('omits non-gate skills from gates[]', async () => {
+    await setupMetrics(tmpDir, [sessionEntry({ skills_used: ['cook', 'plan', 'scout', 'debug'] })]);
+
+    const result = await assembleGovernance(tmpDir, 30);
+    const nonGateInGates = result.gates.filter(
+      (g) =>
+        ![
+          'sentinel',
+          'sentinel-env',
+          'preflight',
+          'completion-gate',
+          'logic-guardian',
+          'constraint-check',
+          'hallucination-guard',
+          'integrity-check',
+        ].includes(g.name),
+    );
+    assert.equal(nonGateInGates.length, 0, 'no non-gate skills should appear in gates[]');
+  });
+
+  it('gate entries have required schema fields', async () => {
+    await setupMetrics(tmpDir, [sessionEntry({ skills_used: ['sentinel'] })]);
+
+    const result = await assembleGovernance(tmpDir, 30);
+    const gate = result.gates[0];
+    assert.ok(Object.hasOwn(gate, 'name'));
+    assert.ok(Object.hasOwn(gate, 'fired'));
+    assert.ok(Object.hasOwn(gate, 'passed'));
+    assert.ok(Object.hasOwn(gate, 'bypassed'));
+    assert.ok(Object.hasOwn(gate, 'blocked'));
+    assert.equal(typeof gate.fired, 'number');
+    // passed/bypassed remain 0 — not observable at the hook layer (GAP-1)
+    assert.equal(gate.passed, 0, 'passed must be 0 (GAP-1: no outcome capture)');
+    assert.equal(gate.bypassed, 0, 'bypassed must be 0 (GAP-1: no outcome capture)');
+    // blocked IS captured when gate-outcomes.jsonl is present (Phase 3).
+    // In this test there is no fixture, so blocked === 0.
+    assert.equal(gate.blocked, 0, 'blocked must be 0 when no gate-outcomes.jsonl fixture is present');
+  });
+
+  it('surfaces blocked count from gate-outcomes.jsonl (HIGH-1 regression)', async () => {
+    // Arrange: write a gate-outcomes.jsonl with 3 blocked events for "privacy-mesh".
+    // "privacy-mesh" is NOT in GATE_SKILLS, so this test specifically exercises the
+    // HIGH-1 fix: gateOutcomes.keys() must be included in allGateNames.
+    const metricsDir = path.join(tmpDir, '.rune', 'metrics');
+    await mkdir(metricsDir, { recursive: true });
+
+    const ts1 = '2026-06-01T10:00:00.000Z';
+    const ts2 = '2026-06-02T11:00:00.000Z';
+    const ts3 = '2026-06-03T12:00:00.000Z';
+    const lines = `${[
+      JSON.stringify({ ts: ts1, gate: 'privacy-mesh', outcome: 'blocked', detail: 'file matched BLOCK-tier' }),
+      JSON.stringify({ ts: ts2, gate: 'privacy-mesh', outcome: 'blocked', detail: 'file matched BLOCK-tier' }),
+      JSON.stringify({ ts: ts3, gate: 'privacy-mesh', outcome: 'blocked', detail: 'file matched BLOCK-tier' }),
+    ].join('\n')}\n`;
+    await writeFile(path.join(metricsDir, 'gate-outcomes.jsonl'), lines);
+
+    // Act
+    const result = await assembleGovernance(tmpDir, 30);
+
+    // Assert: privacy-mesh must appear in gates[] with blocked=3 and a non-null ts
+    const pmGate = result.gates.find((g) => g.name === 'privacy-mesh');
+    assert.ok(pmGate, 'privacy-mesh gate must appear in gates[] when it has blocked events');
+    assert.equal(pmGate.blocked, 3, 'blocked must equal the number of blocked outcome records');
+    assert.ok(pmGate.ts !== null && typeof pmGate.ts === 'string', 'ts must be non-null when blocked events exist');
+    assert.equal(pmGate.ts, ts3, 'ts must be the most-recent blocked event timestamp');
+    // fired and passed/bypassed are 0 — no sessions or skills.json for this gate
+    assert.equal(pmGate.fired, 0, 'fired must be 0 when gate has no session/skills.json data');
+  });
+
+  it('reads gate counts from skills.json totals when no windowed sessions', async () => {
+    // No sessions — but skills.json says sentinel ran 5 times globally.
+    // skills.json uses the REAL producer shape: { skill: { total_invocations, last_used } }.
+    await setupMetrics(tmpDir, [], {
+      sentinel: { total_invocations: 5, last_used: today() },
+      cook: { total_invocations: 10, last_used: today() },
+    });
+
+    const result = await assembleGovernance(tmpDir, 30);
+    const sentinelGate = result.gates.find((g) => g.name === 'sentinel');
+    assert.ok(sentinelGate, 'sentinel should appear from skills.json totals');
+    assert.equal(sentinelGate.fired, 5, 'fired must come from total_invocations');
+    assert.ok(sentinelGate.ts, 'ts should be derived from last_used');
+    // cook is not a gate skill — should not appear
+    const cookGate = result.gates.find((g) => g.name === 'cook');
+    assert.equal(cookGate, undefined, 'cook should not appear in gates[]');
+  });
+});
+
+describe('assembleGovernance — signals from static mesh', () => {
+  let tmpDir;
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(path.join(os.tmpdir(), 'rune-gov-test-'));
+  });
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('signals[] is an array (may be empty if skills dir missing)', async () => {
+    const result = await assembleGovernance(tmpDir, 30);
+    assert.ok(Array.isArray(result.signals));
+  });
+
+  it('does not throw when skills/ dir is missing', async () => {
+    // tmpDir has no skills/ — should degrade to []
+    const result = await assembleGovernance(tmpDir, 30);
+    assert.deepEqual(result.signals, []);
+  });
+
+  it('signal entries have required fields when signals exist', async () => {
+    // Create a minimal skills/ dir with one SKILL.md that has signals
+    const skillsDir = path.join(tmpDir, 'skills', 'test-skill');
+    await mkdir(skillsDir, { recursive: true });
+    const skillContent = `---
+name: test-skill
+description: A test skill
+metadata:
+  version: "0.1.0"
+  layer: L2
+  emit: test.signal.done
+  listen: test.signal.start
+---
+# test-skill
+A minimal skill for testing.
+`;
+    await writeFile(path.join(skillsDir, 'SKILL.md'), skillContent);
+
+    const result = await assembleGovernance(tmpDir, 30);
+    // Signals array may be empty if the visualizer cannot fully parse, but it should not throw
+    assert.ok(Array.isArray(result.signals));
+    // If signals populated, verify shape
+    for (const sig of result.signals) {
+      assert.ok(typeof sig.name === 'string', 'signal must have a name');
+      assert.ok(Object.hasOwn(sig, 'count'), 'signal must have count field');
+      assert.equal(typeof sig.count, 'number');
+    }
+  });
+});
+
+describe('assembleGovernance — compliance from Business packs', () => {
+  // Isolation: a single temp ROOT holds both the Free-side runeRoot and the
+  // Business sibling, so the collector's `runeRoot/../Business` resolution works
+  // AND the whole tree is cleaned up — never pollutes the shared os.tmpdir().
+  let root, runeRoot;
+  beforeEach(async () => {
+    root = await mkdtemp(path.join(os.tmpdir(), 'rune-gov-root-'));
+    runeRoot = path.join(root, 'Free');
+    await mkdir(runeRoot, { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it('returns empty compliance[] when no Business dir exists', async () => {
+    const result = await assembleGovernance(runeRoot, 30);
+    assert.deepEqual(result.compliance, []);
+  });
+
+  it('extracts MUST constraints from a Business PACK.md', async () => {
+    const bizRoot = path.join(root, 'Business', 'extensions', 'pro-test-pack');
+    await mkdir(bizRoot, { recursive: true });
+
+    const packContent = `---
+name: "@rune-pro/test-pack"
+metadata:
+  version: "1.0.0"
+---
+# @rune-pro/test-pack
+
+## Constraints
+
+1. MUST verify user permissions before returning data
+2. MUST NOT make changes without approval
+3. NEVER log sensitive credentials
+
+## Done When
+
+- [ ] At least one system connected (verified via health check)
+- [x] All permissions verified
+`;
+    await writeFile(path.join(bizRoot, 'PACK.md'), packContent);
+
+    const result = await assembleGovernance(runeRoot, 30);
+
+    assert.ok(Array.isArray(result.compliance));
+    const mustItems = result.compliance.filter(
+      (c) => c.obligation.startsWith('MUST') || c.obligation.startsWith('NEVER'),
+    );
+    assert.ok(mustItems.length >= 2, 'should extract MUST/NEVER constraints');
+
+    for (const item of result.compliance) {
+      assert.ok(typeof item.pack === 'string');
+      assert.ok(typeof item.obligation === 'string');
+      assert.ok(['met', 'partial', 'gap', 'unknown'].includes(item.status));
+    }
+  });
+});
+
+describe('assembleGovernance — error resilience', () => {
+  let tmpDir;
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(path.join(os.tmpdir(), 'rune-gov-test-'));
+  });
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('does not throw when sessions.jsonl contains invalid JSON lines', async () => {
+    const metricsDir = path.join(tmpDir, '.rune', 'metrics');
+    await mkdir(metricsDir, { recursive: true });
+    await writeFile(
+      path.join(metricsDir, 'sessions.jsonl'),
+      `${JSON.stringify(sessionEntry({ skills_used: ['sentinel'] }))}\nNOT_JSON\n${JSON.stringify(sessionEntry())}\n`,
+    );
+
+    const result = await assembleGovernance(tmpDir, 30);
+    assert.ok(result, 'should not throw on malformed JSONL');
+    assert.ok(Array.isArray(result.gates));
+  });
+
+  it('does not throw when skills.json is corrupted', async () => {
+    const metricsDir = path.join(tmpDir, '.rune', 'metrics');
+    await mkdir(metricsDir, { recursive: true });
+    await writeFile(path.join(metricsDir, 'skills.json'), 'NOT_JSON');
+
+    const result = await assembleGovernance(tmpDir, 30);
+    assert.ok(result);
+    assert.ok(Array.isArray(result.gates));
+  });
+
+  it('does not throw when .rune/ directory does not exist', async () => {
+    // tmpDir exists but has no .rune/ subdirectory
+    const result = await assembleGovernance(tmpDir, 30);
+    assert.ok(result);
+    assert.ok(typeof result.generated_at === 'string');
+    assert.deepEqual(result.gates, []);
+  });
+
+  it('decisions[] is always an empty array in Phase 1', async () => {
+    await setupMetrics(tmpDir, [sessionEntry({ skills_used: ['sentinel'] })]);
+    const result = await assembleGovernance(tmpDir, 30);
+    assert.deepEqual(result.decisions, [], 'decisions must be [] until provenance capture is added (GAP-5)');
+  });
+});

package/compiler/__tests__/setup.test.js

@@ -42,6 +42,11 @@ async function seedFakeRuneRoot(root) {
 }
 
 beforeEach(async () => {
+  // Clear tier env vars BEFORE each test so detection-isolation tests are
+  // deterministic regardless of the operator's shell (e.g. a dev with
+  // RUNE_PRO_ROOT set). afterEach also clears them.
+  delete process.env.RUNE_PRO_ROOT;
+  delete process.env.RUNE_BUSINESS_ROOT;
   tmpRoot = await mkdtemp(path.join(tmpdir(), 'rune-setup-'));
   await mkdir(path.join(tmpRoot, 'project'), { recursive: true });
 });

package/compiler/analytics.js

@@ -6,6 +6,11 @@
  *
  * Upgrade path: swap readJsonl() with DuckDB queries when data
  * volume exceeds ~1000 sessions (currently capped at 100).
+ *
+ * NOTE (metric scale): `tool_calls` semantics changed when context-watch widened
+ * its matcher from Edit|Write to all tools. Rows written before that change are
+ * Edit/Write-scaled (~2-3x lower); trend lines may show a one-time discontinuity.
+ * Treat absolute tool_calls comparisons across that boundary with care.
  */
 
 import { existsSync } from 'node:fs';

package/compiler/bin/rune.js

@@ -25,9 +25,11 @@ import { installHooks } from '../commands/hooks/install.js';
 import { hookStatus } from '../commands/hooks/status.js';
 import { uninstallHooks } from '../commands/hooks/uninstall.js';
 import { formatSetupResult, runSetup } from '../commands/setup.js';
+import { generateComprehensionHTML } from '../comprehension.js';
 import { generateDashboardHTML } from '../dashboard.js';
 import { checkMeshIntegrity, formatDoctorResults, formatMeshResults, runDoctor } from '../doctor.js';
 import { buildAll } from '../emitter.js';
+import { assembleGovernance } from '../governance-collector.js';
 import { collectStats, renderStatus, renderStatusJson } from '../status.js';
 import { collectGraphData, generateMeshHTML } from '../visualizer.js';
 
@@ -438,7 +440,7 @@ async function cmdAnalytics(projectRoot, args) {
     return;
   }
 
-  const days = args.days ? parseInt(args.days, 10) : 30;
+  const days = Number.isFinite(parseInt(args.days, 10)) ? parseInt(args.days, 10) : 30;
 
   logStep('◎', `Querying metrics (${days > 0 ? `${days} days` : 'all time'})...`);
   const data = await getAllAnalytics(projectRoot, days);
@@ -479,6 +481,163 @@ async function cmdAnalytics(projectRoot, args) {
   }
 }
 
+// ─── Dashboard Command (Comprehension) ───
+// Access control: intentionally open-to-all for MVP. Tier-gating (e.g. Business-only)
+// is deferred to Phase 5 of the dashboard plan — see docs/VISION.md.
+// Mesh fallback: collectGraphData(projectRoot) returns empty for non-Rune projects by
+// design; the Understand tab prefers the project's own comprehension.json over the
+// Rune mesh, so external projects see an empty graph until they run rune onboard.
+
+async function cmdDashboard(projectRoot, args) {
+  const runeDir = path.join(projectRoot, '.rune');
+  const days = Number.isFinite(parseInt(args.days, 10)) ? parseInt(args.days, 10) : 30;
+
+  logStep('◎', 'Assembling dashboard data...');
+
+  // ── Tier detection (reuse existing detectTiers from setup.js) ──
+  // Mirrors the pattern used by cmdHooks (line ~317). detectTiers checks:
+  //   1. $RUNE_PRO_ROOT / $RUNE_BUSINESS_ROOT env vars
+  //   2. sibling monorepo paths (../Pro, ../Business)
+  //   3. Well-known developer paths (D:/Project/Rune/Pro etc.)
+  // Dashboard generation is always open (no CLI gate) — tier only affects
+  // WHICH panels render real data vs honest upsell inside the HTML.
+  const { detectTiers } = await import('../commands/setup.js');
+  const detectedTiers = detectTiers(projectRoot);
+  const hasPro = detectedTiers.pro !== null;
+  const hasBusiness = detectedTiers.business !== null;
+  const tier = hasBusiness ? 'business' : hasPro ? 'pro' : 'free';
+  logStep(
+    '◎',
+    `Tier: ${tier}${hasPro && !hasBusiness ? ' (Pro detected)' : ''}${hasBusiness ? ' (Business detected)' : ''}`,
+  );
+
+  // 1. comprehension.json (optional — onboard/autopsy writes this)
+  let comprehensionData = {};
+  const comprehensionPath = path.join(runeDir, 'comprehension.json');
+  try {
+    if (existsSync(comprehensionPath)) {
+      comprehensionData = JSON.parse(await readFile(comprehensionPath, 'utf-8'));
+      logStep('✓', 'comprehension.json loaded');
+    } else {
+      logStep('·', 'comprehension.json not found — run rune onboard or rune autopsy to generate it');
+    }
+  } catch {
+    logStep('·', 'comprehension.json unreadable — skipping');
+  }
+
+  // 2. Governance (assembleGovernance collects from metrics + mesh + Business packs)
+  let governanceData = { gates: [], signals: [], compliance: [], decisions: [] };
+  try {
+    governanceData = await assembleGovernance(projectRoot, days);
+    logStep('✓', `Governance: ${governanceData.gates.length} gates, ${governanceData.compliance.length} obligations`);
+  } catch {
+    logStep('·', 'Governance collection failed — using empty defaults');
+  }
+
+  // 3. Analytics
+  let analyticsData = {};
+  try {
+    analyticsData = await getAllAnalytics(projectRoot, days);
+    logStep('✓', `Analytics: ${analyticsData.overview?.total_sessions ?? 0} sessions`);
+  } catch {
+    logStep('·', 'Analytics collection failed — using empty defaults');
+  }
+
+  // 4. Mesh graph data
+  let meshData = { nodes: [], edges: [] };
+  try {
+    const graphResult = await collectGraphData(projectRoot);
+    // collectGraphData returns { nodes, edges, signalEdges, ... }
+    meshData = { nodes: graphResult.nodes || [], edges: graphResult.edges || [] };
+    logStep('✓', `Mesh: ${meshData.nodes.length} nodes, ${meshData.edges.length} edges`);
+  } catch {
+    logStep('·', 'Mesh graph collection failed — using empty defaults');
+  }
+
+  // 5. Dashboard profile (optional — persona + pinnedConcerns persisted by UI)
+  let profileData = null;
+  const profilePath = path.join(runeDir, 'dashboard-profile.json');
+  try {
+    if (existsSync(profilePath)) {
+      profileData = JSON.parse(await readFile(profilePath, 'utf-8'));
+      logStep('✓', `Dashboard profile loaded (persona: ${profileData.persona || 'exec'})`);
+    }
+  } catch {
+    logStep('·', 'dashboard-profile.json unreadable — using defaults');
+  }
+
+  // Merge into one data object
+  const data = {
+    // From comprehension.json
+    project: comprehensionData.project || '',
+    generated_at: comprehensionData.generated_at || new Date().toISOString(),
+    health_score: comprehensionData.health_score ?? null,
+    modules: comprehensionData.modules || [],
+    edges: comprehensionData.edges || [],
+    layers: comprehensionData.layers || [],
+    domains: comprehensionData.domains || [],
+    // From governance
+    gates: governanceData.gates || [],
+    signals: governanceData.signals || [],
+    compliance: governanceData.compliance || [],
+    decisions: governanceData.decisions || [],
+    window_days: days,
+    // From analytics — getSkillFrequency returns { skill, sessions_count }; renderMeasure
+    // reads .count, so we normalise here to avoid NaN bars.
+    overview: analyticsData.overview || {},
+    skillFrequency: (analyticsData.skillFrequency || []).map((s) => ({
+      skill: s.skill,
+      count: s.count ?? s.sessions_count ?? 0,
+    })),
+    modelDistribution: analyticsData.modelDistribution || [],
+    // Phase 5a additions — Measure tab enrichment
+    skillHeatmap: analyticsData.skillHeatmap || { heatmap: [], dates: [], maxCount: 1 },
+    sessionTimeline: analyticsData.sessionTimeline || [],
+    skillChains: analyticsData.skillChains || [],
+    // Mesh (for Understand tab fallback when no comprehension.json)
+    skillMesh: meshData,
+    // Profile (persona + pinnedConcerns) — seeds initial UI state
+    profile: profileData,
+    // Phase 5b — tier gating
+    // tier: 'free' | 'pro' | 'business'
+    // hasPro / hasBusiness: booleans used by the renderer to decide which panels to show.
+    // Free → Govern shows honest upsell (no real compliance/ledger panels).
+    // Pro  → unlocks My Lens persona option.
+    // Business → Govern fully unlocked (existing scorecard/ledger/compliance/persona/provenance).
+    tier,
+    hasPro,
+    hasBusiness,
+  };
+
+  const html = generateComprehensionHTML(data);
+
+  // Ensure .rune/ exists
+  if (!existsSync(runeDir)) {
+    const { mkdir: mkdirFs } = await import('node:fs/promises');
+    await mkdirFs(runeDir, { recursive: true });
+  }
+
+  const outputPath = args.output ? path.resolve(projectRoot, args.output) : path.join(runeDir, 'comprehension.html');
+
+  const { writeFile: writeFileFs } = await import('node:fs/promises');
+  await writeFileFs(outputPath, html, 'utf-8');
+  logStep('✓', `Dashboard written to ${path.relative(projectRoot, outputPath)}`);
+
+  // Open in browser (mirror analytics command pattern)
+  try {
+    const { exec } = await import('node:child_process');
+    const cmd =
+      process.platform === 'win32'
+        ? `start "" "${outputPath}"`
+        : process.platform === 'darwin'
+          ? `open "${outputPath}"`
+          : `xdg-open "${outputPath}"`;
+    exec(cmd);
+  } catch {
+    /* ignore if browser open fails */
+  }
+}
+
 // ─── Hook Commands ───
 
 async function cmdHooks(projectRoot, args, subcommand) {
@@ -703,6 +862,9 @@ async function main() {
     case 'dash':
       await cmdAnalytics(projectRoot, args);
       break;
+    case 'dashboard':
+      await cmdDashboard(projectRoot, args);
+      break;
     case 'hooks':
       await cmdHooks(projectRoot, args, subcommand);
       break;
@@ -733,6 +895,8 @@ async function main() {
       log('    status   Project dashboard (skills, signals, packs, health)');
       log('    visualize  Interactive mesh graph (opens in browser)');
       log('    analytics  Usage analytics dashboard (Business tier)');
+      log('    dashboard  Comprehension dashboard — Verdict hero + Govern + Measure + Understand tabs');
+      log('               [--days <n>]  Lookback window for gate counts (default: 30)');
       log('    hooks      Install/uninstall/status for multi-platform auto-discipline');
       log(
         '               hooks install [--preset gentle|strict|off] [--platform claude|cursor|windsurf|antigravity|all] [--global]',