@rune-kit/rune 2.18.0 → 2.20.0

package/compiler/__tests__/setup.test.js

@@ -1,9 +1,11 @@
 import assert from 'node:assert';
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
+import { platform as osPlatform, tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, test } from 'node:test';
-import { detectTiers, formatSetupResult, runSetup } from '../commands/setup.js';
+import { resolveTier } from '../commands/hooks/tiers.js';
+import { detectTiers, formatSetupResult, installTierSkills, runSetup } from '../commands/setup.js';
 
 let tmpRoot;
 
@@ -11,11 +13,11 @@ async function seedClaude(root) {
   await mkdir(path.join(root, '.claude'), { recursive: true });
 }
 
-async function seedTier(root, tier) {
-  const dir = path.join(root, '..', tier === 'pro' ? 'Pro' : 'Business', 'hooks');
-  await mkdir(dir, { recursive: true });
+async function seedTier(root, tier, opts = {}) {
+  const tierRoot = path.join(root, '..', tier === 'pro' ? 'Pro' : 'Business');
+  await mkdir(path.join(tierRoot, 'hooks'), { recursive: true });
   await writeFile(
-    path.join(dir, 'manifest.json'),
+    path.join(tierRoot, 'hooks', 'manifest.json'),
     JSON.stringify({
       tier,
       version: '1.0.0',
@@ -24,9 +26,27 @@ async function seedTier(root, tier) {
       entries: [],
     }),
   );
+  if (Array.isArray(opts.skills)) {
+    for (const skill of opts.skills) {
+      const skillDir = path.join(tierRoot, 'skills', skill);
+      await mkdir(skillDir, { recursive: true });
+      await writeFile(path.join(skillDir, 'SKILL.md'), `---\nname: ${skill}\n---\n# ${skill}\n`);
+    }
+  }
+}
+
+async function seedFakeRuneRoot(root) {
+  const runeRoot = path.join(root, 'fake-rune');
+  await mkdir(path.join(runeRoot, 'skills'), { recursive: true });
+  return runeRoot;
 }
 
 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 });
 });
@@ -120,6 +140,256 @@ describe('runSetup (non-interactive)', () => {
   });
 });
 
