@geraldmaron/construct 1.0.0 → 1.0.2

package/bin/construct

@@ -14,19 +14,55 @@ import { spawnSync } from 'node:child_process';
 
 import { CLI_COMMANDS, CLI_COMMANDS_BY_CATEGORY, CATEGORY_ORDER } from '../lib/cli-commands.mjs';
 import { buildStatus, formatStatusReport } from '../lib/status.mjs';
-import { runWorkflowCli, loadWorkflow, validateWorkflowState } from '../lib/workflow-state.mjs';
 import { validateRegistry } from '../lib/validator.mjs';
-import { readCurrentModels, readOpenRouterApiKeyFromOpenCodeConfig, pollFreeModels, topForTier, selectForTier, applyToEnv, resetEnv, setTierModel, setModelWithTierInference } from '../lib/model-router.mjs';
+import { readCurrentModels, readOpenRouterApiKeyFromOpenCodeConfig, applyToEnv, resetEnv, setTierModel, setModelWithTierInference } from '../lib/model-router.mjs';
+import { pollFreeModels, topForTier, selectForTier } from '../lib/model-free-selector.mjs';
 import { cmdMcpList, cmdMcpAdd, cmdMcpRemove, cmdMcpInfo } from '../lib/mcp-manager.mjs';
+import { cmdOllama } from '../lib/ollama-manager.mjs';
 import { printHostCapabilities } from '../lib/host-capabilities.mjs';
+import { getPluginById, initPluginManifest, loadPluginRegistry } from '../lib/plugin-registry.mjs';
 import { runSetup } from '../lib/setup.mjs';
-import { loadConstructEnv, getUserEnvPath } from '../lib/env-config.mjs';
+import { runUpdate } from '../lib/update.mjs';
+import { runUpgrade } from '../lib/upgrade.mjs';
+import { runUninstall } from '../lib/uninstall/uninstall.mjs';
+import { maybeFirstInvocationProbe } from '../lib/install/first-invocation.mjs';
+import { loadConstructEnv, getUserEnvPath, writeEnvValues, ensureUserConfigDir } from '../lib/env-config.mjs';
+import {
+  loadProjectConfig,
+  writeProjectConfig,
+  initProjectConfig,
+  findProjectConfigPath,
+  getConfigValue,
+  setConfigValue,
+  PROJECT_CONFIG_FILENAME,
+} from '../lib/config/project-config.mjs';
+import { validateProjectConfig } from '../lib/config/schema.mjs';
+import {
+  DEPLOYMENT_MODES,
+  DEFAULT_DEPLOYMENT_MODE,
+  DEPLOYMENT_MODE_ENV_KEY,
+  describeDeploymentMode,
+  describeResourceLine,
+  getDeploymentMode,
+  isValidDeploymentMode,
+  resolveResourceMode,
+} from '../lib/deployment-mode.mjs';
 import { runDistillCli } from '../lib/distill.mjs';
-import { generateCompletions } from '../lib/completions.mjs';
+import { runIngestCli } from '../lib/document-ingest.mjs';
+import { runInferCli } from '../lib/schema-infer.mjs';
+import { COMPLETIONS_DIR, generateCompletions, getCompletionScript } from '../lib/completions.mjs';
 import { runHeadhunt, listTeamTemplates } from '../lib/headhunt.mjs';
+import {
+  getLockStatus,
+  cleanupStaleLock,
+  cleanupStaleQueue,
+  readQueue,
+  formatStatus,
+} from '../lib/beads-lock.mjs';
+import { runBd, getHumanStatus, acquireMergeSlot, releaseMergeSlot } from '../lib/beads-client.mjs';
 import { auditSkills, runAuditSkillsCli } from '../lib/audit-skills.mjs';
 import { runTeamReviewCli } from '../lib/telemetry/team-rollup.mjs';
-import { readDashboardState, startDashboard, startServices, stopDashboard } from '../lib/service-manager.mjs';
+import { readDashboardState, startDashboard, startServices } from '../lib/service-manager.mjs';
 import { readCostLog, summarizeCostData, formatCostReport, clearCostLog } from '../lib/cost.mjs';
 import { readEfficiencyLog, summarizeEfficiencyData, formatEfficiencyReport } from '../lib/efficiency.mjs';
 import { buildHybridSearchResultsAsync } from '../lib/storage/hybrid-query.mjs';
@@ -34,6 +70,8 @@ import { createSqlClient, closeSqlClient, readVectorConfig } from '../lib/storag
 import { describeVectorStore } from '../lib/storage/vector-store.mjs';
 import { describeSqlStore } from '../lib/storage/sql-store.mjs';
 import { syncFileStateToSql } from '../lib/storage/sync.mjs';
+import { deleteIngestedArtifacts, getStorageStatus, inferProjectName, resetStorage } from '../lib/storage/admin.mjs';
+import { runPressureRelease } from '../lib/runtime-pressure.mjs';
 
 const ROOT_DIR = path.resolve(import.meta.dirname, '..');
 const HOME = os.homedir();