+describe('installTierSkills', () => {
+  test('copies Pro skill directories into runeRoot/skills', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    await seedTier(projectRoot, 'pro', { skills: ['autopilot', 'context-inject'] });
+    const manifest = await resolveTier('pro', projectRoot);
+
+    const result = await installTierSkills({ tier: 'pro', tierManifest: manifest, runeRoot });
+
+    assert.strictEqual(result.tier, 'pro');
+    assert.deepStrictEqual(result.installed.sort(), ['autopilot', 'context-inject']);
+    assert.deepStrictEqual(result.skipped, []);
+    assert.strictEqual(result.reason, null);
+    assert.ok(existsSync(path.join(runeRoot, 'skills', 'autopilot', 'SKILL.md')));
+    assert.ok(existsSync(path.join(runeRoot, 'skills', 'context-inject', 'SKILL.md')));
+  });
+
+  test('skips skills already present (no Free clobber, no edit stomp)', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    // Pre-existing skill at target (e.g. Free skill with same name, or prior install)
+    await mkdir(path.join(runeRoot, 'skills', 'autopilot'), { recursive: true });
+    await writeFile(path.join(runeRoot, 'skills', 'autopilot', 'SKILL.md'), '# existing — must not be overwritten');
+    await seedTier(projectRoot, 'pro', { skills: ['autopilot'] });
+    const manifest = await resolveTier('pro', projectRoot);
+
+    const result = await installTierSkills({ tier: 'pro', tierManifest: manifest, runeRoot });
+
+    assert.deepStrictEqual(result.installed, []);
+    assert.strictEqual(result.skipped.length, 1);
+    assert.strictEqual(result.skipped[0].skill, 'autopilot');
+    const preserved = readFileSync(path.join(runeRoot, 'skills', 'autopilot', 'SKILL.md'), 'utf-8');
+    assert.match(preserved, /existing — must not be overwritten/);
+  });
+
+  test('dry mode reports installs without writing', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    await seedTier(projectRoot, 'pro', { skills: ['autopilot'] });
+    const manifest = await resolveTier('pro', projectRoot);
+
+    const result = await installTierSkills({ tier: 'pro', tierManifest: manifest, runeRoot, dry: true });
+
+    assert.deepStrictEqual(result.installed, ['autopilot']);
+    assert.ok(!existsSync(path.join(runeRoot, 'skills', 'autopilot')));
+  });
+
+  test('returns reason when tier has no skills/ dir', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    await seedTier(projectRoot, 'pro'); // no skills option
+    const manifest = await resolveTier('pro', projectRoot);
+
+    const result = await installTierSkills({ tier: 'pro', tierManifest: manifest, runeRoot });
+
+    assert.deepStrictEqual(result.installed, []);
+    assert.match(result.reason, /no skills\//);
+  });
+
+  test('returns reason when runeRoot/skills target missing', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    await seedTier(projectRoot, 'pro', { skills: ['autopilot'] });
+    const manifest = await resolveTier('pro', projectRoot);
+    const runeRoot = path.join(tmpRoot, 'missing-rune-root');
+
+    const result = await installTierSkills({ tier: 'pro', tierManifest: manifest, runeRoot });
+
+    assert.deepStrictEqual(result.installed, []);
+    assert.match(result.reason, /target skills\/ missing/);
+  });
+
+  test('rejects adversarial skill directory names (path traversal)', async () => {
+    // The OS won't let us mkdir literal '..' or names with '/', so the basename
+    // guard is unit-tested at the path.basename level. The runtime guard inside
+    // installTierSkills uses the same path.basename(name) !== name check.
+    assert.strictEqual(path.basename('normal'), 'normal');
+    assert.notStrictEqual(path.basename('../escape'), '../escape');
+    assert.notStrictEqual(path.basename('a/b'), 'a/b');
+    // Integration smoke: a clean install still works after the guard was added
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    await seedTier(projectRoot, 'pro', { skills: ['normal'] });
+    const manifest = await resolveTier('pro', projectRoot);
+    const result = await installTierSkills({ tier: 'pro', tierManifest: manifest, runeRoot });
+    assert.deepStrictEqual(result.installed, ['normal']);
+  });
+
+  test('rejects relative tierManifest.source path', async () => {
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    const fakeManifest = {
+      tier: 'pro',
+      source: './relative/manifest.json', // not absolute
+      entries: [],
+    };
+
+    const result = await installTierSkills({ tier: 'pro', tierManifest: fakeManifest, runeRoot });
+
+    assert.deepStrictEqual(result.installed, []);
+    assert.match(result.reason, /must be absolute/);
+  });
+
+  test('skips non-directory entries in skills/ (e.g. stray README.md)', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    await seedTier(projectRoot, 'pro', { skills: ['autopilot'] });
+    // Stray file at sibling of skill dirs — must NOT be installed
+    await writeFile(path.join(tmpRoot, 'Pro', 'skills', 'README.md'), '# Pro skills\n');
+    const manifest = await resolveTier('pro', projectRoot);
+
+    const result = await installTierSkills({ tier: 'pro', tierManifest: manifest, runeRoot });
+
+    assert.deepStrictEqual(result.installed, ['autopilot']);
+    assert.ok(!existsSync(path.join(runeRoot, 'skills', 'README.md')));
+  });
+
+  test('skip message includes version drift when source > installed', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    // Installed v1.0.0 at target
+    await mkdir(path.join(runeRoot, 'skills', 'autopilot'), { recursive: true });
+    await writeFile(
+      path.join(runeRoot, 'skills', 'autopilot', 'SKILL.md'),
+      '---\nname: autopilot\nmetadata:\n  version: "1.0.0"\n---\n# autopilot\n',
+    );
+    // Seed Pro tier (creates manifest.json) then source skill with v1.5.0
+    await seedTier(projectRoot, 'pro');
+    await mkdir(path.join(tmpRoot, 'Pro', 'skills', 'autopilot'), { recursive: true });
+    await writeFile(
+      path.join(tmpRoot, 'Pro', 'skills', 'autopilot', 'SKILL.md'),
+      '---\nname: autopilot\nmetadata:\n  version: "1.5.0"\n---\n# autopilot\n',
+    );
+    const manifest = await resolveTier('pro', projectRoot);
+
+    const result = await installTierSkills({ tier: 'pro', tierManifest: manifest, runeRoot });
+
+    assert.deepStrictEqual(result.installed, []);
+    assert.strictEqual(result.skipped.length, 1);
+    assert.match(result.skipped[0].reason, /stale: installed v1\.0\.0, source has v1\.5\.0/);
+  });
+
+  test('rejects symlink entries inside skills/ (no sandbox escape)', async (t) => {
+    // Symlinks on Windows require elevated privileges or Developer Mode — skip cleanly.
+    if (osPlatform() === 'win32') {
+      t.skip('symlink creation needs admin/dev-mode on Windows');
+      return;
+    }
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    await seedTier(projectRoot, 'pro', { skills: ['real-skill'] });
+    // Create a malicious symlink targeting /etc inside the Pro skills/ dir
+    const escapeTarget = path.join(tmpRoot, 'attacker-target');
+    await mkdir(escapeTarget, { recursive: true });
+    await writeFile(path.join(escapeTarget, 'SECRET'), 'should not be reachable');
+    await symlink(escapeTarget, path.join(tmpRoot, 'Pro', 'skills', 'escape-link'), 'dir');
+    const manifest = await resolveTier('pro', projectRoot);
+
+    const result = await installTierSkills({ tier: 'pro', tierManifest: manifest, runeRoot });
+
+    assert.deepStrictEqual(result.installed, ['real-skill']);
+    const rejected = result.skipped.find((s) => s.skill === 'escape-link');
+    assert.ok(rejected, 'symlink entry should appear in skipped[]');
+    assert.match(rejected.reason, /rejected: symlink/);
+    assert.ok(!existsSync(path.join(runeRoot, 'skills', 'escape-link')), 'symlink must not be recreated at target');
+  });
+
+  test('version regex ignores `version:` text inside multiline description', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    // Installed v1.0.0
+    await mkdir(path.join(runeRoot, 'skills', 'foo'), { recursive: true });
+    await writeFile(
+      path.join(runeRoot, 'skills', 'foo', 'SKILL.md'),
+      '---\nname: foo\nmetadata:\n  version: "1.0.0"\n---\n',
+    );
+    // Source has DECEPTIVE description with `version: 9.9.9` text inside YAML block scalar;
+    // real metadata.version is also 1.0.0 → drift detector must report "same version", NOT "stale v9.9.9 → v1.0.0"
+    await seedTier(projectRoot, 'pro');
+    await mkdir(path.join(tmpRoot, 'Pro', 'skills', 'foo'), { recursive: true });
+    await writeFile(
+      path.join(tmpRoot, 'Pro', 'skills', 'foo', 'SKILL.md'),
+      '---\nname: foo\ndescription: |\n  version: 9.9.9 is the legacy format we used to use\nmetadata:\n  version: "1.0.0"\n---\n',
+    );
+    const manifest = await resolveTier('pro', projectRoot);
+
+    const result = await installTierSkills({ tier: 'pro', tierManifest: manifest, runeRoot });
+
+    // Same version — reason should be "already present (v1.0.0)", NOT a stale-drift message
+    assert.strictEqual(result.skipped.length, 1);
+    assert.match(result.skipped[0].reason, /already present \(v1\.0\.0\)/);
+    assert.doesNotMatch(result.skipped[0].reason, /9\.9\.9/);
+    assert.doesNotMatch(result.skipped[0].reason, /stale/);
+  });
+
+  test('skip message reports matching version when source == installed', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    await mkdir(path.join(runeRoot, 'skills', 'autopilot'), { recursive: true });
+    await writeFile(
+      path.join(runeRoot, 'skills', 'autopilot', 'SKILL.md'),
+      '---\nname: autopilot\nmetadata:\n  version: "1.0.0"\n---\n',
+    );
+    await seedTier(projectRoot, 'pro');
+    await mkdir(path.join(tmpRoot, 'Pro', 'skills', 'autopilot'), { recursive: true });
+    await writeFile(
+      path.join(tmpRoot, 'Pro', 'skills', 'autopilot', 'SKILL.md'),
+      '---\nname: autopilot\nmetadata:\n  version: "1.0.0"\n---\n',
+    );
+    const manifest = await resolveTier('pro', projectRoot);
+
+    const result = await installTierSkills({ tier: 'pro', tierManifest: manifest, runeRoot });
+
+    assert.match(result.skipped[0].reason, /already present \(v1\.0\.0\)/);
+  });
+});
+
+describe('runSetup — Pro skill installation (regression: rune:autopilot Unknown skill)', () => {
+  test('installs Pro skills into runeRoot/skills as part of setup', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    await seedClaude(projectRoot);
+    await seedTier(projectRoot, 'pro', { skills: ['autopilot'] });
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+
+    const result = await runSetup({
+      projectRoot,
+      runeRoot,
+      args: { here: true, preset: 'gentle', tier: 'pro' },
+    });
+
+    assert.deepStrictEqual(result.tiers, ['pro']);
+    assert.strictEqual(result.skillResults.length, 1);
+    assert.strictEqual(result.skillResults[0].tier, 'pro');
+    assert.deepStrictEqual(result.skillResults[0].installed, ['autopilot']);
+    assert.ok(existsSync(path.join(runeRoot, 'skills', 'autopilot', 'SKILL.md')));
+  });
+
+  test('skillResults empty array when no tier selected', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    await seedClaude(projectRoot);
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+
+    const result = await runSetup({
+      projectRoot,
+      runeRoot,
+      args: { here: true, preset: 'gentle', 'no-tier': true },
+    });
+
+    assert.deepStrictEqual(result.skillResults, []);
+  });
+});
+
 describe('formatSetupResult', () => {
   test('renders summary with scope and tiers', () => {
     const out = formatSetupResult({
@@ -149,4 +419,65 @@ describe('formatSetupResult', () => {
     });
     assert.match(out, /GLOBAL/);
   });
+
+  test('renders skill install summary when skillResults present', () => {
+    const out = formatSetupResult({
+      scope: 'current',
+      targetRoot: '/path/to/project',
+      tiers: ['pro'],
+      preset: 'gentle',
+      platforms: ['claude'],
+      written: true,
+      notes: [],
+      skillResults: [{ tier: 'pro', installed: ['autopilot'], skipped: [], reason: null }],
+    });
+    assert.match(out, /Skills:.*pro: 1 installed.*autopilot/);
+  });
+
+  test('renders skip + warn lines for tiers with collisions or missing skills/', () => {
+    const out = formatSetupResult({
+      scope: 'current',
+      targetRoot: '/path/to/project',
+      tiers: ['pro', 'business'],
+      preset: 'gentle',
+      platforms: ['claude'],
+      written: true,
+      notes: [],
+      skillResults: [
+        { tier: 'pro', installed: [], skipped: [{ skill: 'autopilot', reason: 'already present' }], reason: null },
+        { tier: 'business', installed: [], skipped: [], reason: 'no skills/ dir at /tmp/Business/skills' },
+      ],
+    });
+    assert.match(out, /Skipped:.*pro: 1 already present/);
+    assert.match(out, /Skill warn:business: no skills\//);
+  });
+
+  test('partitions skipped into benign vs rejected and surfaces rejection details', () => {
+    const out = formatSetupResult({
+      scope: 'current',
+      targetRoot: '/path/to/project',
+      tiers: ['pro'],
+      preset: 'gentle',
+      platforms: ['claude'],
+      written: true,
+      notes: [],
+      skillResults: [
+        {
+          tier: 'pro',
+          installed: ['safe-skill'],
+          skipped: [
+            { skill: 'autopilot', reason: 'already present (v1.0.0)' },
+            { skill: 'evil-link', reason: 'rejected: symlink (would escape sandbox)' },
+            { skill: '../escape', reason: 'rejected: unsafe directory name' },
+          ],
+          reason: null,
+        },
+      ],
+    });
+    // Counts partitioned and reported together
+    assert.match(out, /Skipped:.*pro: 1 already present, 2 rejected/);
+    // Each rejected skill surfaced as a warning line (security visibility)
+    assert.match(out, /⚠ evil-link: rejected: symlink/);
+    assert.match(out, /⚠ \.\.\/escape: rejected: unsafe directory name/);
+  });
 });

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]',