@@ -55,16 +93,84 @@ function ok(message) { println(`  ${COLORS.green}✓${COLORS.reset}  ${message}`
 function warn(message) { println(`  ${COLORS.yellow}⚠${COLORS.reset}  ${message}`); }
 function info(message) { println(`  ${COLORS.cyan}→${COLORS.reset}  ${message}`); }
 
+// VS16-suffixed emojis (e.g. ⌨️, 🛠️, ⬆️) come from BMP "text symbol" Unicode
+// blocks and are commonly rendered as 1 visual column in macOS Terminal /
+// iTerm2 despite the U+FE0F variation-selector intent. Pad them with an
+// extra trailing space so the command-name column stays aligned regardless
+// of which icon a CLI entry uses.
+
+function iconColumn(emoji) {
+  const trailingSpaces = emoji.includes('️') ? '  ' : ' ';
+  return emoji + trailingSpaces;
+}
+
 function usage() {
-  println(`${COLORS.bold}construct${COLORS.reset} — AI agent harness`);
+  const showAll = restArgsCache.includes('--all') || restArgsCache.includes('-a');
+  const commands = showAll ? CLI_COMMANDS : CLI_COMMANDS.filter(c => c.core);
+  
+  if (showAll) {
+    println(`${COLORS.bold}construct${COLORS.reset} — AI agent harness (all commands)`);
+  } else {
+    println(`${COLORS.bold}construct${COLORS.reset} — AI agent harness`);
+    println(`${COLORS.dim}Tip: Run ${COLORS.reset}construct --all${COLORS.dim} to see all commands${COLORS.reset}`);
+  }
+  
   println(`\n${COLORS.dim}Usage:${COLORS.reset} construct <command> [options]\n`);
+  
   for (const category of CATEGORY_ORDER) {
-    const commands = CLI_COMMANDS_BY_CATEGORY[category] ?? [];
-    if (!commands.length) continue;
+    const categoryCommands = commands.filter(c => c.category === category);
+    if (!categoryCommands.length) continue;
     println(`${COLORS.bold}${category}${COLORS.reset}`);
-    for (const command of commands) {
-      println(`  ${command.emoji} ${command.name.padEnd(14)} ${command.description}`);
+    for (const command of categoryCommands) {
+      println(`  ${iconColumn(command.emoji)}${command.name.padEnd(14)} ${command.description}`);
+    }
+    println('');
+  }
+}
+
+/** Show interactive context-aware menu when construct is run without arguments. */
+async function showInteractiveMenu() {
+  const { loadProjectConfig } = await import('./lib/config/project-config.mjs');
+  const { existsSync } = await import('node:fs');
+  const { join } = await import('node:path');
+  
+  const projectRoot = process.cwd();
+  const isConstructProject = existsSync(join(projectRoot, 'construct.config.json')) ||
+                             existsSync(join(projectRoot, '.cx'));
+  
+  println(`${COLORS.bold}construct${COLORS.reset} — AI agent harness`);
+  println('');
+  
+  if (isConstructProject) {
+    const projectName = process.env.CX_PROJECT_NAME || require('path').basename(projectRoot);
+    println(`${COLORS.dim}Project:${COLORS.reset} ${projectName}`);
+    println('');
+  }
+  
+  println(`${COLORS.bold}Core Commands:${COLORS.reset}`);
+  println(`  ${COLORS.green}🚀 dev${COLORS.reset}              Start services for development`);
+  println(`  ${COLORS.green}⏹ stop${COLORS.reset}              Stop all running services`);
+  println(`  ${COLORS.green}📡 status${COLORS.reset}           Show system health and credentials`);
+  println(`  ${COLORS.green}🏗️  init${COLORS.reset}             Initialize project and start services`);
+  println(`  ${COLORS.green}🔄 sync${COLORS.reset}             Sync agent adapters to AI tools`);
+  println('');
+  println(`${COLORS.dim}Run 'construct <command> --help' for command details${COLORS.reset}`);
+  println(`${COLORS.dim}Run 'construct --all' to see all commands${COLORS.reset}`);
+  println('');
+  
+  // Show context-aware suggestions
+  if (isConstructProject) {
+    const { readDashboardState } = await import('./lib/service-manager.mjs');
+    const dashboard = readDashboardState(HOME);
+    
+    if (!dashboard) {
+      println(`${COLORS.yellow}💡 Services not running. Start with:${COLORS.reset}`);
+      println(`   ${COLORS.green}construct dev${COLORS.reset}`);
+      println('');
     }
+  } else {
+    println(`${COLORS.yellow}💡 Not a Construct project. Initialize with:${COLORS.reset}`);
+    println(`   ${COLORS.green}construct init${COLORS.reset}`);
     println('');
   }
 }
@@ -80,11 +186,14 @@ function runNodeScript(scriptPath, args = [], extraEnv = {}) {
 async function cmdStatus() {
   const jsonOutput = restArgsCache.includes('--json');
   const status = await buildStatus({ rootDir: ROOT_DIR, cwd: process.cwd(), homeDir: HOME, env: process.env });
+  
   if (jsonOutput) {
     println(JSON.stringify(status, null, 2));
     return;
   }
+  
   println(formatStatusReport(status));
+  
 }
 
 async function cmdShow() {
@@ -105,7 +214,31 @@ async function cmdShow() {
 
 async function cmdSync(args) {
   generateCompletions();
-  runNodeScript(path.join(ROOT_DIR, 'sync-agents.mjs'), args);
+  runNodeScript(path.join(ROOT_DIR, 'scripts', 'sync-agents.mjs'), args);
+  if (args.includes('--no-docs')) return;
+  const { regenerateDocs } = await import('../lib/auto-docs.mjs');
+  const { changed } = await regenerateDocs({ rootDir: ROOT_DIR });
+  for (const f of changed) ok(`Updated ${path.relative(ROOT_DIR, f)}`);
+}
+
+async function cmdCompletions(args) {
+  const sub = args[0] ?? 'install';
+  if (sub === 'bash' || sub === 'zsh') {
+    println(getCompletionScript(sub));
+    return;
+  }
+  if (sub === 'install') {
+    const outDir = generateCompletions();
+    if (!outDir) process.exit(1);
+    println(`Completions written to ${outDir}`);
+    println('');
+    println('Enable them in your shell:');
+    println(`  bash: source ${path.join(outDir, 'construct.bash')}`);
+    println(`  zsh:  fpath=(${outDir} $fpath) && autoload -Uz compinit && compinit`);
+    return;
+  }
+  errorln('Usage: construct completions [bash|zsh|install]');
+  process.exit(1);
 }
 
 async function cmdList() {
@@ -122,10 +255,159 @@ async function cmdList() {
 }
 
 async function cmdDoctor() {
+  const args = process.argv.slice(3);
+
+  const DAEMON_SUBS = new Set(['status', 'watch', 'stop', 'logs', 'tick', 'report']);
+  if (args.length > 0 && DAEMON_SUBS.has(args[0])) {
+    const { runCli } = await import('../lib/doctor/cli.mjs');
+    const code = await runCli(args);
+    if (code) process.exit(code);
+    return;
+  }
+
+  if (args[0] === 'credentials' || (args.length && args.some(a => a.startsWith('cred')))) {
+    println(`${COLORS.bold}Credential diagnostics${COLORS.reset}`);
+    println('');
+
+    const { execSync } = await import('node:child_process');
+    const { homedir } = await import('node:os');
+    const { join } = await import('node:path');
+    const fs = await import('node:fs');
+
+    const vars = [
+      'OPENROUTER_API_KEY',
+      'ANTHROPIC_API_KEY',
+      'GITHUB_TOKEN',
+      'OPENAI_API_KEY',
+      'OPENCODE_API_KEY',
+      'JIRA_API_TOKEN',
+      'CONFLUENCE_API_TOKEN',
+      'SLACK_BOT_TOKEN',
+    ];
+
+    for (const varName of vars) {
+      const sources = [];
+
+      // 1. process.env
+      if (process.env[varName]) {
+        sources.push(`process.env (${process.env[varName].slice(0, 8)}…)`);
+      }
+
+      // 2. .env files
+      for (const envPath of [join(process.cwd(), '.env'), join(homedir(), '.env'), join(homedir(), '.construct', 'config.env')]) {
+        if (fs.existsSync(envPath)) {
+          try {
+            const content = fs.readFileSync(envPath, 'utf8');
+            const m = content.match(new RegExp(`^${varName}=["']?(.+?)["']?$`, 'm'));
+            if (m) sources.push(`${envPath.replace(homedir(), '~')} (found)`);
+          } catch {}
+        }
+      }
+
+      // 3. Shell rc files
+      const shellFiles = [join(homedir(), '.zshrc'), join(homedir(), '.bashrc'), join(homedir(), '.bash_profile'), join(homedir(), '.profile')];
+      for (const rcPath of shellFiles) {
+        if (!fs.existsSync(rcPath)) continue;
+        try {
+          const content = fs.readFileSync(rcPath, 'utf8');
+          const opRe = new RegExp(`export\\s+${varName}=["']?\\$\\(op read '([^']+)'\\)["']?`, 'm');
+          const opMatch = content.match(opRe);
+          if (opMatch) {
+            try {
+              const r = execSync(`op read '${opMatch[1]}'`, { encoding: 'utf8', timeout: 5000 });
+              sources.push(`${rcPath.replace(homedir(), '~')} → op read ✓ (${r.stdout?.trim()?.slice(0, 8)}…)`);
+            } catch (e) {
+              const err = (e.stderr || e.message || '').slice(0, 120);
+              sources.push(`${rcPath.replace(homedir(), '~')} → op read ✗: ${err}`);
+            }
+          }
+          // Check for direct export (allow leading whitespace for indented rc files)
+          const directRe = new RegExp(`^\\s*export\\s+${varName}=(.+)$`, 'm');
+          const directMatch = content.match(directRe);
+          if (directMatch) {
+            sources.push(`${rcPath.replace(homedir(), '~')} (export found)`);
+          }
+        } catch {}
+      }
+
+      const pip = sources.length > 0 ? COLORS.green + '✓' : COLORS.yellow + '○';
+      println(`  ${pip}${COLORS.reset} ${COLORS.bold}${varName}${COLORS.reset}`);
+      if (sources.length) {
+        for (const s of sources.slice(0, 3)) {
+          if (s.includes('op read ✗')) {
+            println(`       ${COLORS.red}⚠${COLORS.reset} ${s}`);
+          } else {
+            println(`       ${s}`);
+          }
+        }
+        if (sources.length > 3) println(`       … +${sources.length - 3} more`);
+      } else {
+        println(`       not found in env, .env, config.env, or shell rc files`);
+      }
+    }
+
+    println('');
+    println('Fix tips:');
+    println('  - If op read fails with "does not have a field": the field name in .zshrc');
+    println('    doesn\'t match the 1Password item. Run `op item get <item> --vault <vault>`');
+    println('    to see the correct field name, then update your .zshrc.');
+    println('  - If op read fails with "not signed in": run `op signin` or enable the');
+    println('    1Password desktop app CLI integration (Settings → Developer).');
+    println('  - Set env vars directly in ~/.construct/config.env to bypass shell rc.');
+    return;
+  }
+
+  if (args.includes('--bootstrap')) {
+    const { registerBuiltInResources } = await import('../lib/bootstrap/built-ins.mjs');
+    const { probeAll, formatProbe } = await import('../lib/bootstrap/resources.mjs');
+    registerBuiltInResources();
+    const probes = await probeAll();
+    println('Bootstrap resource probe');
+    println('═══════════════════════');
+    for (const probe of probes) println(formatProbe(probe));
+    const missingRequired = probes.filter((p) => p.required && !p.present);
+    const missingOptional = probes.filter((p) => !p.required && !p.present);
+    println('');
+    if (missingRequired.length) {
+      errorln(`${missingRequired.length} required resource(s) missing — install them before continuing.`);
+      process.exit(1);
+    }
+    if (missingOptional.length) {
+      println(`${missingOptional.length} optional resource(s) absent — Construct runs in degraded mode.`);
+      println('Run `construct setup` to install on consent.');
+    } else {
+      ok('All resources present.');
+    }
+    return;
+  }
+
   const checks = [];
   const add = (label, pass, optional = false) => checks.push({ label, pass, optional });
   add('registry.json exists', fs.existsSync(path.join(ROOT_DIR, 'agents', 'registry.json')));
-  add('sync-agents.mjs exists', fs.existsSync(path.join(ROOT_DIR, 'sync-agents.mjs')));
+  add('sync-agents.mjs exists', fs.existsSync(path.join(ROOT_DIR, 'scripts', 'sync-agents.mjs')));
+
+  // Tier model selection. Construct ships with no default — at least
+  // one tier must be configured (registry.json primary OR CX_MODEL_*
+  // env override) before any LLM-backed workflow can run.
+  // Skip in CI — model tiers are user-specific, not repo-wide.
+  const inCI = process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true';
+  try {
+    const { resolveModelTiers } = await import('../lib/model-registry.mjs');
+    const resolved = resolveModelTiers({ env: process.env });
+    if (resolved.complete && !resolved.errors) {
+      add('Models — all tiers configured', true);
+    } else if (resolved.configured === 0) {
+      add('Models — no tier configured (pick one in the dashboard or run `construct models --apply`)', inCI, inCI);
+    } else {
+      const missing = Object.entries(resolved.models)
+        .filter(([, v]) => !v)
+        .map(([k]) => k);
+      add(`Models — only ${resolved.configured}/3 tiers configured (missing: ${missing.join(', ')})`, inCI, inCI);
+    }
+  } catch (err) {
+    add(`Models — check failed: ${err.message}`, inCI, inCI);
+  }
+
   add('Node.js 20+ (recommended)', Number.parseInt(process.versions.node.split('.')[0], 10) >= 20);
   add('npm available', true);
   const constructOnPath = spawnSync('zsh', ['-lc', 'command -v construct'], { encoding: 'utf8', env: process.env });
@@ -147,6 +429,132 @@ async function cmdDoctor() {
   fs.mkdirSync(path.join(HOME, '.cx', 'performance-reviews'), { recursive: true });
   add('~/.cx/performance-reviews/ ready', true);
 
+  // construct.config.json — optional today (config is permitted to be absent;
+  // env vars + defaults still work). The check enforces that when the file
+  // *is* present it parses and validates against the v1 schema.
+  try {
+    const projectCfg = loadProjectConfig(process.cwd(), process.env);
+    if (projectCfg.source === 'invalid') {
+      add(`construct.config.json valid (${projectCfg.errors.length} error${projectCfg.errors.length === 1 ? '' : 's'} — run \`construct config validate\`)`, false, false);
+    } else if (projectCfg.source === 'file') {
+      add(`construct.config.json valid`, true, true);
+    } else {
+      add('construct.config.json (optional)', true, true);
+    }
+  } catch (err) {
+    add(`construct.config.json check failed: ${err.message}`, false, true);
+  }
+
+  // Claude Code Stop-hook installation check. The settings template
+  // wires several Stop hooks (policy-engine / stop-typecheck /
+  // stop-notify / readme-age-check) that reference
+  // $HOME/.construct/lib/hooks/*. If that path doesn't resolve, every
+  // Stop hook fails silently — including stop-notify, which is what
+  // appends session cost data. Result: the dashboard stops updating
+  // and the user sees stale data. Surface loudly so the fix is one
+  // command away.
+  try {
+    const settingsPath = path.join(HOME, '.claude', 'settings.json');
+    if (fs.existsSync(settingsPath)) {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      const stopHooks = settings?.hooks?.Stop || [];
+      const installRoot = path.join(HOME, '.construct', 'lib', 'hooks');
+      const installed = fs.existsSync(installRoot);
+      const referenced = [];
+      for (const group of stopHooks) {
+        for (const h of (group?.hooks || [])) {
+          const cmd = String(h?.command || '');
+          const m = cmd.match(/\.construct\/lib\/hooks\/([a-zA-Z0-9_-]+\.mjs)/);
+          if (m) referenced.push(m[1]);
+        }
+      }
+      const missing = installed
+        ? referenced.filter((f) => !fs.existsSync(path.join(installRoot, f)))
+        : referenced;
+      if (referenced.length > 0 && missing.length > 0) {
+        add(
+          `Claude Stop hooks broken: ${missing.length} hook${missing.length === 1 ? '' : 's'} missing in ~/.construct/lib/hooks/. Symlink the install: ln -sfn ${ROOT_DIR}/lib ~/.construct/lib`,
+          false,
+          false,
+        );
+      } else if (referenced.length > 0) {
+        add(`Claude Stop hooks installed (${referenced.length} hooks resolve)`, true, true);
+      }
+    }
+  } catch (err) {
+    add(`Claude Stop hooks check failed: ${err.message}`, false, true);
+  }
+
+  // Handoff hygiene. Files in .cx/handoffs/ accumulate per session; this
+  // probe surfaces stale files past retention and files whose bead refs
+  // have all closed (safe to prune). Advisory — graceful when no .cx/
+  // handoffs/ directory exists.
+  try {
+    const { summarizeHandoffs } = await import('../lib/handoffs/inventory.mjs');
+    const h = summarizeHandoffs(process.cwd(), process.env);
+    if (h.state === 'empty') {
+      add('Handoffs: empty', true, true);
+    } else if (h.pastRetentionCount > 0) {
+      add(`Handoffs: ${h.pastRetentionCount} past ${h.maxDays}d retention — \`construct prune\``, false, true);
+    } else if (h.resolvedCount > 0) {
+      add(`Handoffs: ${h.total} files (${h.resolvedCount} reference only closed beads)`, true, true);
+    } else {
+      add(`Handoffs: ${h.total} files (oldest ${h.oldestAgeDays?.toFixed(0)}d)`, true, true);
+    }
+  } catch (err) {
+    add(`Handoff check failed: ${err.message}`, false, true);
+  }
+
+  // Disk resource budgets. Construct writes .cx/traces/, .cx/intake/,
+  // task graphs, backups, worker logs continuously. Without ceilings a
+  // long-lived install can fill the user's disk. Doctor surfaces usage
+  // vs cap as advisory at <=80%, warn at 80-100%, fail at >100%.
+  try {
+    const { measureUsage } = await import('../lib/resources/budget.mjs');
+    const u = measureUsage(process.cwd(), process.env);
+    const usedMb = u.totalCxBytes / 1024 / 1024;
+    const capMb = u.totalCxCap / 1024 / 1024;
+    const pct = (u.totalCxUsageRatio * 100).toFixed(0);
+    if (u.totalCxUsageRatio > 1) {
+      add(`.cx/ ${usedMb.toFixed(0)}MB / ${capMb.toFixed(0)}MB cap (${pct}% — over) — run \`construct prune\``, false, false);
+    } else if (u.totalCxUsageRatio > 0.8) {
+      add(`.cx/ ${usedMb.toFixed(1)}MB / ${capMb.toFixed(0)}MB cap (${pct}% — warning) — \`construct prune\` recommended`, false, true);
+    } else {
+      add(`.cx/ ${usedMb.toFixed(1)}MB / ${capMb.toFixed(0)}MB cap (${pct}%)`, true, true);
+    }
+  } catch (err) {
+    add(`Resource budget check failed: ${err.message}`, false, true);
+  }
+
+  // Pricing-catalog freshness + divergence. Cost ceilings (Phase 7b)
+  // are only as trustworthy as the catalog underneath. Stale catalog →
+  // drift between computed cost and actual provider bill. Divergence
+  // (>25%) → LiteLLM and static disagree on a known model, surface so
+  // the operator can verify which is current. Both advisory: degraded
+  // pricing still falls back to a usable source.
+  try {
+    const { describePricingCatalogFreshness, checkPricingDivergence } = await import('../lib/telemetry/model-pricing-catalog.mjs');
+    const freshness = describePricingCatalogFreshness();
+    if (freshness.stale) {
+      add(`Pricing catalog: ${freshness.message}`, false, true);
+    } else {
+      add(`Pricing catalog fresh (${freshness.ageHours?.toFixed(1) || '0.0'}h old)`, true, true);
+    }
+    if (freshness.present) {
+      try {
+        const cached = JSON.parse(fs.readFileSync(path.join(HOME, '.cx', 'pricing-cache.json'), 'utf8'));
+        const divergences = checkPricingDivergence(cached.models || []);
+        if (divergences.length === 0) {
+          add('Pricing matches static fallback (no >25% divergence)', true, true);
+        } else {
+          add(`Pricing divergence on ${divergences.length} model(s) — run \`construct pricing check\``, false, true);
+        }
+      } catch { /* divergence is advisory */ }
+    }
+  } catch (err) {
+    add(`Pricing catalog check failed: ${err.message}`, false, true);
+  }
+
   // Validate promptFile references and skill bindings
   try {
     const registry = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'agents', 'registry.json'), 'utf8'));
@@ -161,6 +569,9 @@ async function cmdDoctor() {
     add('Headhunt classifier agents exist in registry', classifierOrphans.length === 0);
     const skillAudit = auditSkills({ rootDir: ROOT_DIR, silent: true });
     add('No declared skills missing on disk', skillAudit.pass, false);
+    const { lintResearchRepo } = await import('../lib/research-lint.mjs');
+    const researchLintResults = lintResearchRepo({ rootDir: process.cwd() });
+    add('Research artifacts meet minimum evidence structure', researchLintResults.every((entry) => entry.errors.length === 0), true);
 
     const sqlConfig = describeSqlStore(process.env);
     const sqlClient = createSqlClient(process.env);
@@ -169,16 +580,254 @@ async function cmdDoctor() {
         await sqlClient`select 1 as ok`;
         add('SQL backend reachable', true);
       } catch {
-        add('SQL backend reachable', false);
+        add('SQL backend reachable', false, true);
       } finally {
         await closeSqlClient(sqlClient);
       }
     } else {
-      add('SQL backend configured', sqlConfig.fallbackAvailable);
+      add('SQL backend configured', sqlConfig.fallbackAvailable, true);
     }
 
     const vectorConfig = describeVectorStore(process.env);
     add('Vector backend configured', Boolean(vectorConfig.endpoint || vectorConfig.indexPath || vectorConfig.mode === 'file'));
+
+    const { regenerateDocs } = await import('../lib/auto-docs.mjs');
+    const { changed: stale } = await regenerateDocs({ rootDir: ROOT_DIR, check: true });
+    add('AUTO docs up to date', stale.length === 0, true);
+
+    const settingsPath = path.join(ROOT_DIR, 'platforms', 'claude', 'settings.template.json');
+    if (fs.existsSync(settingsPath)) {
+      const raw = fs.readFileSync(settingsPath, 'utf8');
+      const refs = [...raw.matchAll(/lib\/hooks\/([\w-]+\.m?js)/g)].map((m) => m[1]);
+      const uniq = [...new Set(refs)];
+      const missing = uniq.filter((f) => !fs.existsSync(path.join(ROOT_DIR, 'lib', 'hooks', f)));
+      const label = missing.length === 0
+        ? `Hook registrations resolve (${uniq.length} hooks)`
+        : `Hook registrations resolve (${missing.length} phantom: ${missing.join(', ')})`;
+      add(label, missing.length === 0);
+    }
+
+    const beadsPreCommit = path.join(ROOT_DIR, '.beads', 'hooks', 'pre-commit');
+    const inCI = process.env.CI === 'true' || process.env.CI === '1';
+    if (fs.existsSync(beadsPreCommit) && !inCI) {
+      const hp = spawnSync('git', ['config', '--get', 'core.hooksPath'], { cwd: ROOT_DIR, encoding: 'utf8' });
+      const value = hp.status === 0 ? (hp.stdout || '').trim() : '';
+      const wired = value === '.beads/hooks';
+      const label = wired
+        ? 'Git hooks wired (core.hooksPath = .beads/hooks)'
+        : value
+          ? `Git hooks unwired (core.hooksPath = '${value}', expected '.beads/hooks') — pre-commit policy gates inactive`
+          : 'Git hooks unwired (core.hooksPath unset) — pre-commit policy gates inactive. Fix: git config core.hooksPath .beads/hooks';
+      add(label, wired);
+    }
+
+    const pluginRegistry = loadPluginRegistry({ cwd: process.cwd(), homeDir: HOME, rootDir: ROOT_DIR, env: process.env });
+    add('Plugin manifests valid', pluginRegistry.valid);
+
+    try {
+      const { describeEngine } = await import('../lib/engine/index.mjs');
+      const engine = await describeEngine({ rootDir: process.cwd() });
+      add('Retrieval engine layers resolve', engine.errors.length === 0, true);
+    } catch {
+      add('Retrieval engine layers resolve', false, true);
+    }
+
+    try {
+      const { checkParity } = await import('../lib/parity.mjs');
+      const parity = checkParity({ rootDir: ROOT_DIR, homeDir: HOME });
+      add(`Cross-surface adapter parity (${parity.summary.join(' · ')})`, parity.ok);
+    } catch {
+      add('Cross-surface adapter parity', false);
+    }
+
+    try {
+      const { validateSkills } = await import('../lib/validators/skills.mjs');
+      const skillsRoot = path.join(ROOT_DIR, 'skills');
+      const skillReport = validateSkills(skillsRoot);
+      const label = skillReport.warnings.length > 0
+        ? `Skill structure (${skillReport.skills.length} skills, ${skillReport.warnings.length} authoring warnings)`
+        : `Skill structure (${skillReport.skills.length} skills)`;
+      add(label, skillReport.valid, true);
+    } catch {
+      add('Skill structure', false, true);
+    }
+
+    try {
+      const { describeBreakers, STATES } = await import('../lib/providers/circuit-breaker.mjs');
+      const breakers = describeBreakers();
+      const open = breakers.filter((b) => b.state === STATES.OPEN);
+      const label = open.length === 0
+        ? `Provider circuit breakers (${breakers.length} tracked, none open)`
+        : `Provider circuit breakers (${open.length} open: ${open.map((b) => b.key).join(', ')})`;
+      add(label, open.length === 0, true);
+    } catch {
+      add('Provider circuit breakers', false, true);
+    }
+
+    try {
+      const { recentViolations } = await import('../lib/agent-contracts-enforce.mjs');
+      const violations = recentViolations({ windowMs: 24 * 60 * 60 * 1000 });
+      const label = violations.length === 0
+        ? 'Contract violations (none in last 24h)'
+        : `Contract violations (${violations.length} in last 24h — see ~/.cx/contract-violations.jsonl)`;
+      add(label, violations.length === 0, true);
+    } catch {
+      add('Contract violations', false, true);
+    }
+
+    try {
+      const capWarnPath = path.join(process.cwd(), '.cx', 'observation-cap-warnings.jsonl');
+      if (fs.existsSync(capWarnPath)) {
+        const lines = fs.readFileSync(capWarnPath, 'utf8').trim().split('\n').filter(Boolean);
+        const cutoff = Date.now() - 7 * 24 * 60 * 60 * 1000;
+        const recent = lines.filter((l) => {
+          try { return new Date(JSON.parse(l).ts).getTime() >= cutoff; } catch { return false; }
+        });
+        const totalDropped = recent.reduce((acc, l) => {
+          try { return acc + (JSON.parse(l).dropped || 0); } catch { return acc; }
+        }, 0);
+        const label = recent.length === 0
+          ? 'Observation cap (no recent drops)'
+          : `Observation cap (${totalDropped} obs dropped in last 7d — run \`construct memory consolidate\`)`;
+        add(label, recent.length === 0, true);
+      } else {
+        add('Observation cap (no recent drops)', true, true);
+      }
+    } catch {
+      add('Observation cap', false, true);
+    }
+
+    try {
+      const { checkObservationsSize } = await import('../lib/observation-store.mjs');
+      const sz = checkObservationsSize(process.cwd());
+      const mb = (sz.size / 1024 / 1024).toFixed(1);
+      const capMb = (sz.cap / 1024 / 1024).toFixed(0);
+      const sizeLabel = sz.ok
+        ? `Observation size (${mb} MB / ${capMb} MB cap)`
+        : `Observation size (${mb} MB exceeds ${capMb} MB cap — run \`construct memory consolidate\`)`;
+      add(sizeLabel, sz.ok, true);
+    } catch {
+      add('Observation size', false, true);
+    }
+
+    if (sqlConfig.configured) {
+      try {
+        const migClient = createSqlClient(process.env);
+        if (migClient) {
+          const { describeMigrations } = await import('../lib/storage/migrations.mjs');
+          const m = await describeMigrations(migClient);
+          await closeSqlClient(migClient);
+          const ok = !!m.ok && m.drift.length === 0;
+          let label = 'Schema migrations applied + no drift';
+          if (!ok && m.drift && m.drift.length > 0) {
+            const repairable = m.drift.filter((d) => d.idempotent).length;
+            const notRepairable = m.drift.length - repairable;
+            if (notRepairable === 0) {
+              label = `Schema migrations: ${m.drift.length} drifted (all idempotent — run \`construct storage repair-migrations --yes\`)`;
+            } else {
+              label = `Schema migrations: ${m.drift.length} drifted (${notRepairable} non-idempotent — write a new migration file)`;
+            }
+          }
+          add(label, ok, true);
+        }
+      } catch {
+        add('Schema migrations applied + no drift', false, true);
+      }
+    }
+
+    try {
+      const { detectBeadsDrift } = await import('../lib/beads/drift.mjs');
+      const drift = detectBeadsDrift();
+      const ok = drift.counts.stuckInProgress === 0 && drift.counts.mergeDrift === 0;
+      let label = 'Beads hygiene: no drift';
+      if (!ok) {
+        const parts = [];
+        if (drift.counts.stuckInProgress > 0) parts.push(`${drift.counts.stuckInProgress} stuck in_progress`);
+        if (drift.counts.mergeDrift > 0) parts.push(`${drift.counts.mergeDrift} possible merge-drift`);
+        label = `Beads hygiene: ${parts.join(', ')} — run \`construct beads drift\``;
+      } else if (drift.counts.staleOpen > 0) {
+        label = `Beads hygiene: ${drift.counts.staleOpen} stale-open (advisory) — run \`construct beads drift\``;
+      }
+      add(label, ok, true);
+    } catch {
+      // bd not on PATH or repo not a bd workspace — skip silently.
+    }
+
+    // cm and Docker are optional but downstream services (memory MCP,
+    // managed Postgres) depend on them. Surface missing tools
+    // as warnings rather than failures so doctor doesn't flip-flop.
+    try {
+      const cmProbe = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['cm'], { stdio: 'pipe' });
+      const cmAvailable = cmProbe.status === 0;
+      add(cmAvailable ? 'cm available' : 'cm available (optional — memory MCP at 127.0.0.1:8765 needs it)', cmAvailable, true);
+    } catch {
+      add('cm available', false, true);
+    }
+
+    try {
+      const dockerCli = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['docker'], { stdio: 'pipe' });
+      let dockerOk = false;
+      let dockerNote = 'Docker not installed (optional — managed Postgres needs it)';
+      if (dockerCli.status === 0) {
+        const dockerInfo = spawnSync('docker', ['info'], { stdio: 'pipe' });
+        if (dockerInfo.status === 0) {
+          dockerOk = true;
+          dockerNote = 'Docker daemon reachable';
+        } else {
+          dockerNote = 'Docker CLI installed but daemon not reachable — run `construct up` on macOS to auto-start, or start Docker manually';
+        }
+      }
+      add(dockerOk ? 'Docker daemon reachable' : `Docker daemon reachable (${dockerNote})`, dockerOk, true);
+    } catch {
+      add('Docker daemon reachable', false, true);
+    }
+
+    try {
+      const failuresPath = path.join(HOME, '.cx', 'hook-failures.jsonl');
+      if (fs.existsSync(failuresPath)) {
+        const lines = fs.readFileSync(failuresPath, 'utf8').trim().split('\n').filter(Boolean);
+        const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+        const recent = lines.filter((l) => {
+          try { return new Date(JSON.parse(l).ts).getTime() >= cutoff; } catch { return false; }
+        });
+        add(`No recent hook failures (${recent.length} in last 24h)`, recent.length === 0, true);
+      } else {
+        add('No recent hook failures (0 in last 24h)', true, true);
+      }
+    } catch {
+      add('No recent hook failures (24h)', false, true);
+    }
+
+    // Agent contracts integrity
+    const { getAllContracts, summarize } = await import('../lib/agent-contracts.mjs');
+    const contracts = getAllContracts();
+    add('Agent contracts loaded', contracts.length > 0);
+    if (contracts.length > 0) {
+      const missingTerminals = contracts.filter((c) =>
+        c.consumer && !c.consumer.startsWith('cx-') && c.consumer !== 'construct' && c.consumer !== '*'
+          ? false : false,
+      );
+      add('Agent contract schema intact', missingTerminals.length === 0);
+    }
+
+    // Skills profile — if present, check staleness against current tags
+    const profilePath = path.join(process.cwd(), '.cx', 'skills-profile.json');
+    if (fs.existsSync(profilePath)) {
+      try {
+        const { detectProjectProfile } = await import('../lib/project-profile.mjs');
+        const current = detectProjectProfile(process.cwd());
+        const saved = JSON.parse(fs.readFileSync(profilePath, 'utf8'));
+        const savedTags = new Set(saved?.profile?.tags || []);
+        const currentTags = new Set(current.tags);
+        const drift =
+          savedTags.size !== currentTags.size ||
+          [...savedTags].some((t) => !currentTags.has(t)) ||
+          [...currentTags].some((t) => !savedTags.has(t));
+        add('Skills profile matches current project stack', !drift, true);
+      } catch {
+        add('Skills profile matches current project stack', false, true);
+      }
+    }
   } catch {
     add('Registry integrity check', false);
   }
@@ -200,7 +849,25 @@ async function cmdDoctor() {
 }
 
 async function cmdUp() {
-  const { results } = await startServices({ rootDir: ROOT_DIR, homeDir: HOME });
+  // Auto-magic health check — catch missing prerequisites before starting services
+  const { quickHealthCheck, detectCredentials, resolveCredentials } = await import('../lib/health-check.mjs');
+  
+  // Resolve credentials from env, .env files, and 1Password before starting services
+  const resolvedCreds = await resolveCredentials({ homeDir: HOME });
+  
+  const health = await quickHealthCheck({ homeDir: HOME, showCredentials: true });
+  
+  if (!health.ok) {
+    errorln('Prerequisites missing for starting services:');
+    for (const item of health.missing) {
+      errorln(`  ✗  ${item}`);
+    }
+    println('');
+    info('Run `construct install --yes` to install missing dependencies.');
+    process.exit(1);
+  }
+  
+  const { results, recovery } = await startServices({ rootDir: ROOT_DIR, homeDir: HOME });
   for (const svc of results) {
     const label = svc.url ? `${svc.name} → ${svc.url}` : svc.name;
     if (svc.status === 'started') ok(svc.note ? `${label} (${svc.note})` : label);
@@ -209,17 +876,119 @@ async function cmdUp() {
     else if (svc.status === 'failed') errorln(`${svc.name}: ${svc.note}`);
     else warn(`${svc.name}: ${svc.note}`);
   }
+
+  if (recovery) {
+    println('');
+    info(`Recovery: ${recovery.message}`);
+    const anchors = [
+      recovery.durable?.plan,
+      recovery.durable?.context,
+      recovery.durable?.latestHandoff,
+      recovery.durable?.beads,
+    ].filter(Boolean);
+    if (anchors.length) info(`Durable anchors: ${anchors.join(', ')}`);
+    if (recovery.degraded?.length) {
+      info(`Degraded services: ${recovery.degraded.map((entry) => `${entry.name} (${entry.status})`).join(', ')}`);
+    }
+  }
+  
+  // Auto-start embed daemon if embed.yaml exists and autoEmbed is enabled
+  const { loadProjectConfig } = await import('../lib/config/project-config.mjs');
+  const { existsSync } = await import('node:fs');
+  const { join } = await import('node:path');
+  
+  const embedConfigExists = existsSync(join(ROOT_DIR, 'embed.yaml'));
+  const config = loadProjectConfig(ROOT_DIR);
+  const autoEmbed = config.config?.autoEmbed;
+  
+  if (embedConfigExists && autoEmbed) {
+    try {
+      const { runEmbedCli } = await import('../lib/embed/cli.mjs');
+      await runEmbedCli(['start']);
+    } catch {
+      // best effort
+    }
+  }
+
+  // Post-start summary
+  println('');
+  println('═══════════════════════════════════════════════════════════');
+  println('  SERVICES RUNNING');
+  println('═══════════════════════════════════════════════════════════');
+  println('');
+  for (const svc of results) {
+    if (svc.status === 'started' || svc.status === 'reused') {
+      const label = svc.url ? `${svc.url}` : svc.name;
+      println(`  ${svc.name.padEnd(14)} ${label}`);
+    }
+  }
+
+  // Show credentials summary
+  const creds = health.credentials;
+  const credKeys = Object.keys(resolvedCreds);
+  if (creds || credKeys.length > 0) {
+    const configured = [];
+    if (creds.github_cli) configured.push('GitHub CLI');
+    if (creds.copilot) configured.push('Copilot');
+    if (creds.anthropic_key || credKeys.includes('ANTHROPIC_API_KEY')) configured.push('Anthropic');
+    if (creds.openai_key || credKeys.includes('OPENAI_API_KEY')) configured.push('OpenAI');
+    if (creds.openrouter_key || credKeys.includes('OPENROUTER_API_KEY')) configured.push('OpenRouter');
+    if (creds.ollama) configured.push('Ollama');
+    if (creds.vscode) configured.push('VS Code');
+    if (creds.claude_code) configured.push('Claude Code');
+    if (creds.opencode) configured.push('OpenCode');
+    if (creds.github_token || credKeys.includes('GITHUB_TOKEN') || credKeys.includes('GH_TOKEN')) configured.push('GitHub token');
+
+    if (configured.length > 0) {
+      println('');
+      println('  Credentials:');
+      println(`  ${configured.join(', ')}`);
+      if (credKeys.length > 0) {
+        println(`  ${credKeys.length} key${credKeys.length === 1 ? '' : 's'} resolved`);
+      }
+    }
+  }
+  
+  println('');
+  println('Dashboard: http://127.0.0.1:4242');
+  println('Run \x1b[32mconstruct\x1b[0m for commands');
+  println('');
 }
 
 async function cmdDown() {
-  const result = stopDashboard(HOME);
-  if (result.stopped) ok(`Dashboard stopped (pid ${result.pid}, port ${result.port}).`);
-  else if (result.reason === 'stale-state') warn('Dashboard state was stale (process already gone). Cleaned up.');
-  else warn('No managed dashboard was running.');
-  info('Other services still need to be stopped with their native commands or process manager.');
+  const { stopServices } = await import('../lib/service-manager.mjs');
+  const result = await stopServices({ homeDir: HOME, rootDir: ROOT_DIR });
+  for (const svc of result.results) {
+    if (svc.status === 'stopped') ok(`${svc.name} stopped${svc.note ? ` (${svc.note})` : ''}.`);
+    else if (svc.status === 'cleaned') warn(`${svc.name}: ${svc.note}.`);
+    else if (svc.status === 'error') errorln(`${svc.name}: ${svc.note}.`);
+    else if (svc.status === 'skipped') info(`${svc.name}: skipped — ${svc.note}.`);
+    else info(`${svc.name}: not running.`);
+  }
+
+  try {
+    const { autoCleanHandoffs } = await import('../lib/handoffs/cleanup.mjs');
+    const { result: cleanResult } = autoCleanHandoffs(process.cwd(), process.env);
+    const total = (cleanResult.moved?.length || 0) + (cleanResult.deleted?.length || 0);
+    if (total > 0) info(`Handoff cleanup: ${cleanResult.moved?.length || 0} archived, ${cleanResult.deleted?.length || 0} deleted.`);
+  } catch { /* best effort */ }
 }
 
 async function cmdServe() {
+  if (restArgsCache.includes('--token')) {
+    const { generateToken, setDashboardToken, getDashboardToken } = await import('../lib/server/auth.mjs');
+    const existing = getDashboardToken();
+    if (existing) {
+      println(`Dashboard token already set. To rotate it, remove CONSTRUCT_DASHBOARD_TOKEN from ~/.construct/config.env and re-run.`);
+      return;
+    }
+    const token = generateToken();
+    setDashboardToken(token);
+    println(`Dashboard token generated and saved to ~/.construct/config.env`);
+    println(`CONSTRUCT_DASHBOARD_TOKEN=${token}`);
+    println(`Pass this token in the dashboard login prompt or as: Authorization: Bearer <token>`);
+    return;
+  }
   const dashboard = await startDashboard({ rootDir: ROOT_DIR, homeDir: HOME });
   if (dashboard.reused) {
     println(`Construct dashboard already running on ${dashboard.url} (pid ${dashboard.pid})`);
@@ -235,59 +1004,54 @@ async function cmdVersion() {
 
 async function cmdReview(args) {
   fs.mkdirSync(path.join(HOME, '.cx', 'performance-reviews'), { recursive: true });
-  if (!process.env.LANGFUSE_PUBLIC_KEY || !process.env.LANGFUSE_SECRET_KEY) {
-    errorln('Error: LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY must be set.');
-    errorln('Configure Langfuse credentials in ~/.construct/config.env or .env.');
-    process.exit(1);
-  }
-  runNodeScript(path.join(ROOT_DIR, 'lib', 'review.mjs'), args);
-}
+  const sub = args[0];
 
-async function cmdInitDocs(args) { runNodeScript(path.join(ROOT_DIR, 'lib', 'init-docs.mjs'), args); }
-async function cmdDistill(args) { runDistillCli(args); }
+  if (!sub || sub === 'run') {
+    const { runGenerator } = await import('../lib/performance/generate.mjs');
+    const result = await runGenerator({ env: process.env });
+    info(`Wrote ${result.filename} · ${result.agentCount} agent${result.agentCount === 1 ? '' : 's'}`);
+    println(`  ${result.path}`);
+    return;
+  }
 
-function parseQueryCommandArgs(args, defaults = {}) {
-  const flags = {};
-  const queryParts = [];
-  for (const arg of args) {
-    if (arg.startsWith('--')) {
-      const [key, ...valueParts] = arg.slice(2).split('=');
-      flags[key] = valueParts.length ? valueParts.join('=') : true;
-    } else {
-      queryParts.push(arg);
+  if (sub === 'legacy') {
+    if (!ENV.CONSTRUCT_TELEMETRY_PUBLIC_KEY || !ENV.CONSTRUCT_TELEMETRY_SECRET_KEY) {
+      errorln('Error: CONSTRUCT_TELEMETRY_PUBLIC_KEY and CONSTRUCT_TELEMETRY_SECRET_KEY must be set.');
+      errorln('Configure telemetry credentials in ~/.construct/config.env or .env.');
+      process.exit(1);
     }
+    runNodeScript(path.join(ROOT_DIR, 'scripts', 'review.mjs'), args.slice(1), ENV);
+    return;
   }
-  return {
-    query: queryParts.join(' ').trim(),
-    dir: typeof flags.dir === 'string' ? flags.dir : defaults.dir,
-    ext: typeof flags.ext === 'string' ? flags.ext : defaults.ext,
-    depth: typeof flags.depth === 'string' ? flags.depth : defaults.depth,
-  };
+
+  errorln('Usage: construct review [run|legacy]');
+  process.exit(1);
 }
 
-async function cmdResearch(args) {
-  const parsed = parseQueryCommandArgs(args, { dir: 'docs' });
-  const query = parsed.query;
-  if (!query) {
-    errorln('Usage: construct research <query> [--dir=PATH] [--ext=LIST] [--depth=N]');
+async function cmdInit(args) { runNodeScript(path.join(ROOT_DIR, 'lib', 'init-unified.mjs'), args); }
+async function cmdDocsVerify(args) { runNodeScript(path.join(ROOT_DIR, 'lib', 'docs-verify.mjs'), args); }
+async function cmdInitUpdate(args) { 
+  runNodeScript(path.join(ROOT_DIR, 'lib', 'init-update.mjs'), args);
+}
+async function cmdDistill(args) { runDistillCli(args); }
+async function cmdIngest(args) {
+  try {
+    const result = await runIngestCli(args, { cwd: process.cwd(), env: process.env });
+    println(JSON.stringify(result, null, 2));
+  } catch (error) {
+    errorln(error?.message || 'document ingest failed');
     process.exit(1);
   }
-  const distillArgs = [parsed.dir, '--format=extract', `--query=${query}`, '--mode=json'];
-  if (parsed.ext) distillArgs.push(`--ext=${parsed.ext}`);
-  if (parsed.depth) distillArgs.push(`--depth=${parsed.depth}`);
-  await runDistillCli(distillArgs);
 }
 
-async function cmdDocs(args) {
-  const parsed = parseQueryCommandArgs(args, { dir: 'docs', ext: 'md,mdx,rst,txt' });
-  const query = parsed.query;
-  if (!query) {
-    errorln('Usage: construct docs <query> [--dir=PATH] [--depth=N]');
+async function cmdInfer(args) {
+  try {
+    const result = await runInferCli(args, { cwd: process.cwd() });
+    println(JSON.stringify(result, null, 2));
+  } catch (error) {
+    errorln(error?.message || 'schema inference failed');
     process.exit(1);
   }
-  const distillArgs = [parsed.dir, '--format=extract', `--query=${query}`, '--mode=json', `--ext=${parsed.ext}`];
-  if (parsed.depth) distillArgs.push(`--depth=${parsed.depth}`);
-  await runDistillCli(distillArgs);
 }
 
 async function cmdSearch(args) {
@@ -304,87 +1068,1350 @@ async function cmdSearch(args) {
   }
   const limitFlag = [...flags].find((flag) => flag.startsWith('--limit='));
   const limit = limitFlag ? Number.parseInt(limitFlag.split('=')[1], 10) : 10;
-  const results = await buildHybridSearchResultsAsync(ROOT_DIR, query, { limit: Number.isFinite(limit) ? limit : 10, env: process.env });
+  const results = await buildHybridSearchResultsAsync(process.cwd(), query, { limit: Number.isFinite(limit) ? limit : 10, env: process.env });
   println(JSON.stringify(results, null, 2));
 }
 
 async function cmdStorage(args) {
   const [action, ...rest] = args;
   if (!action) {
-    errorln('Usage: construct storage <sync|status>');
+    errorln('Usage: construct storage <sync|status|reset|delete-ingested|repair-migrations|migrations>');
     process.exit(1);
   }
+  if (action === 'migrations') {
+    const { describeMigrations } = await import('../lib/storage/migrations.mjs');
+    const sqlClient = createSqlClient(process.env);
+    if (!sqlClient) { errorln('No DATABASE_URL configured.'); process.exit(1); }
+    try {
+      const report = await describeMigrations(sqlClient);
+      println(JSON.stringify(report, null, 2));
+      if (report.drift?.length > 0) process.exit(2);
+    } finally {
+      await closeSqlClient(sqlClient);
+    }
+    return;
+  }
+  if (action === 'repair-migrations') {
+    const confirm = rest.includes('--yes');
+    if (!confirm) {
+      errorln('This re-applies drifted migrations (idempotent only) and updates their recorded SHA.');
+      errorln('Destructive migrations (DROP / TRUNCATE / ALTER…DROP / DELETE) are refused.');
+      errorln('Re-run with --yes to proceed.');
+      process.exit(1);
+    }
+    const { runMigrations } = await import('../lib/storage/migrations.mjs');
+    const sqlClient = createSqlClient(process.env);
+    if (!sqlClient) { errorln('No DATABASE_URL configured.'); process.exit(1); }
+    try {
+      const result = await runMigrations(sqlClient, { repair: true });
+      println(JSON.stringify({
+        applied: result.applied,
+        repaired: result.repaired,
+        skipped: result.skipped,
+        drift: result.drift,
+      }, null, 2));
+      if (result.drift.length > 0) {
+        errorln('');
+        errorln('Refused to repair non-idempotent migrations:');
+        for (const d of result.drift) errorln(`  ${d.filename}`);
+        process.exit(2);
+      }
+      info(`Repaired ${result.repaired.length} migration(s); applied ${result.applied.length} new.`);
+    } finally {
+      await closeSqlClient(sqlClient);
+    }
+    return;
+  }
   if (action === 'sync') {
-    const result = await syncFileStateToSql(process.cwd(), { env: process.env, project: 'construct' });
+    const result = await syncFileStateToSql(process.cwd(), { env: process.env, project: inferProjectName(process.cwd()) });
     println(JSON.stringify(result, null, 2));
     return;
   }
   if (action === 'status') {
-    const sqlClient = createSqlClient(process.env);
-    const vector = readVectorConfig(process.env);
-    let sqlStatus = { status: 'unavailable', message: 'No SQL store configured' };
-    if (sqlClient) {
-      try {
-        await sqlClient`select 1 as ok`;
-        sqlStatus = { status: 'healthy', message: 'Shared Postgres store reachable' };
-      } catch (error) {
-        sqlStatus = { status: 'degraded', message: `SQL store unreachable: ${error?.message || 'unknown error'}` };
-      } finally {
-        await closeSqlClient(sqlClient);
-      }
+    const result = await getStorageStatus(process.cwd(), { env: process.env, project: inferProjectName(process.cwd()) });
+    println(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (action === 'reset') {
+    const confirm = rest.includes('--yes');
+    const includeIngested = rest.includes('--include-ingested');
+    const sqlOnly = rest.includes('--sql-only');
+    const vectorOnly = rest.includes('--vector-only');
+    if (!confirm) {
+      errorln('Usage: construct storage reset --yes [--include-ingested] [--sql-only|--vector-only]');
+      process.exit(1);
     }
-    println(JSON.stringify({ sql: sqlStatus, vector }, null, 2));
+    const result = await resetStorage(process.cwd(), {
+      env: process.env,
+      project: inferProjectName(process.cwd()),
+      resetSql: vectorOnly ? false : true,
+      resetVector: sqlOnly ? false : true,
+      resetIngested: includeIngested,
+      confirm: true,
+    });
+    println(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (action === 'delete-ingested') {
+    const confirm = rest.includes('--yes');
+    const files = rest.filter((arg) => !arg.startsWith('--'));
+    if (!confirm) {
+      errorln('Usage: construct storage delete-ingested --yes [relative-file ...]');
+      process.exit(1);
+    }
+    const result = deleteIngestedArtifacts(process.cwd(), { files, confirm: true });
+    println(JSON.stringify(result, null, 2));
     return;
   }
-  errorln('Usage: construct storage <sync|status>');
+  errorln('Usage: construct storage <sync|status|reset|delete-ingested|repair-migrations|migrations>');
   process.exit(1);
 }
-async function cmdHeadhunt(args) { await runHeadhunt({ args, cwd: process.cwd(), homeDir: HOME }); }
-async function cmdHosts() { printHostCapabilities(); }
-async function cmdSetup(args) { await runSetup({ rootDir: ROOT_DIR, args, homeDir: HOME }); }
 
-async function cmdDo(args) {
-  const goal = args.join(' ').trim();
-  if (!goal) {
-    errorln('Usage: construct do <goal>');
-    process.exit(1);
+async function cmdPrune(args) {
+  const dryRun = args.includes('--dry-run');
+  const { planPrune, executePrune, measureUsage } = await import('../lib/resources/budget.mjs');
+  const actions = planPrune(process.cwd(), process.env);
+  if (actions.length === 0) { info('Nothing to prune. .cx/ is within all configured budgets.'); return; }
+  const byCat = {};
+  let totalBytes = 0;
+  for (const a of actions) {
+    byCat[a.category] = (byCat[a.category] || 0) + 1;
+    totalBytes += a.bytes || 0;
   }
-  println(`@construct ${goal}`);
+  println(`Plan: prune ${actions.length} file(s), free ${Math.round(totalBytes / 1024)}KB`);
+  for (const [cat, count] of Object.entries(byCat)) println(`  ${cat}: ${count} file(s)`);
+  if (dryRun) { info('--dry-run: no files removed.'); return; }
+  const result = executePrune(actions);
+  info(`Pruned ${result.removed.length} file(s), freed ${Math.round(result.bytesFreed / 1024)}KB.`);
+  const after = measureUsage(process.cwd(), process.env);
+  println(`.cx/ now at ${Math.round(after.totalCxBytes / 1024 / 1024)}MB / ${Math.round(after.totalCxCap / 1024 / 1024)}MB cap (${Math.round(after.totalCxUsageRatio * 100)}%).`);
 }
 
-async function cmdValidate() {
-  const reg = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'agents', 'registry.json'), 'utf8'));
-  const result = validateRegistry(reg, { rootDir: ROOT_DIR });
-  const workflow = loadWorkflow(process.cwd());
-  const workflowResult = workflow ? validateWorkflowState(workflow) : { valid: true, errors: [] };
-  if (result.valid && workflowResult.valid) {
-    println(`✓ Registry valid (${result.summary})`);
-    if (workflow) println(`✓ Workflow valid (${workflow.id})`);
+async function cmdCosts(args) {
+  const sub = args[0] || 'status';
+  const {
+    getDailySpend,
+    getTotalDailySpend,
+    personaBudget,
+    totalBudget,
+    enforcementActive,
+    checkBudget,
+  } = await import('../lib/cost-ledger.mjs');
+
+  if (sub === 'status') {
+    const total = getTotalDailySpend();
+    const cap = totalBudget();
+    const pct = cap > 0 ? Math.round((total.costUsd / cap) * 100) : 0;
+    println(`Today's total spend: $${total.costUsd.toFixed(4)} / $${cap.toFixed(2)} cap (${pct}%)`);
+    println(`Enforcement: ${enforcementActive() ? 'on (hard-stop at cap)' : 'advisory (warning only)'}`);
+    println('');
+    println('Per-persona daily spend:');
+    const personas = Object.keys(total.byPersona || {});
+    if (personas.length === 0) {
+      println('  (no recorded spend today)');
+    } else {
+      for (const p of personas.sort()) {
+        const spend = getDailySpend({ personaId: p });
+        const personaCap = personaBudget(p);
+        const personaPct = personaCap > 0 ? Math.round((spend.costUsd / personaCap) * 100) : 0;
+        println(`  ${p.padEnd(22)} $${spend.costUsd.toFixed(4).padStart(10)} / $${personaCap.toFixed(2)} (${personaPct}%)`);
+      }
+    }
     return;
   }
-  if (!result.valid) result.errors.forEach((e, i) => errorln(`${i + 1}. ${e}`));
-  if (!workflowResult.valid) workflowResult.errors.forEach((e, i) => errorln(`${i + 1}. ${e}`));
+
+  if (sub === 'check') {
+    const persona = args[1];
+    if (!persona) { errorln('Usage: construct costs check <personaId>'); process.exit(1); }
+    const result = checkBudget({ personaId: persona });
+    println(JSON.stringify(result, null, 2));
+    if (!result.allowed) process.exit(2);
+    return;
+  }
+
+  errorln('Usage: construct costs <status|check <personaId>>');
   process.exit(1);
 }
 
-async function cmdModels(args) {
-  const tier = args.find((arg) => arg.startsWith('--tier='))?.split('=')[1] ?? '';
-  const setModel = args.find((arg) => arg.startsWith('--set='))?.split('=')[1] ?? '';
-  const envPath = getUserEnvPath(HOME);
-  if (args.includes('--reset')) {
-    resetEnv(envPath);
-    println('Removed CX_MODEL_* overrides from ~/.construct/config.env.');
-    await cmdSync([]);
+async function cmdHandoffs(args) {
+  const sub = args[0] || 'status';
+  const { summarizeHandoffs } = await import('../lib/handoffs/inventory.mjs');
+  const summary = summarizeHandoffs(process.cwd(), process.env);
+  if (sub === 'status') {
+    if (summary.state === 'empty') { info('No handoffs in .cx/handoffs/.'); return; }
+    println(`Handoffs: ${summary.total} files · ${Math.round(summary.bytes / 1024)}KB · oldest ${summary.oldestAgeDays?.toFixed(1)}d`);
+    println(`Retention: ${summary.maxDays}d / ${summary.maxItems} items`);
+    println('');
+    if (summary.pastRetentionCount > 0) {
+      println(`⚠  ${summary.pastRetentionCount} file(s) past retention — run \`construct prune\``);
+    }
+    if (summary.resolvedCount > 0) {
+      println(`ℹ  ${summary.resolvedCount} file(s) reference only closed beads (resolved-but-kept)`);
+    }
+    if (!summary.pastRetentionCount && !summary.resolvedCount) {
+      println(`✓ All handoffs within retention and reference open work.`);
+    }
+    println('');
+    println('Recent:');
+    for (const r of summary.recent) {
+      println(`  ${r.ageDays.toFixed(1).padStart(5)}d  ${r.filename}  ${r.beadRefs.length ? `(${r.beadRefs.join(', ')})` : ''}`);
+    }
     return;
   }
-  if (tier && setModel) {
-    const preferFree = args.includes('--prefer-free');
-    const preferFreeSameFamily = args.includes('--prefer-free-same-family');
-    const inferred = setModelWithTierInference(envPath, tier, setModel, registry.models ?? {}, { preferFree, preferFreeSameFamily });
-    println(`Set ${tier} -> ${setModel} in ~/.construct/config.env`);
-    if (preferFreeSameFamily) println('Prefer-free-same-family mode: enabled');
-    if (preferFree) println('Prefer-free mode: enabled');
-    println(`Resolved tier set:`);
+  if (sub === 'list') {
+    if (summary.state === 'empty') { info('No handoffs.'); return; }
+    for (const f of summary.files) {
+      const tag = f.beadRefs.length ? ` (${f.beadRefs.join(', ')})` : '';
+      println(`${f.ageDays.toFixed(1).padStart(5)}d  ${f.status.padEnd(8)}  ${f.filename}${tag}`);
+    }
+    return;
+  }
+
+  if (sub === 'show') {
+    const target = args[1];
+    if (!target) { errorln('Usage: construct handoffs show <filename-or-id>'); process.exit(1); }
+    const match = summary.files?.find((f) => f.filename === target || f.filename.startsWith(target) || f.id === target);
+    if (!match) { errorln(`No handoff matching "${target}".`); process.exit(1); }
+    const { parseHandoffFile } = await import('../lib/handoffs/contract.mjs');
+    const parsed = parseHandoffFile(match.path);
+    println(`--- ${match.filename} ---`);
+    println(`Status: ${parsed.status}`);
+    if (parsed.frontmatter?.title) println(`Title:  ${parsed.frontmatter.title}`);
+    if (parsed.frontmatter?.beads?.length) println(`Beads:  ${parsed.frontmatter.beads.join(', ')}`);
+    if (parsed.frontmatter?.created) println(`Created: ${parsed.frontmatter.created}`);
+    println('');
+    for (const [heading, content] of Object.entries(parsed.sections)) {
+      println(`## ${heading}`);
+      println(content);
+      println('');
+    }
+    return;
+  }
+
+  if (sub === 'validate') {
+    const { parseHandoffFile, validateHandoff } = await import('../lib/handoffs/contract.mjs');
+    if (summary.state === 'empty') { info('No handoffs to validate.'); return; }
+    let hasErrors = false;
+    for (const f of summary.files) {
+      const parsed = parseHandoffFile(f.path);
+      const { valid, errors } = validateHandoff(parsed);
+      if (valid) {
+        println(`✓ ${f.filename}`);
+      } else {
+        hasErrors = true;
+        println(`✗ ${f.filename}`);
+        for (const e of errors) println(`    ${e}`);
+      }
+    }
+    if (hasErrors) process.exit(1);
+    return;
+  }
+
+  if (sub === 'prune') {
+    const { autoCleanHandoffs } = await import('../lib/handoffs/cleanup.mjs');
+    const { result } = autoCleanHandoffs(process.cwd(), process.env);
+    if (result.moved.length === 0 && result.deleted.length === 0) {
+      info('Nothing to prune.');
+      return;
+    }
+    for (const a of result.moved) println(`archived  ${path.basename(a.from)}`);
+    for (const a of result.deleted) println(`deleted   ${path.basename(a.path)}`);
+    println(`Done: ${result.moved.length} archived, ${result.deleted.length} deleted.`);
+    return;
+  }
+
+  errorln('Usage: construct handoffs [status|list|show|validate|prune]');
+  process.exit(1);
+}
+
+async function cmdResources(args) {
+  const sub = args[0] || 'status';
+  const { measureUsage } = await import('../lib/resources/budget.mjs');
+  if (sub === 'status') {
+    const u = measureUsage(process.cwd(), process.env);
+    const totalMb = u.totalCxBytes / 1024 / 1024;
+    const capMb = u.totalCxCap / 1024 / 1024;
+    println(`.cx/ total: ${totalMb.toFixed(1)}MB / ${capMb.toFixed(0)}MB (${(u.totalCxUsageRatio * 100).toFixed(0)}%)`);
+    println('');
+    println('Category                  Files     Size  Enforcement');
+    for (const [name, c] of Object.entries(u.categories)) {
+      const sizeKb = (c.bytes / 1024).toFixed(1);
+      println(`  ${name.padEnd(22)}  ${String(c.files).padStart(5)}  ${sizeKb.padStart(8)}KB  ${c.enforcement}`);
+    }
+    return;
+  }
+  errorln('Usage: construct resources status');
+  process.exit(1);
+}
+
+async function cmdOverrides(args) {
+  const sub = args[0] || 'list';
+  const {
+    describeOverrides,
+    listBackups,
+    pruneBackups,
+    resolveOverride,
+    SUPPORTED_CATEGORIES,
+  } = await import('../lib/overrides/resolver.mjs');
+
+  if (sub === 'list') {
+    const summary = describeOverrides(process.cwd());
+    let total = 0;
+    for (const category of SUPPORTED_CATEGORIES) {
+      const entries = summary[category] || [];
+      if (entries.length === 0) continue;
+      println(`${category}/`);
+      for (const entry of entries) println(`  ${entry}`);
+      total += entries.length;
+    }
+    if (total === 0) info('No user overrides — running on shipped defaults.');
+    return;
+  }
+
+  if (sub === 'backups') {
+    const category = args[1];
+    const name = args[2];
+    if (!category || !name) { errorln('Usage: construct overrides backups <category> <name>'); process.exit(1); }
+    const backups = listBackups(process.cwd(), category, name);
+    if (backups.length === 0) { info(`No backups for ${category}/${name}.`); return; }
+    for (const b of backups) {
+      const age = Math.floor((Date.now() - b.mtimeMs) / 1000);
+      println(`${b.filename}  ${b.size}B  ${age}s ago`);
+    }
+    return;
+  }
+
+  if (sub === 'prune') {
+    const daysFlag = args.find((a) => a.startsWith('--max-days='));
+    const maxDays = daysFlag ? Number.parseInt(daysFlag.split('=')[1], 10) : 60;
+    const result = pruneBackups(process.cwd(), { maxDays });
+    info(`Pruned ${result.pruned.length} backup file(s) older than ${maxDays}d (kept ${result.kept}).`);
+    return;
+  }
+
+  if (sub === 'resolve') {
+    const category = args[1];
+    const name = args[2];
+    if (!category || !name) { errorln('Usage: construct overrides resolve <category> <name>'); process.exit(1); }
+    const r = resolveOverride(process.cwd(), category, name);
+    println(JSON.stringify(r, null, 2));
+    return;
+  }
+
+  errorln('Usage: construct overrides <list|backups|prune|resolve>');
+  process.exit(1);
+}
+
+async function cmdPricing(args) {
+  const sub = args[0] || 'status';
+  const {
+    describePricingCatalogFreshness,
+    refreshPricingCatalog,
+    checkPricingDivergence,
+    resolveModelPricing,
+  } = await import('../lib/telemetry/model-pricing-catalog.mjs');
+
+  if (sub === 'status') {
+    const f = describePricingCatalogFreshness();
+    println(JSON.stringify(f, null, 2));
+    const tiers = ['CX_MODEL_REASONING', 'CX_MODEL_STANDARD', 'CX_MODEL_FAST'];
+    println('');
+    println('Resolved pricing per tier:');
+    for (const env of tiers) {
+      const model = process.env[env];
+      if (!model) { println(`  ${env}: (unset)`); continue; }
+      const p = resolveModelPricing(model);
+      if (!p) { println(`  ${env} (${model}): unavailable`); continue; }
+      println(`  ${env} (${model}): in $${p.inputPrice.toFixed(8)}/tok · out $${p.outputPrice.toFixed(8)}/tok · source: ${p.source}`);
+    }
+    return;
+  }
+
+  if (sub === 'refresh') {
+    const force = args.includes('--force');
+    info(`Refreshing LiteLLM pricing catalog${force ? ' (force)' : ''}…`);
+    const result = await refreshPricingCatalog(globalThis.fetch, { force });
+    info(`Fetched ${result.fetched} models.`);
+    if (result.divergences?.length) {
+      println('');
+      println(`⚠  ${result.divergences.length} model(s) diverge >25% from static fallback:`);
+      for (const d of result.divergences) println(`  ${d.message}`);
+    } else {
+      info('No pricing divergences from static fallback (>25%).');
+    }
+    return;
+  }
+
+  if (sub === 'check' || sub === 'divergence') {
+    const f = describePricingCatalogFreshness();
+    if (!f.present) { info(f.message); return; }
+    try {
+      const cached = JSON.parse(fs.readFileSync(path.join(HOME, '.cx', 'pricing-cache.json'), 'utf8'));
+      const divergences = checkPricingDivergence(cached.models || []);
+      if (divergences.length === 0) { info('No pricing divergences (>25%) between LiteLLM and the static fallback.'); return; }
+      println(`⚠  ${divergences.length} divergence(s):`);
+      for (const d of divergences) println(`  ${d.message}`);
+      process.exit(2);
+    } catch (err) {
+      errorln(`pricing cache read failed: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  errorln(`Usage: construct pricing <status|refresh|check>`);
+  process.exit(1);
+}
+
+async function cmdHeadhunt(args) { await runHeadhunt({ args, cwd: process.cwd(), homeDir: HOME }); }
+async function cmdHosts() { printHostCapabilities(); }
+async function cmdSetup(args) { await runSetup({ rootDir: ROOT_DIR, args, homeDir: HOME }); }
+
+function printConfigModeHelp() {
+  println('Construct config — inspect and set deployment posture.');
+  println('');
+  println('Usage:');
+  println('  construct config                          Show active deployment mode and resource topology.');
+  println('  construct config mode                     Print the active deployment mode.');
+  println('  construct config set deployment.mode <m>  Set mode to solo | team | enterprise (writes construct.config.json).');
+  println('  construct config get deployment.mode      Read the configured mode from construct.config.json.');
+  println('');
+  println('Notes:');
+  println('  • Single setter: `construct config set` is the only way to persist mode changes.');
+  println('  • Env var CX_DEPLOYMENT_MODE still wins at runtime for one-off overrides (export it for the session).');
+  println('');
+  println('Modes:');
+  for (const mode of DEPLOYMENT_MODES) {
+    println(`  ${mode.padEnd(11)} ${describeDeploymentMode(mode)}`);
+  }
+}
+
+function printActiveConfig() {
+  const mode = getDeploymentMode(process.env);
+  const topology = resolveResourceMode(mode);
+  println(`Deployment mode: ${mode}`);
+  println(`  ${describeDeploymentMode(mode)}`);
+  println('');
+  println('Resource topology:');
+  for (const [key, value] of Object.entries(topology)) {
+    println(`  ${key.padEnd(11)} ${value}`);
+  }
+  println('');
+  println(`Persisted at: ${getUserEnvPath(HOME)} (${DEPLOYMENT_MODE_ENV_KEY})`);
+}
+
+function printIntakeHelp() {
+  println('Construct intake — inspect and process the R&D intake queue.');
+  println('');
+  println('Usage:');
+  println('  construct intake list                List pending intake packets (ID, type, stage, owner, action).');
+  println('  construct intake show <id>           Show a single packet: triage, source, excerpt, related docs.');
+  println('  construct intake done <id> [--notes=…]    Mark a pending packet processed.');
+  println('  construct intake skip <id> [--reason=…]   Mark a pending packet skipped (preserves audit trail).');
+  println('  construct intake reopen <id>         Move a processed or skipped packet back to pending.');
+  println('  construct intake metrics               Show pipeline volume, velocity, and processing stats.');
+  println('  construct intake integrate <id> <system>    Push intake to external system (github, jira, confluence).');
+  println('  construct intake integrate <id> <system> --create-issue  Create an issue from the intake packet.');
+  println('  construct intake config               Show current watch dirs + scan depth.');
+  println('  construct intake config set --depth=N [--add-dir=PATH] [--remove-dir=PATH]');
+  println('                                       Update intake config. --depth caps at the hard limit.');
+  println('  construct intake config set --include-project-inbox=on|off');
+  println('  construct intake config set --include-docs-intake=on|off');
+}
+
+function parseKvFlags(args, keys) {
+  const out = {};
+  for (const arg of args) {
+    for (const key of keys) {
+      const prefix = `--${key}=`;
+      if (arg.startsWith(prefix)) out[key] = arg.slice(prefix.length);
+    }
+  }
+  return out;
+}
+
+function formatIntakeTable(rows) {
+  if (rows.length === 0) {
+    println('No pending intake packets.');
+    return;
+  }
+  const headers = ['ID', 'Type', 'Stage', 'Owner', 'Action'];
+  const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i] || '').length)));
+  const fmt = (cells) => cells.map((c, i) => String(c || '').padEnd(widths[i])).join('  ');
+  println(fmt(headers));
+  println(widths.map((w) => '─'.repeat(w)).join('  '));
+  for (const row of rows) println(fmt(row));
+}
+
+async function cmdIntake(args) {
+  const sub = args[0];
+
+  if (!sub || sub === '--help' || sub === '-h') {
+    printIntakeHelp();
+    return;
+  }
+
+  const { createIntakeQueue } = await import('../lib/intake/queue.mjs');
+  const cwd = process.cwd();
+  const queue = createIntakeQueue(cwd, process.env);
+
+  if (sub === 'list') {
+    const pending = queue.listPending();
+    const rows = pending.map((p) => {
+      const t = p.triage || {};
+      return [p.id, t.intakeType || 'unknown', t.rdStage || 'unknown', t.primaryOwner || '—', t.recommendedAction || '—'];
+    });
+    formatIntakeTable(rows);
+    return;
+  }
+
+  const id = args[1];
+  if (sub === 'show') {
+    if (!id) { errorln('Usage: construct intake show <id>'); process.exit(1); }
+    const entry = queue.read(id);
+    if (!entry) { errorln(`No intake packet with id: ${id}`); process.exit(1); }
+    const t = entry.triage || {};
+    println(`ID:        ${entry.id}`);
+    println(`Status:    ${entry.status}`);
+    println(`Source:    ${entry.intake?.sourcePath || '(none)'}`);
+    if (entry.processedAt) println(`Processed: ${entry.processedAt} by ${entry.processedBy || 'unknown'}`);
+    if (entry.skippedAt) println(`Skipped:   ${entry.skippedAt} by ${entry.skippedBy || 'unknown'}${entry.reason ? ` — ${entry.reason}` : ''}`);
+    println('');
+    println('Triage:');
+    println(`  intakeType:        ${t.intakeType || 'unknown'}`);
+    println(`  rdStage:           ${t.rdStage || 'unknown'}`);
+    println(`  primaryOwner:      ${t.primaryOwner || '—'}`);
+    println(`  recommendedChain:  ${(t.recommendedChain || []).join(' → ') || '—'}`);
+    println(`  recommendedAction: ${t.recommendedAction || '—'}`);
+    println(`  risk:              ${t.risk || '—'}`);
+    println(`  requiresApproval:  ${t.requiresApproval ? 'yes' : 'no'}`);
+    println(`  confidence:        ${typeof t.confidence === 'number' ? t.confidence.toFixed(2) : '—'}`);
+    if (t.rationale) println(`  rationale:         ${t.rationale}`);
+    if (entry.customers?.length > 0) {
+      println('');
+      println(`Linked customers: ${entry.customers.join(', ')}`);
+    }
+    if (entry.externalRefs) {
+      println('');
+      println('External references:');
+      for (const [system, ref] of Object.entries(entry.externalRefs)) {
+        println(`  ${system}: ${ref.url} (id: ${ref.id})`);
+      }
+    }
+    if (entry.suggestion?.lane) {
+      println('');
+      println(`Suggested lane: ${entry.suggestion.lane} (${entry.suggestion.source})`);
+    }
+    if ((entry.related || []).length > 0) {
+      println('');
+      println('Related artifacts:');
+      for (const r of entry.related) {
+        const score = typeof r.score === 'number' ? ` · score ${r.score.toFixed(2)}` : '';
+        println(`  - ${r.path || r.title}${score}`);
+      }
+    }
+    if (entry.excerpt) {
+      println('');
+      println('Excerpt:');
+      for (const line of String(entry.excerpt).split('\n').slice(0, 12)) println(`  ${line}`);
+    }
+    // Show similar items if there are multiple pending packets
+    try {
+      const pendingDir = path.join(cwd || process.cwd(), '.cx', 'intake', 'pending');
+      if (fs.existsSync(pendingDir)) {
+        const allPackets = [];
+        for (const f of fs.readdirSync(pendingDir)) {
+          if (!f.endsWith('.json')) continue;
+          if (f === `${entry.id}.json`) continue;
+          try {
+            const pkt = JSON.parse(fs.readFileSync(path.join(pendingDir, f), 'utf8'));
+            allPackets.push({ id: f.replace('.json', ''), text: (pkt.excerpt || '') + ' ' + (pkt.triage?.intakeType || '') });
+          } catch { /* skip */ }
+        }
+        if (allPackets.length > 0) {
+          println('');
+          println('Similar signals (semantic):');
+          println('  (run `construct intake list` to see all pending)');
+        }
+      }
+    } catch { /* dir not available */ }
+
+    // Show active recommendations related to this packet
+    try {
+      const { listActiveRecommendations } = await import('../lib/embed/recommendation-store.mjs');
+      const active = listActiveRecommendations({ limit: 5 });
+      if (active.length > 0) {
+        println('');
+        println('Active recommendations:');
+        for (const rec of active) {
+          println(`  ${rec.priority} ${rec.type.toUpperCase()}: ${rec.title} (${rec.totalSignalCount} signal(s) · score ${rec.score})`);
+        }
+        println('  Run `construct recommendations list` for details');
+      }
+    } catch { /* recommendations not available */ }
+
+    println('');
+    println('Next steps:');
+    println(`  construct graph from-intake ${entry.id}     Generate task graph from triage`);
+    if (entry.suggestion?.lane) {
+      println(`  Edit docs/${entry.suggestion.lane}/          Review/update the suggested lane`);
+    }
+    println(`  construct intake done ${entry.id}            Mark as processed`);
+    println(`  construct intake skip ${entry.id}             Mark as skipped`);
+    return;
+  }
+
+  if (sub === 'done') {
+    if (!id) { errorln('Usage: construct intake done <id> [--notes=…]'); process.exit(1); }
+    const flags = parseKvFlags(args.slice(2), ['notes']);
+    try {
+      const r = queue.markProcessed(id, { processedBy: 'construct-intake-cli', notes: flags.notes || '' });
+      info(`Marked ${r.id} processed.`);
+    } catch (err) {
+      errorln(err.message || 'mark processed failed');
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (sub === 'skip') {
+    if (!id) { errorln('Usage: construct intake skip <id> [--reason=…]'); process.exit(1); }
+    const flags = parseKvFlags(args.slice(2), ['reason']);
+    try {
+      const r = queue.markSkipped(id, { skippedBy: 'construct-intake-cli', reason: flags.reason || '' });
+      info(`Marked ${r.id} skipped.`);
+    } catch (err) {
+      errorln(err.message || 'mark skipped failed');
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (sub === 'reopen') {
+    if (!id) { errorln('Usage: construct intake reopen <id>'); process.exit(1); }
+    try {
+      const r = queue.reopen(id);
+      info(`Reopened ${r.id} (from ${r.from}).`);
+    } catch (err) {
+      errorln(err.message || 'reopen failed');
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (sub === 'metrics') {
+    return await cmdIntakeMetrics();
+  }
+
+  if (sub === 'integrate') {
+    return await cmdIntakeIntegrate(id, args.slice(2), cwd);
+  }
+
+  if (sub === 'config') {
+    return await cmdIntakeConfig(args.slice(1));
+  }
+
+  errorln(`Unknown intake subcommand: ${sub}. Available: list, show, done, skip, reopen, integrate, config`);
+  process.exit(1);
+}
+
+async function cmdIntakeConfig(args) {
+  const { loadIntakeConfig, saveIntakeConfig, INTAKE_DEPTH_GUIDANCE, INTAKE_HARD_MAX_DEPTH, describeIntakeDepth } =
+    await import('../lib/intake/intake-config.mjs');
+  const cwd = process.cwd();
+
+  const action = args[0];
+  if (!action || action === 'show') {
+    const cfg = loadIntakeConfig(cwd, process.env);
+    const desc = describeIntakeDepth(cfg.maxDepth);
+    println(`Intake config (root: ${cwd})`);
+    println('');
+    println(`  includeProjectInbox: ${cfg.includeProjectInbox ? 'on' : 'off'} (.cx/inbox)`);
+    println(`  includeDocsIntake:   ${cfg.includeDocsIntake ? 'on' : 'off'} (docs/intake)`);
+    println(`  maxDepth:            ${cfg.maxDepth} — ${desc.label}`);
+    println(`                       ${desc.detail}`);
+    println(`  hardMaxDepth:        ${INTAKE_HARD_MAX_DEPTH}`);
+    if (cfg.parentDirs.length === 0) {
+      println('  parentDirs:          (none — only the built-in zones are watched)');
+    } else {
+      println('  parentDirs:');
+      for (const dir of cfg.parentDirs) println(`    - ${dir}`);
+    }
+    println('');
+    println('Depth guide:');
+    for (const g of INTAKE_DEPTH_GUIDANCE) {
+      println(`  ${String(g.value).padStart(2)}  ${g.label} — ${g.detail}`);
+    }
+    return;
+  }
+
+  if (action !== 'set') {
+    errorln(`Unknown intake config action: ${action}. Available: show, set`);
+    process.exit(1);
+  }
+
+  const patch = {};
+  const tail = args.slice(1);
+  const depthFlag = tail.find((a) => a.startsWith('--depth='));
+  if (depthFlag) patch.maxDepth = Number(depthFlag.split('=')[1]);
+
+  const projectFlag = tail.find((a) => a.startsWith('--include-project-inbox='));
+  if (projectFlag) patch.includeProjectInbox = /^(on|true|1|yes)$/i.test(projectFlag.split('=')[1] || '');
+
+  const docsFlag = tail.find((a) => a.startsWith('--include-docs-intake='));
+  if (docsFlag) patch.includeDocsIntake = /^(on|true|1|yes)$/i.test(docsFlag.split('=')[1] || '');
+
+  const addFlags = tail.filter((a) => a.startsWith('--add-dir='));
+  const removeFlags = tail.filter((a) => a.startsWith('--remove-dir='));
+
+  if (addFlags.length || removeFlags.length) {
+    const current = loadIntakeConfig(cwd, process.env);
+    const toAdd = addFlags.map((a) => a.split('=').slice(1).join('=')).filter(Boolean);
+    const toRemove = new Set(removeFlags.map((a) => a.split('=').slice(1).join('=')).filter(Boolean));
+    const next = [...current.parentDirs.filter((d) => !toRemove.has(d)), ...toAdd];
+    patch.parentDirs = Array.from(new Set(next));
+  }
+
+  if (Object.keys(patch).length === 0) {
+    errorln('Nothing to change. Pass --depth=N, --add-dir=PATH, --remove-dir=PATH, --include-project-inbox=on|off, or --include-docs-intake=on|off.');
+    process.exit(1);
+  }
+
+  try {
+    const saved = saveIntakeConfig(cwd, patch);
+    println('Saved intake config:');
+    println(JSON.stringify(saved, null, 2));
+  } catch (err) {
+    errorln(err.message || 'failed to save intake config');
+    process.exit(1);
+  }
+}
+
+async function cmdIntakeMetrics() {
+  try {
+    const { computeIntakeMetrics, pendingAge } = await import('../lib/embed/intake-metrics.mjs');
+    const metrics = computeIntakeMetrics({ rootDir: cwd });
+    const age = pendingAge({ rootDir: cwd });
+
+    println(`${COLORS.bold}Intake pipeline metrics:${COLORS.reset}`);
+    println('');
+    println(`  ${COLORS.cyan}Volume${COLORS.reset}`);
+    println(`    Pending:     ${metrics.volume.pending}`);
+    println(`    Processed:   ${metrics.volume.processed}`);
+    println(`    Skipped:     ${metrics.volume.skipped}`);
+    println(`    Total:       ${metrics.volume.total}`);
+    println('');
+    println(`  ${COLORS.cyan}Velocity${COLORS.reset}`);
+    println(`    Rate:        ${metrics.velocity} items/day (trailing 7d)`);
+    if (metrics.avgProcessingTimeFormatted) {
+      println(`    Avg process: ${metrics.avgProcessingTimeFormatted}`);
+    }
+    if (metrics.acceptRate !== null) {
+      println(`    Accept rate: ${metrics.acceptRate}%`);
+    }
+    println('');
+    println(`  ${COLORS.cyan}Customer intelligence${COLORS.reset}`);
+    println(`    Customer-linked items: ${metrics.customerLinked}`);
+    println('');
+    println(`  ${COLORS.cyan}Recommendations${COLORS.reset}`);
+    println(`    Active:      ${metrics.recommendations.active}`);
+    println(`    Dismissed:   ${metrics.recommendations.dismissed}`);
+    println(`    Total:       ${metrics.recommendations.total}`);
+    println('');
+    println(`  ${COLORS.cyan}Backlog${COLORS.reset}`);
+    println(`    Pending items: ${age.count}`);
+    if (age.oldest) {
+      println(`    Oldest:      ${age.oldest} (${age.ageHours}h old)`);
+      println(`    Stale (>24h): ${age.oldItemsCount}`);
+    }
+  } catch (err) {
+    errorln(`Intake metrics error: ${err.message}`);
+  }
+}
+
+async function cmdIntakeIntegrate(id, args, cwd) {
+  if (!id) { errorln('Usage: construct intake integrate <id> <github|jira|confluence>'); process.exit(1); }
+
+  const system = args[0];
+  if (!system || !['github', 'jira', 'confluence'].includes(system)) {
+    errorln('Usage: construct intake integrate <id> <github|jira|confluence>');
+    errorln('Available systems: github, jira, confluence');
+    process.exit(1);
+  }
+
+  const { createIntakeQueue } = await import('../lib/intake/queue.mjs');
+  const queue = createIntakeQueue(cwd, process.env);
+  const entry = queue.read(id);
+  if (!entry) { errorln(`No intake packet with id: ${id}`); process.exit(1); }
+
+  let result;
+
+  if (system === 'github') {
+    const { createGitHubIssue, tagIntakeWithExternalRef } = await import('../lib/integrations/intake-integrations.mjs');
+    info(`Creating GitHub issue from intake ${id}...`);
+    result = await createGitHubIssue(entry);
+    if (result.ok) {
+      ok(`GitHub issue created: ${result.externalUrl}`);
+      tagIntakeWithExternalRef(cwd, id, 'github', result.externalUrl, result.externalId);
+    } else {
+      errorln(`Failed: ${result.error}`);
+      process.exit(1);
+    }
+  }
+
+  if (system === 'jira') {
+    const { createJiraTicket, tagIntakeWithExternalRef } = await import('../lib/integrations/intake-integrations.mjs');
+    info(`Creating Jira ticket from intake ${id}...`);
+    result = await createJiraTicket(entry);
+    if (result.ok) {
+      ok(`Jira ticket created: ${result.externalUrl}`);
+      tagIntakeWithExternalRef(cwd, id, 'jira', result.externalUrl, result.externalId);
+    } else {
+      errorln(`Failed: ${result.error}`);
+      process.exit(1);
+    }
+  }
+
+  if (system === 'confluence') {
+    const { publishArtifactToConfluence, tagIntakeWithExternalRef } = await import('../lib/integrations/intake-integrations.mjs');
+    const artifact = {
+      type: entry?.triage?.intakeType === 'requirement' ? 'prd' : 'adr',
+      number: 1,
+      title: entry?.excerpt?.slice(0, 60) || `Intake ${id}`,
+      content: `# Intake: ${id}\n\n${entry?.excerpt || ''}\n\nSee also: ${entry?.intake?.sourcePath || ''}`,
+    };
+    info(`Publishing Confluence page from intake ${id}...`);
+    result = await publishArtifactToConfluence(artifact);
+    if (result.ok) {
+      ok(`Confluence page: ${result.externalUrl}`);
+      tagIntakeWithExternalRef(cwd, id, 'confluence', result.externalUrl, result.externalId);
+    } else {
+      errorln(`Failed: ${result.error}`);
+      process.exit(1);
+    }
+  }
+}
+
+function printGraphHelp() {
+  println('Construct graph — inspect and generate task graphs derived from R&D intake.');
+  println('');
+  println('Usage:');
+  println('  construct graph list                            List all task graphs in this project.');
+  println('  construct graph show <graph-id>                 Print a graph: nodes, edges, status, verification.');
+  println('  construct graph from-intake <intake-id>         Generate a task graph from a pending intake packet.');
+  println('  construct graph status <graph-id> <node-id> <status> [--evidence=text]');
+  println('                                                  Update a node status. Valid: pending, claimed, in-progress, done, blocked, needs-input, skipped.');
+}
+
+async function cmdIntegrations(args) {
+  const sub = args[0];
+  if (sub === '--help' || sub === '-h') {
+    println('construct integrations — check and manage external system integrations.');
+    println('');
+    println('Usage:');
+    println('  construct integrations status    Check which integrations are configured');
+    return;
+  }
+
+  if (sub === 'status') {
+    const { detectIntegrationConfig } = await import('../lib/integrations/intake-integrations.mjs');
+    const config = detectIntegrationConfig();
+    println(`${COLORS.bold}Integration status:${COLORS.reset}`);
+    const ghMethod = config.githubMethod === 'gh' ? ' (gh CLI)' : config.githubMethod === 'env' ? ' (env vars)' : '';
+    const ghLabel = `GitHub Issues${ghMethod}`;
+    if (config.github) {
+      println(`  ${COLORS.green}✓${COLORS.reset} ${ghLabel} — repo: ${config.githubRepo}`);
+    } else {
+      println(`  ${COLORS.yellow}⚠${COLORS.reset} GitHub Issues not configured (run gh auth login, or set GITHUB_TOKEN)`);
+    }
+    println(`  ${config.jira ? COLORS.green + '✓' : COLORS.yellow + '⚠'}${COLORS.reset} Jira${config.jira ? ` — ${config.jiraHost}` : ' not configured'}`);
+    println(`  ${config.confluence ? COLORS.green + '✓' : COLORS.yellow + '⚠'}${COLORS.reset} Confluence${config.confluence ? ` — ${config.confluenceSpace}` : ' not configured'}`);
+    println('');
+    println('Auth methods (tried in order):');
+    println('  GitHub:    gh CLI → GITHUB_TOKEN env → .env → config.env → 1Password');
+    println('  Jira/Conf: JIRA_/CONFLUENCE_ env → ~/.env → config.env → shell rc → 1Password');
+    println('');
+    println('Configure: construct intake integrate <id> <github|jira|confluence>');
+    return;
+  }
+
+  errorln(`Unknown subcommand: ${sub}. Available: status`);
+}
+
+function printCustomerHelp() {
+  println('');
+  println('Construct customer — manage customer profiles for product intelligence.');
+  println('');
+  println('Usage:');
+  println('  construct customer list                     List all customer profiles');
+  println('  construct customer show <id>                Show detailed profile');
+  println('  construct customer add --name=Acme [--owner=Jane] [--domain=acme.com]');
+  println('  construct customer search <query>           Search by name, domain, or alias');
+  println('  construct customer update <id> --status=inactive   Update profile status');
+}
+
+async function cmdCustomer(args) {
+  const sub = args[0];
+  if (!sub || sub === '--help' || sub === '-h') { printCustomerHelp(); return; }
+
+  const { createCustomerProfile, getCustomerProfile, listCustomerProfiles, searchCustomerProfiles, updateCustomerProfile } = await import('../lib/embed/customer-profiles.mjs');
+
+  if (sub === 'list') {
+    const profiles = listCustomerProfiles();
+    if (!profiles.length) { println('No customer profiles. Create one with: construct customer add --name=Acme'); return; }
+    println(`${COLORS.bold}Customer profiles:${COLORS.reset}`);
+    for (const p of profiles) {
+      println(`  ${COLORS.cyan}${p.id}${COLORS.reset}  ${COLORS.bold}${p.name}${COLORS.reset}  [${p.status}]  ${p.workspace}  updated ${p.updatedAt?.slice(0, 10)}`);
+    }
+    return;
+  }
+
+  if (sub === 'show') {
+    const id = args[1];
+    if (!id) { errorln('Usage: construct customer show <id>'); process.exit(1); }
+    const profile = getCustomerProfile(id);
+    if (!profile) { errorln(`Customer profile not found: ${id}`); process.exit(1); }
+    println(`ID:      ${profile.id}`);
+    println(`Name:    ${profile.name}`);
+    println(`Status:  ${profile.status}`);
+    println(`Owner:   ${profile.owner}`);
+    println(`Workspace: ${profile.workspace}`);
+    println(`Updated: ${profile.updatedAt?.slice(0, 10) || '—'}`);
+    return;
+  }
+
+  if (sub === 'add') {
+    const name = args.find(a => a.startsWith('--name='))?.split('=').slice(1).join('=');
+    const owner = args.find(a => a.startsWith('--owner='))?.split('=').slice(1).join('=');
+    const domain = args.find(a => a.startsWith('--domain='))?.split('=').slice(1).join('=');
+    if (!name) { errorln('Usage: construct customer add --name=Acme [--owner=Jane] [--domain=acme.com]'); process.exit(1); }
+    const result = createCustomerProfile({ name, owner, domain });
+    println(`Created customer profile: ${result.id} — ${result.profile.name}`);
+    return;
+  }
+
+  if (sub === 'search') {
+    const query = args.slice(1).join(' ');
+    if (!query) { errorln('Usage: construct customer search <query>'); process.exit(1); }
+    const results = searchCustomerProfiles(query);
+    if (!results.length) { println('No matches.'); return; }
+    for (const r of results) {
+      println(`  ${r.id}  ${r.name}  [${r.status}]`);
+    }
+    return;
+  }
+
+  if (sub === 'update') {
+    const id = args[1];
+    const status = args.find(a => a.startsWith('--status='))?.split('=').slice(1).join('=');
+    if (!id || !status) { errorln('Usage: construct customer update <id> --status=active|inactive|archived'); process.exit(1); }
+    updateCustomerProfile(id, { status, changeLogEntry: `Status changed to ${status} via CLI` });
+    println(`Updated: ${id}`);
+    return;
+  }
+
+  errorln(`Unknown customer subcommand: ${sub}. Available: list, show, add, search, update`);
+}
+
+function printWorkspaceHelp() {
+  println('');
+  println('Construct workspace — manage PM workspaces for signal routing.');
+  println('');
+  println('Usage:');
+  println('  construct workspace list                              List all workspaces');
+  println('  construct workspace create --name=Auth --owner=Jane   Create a new workspace');
+  println('  construct workspace show <id>                         Show workspace details');
+  println('  construct workspace assign --customer=X --workspace=Y Assign customer to workspace');
+}
+
+async function cmdWorkspace(args) {
+  const sub = args[0];
+  if (!sub || sub === '--help' || sub === '-h') { printWorkspaceHelp(); return; }
+
+  const { createWorkspace, getWorkspace, listWorkspaces, updateWorkspace } = await import('../lib/embed/workspaces.mjs');
+
+  if (sub === 'list') {
+    const workspaces = listWorkspaces();
+    if (!workspaces.length) { println('No workspaces.'); return; }
+    println(`${COLORS.bold}Workspaces:${COLORS.reset}`);
+    for (const ws of workspaces) {
+      println(`  ${COLORS.cyan}${ws.id}${COLORS.reset}  ${COLORS.bold}${ws.name}${COLORS.reset}  owner: ${ws.owner}  [${ws.status}]  areas: ${(ws.productAreas || []).join(', ') || '—'}`);
+    }
+    return;
+  }
+
+  if (sub === 'create') {
+    const name = args.find(a => a.startsWith('--name='))?.split('=').slice(1).join('=');
+    const owner = args.find(a => a.startsWith('--owner='))?.split('=').slice(1).join('=');
+    const areas = args.find(a => a.startsWith('--areas='))?.split('=').slice(1).join('=')?.split(',') || [];
+    if (!name || !owner) { errorln('Usage: construct workspace create --name=Auth --owner=Jane [--areas=auth,users]'); process.exit(1); }
+    const result = createWorkspace({ name, owner, productAreas: areas });
+    println(`Created workspace: ${result.id} — ${result.workspace.name}`);
+    return;
+  }
+
+  if (sub === 'show') {
+    const id = args[1];
+    if (!id) { errorln('Usage: construct workspace show <id>'); process.exit(1); }
+    const ws = getWorkspace(id);
+    if (!ws) { errorln(`Workspace not found: ${id}`); process.exit(1); }
+    println(`ID:          ${ws.id}`);
+    println(`Name:        ${ws.name}`);
+    println(`Owner:       ${ws.owner}`);
+    println(`Status:      ${ws.status}`);
+    println(`Product areas: ${(ws.productAreas || []).join(', ') || '—'}`);
+    println(`Customers:   ${(ws.customerIds || []).join(', ') || '—'}`);
+    return;
+  }
+
+  errorln(`Unknown workspace subcommand: ${sub}. Available: list, create, show`);
+}
+
+function printRecommendationsHelp() {
+  println('');
+  println('Construct recommendations — view and manage artifact recommendations.');
+  println('');
+  println('These are generated by the daemon\'s docs-lifecycle job based on intake');
+  println('signals, snapshot analysis, and doc gap detection. Recommendations are');
+  println('deduplicated, prioritized, and auto-suppressed after 7 days without new signals.');
+  println('');
+  println('Usage:');
+  println('  construct recommendations list [--type=prd] [--priority=P0]');
+  println('                                        List active recommendations, sorted by priority.');
+  println('  construct recommendations stats       Show recommendation store stats.');
+  println('  construct recommendations dismiss <type> <title> [--reason=…]');
+  println('                                        Permanently dismiss a recommendation.');
+  println('  construct recommendations dismiss <type> <title> --suppress-days=30');
+  println('                                        Temporarily suppress a recommendation.');
+}
+
+async function cmdRecommendations(args) {
+  const sub = args[0];
+  if (!sub || sub === '--help' || sub === '-h') { printRecommendationsHelp(); return; }
+
+  if (sub === 'list') {
+    const typeFlag = args.find(a => a.startsWith('--type='))?.split('=')[1];
+    const priorityFlag = args.find(a => a.startsWith('--priority='))?.split('=')[1];
+    try {
+      const { listActiveRecommendations, recommendationStats } = await import('../lib/embed/recommendation-store.mjs');
+      const recs = listActiveRecommendations({ type: typeFlag, priority: priorityFlag, limit: 30 });
+      if (!recs.length) {
+        println('No active recommendations.');
+        const stats = recommendationStats();
+        println(`(${stats.total} total in store: ${stats.active} active, ${stats.dismissed} dismissed, ${stats.superseded} superseded)`);
+        return;
+      }
+      println(`${COLORS.bold}Active recommendations:${COLORS.reset}`);
+      for (const rec of recs) {
+        const priorityColor = rec.priority === 'P0' ? COLORS.red : rec.priority === 'P1' ? COLORS.yellow : COLORS.reset;
+        println(`  ${priorityColor}${rec.priority}${COLORS.reset} ${COLORS.bold}${rec.type.toUpperCase()}${COLORS.reset}: ${rec.title}`);
+        println(`       Score: ${rec.score} · Signals: ${rec.totalSignalCount} · Impact: ${rec.customerImpact}/3 · ${rec.reason?.slice(0, 80)}`);
+      }
+      const stats = recommendationStats();
+      println(`\n(${stats.active} active · ${stats.dismissed} dismissed · ${stats.superseded} superseded)`);
+    } catch (err) {
+      errorln(`Recommendations error: ${err.message}`);
+    }
+    return;
+  }
+
+  if (sub === 'stats') {
+    try {
+      const { recommendationStats } = await import('../lib/embed/recommendation-store.mjs');
+      const stats = recommendationStats();
+      println('Recommendation store:');
+      println(`  Total:       ${stats.total}`);
+      println(`  Active:      ${stats.active}`);
+      println(`  Dismissed:   ${stats.dismissed}`);
+      println(`  Superseded:  ${stats.superseded}`);
+      println(`  By priority: ${JSON.stringify(stats.byPriority)}`);
+      println(`  By type:     ${JSON.stringify(stats.byType)}`);
+    } catch (err) {
+      errorln(`Recommendations stats error: ${err.message}`);
+    }
+    return;
+  }
+
+  if (sub === 'dismiss') {
+    const recType = args[1];
+    const recTitle = args[2];
+    if (!recType || !recTitle) {
+      errorln('Usage: construct recommendations dismiss <type> <title> [--reason=…] [--suppress-days=N]');
+      process.exit(1);
+    }
+    const reasonFlag = args.find(a => a.startsWith('--reason='))?.split('=').slice(1).join('=');
+    const suppressDaysFlag = args.find(a => a.startsWith('--suppress-days='))?.split('=')[1];
+    try {
+      const { dedupKey: computeKey } = await import('../lib/embed/recommendation-store.mjs');
+      const key = `${recType}::${recTitle.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 60)}`;
+      const { dismissRecommendation } = await import('../lib/embed/recommendation-store.mjs');
+      dismissRecommendation(key, {
+        reason: reasonFlag || 'CLI dismiss',
+        suppressDays: suppressDaysFlag ? Number(suppressDaysFlag) : undefined,
+      });
+      println(`Dismissed: ${recType} / ${recTitle}`);
+    } catch (err) {
+      errorln(`Dismiss error: ${err.message}`);
+    }
+    return;
+  }
+
+  errorln(`Unknown recommendations subcommand: ${sub}. Available: list, stats, dismiss`);
+}
+
+async function cmdGraph(args) {
+  const sub = args[0];
+  if (!sub || sub === '--help' || sub === '-h') { printGraphHelp(); return; }
+
+  const { FilesystemTaskGraphStore } = await import('../lib/task-graph/store.mjs');
+  const { generateTaskGraphFromTriage } = await import('../lib/task-graph/generate.mjs');
+  const cwd = process.cwd();
+  const store = new FilesystemTaskGraphStore(cwd);
+
+  if (sub === 'list') {
+    const graphs = store.list();
+    if (graphs.length === 0) { println('No task graphs.'); return; }
+    println('Graph ID                                                Nodes  Triage');
+    println('-'.repeat(80));
+    for (const g of graphs) {
+      const triage = g.triage ? `${g.triage.intakeType}/${g.triage.rdStage}` : '—';
+      println(`${g.id.padEnd(56)}  ${String(g.nodes.length).padStart(5)}  ${triage}`);
+    }
+    return;
+  }
+
+  if (sub === 'show') {
+    const id = args[1];
+    if (!id) { errorln('Usage: construct graph show <graph-id>'); process.exit(1); }
+    const g = store.read(id);
+    if (!g) { errorln(`No graph: ${id}`); process.exit(1); }
+    println(`Graph: ${g.id}`);
+    println(`Created: ${g.createdAt}`);
+    if (g.triage) println(`Triage: ${g.triage.intakeType} / ${g.triage.rdStage} · owner ${g.triage.primaryOwner}`);
+    if (g.intake?.sourcePath) println(`Source: ${g.intake.sourcePath}`);
+    if (g.verificationRequirements?.length) println(`Verification: ${g.verificationRequirements.join(', ')}`);
+    println('');
+    println('Nodes:');
+    for (const node of g.nodes) {
+      const deps = (node.dependsOn || []).length > 0 ? ` ← ${node.dependsOn.length} dep(s)` : '';
+      println(`  [${node.status.padEnd(11)}] ${node.title}${deps}`);
+      if ((node.evidence || []).length > 0) {
+        for (const ev of node.evidence) println(`    evidence: ${typeof ev === 'string' ? ev : JSON.stringify(ev)}`);
+      }
+    }
+    if ((g.edges || []).length > 0) {
+      println('');
+      println(`Edges: ${g.edges.length}`);
+    }
+    return;
+  }
+
+  if (sub === 'from-intake') {
+    const intakeId = args[1];
+    if (!intakeId) { errorln('Usage: construct graph from-intake <intake-id>'); process.exit(1); }
+    const { createIntakeQueue } = await import('../lib/intake/queue.mjs');
+    const queue = createIntakeQueue(cwd, process.env);
+    const entry = queue.read(intakeId);
+    if (!entry) { errorln(`No intake packet: ${intakeId}`); process.exit(1); }
+    const graph = generateTaskGraphFromTriage({
+      triage: entry.triage,
+      project: path.basename(path.resolve(cwd)),
+      request: entry.excerpt || '',
+      intake: entry.intake,
+    });
+    const r = store.save(graph);
+    info(`Generated ${graph.nodes.length}-node graph ${r.id}`);
+    println(`Wrote: ${r.filePath}`);
+    return;
+  }
+
+  if (sub === 'status') {
+    const graphId = args[1];
+    const nodeId = args[2];
+    const status = args[3];
+    if (!graphId || !nodeId || !status) {
+      errorln('Usage: construct graph status <graph-id> <node-id> <status> [--evidence=…]');
+      process.exit(1);
+    }
+    const flags = parseKvFlags(args.slice(4), ['evidence']);
+    try {
+      const patch = flags.evidence ? { addEvidence: flags.evidence } : {};
+      const updated = store.updateNodeStatus(graphId, nodeId, status, patch);
+      info(`Updated ${nodeId} → ${updated.status}`);
+    } catch (err) {
+      errorln(err.message || 'status update failed');
+      process.exit(1);
+    }
+    return;
+  }
+
+  errorln(`Unknown graph subcommand: ${sub}. Available: list, show, from-intake, status`);
+  process.exit(1);
+}
+
+async function cmdConfig(args) {
+  const sub = args[0];
+
+  if (!sub || sub === '--help' || sub === '-h') {
+    if (!sub) { printActiveConfig(); return; }
+    printConfigModeHelp();
+    return;
+  }
+
+  if (sub === 'mode') {
+    const value = args[1];
+
+    if (!value) {
+      println(getDeploymentMode(process.env));
+      return;
+    }
+
+    if (value === '--help' || value === '-h') { printConfigModeHelp(); return; }
+
+    // Setter consolidated into `construct config set`. Refuse here with a one-line redirect
+    // so users learn the single canonical setter instead of two slightly-divergent paths.
+    errorln(`\`construct config mode <value>\` is no longer a setter. Use the single canonical path:`);
+    errorln(`  construct config set deployment.mode ${value}`);
+    errorln('');
+    errorln('For ephemeral runtime overrides (CI, scripts), export CX_DEPLOYMENT_MODE instead.');
+    process.exit(1);
+  }
+
+  if (sub === 'init') {
+    try {
+      const filePath = initProjectConfig(process.cwd());
+      info(`Created ${filePath}`);
+    } catch (err) {
+      errorln(err.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (sub === 'show') {
+    const { path: cfgPath, config, source, errors } = loadProjectConfig(process.cwd(), process.env);
+    if (errors.length) {
+      errorln(`Config has ${errors.length} error${errors.length === 1 ? '' : 's'}:`);
+      for (const e of errors) errorln(`  - ${e}`);
+    }
+    println(`# source: ${source}${cfgPath ? ` (${cfgPath})` : ''}`);
+    println(JSON.stringify(config, null, 2));
+    return;
+  }
+
+  if (sub === 'get') {
+    const keyPath = args[1];
+    if (!keyPath) { errorln('Usage: construct config get <dotted.key>'); process.exit(1); }
+    const { config } = loadProjectConfig(process.cwd(), process.env);
+    const value = getConfigValue(config, keyPath, null);
+    println(value === null ? '' : (typeof value === 'string' ? value : JSON.stringify(value)));
+    return;
+  }
+
+  if (sub === 'set') {
+    const keyPath = args[1];
+    const rawValue = args[2];
+    if (!keyPath || rawValue === undefined) {
+      errorln('Usage: construct config set <dotted.key> <value>');
+      process.exit(1);
+    }
+    let parsedValue = rawValue;
+    if (rawValue === 'true') parsedValue = true;
+    else if (rawValue === 'false') parsedValue = false;
+    else if (rawValue === 'null') parsedValue = null;
+    else if (!Number.isNaN(Number(rawValue)) && rawValue.trim() !== '') parsedValue = Number(rawValue);
+    const cfgPath = findProjectConfigPath(process.cwd()) || path.join(process.cwd(), PROJECT_CONFIG_FILENAME);
+    const { config } = loadProjectConfig(process.cwd(), process.env);
+    const next = setConfigValue(config, keyPath, parsedValue);
+    try {
+      writeProjectConfig(cfgPath, next);
+      info(`set ${keyPath} = ${JSON.stringify(parsedValue)} in ${cfgPath}`);
+    } catch (err) {
+      errorln(err.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (sub === 'validate') {
+    const cfgPath = findProjectConfigPath(process.cwd());
+    if (!cfgPath) {
+      info(`no ${PROJECT_CONFIG_FILENAME} found — using defaults`);
+      return;
+    }
+    let raw;
+    try { raw = JSON.parse(fs.readFileSync(cfgPath, 'utf8')); }
+    catch (err) { errorln(`parse error: ${err.message}`); process.exit(1); }
+    const result = validateProjectConfig(raw);
+    if (result.valid) {
+      info(`${cfgPath} is valid`);
+      return;
+    }
+    errorln(`${cfgPath} has ${result.errors.length} error${result.errors.length === 1 ? '' : 's'}:`);
+    for (const e of result.errors) errorln(`  - ${e}`);
+    process.exit(1);
+  }
+
+  errorln(`Unknown config subcommand: ${sub}. Available: mode, init, show, get, set, validate`);
+  process.exit(1);
+}
+async function cmdUninstall(args) {
+  try {
+    const result = await runUninstall(args);
+    if (result?.canceled) process.exit(130);
+  } catch (err) {
+    errorln(err?.message || 'uninstall failed');
+    process.exit(1);
+  }
+}
+
+async function cmdUpdate() {
+  try {
+    runUpdate({ cwd: process.cwd(), env: process.env, stdout: process.stdout });
+  } catch (error) {
+    errorln(error?.message || 'construct update failed');
+    process.exit(1);
+  }
+}
+
+async function cmdUpgrade(args) {
+  try {
+    const yes = args.includes('--yes');
+    const result = runUpgrade({ cwd: process.cwd(), env: process.env, stdout: process.stdout, yes });
+    if (!result.success) process.exit(1);
+  } catch (error) {
+    errorln(error?.message || 'construct upgrade failed');
+    process.exit(1);
+  }
+}
+async function cmdValidate() {
+  const reg = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'agents', 'registry.json'), 'utf8'));
+  const result = validateRegistry(reg, { rootDir: ROOT_DIR });
+  if (result.valid) {
+    println(`✓ Registry valid (${result.summary})`);
+    return;
+  }
+  if (!result.valid) result.errors.forEach((e, i) => errorln(`${i + 1}. ${e}`));
+  process.exit(1);
+}
+
+async function cmdModels(args) {
+  const tier = args.find((arg) => arg.startsWith('--tier='))?.split('=')[1] ?? '';
+  const setModel = args.find((arg) => arg.startsWith('--set='))?.split('=')[1] ?? '';
+  const envPath = getUserEnvPath(HOME);
+  if (args.includes('--reset')) {
+    resetEnv(envPath);
+    println('Removed CX_MODEL_* overrides from ~/.construct/config.env.');
+    await cmdSync([]);
+    return;
+  }
+  if (tier && setModel) {
+    const preferFree = args.includes('--prefer-free');
+    const preferFreeSameFamily = args.includes('--prefer-free-same-family');
+    const inferred = setModelWithTierInference(envPath, tier, setModel, registry.models ?? {}, { preferFree, preferFreeSameFamily });
+    println(`Set ${tier} -> ${setModel} in ~/.construct/config.env`);
+    if (preferFreeSameFamily) println('Prefer-free-same-family mode: enabled');
+    if (preferFree) println('Prefer-free mode: enabled');
+    println(`Resolved tier set:`);
     println(`  reasoning  ${String(inferred.reasoning)}`);
     println(`  standard   ${String(inferred.standard)}`);
     println(`  fast       ${String(inferred.fast)}`);
@@ -424,9 +2451,20 @@ async function cmdModels(args) {
   }
   const registry = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'agents', 'registry.json'), 'utf8'));
   const result = readCurrentModels(envPath, registry.models ?? {});
+  const nothingSelected = ['reasoning', 'standard', 'fast'].every((t) => !result[t]);
   println('Current model assignments:');
   for (const currentTier of ['reasoning', 'standard', 'fast']) {
-    println(`  ${currentTier.padEnd(11)}${String(result[currentTier] ?? '(none)')}`);
+    const id = result[currentTier];
+    const source = result.sources?.[currentTier] || (id ? 'registry' : 'not configured');
+    println(`  ${currentTier.padEnd(11)}${id ? `${id} [${source}]` : '(not configured)'}`);
+  }
+  if (nothingSelected) {
+    println('');
+    println('No tier has a model selected. Construct ships with no default.');
+    println('Pick one of:');
+    println('  • Dashboard → Models page (single source of truth)');
+    println('  • construct models --set=<provider/model-id> --tier=reasoning|standard|fast');
+    println('  • construct models --apply           Poll OpenRouter free catalog and seed all tiers');
   }
 }
 
@@ -441,16 +2479,202 @@ async function cmdMcp(args) {
   process.exit(1);
 }
 
+async function cmdOllamaCmd(args) {
+  return cmdOllama(args);
+}
+
+async function cmdPlugin(args) {
+  const [subcmd = 'list', id, ...rest] = args;
+  const registry = loadPluginRegistry({ cwd: process.cwd(), homeDir: HOME, rootDir: ROOT_DIR, env: process.env });
+
+  if (subcmd === 'list') {
+    println('Construct Plugins');
+    println('═════════════════');
+    println('');
+    for (const plugin of registry.plugins) {
+      const source = plugin.builtIn ? 'built-in' : path.relative(process.cwd(), plugin.manifestPath);
+      println(`  ${plugin.id.padEnd(22)} ${plugin.version.padEnd(8)} ${plugin.name}`);
+      println(`    ${source}`);
+      if ((plugin.mcps ?? []).length) println(`    mcps: ${(plugin.mcps ?? []).map((mcp) => mcp.id).join(', ')}`);
+    }
+    if (registry.errors.length) {
+      println('');
+      errorln('Registry errors:');
+      for (const error of registry.errors) errorln(`  ✗ ${error}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (subcmd === 'validate') {
+    if (registry.valid) {
+      println(`✓ Plugin registry valid (${registry.plugins.length} plugins, ${registry.mcps.length} MCP entries)`);
+      return;
+    }
+    for (const error of registry.errors) errorln(`✗ ${error}`);
+    process.exit(1);
+  }
+
+  if (subcmd === 'info') {
+    const plugin = getPluginById(id, { cwd: process.cwd(), homeDir: HOME, rootDir: ROOT_DIR, env: process.env });
+    if (!plugin) {
+      errorln(`Unknown plugin: ${id}`);
+      process.exit(1);
+    }
+    println(`${plugin.name} (${plugin.id})`);
+    println('─'.repeat(48));
+    println(`Version:      ${plugin.version}`);
+    println(`Capabilities: ${(plugin.capabilities ?? []).join(', ') || '(none)'}`);
+    println(`Source:       ${plugin.builtIn ? 'built-in' : plugin.manifestPath}`);
+    println(`MCPs:         ${(plugin.mcps ?? []).map((mcp) => mcp.id).join(', ') || '(none)'}`);
+    println(`\n${plugin.description}`);
+    return;
+  }
+
+  if (subcmd === 'init') {
+    if (!id) {
+      errorln('Usage: construct plugin init <plugin-id> [--force]');
+      process.exit(1);
+    }
+    try {
+      const filePath = initPluginManifest(id, { cwd: process.cwd(), force: rest.includes('--force') });
+      println(`✓ Created plugin manifest at ${path.relative(process.cwd(), filePath)}`);
+      return;
+    } catch (error) {
+      errorln(error?.message || 'plugin init failed');
+      process.exit(1);
+    }
+  }
+
+  if (subcmd === 'engine') {
+    return await cmdPluginEngine([id, ...rest].filter(Boolean));
+  }
+
+  errorln(`Unknown plugin subcommand: ${subcmd}`);
+  process.exit(1);
+}
+
+async function cmdPluginEngine(args) {
+  const [action = 'list', ...rest] = args;
+  const isGlobal = rest.includes('--global');
+  const targetPath = isGlobal
+    ? path.join(HOME, '.construct', 'plugins.json')
+    : path.join(process.cwd(), '.cx', 'plugins.json');
+
+  function readPluginsJson() {
+    if (!fs.existsSync(targetPath)) return { plugins: [] };
+    try { return JSON.parse(fs.readFileSync(targetPath, 'utf8')); } catch { return { plugins: [] }; }
+  }
+  function writePluginsJson(data) {
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, JSON.stringify(data, null, 2) + '\n');
+  }
+
+  const { describeEngine, LAYERS } = await import('../lib/engine/index.mjs');
+
+  if (action === 'list') {
+    const desc = await describeEngine({ rootDir: process.cwd() });
+    println('Engine plugins');
+    println('══════════════');
+    for (const entry of desc.summary) {
+      println(`  ${entry.layer.padEnd(11)} ${entry.id.padEnd(32)} (${entry.source})`);
+    }
+    if (desc.errors.length) {
+      println('');
+      errorln('Override errors:');
+      for (const e of desc.errors) errorln(`  ✗ [${e.layer}] ${e.error}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (action === 'add') {
+    const layer = rest[0];
+    const pkg = rest[1];
+    if (!layer || !pkg) {
+      errorln('Usage: construct plugin engine add <layer> <package> [--global]');
+      errorln(`       layer ∈ {${LAYERS.join(', ')}}`);
+      errorln('       package: npm name, absolute path, or github:owner/repo#sha');
+      process.exit(1);
+    }
+    if (!LAYERS.includes(layer)) {
+      errorln(`Unknown layer '${layer}'. Allowed: ${LAYERS.join(', ')}`);
+      process.exit(1);
+    }
+    const data = readPluginsJson();
+    data.plugins ??= [];
+    if (data.plugins.some((p) => p.layer === layer && p.package === pkg)) {
+      println(`Already present: ${layer} → ${pkg}`);
+      return;
+    }
+    data.plugins.push({ layer, package: pkg, options: {} });
+    writePluginsJson(data);
+    println(`✓ Added ${layer} → ${pkg} (${path.relative(process.cwd(), targetPath)})`);
+    println('  Run `construct plugin engine list` to verify it loads.');
+    return;
+  }
+
+  if (action === 'remove') {
+    const layer = rest[0];
+    const pkg = rest[1];
+    if (!layer || !pkg) {
+      errorln('Usage: construct plugin engine remove <layer> <package> [--global]');
+      process.exit(1);
+    }
+    const data = readPluginsJson();
+    const before = (data.plugins ?? []).length;
+    data.plugins = (data.plugins ?? []).filter((p) => !(p.layer === layer && p.package === pkg));
+    if (data.plugins.length === before) {
+      println(`No entry to remove for ${layer} → ${pkg}`);
+      return;
+    }
+    writePluginsJson(data);
+    println(`✓ Removed ${layer} → ${pkg}`);
+    return;
+  }
+
+  errorln(`Unknown plugin engine action: ${action}. Available: list, add, remove`);
+  process.exit(1);
+}
+
 async function cmdDiff() {
   warn('construct diff is not yet ported to the Node CLI surface. Use git diff for now.');
 }
 
-async function cmdOptimize() {
-  warn('construct optimize remains available only in environments with Python + DSPy ready.');
+async function cmdOptimize(args) {
+  runNodeScript(path.join(ROOT_DIR, 'scripts', 'optimize.mjs'), args, ENV);
+}
+
+async function cmdSeedTraces(args) {
+  runNodeScript(path.join(ROOT_DIR, 'scripts', 'seed-traces.mjs'), args, ENV);
 }
 
 async function cmdCleanup() {
-  warn('construct cleanup is not yet fully ported cross-platform.');
+  const force = restArgsCache.includes('--pressure-release');
+  const quiet = restArgsCache.includes('--quiet');
+  const report = runPressureRelease({ env: process.env, force });
+
+  if (!quiet) {
+    const swap = report.swapUsage
+      ? `${(report.swapUsage.usedBytes / (1024 ** 3)).toFixed(1)} GiB used`
+      : 'swap unavailable';
+    println(`Pressure guard: ${report.pressureTriggered ? 'triggered' : 'standby'} · ${swap}`);
+    for (const entry of report.warnings ?? []) {
+      const grace = entry.graceMinutes ? `; will terminate after ${entry.graceMinutes}m if still matched` : '';
+      println(`Warning pid ${entry.pid} (${entry.reason})${grace}`);
+    }
+  }
+
+  if (!report.killed.length) {
+    if (!quiet) println('No stale dev-agent processes needed cleanup.');
+    return;
+  }
+
+  if (!quiet) {
+    for (const entry of report.killed) {
+      println(`Stopped pid ${entry.pid} (${entry.reason})`);
+    }
+  }
 }
 
 async function cmdCost(args) {
@@ -490,11 +2714,53 @@ async function cmdEfficiency(args) {
 }
 
 async function cmdEvals(args) {
+  const sub = args[0];
+
+  if (sub === 'retrieval') {
+    const jsonOutput = args.includes('--json');
+    const fixtureArg = args.find((a) => a.startsWith('--fixture='));
+    const defaultFixture = path.join(ROOT_DIR, 'tests', 'fixtures', 'retrieval-eval', 'queries.json');
+    const fixturePath = fixtureArg ? fixtureArg.split('=')[1] : defaultFixture;
+
+    const { evaluateFixture, formatReport } = await import('../lib/engine/eval-retrieval.mjs');
+    const report = await evaluateFixture(fixturePath);
+
+    try {
+      const cacheDir = path.join(HOME, '.cx', 'evals');
+      fs.mkdirSync(cacheDir, { recursive: true });
+      const ts = new Date().toISOString();
+      fs.writeFileSync(
+        path.join(cacheDir, 'retrieval-latest.json'),
+        JSON.stringify({ ts, fixture: fixturePath, report }, null, 2),
+      );
+      const sum = report?.summary || report || {};
+      const historyEntry = {
+        ts,
+        fixture: path.basename(fixturePath),
+        recallAt5: sum.recallAt5 ?? sum.recall_at_5 ?? null,
+        precisionAt5: sum.precisionAt5 ?? sum.precision_at_5 ?? null,
+        mrr: sum.mrr ?? null,
+        p50LatencyMs: sum.p50LatencyMs ?? sum.p50_latency_ms ?? null,
+        p95LatencyMs: sum.p95LatencyMs ?? sum.p95_latency_ms ?? null,
+      };
+      fs.appendFileSync(path.join(cacheDir, 'retrieval-history.jsonl'), JSON.stringify(historyEntry) + '\n');
+    } catch { /* cache write is best-effort */ }
+
+    if (jsonOutput) {
+      println(JSON.stringify(report, null, 2));
+      return;
+    }
+    println(`Retrieval evaluation — ${path.relative(ROOT_DIR, fixturePath)}`);
+    println('═══════════════════════════════════════════════════════');
+    println(formatReport(report));
+    return;
+  }
+
   const jsonOutput = args.includes('--json');
   const catalog = {
-    description: 'Evaluators are managed via Langfuse quality scores. Use cx_score MCP tool or POST /api/public/scores to record quality scores.',
-    backendUrl: process.env.LANGFUSE_BASEURL ?? 'http://localhost:3000',
-    configured: Boolean(process.env.LANGFUSE_PUBLIC_KEY && process.env.LANGFUSE_SECRET_KEY),
+    description: 'Evaluators are managed via telemetry quality scores. Use cx_score MCP tool or POST /api/public/scores to record quality scores. Run `construct evals retrieval` for the local IR-metric harness against a fixture corpus.',
+    backendUrl: process.env.CONSTRUCT_TELEMETRY_BASEURL ?? 'http://localhost:3000',
+    configured: Boolean(process.env.CONSTRUCT_TELEMETRY_PUBLIC_KEY && process.env.CONSTRUCT_TELEMETRY_SECRET_KEY),
   };
   if (jsonOutput) {
     println(JSON.stringify(catalog, null, 2));
@@ -503,11 +2769,14 @@ async function cmdEvals(args) {
   println('Evaluator Catalog');
   println('═════════════════');
   println('');
-  println(`Backend:     Langfuse (${catalog.backendUrl})`);
-  println(`Configured:  ${catalog.configured ? 'yes' : 'no — set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY'}`);
+  println(`Backend:     Telemetry (${catalog.backendUrl})`);
+  println(`Configured:  ${catalog.configured ? 'yes' : 'no — set CONSTRUCT_TELEMETRY_PUBLIC_KEY and CONSTRUCT_TELEMETRY_SECRET_KEY'}`);
   println('');
   println('Quality scores are recorded by agents via the cx_score MCP tool.');
-  println('View and manage scores at your Langfuse dashboard.');
+  println('View and manage scores at your telemetry dashboard.');
+  println('');
+  println('Local retrieval evaluation:');
+  println('  construct evals retrieval [--fixture=PATH] [--json]');
 }
 
 async function cmdDocsUpdate(args) {
@@ -531,62 +2800,539 @@ async function cmdDocsUpdate(args) {
   }
 }
 
+async function cmdDocsCheck(args) {
+  const jsonOutput = args.includes('--json');
+  const { checkDocsCoverage } = await import('../lib/auto-docs.mjs');
+  const result = checkDocsCoverage({ rootDir: ROOT_DIR });
+  if (jsonOutput) {
+    println(JSON.stringify(result, null, 2));
+    return;
+  }
+  println(`Doc coverage: ${result.covered.length}/${result.total} commands have a how-to guide`);
+  if (result.uncovered.length === 0) {
+    ok('All user-facing commands are covered by a how-to guide.');
+  } else {
+    println('');
+    println('Commands with no linked how-to in docs/README.md:');
+    for (const name of result.uncovered) println(`  ✗  construct ${name}`);
+    println('');
+    println(`Add cookbook recipes under docs/cookbook/ and link them from the cookbook index.`);
+    process.exitCode = 1;
+  }
+}
+
 async function cmdDocsSite() {
-  const { buildSite } = await import('../lib/auto-docs.mjs');
-  await buildSite({ rootDir: ROOT_DIR });
-  ok('site/docs/ generated successfully.');
+  const { buildFumadocsReference } = await import('../lib/auto-docs.mjs');
+  const { written } = buildFumadocsReference({ rootDir: ROOT_DIR });
+  if (written.length === 0) {
+    ok('docs/reference/ already up to date.');
+  } else {
+    ok(`docs/reference/ regenerated (${written.length} file${written.length === 1 ? '' : 's'}).`);
+  }
+}
+
+async function cmdDashboardSync(args) {
+  const { runDashboardStaticCli } = await import('../lib/dashboard-static.mjs');
+  const exitCode = await runDashboardStaticCli(args, { rootDir: ROOT_DIR });
+  if (exitCode) process.exit(exitCode);
+}
+
+async function cmdBootstrap(args) {
+  const verbose = args.includes('--verbose') || args.includes('-v');
+  const { runBootstrap } = await import('../lib/bootstrap.mjs');
+  const { imported, skipped, error } = runBootstrap(process.cwd(), { verbose });
+  if (error) { errorln(error); process.exit(1); }
+  ok(`Bootstrap complete: ${imported} imported, ${skipped} skipped (already present).`);
+}
+
+async function cmdMemory(args) {
+  const sub = args[0];
+  if (sub === 'stats') {
+    const { computeStats, formatStats } = await import('../lib/memory-stats.mjs');
+    const projectArg = args.find((a) => a.startsWith('--project='));
+    const project = projectArg ? projectArg.split('=')[1] : null;
+    const lastNArg = args.find((a) => a.startsWith('--last='));
+    const lastN = lastNArg ? Number.parseInt(lastNArg.split('=')[1], 10) || 50 : 50;
+    const stats = computeStats(process.cwd(), { project, lastN });
+    process.stdout.write(formatStats(stats));
+    return;
+  }
+  if (sub === 'consolidate') {
+    const { consolidate } = await import('../lib/engine/consolidate.mjs');
+    const { getEngine } = await import('../lib/engine/index.mjs');
+    const engine = await getEngine({ rootDir: process.cwd() });
+    const summariser = engine.layers.compressor;
+    const thresholdArg = args.find((a) => a.startsWith('--threshold='));
+    const archiveDaysArg = args.find((a) => a.startsWith('--archive-days='));
+    const opts = { summariser };
+    if (thresholdArg) opts.similarityThreshold = Number(thresholdArg.split('=')[1]);
+    if (archiveDaysArg) opts.archiveAfterDays = Number(archiveDaysArg.split('=')[1]);
+    const result = await consolidate(process.cwd(), opts);
+    process.stdout.write(
+      `consolidate: ${result.clustersBefore} observations → ${result.clusters} insights, ` +
+      `${result.archived.length} archived, ${result.archivePruned ?? 0} pruned from archive\n`
+    );
+    return;
+  }
+  errorln(`Unknown memory subcommand: ${sub || '(none)'}. Available: stats, consolidate`);
+  process.exit(1);
 }
 
 async function cmdLintComments(args) {
   const fix = args.includes('--fix');
-  const { lintRepo: lint, formatResults: fmt } = await import('../lib/comment-lint.mjs');
-  const results = lint({ rootDir: ROOT_DIR, fix });
+  const staged = args.includes('--staged');
+  const { lintRepo: lint, lintFile, formatResults: fmt } = await import('../lib/comment-lint.mjs');
+
+  let results;
+  if (staged) {
+    const { execSync } = await import('node:child_process');
+    let stagedList = '';
+    try {
+      stagedList = execSync('git diff --cached --name-only --diff-filter=ACMR', {
+        cwd: process.cwd(),
+        timeout: 3000,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).toString();
+    } catch {
+      process.stdout.write('  ✓  No staged files to lint.\n');
+      return;
+    }
+    const rels = stagedList.split('\n').map((s) => s.trim()).filter(Boolean)
+      .filter((f) => /\.(mjs|js|md|sh)$/.test(f));
+    if (!rels.length) {
+      process.stdout.write('  ✓  No staged comment-eligible files.\n');
+      return;
+    }
+    const path = (await import('node:path')).default;
+    results = rels
+      .map((rel) => lintFile(path.join(process.cwd(), rel), { rootDir: process.cwd(), fix }))
+      .filter((r) => r.errors.length || r.warnings.length);
+  } else {
+    results = lint({ rootDir: ROOT_DIR, fix });
+  }
+
   const { output, exitCode } = fmt(results);
   process.stdout.write(output);
   if (exitCode !== 0) process.exit(exitCode);
 }
 
+async function cmdGatesAudit(args) {
+  const { auditGates, formatReport } = await import('../lib/gates-audit.mjs');
+  const report = auditGates({ rootDir: ROOT_DIR });
+  if (args.includes('--json')) {
+    println(JSON.stringify(report, null, 2));
+  } else {
+    process.stdout.write(formatReport(report));
+  }
+  if (!report.ok) process.exit(1);
+}
+
+async function cmdLintTemplates(args) {
+  const bodyFileArg = args.find((a) => a.startsWith('--body-file='))?.split('=').slice(1).join('=');
+  const bodyArgIdx = args.indexOf('--body-file');
+  const bodyFile = bodyFileArg || (bodyArgIdx >= 0 ? args[bodyArgIdx + 1] : null);
+  const inlineBody = args.find((a) => a.startsWith('--body='))?.split('=').slice(1).join('=');
+  const env = { ...process.env };
+  if (bodyFile) env.PR_BODY_FILE = path.resolve(process.cwd(), bodyFile);
+  if (inlineBody) env.PR_BODY = inlineBody;
+  const result = spawnSync(
+    process.execPath,
+    [path.join(ROOT_DIR, 'scripts', 'lint-commits-pr.mjs')],
+    { stdio: 'inherit', env },
+  );
+  process.exit(result.status ?? 0);
+}
+
+async function cmdLintResearch() {
+  const { lintResearchRepo, formatResearchLintResults } = await import('../lib/research-lint.mjs');
+  const results = lintResearchRepo({ rootDir: process.cwd() });
+  const { output, exitCode } = formatResearchLintResults(results);
+  process.stdout.write(output);
+  if (exitCode !== 0) process.exit(exitCode);
+}
+
+async function cmdLintAgents() {
+  const { validateRegistryFile } = await import('../lib/agents/schema.mjs');
+  const registryPath = path.join(ROOT_DIR, 'agents', 'registry.json');
+  const { errors, agentCount } = validateRegistryFile({ registryPath, rootDir: ROOT_DIR });
+  if (errors.length === 0) {
+    console.log(`agents/registry.json: ${agentCount} agents, 0 errors`);
+    return;
+  }
+  console.error(`agents/registry.json: ${errors.length} error(s) across ${agentCount} agents`);
+  for (const err of errors) console.error(`  ${err}`);
+  process.exit(1);
+}
+
+async function cmdBackup(args) {
+  const sub = args[0];
+
+  if (!sub || sub === 'create') {
+    const includeSecrets = args.includes('--include-secrets');
+    const noPrune = args.includes('--no-prune');
+    const keepArg = args.find((a) => a.startsWith('--keep='));
+    const keep = keepArg
+      ? Number(keepArg.split('=')[1])
+      : Number(process.env.CONSTRUCT_BACKUP_RETAIN || 10);
+    const { createBackup, pruneBackups } = await import('../lib/storage/backup.mjs');
+    println('Creating backup…');
+    try {
+      const result = await createBackup({ includeSecrets });
+      ok(`Backup created: ${result.path}`);
+      println(`  Contents: ${result.manifest.contents.join(', ') || '(empty)'}`);
+      if (!includeSecrets) println('  Secrets redacted. Use --include-secrets to include them.');
+      if (!noPrune) {
+        const pruned = pruneBackups({ keep });
+        if (pruned.removed.length) {
+          println(`  Auto-pruned ${pruned.removed.length} old backup(s); kept ${pruned.kept}.`);
+        }
+      }
+    } catch (err) {
+      errorln(`Backup failed: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (sub === 'prune') {
+    const keepArg = args.find((a) => a.startsWith('--keep='));
+    const keep = keepArg
+      ? Number(keepArg.split('=')[1])
+      : Number(process.env.CONSTRUCT_BACKUP_RETAIN || 10);
+    const { pruneBackups } = await import('../lib/storage/backup.mjs');
+    const result = pruneBackups({ keep });
+    if (result.removed.length === 0) {
+      println(`Nothing to prune (have ${result.kept}, keeping ${keep}).`);
+    } else {
+      ok(`Pruned ${result.removed.length} backup(s); kept ${result.kept}.`);
+      for (const r of result.removed) println(`  removed ${r}`);
+    }
+    return;
+  }
+
+  if (sub === 'verify') {
+    const archivePath = args[1];
+    if (!archivePath) { errorln('Usage: construct backup verify <archive>'); process.exit(1); }
+    const { verifyBackup } = await import('../lib/storage/backup.mjs');
+    const result = await verifyBackup(archivePath);
+    if (result.ok) {
+      ok('Backup verified — all checksums match.');
+    } else {
+      errorln(`Backup verification failed:\n  ${result.errors.join('\n  ')}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (sub === 'restore') {
+    const archivePath = args[1];
+    const yes = args.includes('--yes');
+    if (!archivePath) { errorln('Usage: construct backup restore <archive> [--yes]'); process.exit(1); }
+    if (!yes) {
+      println(`About to restore from: ${archivePath}`);
+      println('This will overwrite observations, sessions, config.env, and registry.json.');
+      println('Press Ctrl+C to cancel, or re-run with --yes to proceed.');
+      await new Promise((r) => setTimeout(r, 3000));
+    }
+    const { restoreBackup } = await import('../lib/storage/backup.mjs');
+    const result = await restoreBackup(archivePath, { yes });
+    if (result.ok) {
+      ok(`Restored: ${result.restored.join(', ')}`);
+    } else {
+      if (result.restored.length) println(`Partially restored: ${result.restored.join(', ')}`);
+      errorln(`Errors:\n  ${result.errors.join('\n  ')}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (sub === 'list') {
+    const { listBackups } = await import('../lib/storage/backup.mjs');
+    const backups = listBackups();
+    if (!backups.length) { println('No backups found.'); return; }
+    for (const b of backups) {
+      const mb = (b.size / 1024 / 1024).toFixed(1);
+      println(`  ${b.name}  (${mb} MB)  ${b.mtime.toISOString().slice(0, 19)}`);
+    }
+    return;
+  }
+
+  errorln(`Unknown backup subcommand: ${sub}. Available: create, verify, restore, list, prune`);
+  process.exit(1);
+}
+
+async function cmdProvider(args) {
+  const sub = args[0];
+
+  if (!sub || sub === 'list') {
+    const { describeProviders } = await import('../lib/providers/registry.mjs');
+    const desc = await describeProviders({ rootDir: process.cwd(), env: process.env });
+    println('Data-source providers');
+    println('═════════════════════');
+    for (const entry of desc.summary) {
+      const status = entry.health.ok ? '✓' : '○';
+      println(`  ${status}  ${entry.id.padEnd(24)} ${entry.displayName}`);
+      println(`     capabilities: ${entry.capabilities.join(', ')}`);
+      if (entry.health.detail) println(`     health: ${entry.health.detail}`);
+      if (entry.source && entry.source !== 'built-in') println(`     source: ${entry.source}`);
+    }
+    if (desc.errors.length) {
+      println('');
+      errorln('Errors loading providers:');
+      for (const e of desc.errors) errorln(`  ✗ [${e.id}] ${e.error}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (sub === 'info') {
+    const id = args[1];
+    if (!id) { errorln('Usage: construct provider info <id>'); process.exit(1); }
+    const { resolveProviders } = await import('../lib/providers/registry.mjs');
+    const { providers, errors } = await resolveProviders({ rootDir: process.cwd(), env: process.env });
+    if (!providers[id]) {
+      errorln(`Unknown provider: ${id}`);
+      if (errors.find((e) => e.id === id)) errorln(errors.find((e) => e.id === id).error);
+      process.exit(1);
+    }
+    const p = providers[id];
+    println(`${p.meta.displayName} (${p.meta.id})`);
+    println('─'.repeat(48));
+    println(`Capabilities: ${p.meta.capabilities.join(', ')}`);
+    if (p.meta.description) println(`Description:  ${p.meta.description}`);
+    if (p.configSchema) {
+      println('');
+      println('Config schema:');
+      println(JSON.stringify(p.configSchema, null, 2));
+    }
+    return;
+  }
+
+  if (sub === 'test') {
+    const id = args[1];
+    if (!id) { errorln('Usage: construct provider test <id>'); process.exit(1); }
+    const { resolveProviders } = await import('../lib/providers/registry.mjs');
+    const { providers } = await resolveProviders({ rootDir: process.cwd(), env: process.env });
+    if (!providers[id]) { errorln(`Unknown provider: ${id}`); process.exit(1); }
+    const health = await providers[id].health({});
+    println(`${id}: ${health.ok ? 'ok' : 'unhealthy'}`);
+    if (health.detail) println(`  ${health.detail}`);
+    process.exit(health.ok ? 0 : 1);
+  }
+
+  if (sub === 'plugins') {
+    const action = args[1];
+    if (action === 'add' || action === 'remove') {
+      const id = args[2];
+      const pkg = args[3];
+      if (!id) { errorln(`Usage: construct provider plugins ${action} <id> [<package>]`); process.exit(1); }
+      const isGlobal = args.includes('--global');
+      const targetPath = isGlobal
+        ? path.join(HOME, '.construct', 'providers.json')
+        : path.join(process.cwd(), '.cx', 'providers.json');
+      let data = { providers: [] };
+      try { data = JSON.parse(fs.readFileSync(targetPath, 'utf8')); } catch { /* fresh */ }
+      data.providers ??= [];
+      if (action === 'add') {
+        if (!pkg) { errorln(`Usage: construct provider plugins add <id> <package>`); process.exit(1); }
+        if (data.providers.some((p) => p.id === id && p.package === pkg)) {
+          println(`Already present: ${id} → ${pkg}`);
+          return;
+        }
+        data.providers.push({ id, package: pkg, options: {} });
+      } else {
+        data.providers = data.providers.filter((p) => p.id !== id);
+      }
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      fs.writeFileSync(targetPath, JSON.stringify(data, null, 2) + '\n');
+      println(`✓ ${action === 'add' ? 'Added' : 'Removed'} ${id}${pkg ? ` → ${pkg}` : ''} (${path.relative(process.cwd(), targetPath)})`);
+      return;
+    }
+    errorln(`Usage: construct provider plugins <add|remove> <id> [<package>] [--global]`);
+    process.exit(1);
+  }
+
+  errorln(`Unknown provider subcommand: ${sub}. Available: list, info, test, plugins`);
+  process.exit(1);
+}
+
+async function cmdHook(args) {
+  const name = args[0];
+  if (!name) {
+    errorln('Usage: construct hook <name>  (e.g. construct hook session-start)');
+    process.exit(1);
+  }
+  const safe = name.replace(/[^a-z0-9-]/gi, '');
+  if (safe !== name) {
+    errorln(`Invalid hook name '${name}': use lowercase letters, digits, or hyphens.`);
+    process.exit(1);
+  }
+  const hookPath = path.join(ROOT_DIR, 'lib', 'hooks', `${safe}.mjs`);
+  if (!fs.existsSync(hookPath)) {
+    errorln(`Hook not found: ${hookPath}`);
+    process.exit(1);
+  }
+  const result = spawnSync(process.execPath, [hookPath, ...args.slice(1)], { stdio: 'inherit' });
+  process.exit(result.status ?? 0);
+}
+
 const [command, ...rest] = process.argv.slice(2);
 const restArgsCache = rest;
 
 const handlers = new Map([
-  ['up', cmdUp],
-  ['down', cmdDown],
+  // Core
+  ['dev', cmdUp],
+  ['stop', cmdDown],
   ['status', cmdStatus],
-  ['show', cmdShow],
-  ['serve', cmdServe],
-  ['setup', cmdSetup],
+  ['install', cmdSetup],
+  ['config', cmdConfig],
+  ['intake', cmdIntake],
+  ['recommendations', cmdRecommendations],
+  ['integrations', cmdIntegrations],
+  ['customer', cmdCustomer],
+  ['workspace', cmdWorkspace],
+  ['graph', cmdGraph],
+  ['uninstall', cmdUninstall],
+  ['update', cmdUpdate],
+  ['upgrade', cmdUpgrade],
+  ['completions', cmdCompletions],
   ['sync', cmdSync],
   ['list', cmdList],
   ['doctor', cmdDoctor],
   ['validate', cmdValidate],
   ['diff', cmdDiff],
-  ['do', cmdDo],
   ['distill', cmdDistill],
-  ['research', cmdResearch],
-  ['docs', cmdDocs],
+  ['ingest', cmdIngest],
+  ['infer', cmdInfer],
   ['search', cmdSearch],
   ['storage', cmdStorage],
+  ['pricing', cmdPricing],
+  ['overrides', cmdOverrides],
+  ['prune', cmdPrune],
+  ['resources', cmdResources],
+  ['costs', cmdCosts],
+  ['handoffs', cmdHandoffs],
   ['headhunt', cmdHeadhunt],
-  ['workflow', async (args) => runWorkflowCli(args)],
-  ['init-docs', cmdInitDocs],
+  ['init', cmdInit],
+  ['docs:verify', cmdDocsVerify],
+  ['init:update', cmdInitUpdate],
   ['models', cmdModels],
+  ['beads:stats', async (args) => {
+    const { getContentionStats, getHumanStatus } = await import('../lib/beads-optimistic.mjs');
+    const jsonOutput = args.includes('--json');
+    if (args.includes('--health')) {
+      process.stdout.write(await getHumanStatus(process.cwd()));
+      return;
+    }
+    const stats = await getContentionStats(process.cwd());
+    if (jsonOutput) {
+      println(JSON.stringify(stats, null, 2));
+    } else {
+      println('Beads Contention Statistics');
+      println('============================');
+      println(`Total operations: ${stats.totalOperations || 0}`);
+      println(`Conflicts: ${stats.conflicts || 0}`);
+      println(`Retries: ${stats.retries || 0}`);
+      println(`Average attempts: ${stats.avgAttempts?.toFixed(2) || '1.00'}`);
+      if (stats.operations) {
+        println('\nPer-operation breakdown:');
+        for (const [op, data] of Object.entries(stats.operations)) {
+          println(`  ${op}: ${data.count} calls, ${data.conflicts} conflicts`);
+        }
+      }
+    }
+  }],
+  ['hooks:health', async (args) => {
+    const { checkAllHooksHealth, formatHealthStatus } = await import('../lib/hook-health.mjs');
+    const health = await checkAllHooksHealth({ 
+      verbose: true, 
+      fix: args.includes('--fix') 
+    });
+    if (args.includes('--json')) {
+      println(JSON.stringify(health, null, 2));
+    } else {
+      process.stdout.write(formatHealthStatus(health));
+    }
+    if (!health.healthy) {
+      process.exit(1);
+    }
+  }],
+  ['policy:list', async (args) => {
+    const { listPolicies, formatPolicyList } = await import('../lib/policy/unified-gates.mjs');
+    if (args.includes('--json')) {
+      println(JSON.stringify(listPolicies(), null, 2));
+    } else {
+      process.stdout.write(formatPolicyList());
+    }
+  }],
+  ['auth:status', async (args) => {
+    const { getTokenStatus } = await import('../lib/providers/auth-manager.mjs');
+    const providers = ['github', 'slack', 'jira', 'salesforce', 'linear'];
+    const results = {};
+    for (const provider of providers) {
+      results[provider] = getTokenStatus(provider);
+    }
+    if (args.includes('--json')) {
+      println(JSON.stringify(results, null, 2));
+    } else {
+      println('Provider Auth Status');
+      println('====================');
+      for (const [provider, status] of Object.entries(results)) {
+        const icon = status.valid ? '✓' : '✗';
+        println(`${icon} ${provider}: ${status.valid ? 'valid' : status.error}`);
+        if (status.expiresIn) {
+          println(`  Expires in: ${Math.floor(status.expiresIn / 60)} minutes`);
+        }
+      }
+    }
+  }],
   ['mcp', cmdMcp],
+  ['ollama', cmdOllamaCmd],
+  ['plugin', cmdPlugin],
   ['hosts', cmdHosts],
   ['review', cmdReview],
   ['optimize', cmdOptimize],
+  ['seed-traces', cmdSeedTraces],
   ['cost', cmdCost],
   ['efficiency', cmdEfficiency],
   ['evals', cmdEvals],
   ['cleanup', cmdCleanup],
   ['version', cmdVersion],
   ['docs:update', cmdDocsUpdate],
+  ['docs:check', cmdDocsCheck],
   ['docs:site', cmdDocsSite],
+  ['dashboard:sync', cmdDashboardSync],
   ['lint:comments', cmdLintComments],
+  ['lint:templates', cmdLintTemplates],
+  ['gates:audit', cmdGatesAudit],
+  ['bootstrap', cmdBootstrap],
+  ['memory', cmdMemory],
+  ['hook', cmdHook],
+  ['backup', cmdBackup],
+  ['provider', cmdProvider],
+  ['lint:research', cmdLintResearch],
+  ['lint:agents', cmdLintAgents],
   ['audit', async (args) => {
     const sub = args[0];
     if (sub === 'skills') return runAuditSkillsCli(args.slice(1));
-    errorln(`Unknown audit subcommand: ${sub}. Available: skills`);
+    if (sub === 'trail' || !sub) {
+      const { runAuditTrailCli } = await import('../lib/audit-trail.mjs');
+      return runAuditTrailCli(args.slice(sub === 'trail' ? 1 : 0));
+    }
+    errorln(`Unknown audit subcommand: ${sub}. Available: skills, trail`);
+    process.exit(1);
+  }],
+  ['doc', async (args) => {
+    const sub = args[0];
+    if (sub === 'verify' || !sub) {
+      const { runDocVerifyCli } = await import('../lib/doc-verify.mjs');
+      return runDocVerifyCli(args.slice(sub === 'verify' ? 1 : 0));
+    }
+    if (sub === 'install-hooks') {
+      const { runDocInstallHooksCli } = await import('../lib/doc-verify.mjs');
+      return runDocInstallHooksCli(args.slice(1));
+    }
+    errorln(`Unknown doc subcommand: ${sub}. Available: verify, install-hooks`);
     process.exit(1);
   }],
   ['team', async (args) => {
@@ -596,9 +3342,456 @@ const handlers = new Map([
     errorln(`Unknown team subcommand: ${sub}. Available: review, templates`);
     process.exit(1);
   }],
+  ['role', async (args) => {
+    const { runCli } = await import('../lib/roles/cli.mjs');
+    const code = await runCli(args);
+    if (code) process.exit(code);
+  }],
+  ['roles:list', async (args) => {
+    const { listRoles, formatRoleList } = await import('../lib/roles/catalog.mjs');
+    const json = args.includes('--json');
+    const departments = args.includes('--departments');
+    const consolidated = args.includes('--consolidated');
+    
+    if (json) {
+      println(JSON.stringify(listRoles({ departments, consolidated }), null, 2));
+    } else {
+      process.stdout.write(formatRoleList({ departments, consolidated }));
+    }
+  }],
+  ['roles:set', async (args) => {
+    const { setRolePreference, getRolePreference } = await import('../lib/roles/preference.mjs');
+    const primaryIdx = args.indexOf('--primary');
+    const secondaryIdx = args.indexOf('--secondary');
+    const primary = primaryIdx !== -1 ? args[primaryIdx + 1] : null;
+    const secondary = secondaryIdx !== -1 ? args[secondaryIdx + 1] : null;
+    
+    if (primary) {
+      const result = setRolePreference('primary', primary);
+      println(`Primary role set: ${result.role}`);
+    }
+    if (secondary) {
+      const result = setRolePreference('secondary', secondary);
+      println(`Secondary role set: ${result.role}`);
+    }
+    if (!primary && !secondary) {
+      const prefs = { primary: getRolePreference('primary'), secondary: getRolePreference('secondary') };
+      println(`Current: primary=${prefs.primary || 'auto'}, secondary=${prefs.secondary || 'auto'}`);
+    }
+  }],
+  ['feedback:record', async (args) => {
+    const { createClassificationFeedback, recordFeedback, getAccuracyStats } = await import('../lib/intake/feedback.mjs');
+    const json = args.includes('--json');
+    const intakeIdIdx = args.indexOf('--intake');
+    const reasonIdx = args.indexOf('--reason');
+    const correctedIdx = args.indexOf('--corrected');
+    
+    if (intakeIdIdx === -1) {
+      // Show stats instead
+      const stats = getAccuracyStats(process.cwd());
+      if (json) {
+        println(JSON.stringify(stats, null, 2));
+      } else {
+        println('Classification Feedback Stats');
+        println('===========================');
+        println(`Total feedback: ${stats.overall.total}`);
+        println(`Corrections: ${stats.overall.corrected}`);
+        println(`Accuracy: ${(stats.overall.accuracy * 100).toFixed(1)}%`);
+      }
+      return;
+    }
+    
+    const intakeId = args[intakeIdIdx + 1];
+    const reason = reasonIdx !== -1 ? args[reasonIdx + 1] : 'other';
+    const corrected = correctedIdx !== -1 ? JSON.parse(args[correctedIdx + 1]) : null;
+    
+    if (!corrected) {
+      errorln('Usage: construct feedback:record --intake <id> --corrected \'{"intakeType":"bug","primaryOwner":"debugger"}\' [--reason wrong-owner]');
+      process.exit(1);
+    }
+    
+    const feedback = createClassificationFeedback({
+      intakeId,
+      original: { intakeType: 'unknown', primaryOwner: 'unknown' }, // Would load from intake
+      corrected,
+      reason,
+    });
+    
+    recordFeedback(process.cwd(), feedback);
+    println(`Feedback recorded for intake ${intakeId}`);
+  }],
+  ['feedback:history', async (args) => {
+    const { getFeedbackHistory, getKeywordAdjustments } = await import('../lib/intake/feedback.mjs');
+    const json = args.includes('--json');
+    const adjustments = args.includes('--adjustments');
+    const limitIdx = args.indexOf('--limit');
+    const limit = limitIdx !== -1 ? parseInt(args[limitIdx + 1], 10) : 20;
+    
+    if (adjustments) {
+      const adj = getKeywordAdjustments(process.cwd());
+      if (json) {
+        println(JSON.stringify(adj, null, 2));
+      } else {
+        println('Keyword Adjustment Suggestions');
+        println('==============================');
+        if (adj.length === 0) {
+          println('No patterns detected yet (need more feedback)');
+        } else {
+          for (const a of adj) {
+            println(`${a.frequency}x: ${a.suggestion}`);
+          }
+        }
+      }
+      return;
+    }
+    
+    const history = getFeedbackHistory(process.cwd(), { limit });
+    if (json) {
+      println(JSON.stringify(history, null, 2));
+    } else {
+      println(`Recent Feedback (last ${history.length})`);
+      for (const fb of history) {
+        println(`[${fb.timestamp}] ${fb.intakeId}: ${fb.reason}`);
+      }
+    }
+  }],
+  ['evaluator:rubrics', async (args) => {
+    const { listRubrics } = await import('../lib/evaluator-optimizer.mjs');
+    const json = args.includes('--json');
+    const rubrics = listRubrics();
+    
+    if (json) {
+      println(JSON.stringify(rubrics, null, 2));
+    } else {
+      println('Available Document Rubrics');
+      println('==========================');
+      for (const r of rubrics) {
+        println(`\n${r.docType.toUpperCase()} — ${r.name}`);
+        println(`Criteria (${r.criteriaCount}):`);
+        for (const c of r.criteria) {
+          println(`  - ${c.name} (${(c.weight * 100).toFixed(0)}%)`);
+        }
+      }
+    }
+  }],
+  ['activation:status', async (args) => {
+    const { getActivationSummary, getActivationStats } = await import('../lib/hooks/proactive-activation.mjs');
+    const json = args.includes('--json');
+    const specialistIdx = args.indexOf('--specialist');
+    
+    if (specialistIdx !== -1) {
+      const specialist = args[specialistIdx + 1];
+      const stats = getActivationStats(specialist);
+      if (json) {
+        println(JSON.stringify(stats, null, 2));
+      } else {
+        println(`Activation Stats: ${specialist}`);
+        println(`Recent: ${stats.recentActivations}/${stats.rateLimit} (rate limit)`);
+        println(`Total: ${stats.totalActivations}`);
+        println(`Last: ${stats.lastActivation ? new Date(stats.lastActivation).toISOString() : 'never'}`);
+      }
+    } else {
+      const summary = getActivationSummary();
+      if (json) {
+        println(JSON.stringify(summary, null, 2));
+      } else {
+        println('Proactive Activation Summary');
+        println('============================');
+        if (Object.keys(summary).length === 0) {
+          println('No activations recorded yet');
+        } else {
+          for (const [specialist, data] of Object.entries(summary)) {
+            println(`${specialist}: ${data.recentActivations} recent, ${data.totalActivations} total`);
+          }
+        }
+      }
+    }
+  }],
+  ['claude:allow', async (args) => {
+    const { listAllowEntries, addAllowEntries, removeAllowEntries, detectAllowlistGaps } =
+      await import('../lib/claude-allow.mjs');
+    const sub = args[0];
+    if (!sub || sub === 'list') {
+      const entries = listAllowEntries();
+      if (entries.length === 0) { console.log('(no permissions.allow entries)'); return; }
+      for (const e of entries) console.log(e);
+      return;
+    }
+    if (sub === 'add') {
+      const patterns = args.slice(1).filter(Boolean);
+      if (patterns.length === 0) { errorln('Usage: construct claude:allow add <pattern> [...]'); process.exit(1); }
+      const result = addAllowEntries(patterns);
+      for (const p of result.added) console.log(`+ ${p}`);
+      for (const p of result.existing) console.log(`= ${p} (already present)`);
+      console.log(`\n${result.added.length} added · ${result.existing.length} unchanged · ${result.total} total · ${result.path}`);
+      if (result.added.length > 0) console.log('Restart Claude Code so the classifier sees the new entries.');
+      return;
+    }
+    if (sub === 'remove') {
+      const patterns = args.slice(1).filter(Boolean);
+      if (patterns.length === 0) { errorln('Usage: construct claude:allow remove <pattern> [...]'); process.exit(1); }
+      const result = removeAllowEntries(patterns);
+      for (const p of result.removed) console.log(`- ${p}`);
+      for (const p of result.notFound) console.log(`? ${p} (not found)`);
+      console.log(`\n${result.removed.length} removed · ${result.notFound.length} not found · ${result.total} total`);
+      return;
+    }
+    if (sub === 'check') {
+      const apply = args.includes('--apply');
+      const gaps = detectAllowlistGaps({ cwd: process.cwd() });
+      if (gaps.length === 0) { console.log('No gaps detected — branch prefixes covered by current allowlist.'); return; }
+      console.log(`Detected ${gaps.length} gap${gaps.length === 1 ? '' : 's'} based on local branch prefixes:`);
+      for (const g of gaps) console.log(`  ${g.prefix}/ → ${g.pattern}`);
+      if (!apply) {
+        console.log(`\nRun \`construct claude:allow check --apply\` to add all ${gaps.length}, or \`construct claude:allow add '<pattern>'\` selectively.`);
+        return;
+      }
+      const result = addAllowEntries(gaps.map((g) => g.pattern));
+      console.log(`\n${result.added.length} added · ${result.total} total · ${result.path}`);
+      console.log('Restart Claude Code so the classifier sees the new entries.');
+      return;
+    }
+    errorln(`Unknown claude:allow subcommand: ${sub}. Available: list, add, remove, check`);
+    process.exit(1);
+  }],
+  ['telemetry-backfill', async (args) => {
+    const { runTelemetryBackfillCli } = await import('../lib/telemetry/backfill.mjs');
+    return runTelemetryBackfillCli(args);
+  }],
+  ['eval-datasets', async (args) => {
+    const { runEvalDatasetsCli } = await import('../lib/telemetry/eval-datasets.mjs');
+    return runEvalDatasetsCli(args);
+  }],
+  ['llm-judge', async (args) => {
+    const { runLLMJudgeCli } = await import('../lib/telemetry/llm-judge.mjs');
+    return runLLMJudgeCli(args);
+  }],
+  ['telemetry-setup', async (args) => {
+    const { runTelemetrySetupCli } = await import('../lib/telemetry/setup.mjs');
+    return runTelemetrySetupCli(args);
+  }],
+  ['beads', async (args) => {
+    const sub = args[0];
+    const subArgs = args.slice(1);
+    
+    if (!sub || sub === 'status') {
+      const jsonOutput = subArgs.includes('--json');
+      const status = getLockStatus({ cwd: process.cwd() });
+      if (jsonOutput) {
+        println(JSON.stringify(status, null, 2));
+      } else {
+        process.stdout.write(await getHumanStatus(process.cwd()));
+      }
+      return;
+    }
+
+    if (sub === 'cleanup') {
+      const staleLocks = cleanupStaleLock({ cwd: process.cwd() });
+      const staleQueue = cleanupStaleQueue({ cwd: process.cwd() });
+      println(`Cleaned up: ${staleLocks ? '1 stale lock' : 'no stale locks'}, ${staleQueue} stale queue entries`);
+      return;
+    }
+
+    if (sub === 'drift') {
+      const { detectBeadsDrift, formatDriftReport } = await import('../lib/beads/drift.mjs');
+      const jsonOutput = subArgs.includes('--json');
+      const opts = {};
+      for (const arg of subArgs) {
+        const m = arg.match(/^--([a-z-]+)=(\d+)$/);
+        if (!m) continue;
+        if (m[1] === 'stale-open-days') opts.staleOpenDays = Number(m[2]);
+        if (m[1] === 'stuck-in-progress-days') opts.stuckInProgressDays = Number(m[2]);
+        if (m[1] === 'merge-lookback') opts.mergeLookback = Number(m[2]);
+      }
+      const report = detectBeadsDrift(opts);
+      if (jsonOutput) {
+        println(JSON.stringify(report, null, 2));
+      } else {
+        process.stdout.write(formatDriftReport(report));
+      }
+      if (report.counts.stuckInProgress > 0 || report.counts.mergeDrift > 0) {
+        process.exit(2);
+      }
+      return;
+    }
+
+    if (sub === 'drift-report') {
+      // Writes a snapshot to .cx/handoffs/beads-drift-<date>.md for the
+      // weekly drift report mechanism the bd hygiene rule promises.
+      const { detectBeadsDrift, formatDriftReport } = await import('../lib/beads/drift.mjs');
+      const report = detectBeadsDrift();
+      const handoffsDir = path.join(process.cwd(), '.cx', 'handoffs');
+      fs.mkdirSync(handoffsDir, { recursive: true });
+      const date = new Date().toISOString().slice(0, 10);
+      const file = path.join(handoffsDir, `beads-drift-${date}.md`);
+      fs.writeFileSync(file, `# Beads drift report — ${date}\n\n${formatDriftReport(report)}\n`);
+      info(`Wrote ${file}`);
+      return;
+    }
+
+    if (sub === 'queue') {
+      const jsonOutput = subArgs.includes('--json');
+      const queue = readQueue({ cwd: process.cwd() });
+      if (jsonOutput) {
+        println(JSON.stringify(queue, null, 2));
+      } else {
+        if (!queue.length) {
+          println('No requests in queue');
+        } else {
+          println(`Queue (${queue.length}):`);
+          queue.forEach((entry, idx) => {
+            const alive = entry.pid && (() => {
+              try { process.kill(entry.pid, 0); return true; } catch { return false; }
+            })();
+            println(`  ${idx + 1}. ${entry.actor} – ${entry.command || entry.args?.join(' ')}${alive ? '' : ' ⚠️ dead'}`);
+          });
+        }
+      }
+      return;
+    }
+
+    if (sub === 'lock-status' || sub === 'lock') {
+      const status = getLockStatus({ cwd: process.cwd() });
+      println(JSON.stringify(status, null, 2));
+      return;
+    }
+
+    if (sub === 'help' || sub === '--help' || sub === '-h') {
+      println('construct beads — manage beads lock and queue');
+      println('');
+      println('Subcommands:');
+      println('  status        Show lock and queue status (default)');
+      println('  lock-status   Detailed lock info in JSON');
+      println('  cleanup       Remove stale locks and dead queue entries');
+      println('  queue         Show pending requests');
+      println('  help          This help');
+      println('');
+      println('Examples:');
+      println('  construct beads            # Show status');
+      println('  construct beads --json     # JSON status');
+      println('  construct beads queue      # Show queue');
+      println('  construct beads cleanup    # Clean stale locks');
+      return;
+    }
+
+    // Default: run the bd command through our wrapper
+    const actor = process.env.USER || process.env.LOGNAME || 'construct';
+    const needsMergeSlot = sub === 'dolt' && subArgs[0] === 'push';
+    let mergeSlotHeld = false;
+    let result;
+    try {
+      if (needsMergeSlot) {
+        const mergeSlot = await acquireMergeSlot({
+          actor,
+          cwd: process.cwd(),
+          silent: subArgs.includes('--silent'),
+        });
+        mergeSlotHeld = Boolean(mergeSlot?.success);
+      }
+
+      result = await runBd(args, {
+        actor,
+        cwd: process.cwd(),
+        silent: subArgs.includes('--silent'),
+      });
+    } finally {
+      if (mergeSlotHeld) {
+        await releaseMergeSlot({
+          actor,
+          cwd: process.cwd(),
+          silent: subArgs.includes('--silent'),
+        });
+      }
+    }
+
+    if (result.success) {
+      process.stdout.write(result.output || '');
+    } else {
+      process.stderr.write(`bd failed: ${result.error || 'Unknown error'}\n`);
+      process.exit(result.exitCode || 1);
+    }
+  }],
+  ['wireframe', async (args) => {
+    const { runWireframeCli } = await import('../lib/wireframe.mjs');
+    return runWireframeCli(args);
+  }],
+  ['skills', async (args) => {
+    const sub = args[0];
+    if (sub === 'scope' || !sub) {
+      const { runSkillsScopeCli } = await import('../lib/skills-scope.mjs');
+      return runSkillsScopeCli(args.slice(sub === 'scope' ? 1 : 0));
+    }
+    if (sub === 'apply') {
+      const { runSkillsApplyCli } = await import('../lib/skills-apply.mjs');
+      return runSkillsApplyCli(args.slice(1));
+    }
+    errorln(`Unknown skills subcommand: ${sub}. Available: scope, apply`);
+    process.exit(1);
+  }],
+  ['ask', async (args) => {
+    const question = args.join(' ').trim();
+    if (!question) {
+      errorln('Usage: construct ask "<question>"');
+      errorln('Example: construct ask "what are the biggest risks?"');
+      process.exit(1);
+    }
+    const { ask, buildCorpus } = await import('../lib/knowledge/rag.mjs');
+    const rootDir = process.cwd();
+    process.stdout.write('Building knowledge index…\n');
+    const corpus = buildCorpus(rootDir);
+    process.stdout.write(`Indexed ${corpus.length} chunks. Retrieving…\n\n`);
+    const result = await ask(question, { rootDir, corpus });
+    if (result.cliMissing) {
+      process.stdout.write('[claude CLI not available — showing retrieved context]\n\n');
+    }
+    process.stdout.write(`${result.answer}\n`);
+    if (result.sources?.length) {
+      process.stdout.write('\n--- Sources ---\n');
+      for (const s of result.sources.slice(0, 5)) {
+        process.stdout.write(`  • [${s.source}] ${s.title} (score: ${s.score?.toFixed(3)})\n`);
+      }
+    }
+  }],
+   ['embed', async (args) => {
+     const { runEmbedCli } = await import('../lib/embed/cli.mjs');
+     return runEmbedCli(args, { rootDir: new URL('..', import.meta.url).pathname });
+   }],
+   ['reflect', async (args) => {
+     const { runReflectCli } = await import('../lib/reflect.mjs');
+     return runReflectCli(args);
+   }],
+  ['knowledge', async (args) => {
+    const sub = args[0] || 'trends';
+    if (sub === 'trends') {
+      const { buildTrendReport } = await import('../lib/knowledge/trends.mjs');
+      const report = buildTrendReport(process.cwd());
+      process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+      return;
+    }
+    if (sub === 'index') {
+      const { buildCorpus } = await import('../lib/knowledge/rag.mjs');
+      const corpus = buildCorpus(process.cwd());
+      process.stdout.write(`Indexed ${corpus.length} chunks from: observations, artifacts, snapshots\n`);
+      const sources = {};
+      for (const c of corpus) sources[c.source] = (sources[c.source] || 0) + 1;
+      for (const [src, count] of Object.entries(sources)) {
+        process.stdout.write(`  ${src}: ${count}\n`);
+      }
+      return;
+    }
+    errorln(`Unknown knowledge subcommand: ${sub}. Available: trends, index`);
+    process.exit(1);
+  }],
 ]);
 
-if (!command || command === '--help' || command === '-h' || command === 'help') {
+// No command provided → show interactive menu
+if (!command) {
+  await showInteractiveMenu();
+  process.exit(0);
+}
+
+// Help flags → show usage
+if (command === '--help' || command === '-h' || command === 'help') {
   usage();
   process.exit(0);
 }
@@ -606,8 +3799,19 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
 const handler = handlers.get(command);
 if (!handler) {
   errorln(`Unknown command: ${command}`);
-  usage();
+  println('');
+  println(`${COLORS.dim}Run 'construct --help' for available commands${COLORS.reset}`);
   process.exit(1);
 }
 
+// First-invocation resource probe — skipped for hooks, setup, uninstall,
+// doctor, and once BOOTSTRAP_CHECKED=1 is cached in ~/.construct/config.env.
+// On TTY: if anything's missing, prints the status table and offers to run
+// setup. Silent on success; never blocks the command.
+
+const probe = await maybeFirstInvocationProbe({ command, homeDir: HOME, env: process.env });
+if (probe?.runSetup) {
+  await cmdSetup([]);
+}
+
 await handler(rest);