qualia-framework 2.6.0 → 3.1.0

package/bin/cli.js

@@ -1,614 +1,813 @@
 #!/usr/bin/env node
 
-const fs = require('fs');
-const path = require('path');
-const readline = require('readline');
-const { execSync } = require('child_process');
-
-const CLAUDE_DIR = path.join(require('os').homedir(), '.claude');
-const PKG_ROOT = path.resolve(__dirname, '..');
-const FRAMEWORK_DIR = path.join(PKG_ROOT, 'framework');
-const PROFILES_DIR = path.join(PKG_ROOT, 'profiles');
-const TEMPLATES_DIR = path.join(PKG_ROOT, 'templates');
-
-// ── Colors ──
-const c = {
-  reset: '\x1b[0m',
-  bold: '\x1b[1m',
-  dim: '\x1b[2m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  red: '\x1b[31m',
-  cyan: '\x1b[36m',
-  magenta: '\x1b[35m',
-};
-
-function log(msg) { console.log(msg); }
-function ok(msg) { log(`      ${c.green}\u2713${c.reset} ${msg}`); }
-function warn(msg) { log(`      ${c.yellow}\u26A0${c.reset} ${msg}`); }
-function fail(msg) { log(`      ${c.red}\u2717${c.reset} ${msg}`); }
-function step(n, total, msg) { log(`\n${c.cyan}[${n}/${total}]${c.reset} ${msg}`); }
-
-// ── Helpers ──
-function copyDirSync(src, dest) {
-  fs.mkdirSync(dest, { recursive: true });
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    if (entry.isDirectory()) {
-      copyDirSync(srcPath, destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-    }
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const readline = require("readline");
+
+const TEAL = "\x1b[38;2;0;206;209m";
+const TG = "\x1b[38;2;0;170;175m";
+const DIM = "\x1b[38;2;80;90;100m";
+const GREEN = "\x1b[38;2;52;211;153m";
+const WHITE = "\x1b[38;2;220;225;230m";
+const YELLOW = "\x1b[38;2;234;179;8m";
+const RED = "\x1b[38;2;239;68;68m";
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+
+const CLAUDE_DIR = path.join(require("os").homedir(), ".claude");
+const PKG = require("../package.json");
+const CONFIG_FILE = path.join(CLAUDE_DIR, ".qualia-config.json");
+
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    return {};
   }
 }
 
-function countDir(dir, type) {
-  if (!fs.existsSync(dir)) return 0;
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  if (type === 'dirs') return entries.filter(e => e.isDirectory()).length;
-  return entries.filter(e => e.isFile()).length;
+function writeConfig(cfg) {
+  if (!fs.existsSync(CLAUDE_DIR)) fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2) + "\n");
 }
 
-function deepMerge(target, source) {
-  const result = { ...target };
-  for (const key of Object.keys(source)) {
-    if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])
-        && target[key] && typeof target[key] === 'object' && !Array.isArray(target[key])) {
-      result[key] = deepMerge(target[key], source[key]);
-    } else if (result[key] === undefined || result[key] === null || result[key] === '') {
-      result[key] = source[key];
-    }
-  }
-  return result;
+function banner() {
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}⬢${RESET} ${WHITE}${BOLD}Qualia Framework${RESET} ${DIM}v${PKG.version}${RESET}`);
+  console.log(`  ${DIM}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
 }
 
-function loadProfiles() {
-  const profiles = {};
-  for (const file of fs.readdirSync(PROFILES_DIR)) {
-    if (!file.endsWith('.json')) continue;
-    const profile = JSON.parse(fs.readFileSync(path.join(PROFILES_DIR, file), 'utf8'));
-    profiles[profile.code.toUpperCase()] = profile;
-  }
-  return profiles;
+// ─── Commands ────────────────────────────────────────────
+
+function cmdInstall() {
+  require("./install.js");
 }
 
-function renderCLAUDEmd(profile) {
-  let template = fs.readFileSync(path.join(TEMPLATES_DIR, 'CLAUDE.md.hbs'), 'utf8');
+function cmdVersion() {
+  banner();
+  const cfg = readConfig();
 
-  const isOwner = profile.role === 'OWNER';
-  const isDeveloper = profile.role === 'DEVELOPER';
-  const isArabic = profile.language && profile.language.includes('ar');
+  console.log(`  ${DIM}Installed:${RESET}  ${WHITE}${PKG.version}${RESET}`);
+  if (cfg.installed_by) {
+    console.log(`  ${DIM}User:${RESET}       ${WHITE}${cfg.installed_by}${RESET} ${DIM}(${cfg.role})${RESET}`);
+  }
+  if (cfg.installed_at) {
+    console.log(`  ${DIM}Date:${RESET}       ${WHITE}${cfg.installed_at}${RESET}`);
+  }
 
-  const roleTitle = isOwner ? 'Founder' : (profile.type === 'full-time' ? 'Full-time Developer' : 'Developer');
+  // Check for updates
+  try {
+    // spawnSync with argv — no bash-only `2>/dev/null` redirect, no shell
+    // interpolation. stdio: "ignore" on stderr silences any npm warnings
+    // (offline, proxy, etc.) without a shell redirect. shell: true on
+    // Windows because `npm` is a .cmd shim that only resolves through cmd.
+    const r = spawnSync("npm", ["view", "qualia-framework", "version"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      shell: process.platform === "win32",
+      timeout: 5000,
+      encoding: "utf8",
+    });
+    const latest = (r.stdout || "").trim();
+    const semverGt = (a, b) => {
+      const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
+      for (let i = 0; i < 3; i++) { if (pa[i] > pb[i]) return true; if (pa[i] < pb[i]) return false; }
+      return false;
+    };
+    if (latest && semverGt(latest, PKG.version)) {
+      console.log("");
+      console.log(`  ${YELLOW}Update available:${RESET} ${WHITE}${latest}${RESET}`);
+      console.log(`  ${DIM}Run:${RESET} npx qualia-framework update`);
+    } else if (latest) {
+      console.log(`  ${DIM}Latest:${RESET}     ${GREEN}${latest} ✓${RESET} ${DIM}(up to date)${RESET}`);
+    }
+  } catch {
+    console.log(`  ${DIM}Latest:${RESET}     ${DIM}(offline — couldn't check)${RESET}`);
+  }
+  console.log("");
+}
 
-  const replacements = {
-    '{{fullName}}': profile.fullName || profile.name,
-    '{{name}}': profile.name,
-    '{{role}}': profile.role,
-    '{{roleTitle}}': roleTitle,
-    '{{location}}': profile.location || '',
-  };
+function cmdUpdate() {
+  banner();
+  const cfg = readConfig();
 
-  for (const [key, val] of Object.entries(replacements)) {
-    template = template.replace(new RegExp(escapeRegex(key), 'g'), val);
+  if (!cfg.code) {
+    console.log(`  ${RED}✗${RESET} No install code saved. Run ${TEAL}install${RESET} first.`);
+    console.log("");
+    process.exit(1);
   }
 
-  // Handle conditionals — inner first, then outer
-  template = processConditional(template, 'canDeploy', profile.permissions?.canDeploy);
-  template = processConditional(template, 'canAccessAllProjects', profile.permissions?.canAccessAllProjects);
-  template = processConditional(template, 'isOwner', isOwner);
-  template = processConditional(template, 'isDeveloper', isDeveloper);
-  template = processConditional(template, 'isArabic', isArabic);
+  console.log(`  ${DIM}Current:${RESET}  ${WHITE}${PKG.version}${RESET}`);
+  console.log(`  ${DIM}Updating...${RESET}`);
+  console.log("");
 
-  // Clean up empty lines
-  template = template.replace(/\n{3,}/g, '\n\n');
+  try {
+    const r = spawnSync("npx", ["qualia-framework@latest", "install"], {
+      input: cfg.code + "\n",
+      stdio: ["pipe", "inherit", "inherit"],
+      shell: process.platform === "win32",  // npx is a .cmd shim on Windows — must go through shell
+      timeout: 120000,
+      encoding: "utf8",
+    });
+    if (r.status !== 0) {
+      console.log(`  ${RED}✗${RESET} Update failed. Run manually: npx qualia-framework@latest install`);
+      process.exit(1);
+    }
+  } catch (e) {
+    console.log(`  ${RED}✗${RESET} Update failed: ${e.message}`);
+    console.log(`  ${DIM}Run manually:${RESET} npx qualia-framework@latest install`);
+    process.exit(1);
+  }
+}
 
-  return template;
+// ─── Uninstall ───────────────────────────────────────────
+// Surgical removal of the Qualia Framework from ~/.claude/.
+// Preserves CLAUDE.md (user may have customized it) and preserves any
+// non-Qualia entries in settings.json (other hooks, user env vars, etc.).
+// --yes / -y skips the confirmation prompt for scripted use.
+
+// 8 Qualia hook filenames — only these are removed from ~/.claude/hooks/,
+// any other hooks the user dropped in there are left alone.
+const QUALIA_HOOK_FILES = [
+  "session-start.js",
+  "auto-update.js",
+  "branch-guard.js",
+  "pre-push.js",
+  "block-env-edit.js",
+  "migration-guard.js",
+  "pre-deploy-gate.js",
+  "pre-compact.js",
+];
+
+// 4 Qualia agents — only these are removed.
+const QUALIA_AGENT_FILES = ["planner.md", "builder.md", "verifier.md", "qa-browser.md"];
+
+// 3 Qualia bin scripts.
+const QUALIA_BIN_FILES = ["state.js", "qualia-ui.js", "statusline.js"];
+
+// 5 Qualia rules.
+const QUALIA_RULE_FILES = ["security.md", "frontend.md", "design-reference.md", "deployment.md", "infrastructure.md"];
+
+function promptYesNo(question, defaultYes) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const suffix = defaultYes ? " (Y/n)" : " (y/N)";
+    rl.question(`  ${WHITE}${question}${RESET}${suffix} `, (answer) => {
+      rl.close();
+      const a = String(answer || "").trim().toLowerCase();
+      if (!a) return resolve(defaultYes);
+      resolve(a === "y" || a === "yes");
+    });
+  });
 }
 
-function escapeRegex(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+function safeUnlink(p, counters) {
+  try {
+    if (fs.existsSync(p)) {
+      fs.unlinkSync(p);
+      counters.filesRemoved++;
+    }
+  } catch (e) {
+    counters.errors.push(`${p}: ${e.message}`);
+  }
 }
 
-function processConditional(text, name, value) {
-  const ifRegex = new RegExp(`\\{\\{#if ${name}\\}\\}([\\s\\S]*?)(?:\\{\\{else\\}\\}([\\s\\S]*?))?\\{\\{/if\\}\\}`, 'g');
-  return text.replace(ifRegex, (_, ifBlock, elseBlock) => {
-    return value ? ifBlock : (elseBlock || '');
-  });
+function safeRmDir(p, counters) {
+  try {
+    if (fs.existsSync(p)) {
+      fs.rmSync(p, { recursive: true, force: true });
+      counters.dirsRemoved++;
+    }
+  } catch (e) {
+    counters.errors.push(`${p}: ${e.message}`);
+  }
 }
 
-function mergeSettings(existingPath, templatePath) {
-  const template = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+function cleanSettingsJson(counters) {
+  const settingsPath = path.join(CLAUDE_DIR, "settings.json");
+  if (!fs.existsSync(settingsPath)) return;
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+  } catch (e) {
+    counters.errors.push(`settings.json: ${e.message}`);
+    return;
+  }
 
-  if (!fs.existsSync(existingPath)) return template;
+  // Only remove entries that point at qualia paths. Leave everything else.
+  const isQualiaCommand = (cmd) =>
+    typeof cmd === "string" && (cmd.includes("qualia") || cmd.includes(".claude/hooks/") || cmd.includes(".claude/bin/"));
 
-  const existing = JSON.parse(fs.readFileSync(existingPath, 'utf8'));
+  const filterHookArray = (arr) => {
+    if (!Array.isArray(arr)) return arr;
+    return arr
+      .map((entry) => {
+        if (!entry || !Array.isArray(entry.hooks)) return entry;
+        const hooks = entry.hooks.filter((h) => !isQualiaCommand(h && h.command));
+        return { ...entry, hooks };
+      })
+      .filter((entry) => Array.isArray(entry.hooks) && entry.hooks.length > 0);
+  };
 
-  // Preserve existing env values (API keys), merge in new ones
-  const merged = { ...template };
-  if (existing.env) {
-    merged.env = { ...template.env };
-    for (const [key, val] of Object.entries(existing.env)) {
-      if (val && val !== '' && !val.startsWith('$')) {
-        merged.env[key] = val;
+  if (settings.hooks && typeof settings.hooks === "object") {
+    for (const key of ["SessionStart", "PreToolUse", "PreCompact"]) {
+      if (settings.hooks[key]) {
+        const cleaned = filterHookArray(settings.hooks[key]);
+        if (cleaned && cleaned.length > 0) {
+          settings.hooks[key] = cleaned;
+        } else {
+          delete settings.hooks[key];
+        }
       }
     }
+    // If hooks is now empty, remove it entirely.
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
   }
 
-  // Overwrite hooks, permissions, statusLine from template (framework-managed)
-  merged.hooks = template.hooks;
-  merged.permissions = template.permissions;
-  // Use node-based statusline on Windows (no bash), bash on Unix
-  if (process.platform === 'win32') {
-    merged.statusLine = { type: 'command', command: 'node ~/.claude/statusline-command.js' };
-  } else {
-    merged.statusLine = template.statusLine;
+  // Status line — only drop it if it points at our renderer.
+  if (settings.statusLine && typeof settings.statusLine === "object") {
+    const cmd = settings.statusLine.command || "";
+    if (isQualiaCommand(cmd) || cmd.includes("statusline.js") || cmd.includes("qualia-ui")) {
+      delete settings.statusLine;
+    }
   }
 
-  // Preserve user's existing plugins and MCP servers
-  if (existing.enabledPlugins) {
-    merged.enabledPlugins = existing.enabledPlugins;
-  }
-  if (existing.mcpServers) {
-    merged.mcpServers = existing.mcpServers;
-  }
+  // Qualia-specific spinner overrides.
+  if (settings.spinnerVerbs) delete settings.spinnerVerbs;
+  if (settings.spinnerTipsOverride) delete settings.spinnerTipsOverride;
 
-  return merged;
-}
+  // Leave settings.env alone — the user may have other env vars in there.
 
-function prompt(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise(resolve => {
-    rl.question(question, answer => {
-      rl.close();
-      resolve(answer.trim());
-    });
-  });
+  try {
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    counters.settingsCleaned = true;
+  } catch (e) {
+    counters.errors.push(`settings.json write: ${e.message}`);
+  }
 }
 
-// ── Uninstall ──
-async function runUninstall() {
-  log('');
-  log(`${c.red}\u2554${'═'.repeat(54)}\u2557${c.reset}`);
-  log(`${c.red}\u2551${c.reset}${c.bold}        QUALIA FRAMEWORK \u2014 UNINSTALLER              ${c.reset}${c.red}\u2551${c.reset}`);
-  log(`${c.red}\u255A${'═'.repeat(54)}\u255D${c.reset}`);
-  log('');
+async function cmdUninstall() {
+  banner();
 
-  if (!fs.existsSync(CLAUDE_DIR)) {
-    warn('Nothing to uninstall \u2014 ~/.claude/ does not exist.');
-    return;
+  const args = process.argv.slice(3);
+  const skipConfirm = args.includes("-y") || args.includes("--yes");
+
+  const cfg = readConfig();
+  console.log("");
+  if (cfg.installed_by) {
+    console.log(`  ${DIM}User:${RESET} ${WHITE}${cfg.installed_by}${RESET} ${DIM}(${cfg.role || "?"})${RESET}`);
+  } else {
+    console.log(`  ${DIM}No Qualia config found at${RESET} ${WHITE}${CONFIG_FILE}${RESET}`);
   }
+  console.log("");
 
-  // Count everything in ~/.claude/
-  const totalFiles = countFilesRecursive(CLAUDE_DIR);
-
-  log(`${c.bold}  NUCLEAR UNINSTALL \u2014 deleting EVERYTHING in ~/.claude/${c.reset}`);
-  log('');
-  log(`    ${c.red}\u2022${c.reset} ${totalFiles} files will be permanently deleted`);
-  log(`    ${c.red}\u2022${c.reset} settings.json will be reset to {}`);
-  log(`    ${c.red}\u2022${c.reset} All skills, agents, hooks, rules, knowledge \u2014 gone`);
-  log(`    ${c.red}\u2022${c.reset} All memory, projects, plans, cache \u2014 gone`);
-  log(`    ${c.red}\u2022${c.reset} CLAUDE.md, .env.claude, all config \u2014 gone`);
-  log('');
-
-  // Confirmation
-  const force = process.argv.includes('--force');
-  if (!force) {
-    log(`${c.red}  \u26A0  THIS CANNOT BE UNDONE.${c.reset}`);
-    log(`${c.red}  \u26A0  ~/.claude/ will be wiped clean. Nothing survives.${c.reset}`);
-    log('');
-    const answer = await prompt(`  Type 'UNINSTALL' to confirm: `);
-    if (answer !== 'UNINSTALL') {
-      log('');
-      ok('Cancelled. Nothing was deleted.');
+  if (!skipConfirm) {
+    const confirm = await promptYesNo("Are you sure you want to uninstall the Qualia Framework?", false);
+    if (!confirm) {
+      console.log("");
+      console.log(`  ${DIM}Aborted.${RESET}`);
+      console.log("");
       return;
     }
-    log('');
   }
 
-  // Step 1: Nuke everything in ~/.claude/ except settings.json (we handle that separately)
-  step(1, 2, 'Nuking ~/.claude/ ...');
+  // Preserve knowledge base by default.
+  let preserveKnowledge = true;
+  if (!skipConfirm) {
+    preserveKnowledge = await promptYesNo(
+      "Preserve knowledge base? (your learned patterns, fixes, client prefs)",
+      true
+    );
+  }
 
-  for (const entry of fs.readdirSync(CLAUDE_DIR, { withFileTypes: true })) {
-    const p = path.join(CLAUDE_DIR, entry.name);
+  console.log("");
+  console.log(`  ${DIM}Removing framework files...${RESET}`);
+  console.log("");
 
-    // Skip settings.json — we reset it in step 2
-    if (entry.name === 'settings.json') continue;
+  const counters = { filesRemoved: 0, dirsRemoved: 0, settingsCleaned: false, errors: [] };
 
-    try {
-      if (entry.isDirectory()) {
-        fs.rmSync(p, { recursive: true, force: true });
-        ok(`${entry.name}/`);
-      } else if (isSymlink(p)) {
-        fs.unlinkSync(p);
-        ok(`${entry.name} (symlink)`);
-      } else {
-        fs.unlinkSync(p);
-        ok(entry.name);
+  // Skills — any directory starting with "qualia" under ~/.claude/skills/.
+  const skillsDir = path.join(CLAUDE_DIR, "skills");
+  try {
+    if (fs.existsSync(skillsDir)) {
+      for (const name of fs.readdirSync(skillsDir)) {
+        if (name === "qualia" || name.startsWith("qualia-")) {
+          safeRmDir(path.join(skillsDir, name), counters);
+        }
       }
-    } catch (e) {
-      fail(`${entry.name}: ${e.message}`);
     }
+  } catch (e) {
+    counters.errors.push(`skills scan: ${e.message}`);
   }
 
-  // Step 2: Reset settings.json to empty
-  step(2, 2, 'Resetting settings.json ...');
-  const settingsPath = path.join(CLAUDE_DIR, 'settings.json');
-  if (fs.existsSync(settingsPath)) {
-    fs.writeFileSync(settingsPath, '{}\n');
-    ok('settings.json reset to {}');
-  } else {
-    ok('No settings.json found');
+  // Agents — only the 4 Qualia ones.
+  for (const f of QUALIA_AGENT_FILES) {
+    safeUnlink(path.join(CLAUDE_DIR, "agents", f), counters);
   }
 
-  log('');
-  log(`${c.green}\u2554${'═'.repeat(54)}\u2557${c.reset}`);
-  log(`${c.green}\u2551${c.reset}${c.bold}  \u2713 NUKED \u2014 ~/.claude/ is clean                    ${c.reset}${c.green}\u2551${c.reset}`);
-  log(`${c.green}\u255A${'═'.repeat(54)}\u255D${c.reset}`);
-  log('');
-  log(`  ${c.dim}Claude Code will use default behavior on next launch.${c.reset}`);
-  log('');
-}
-
-function isSymlink(p) {
-  try { fs.lstatSync(p); return fs.lstatSync(p).isSymbolicLink(); } catch { return false; }
-}
+  // Hooks — only the 8 Qualia ones.
+  for (const f of QUALIA_HOOK_FILES) {
+    safeUnlink(path.join(CLAUDE_DIR, "hooks", f), counters);
+  }
 
-// ── Main ──
-async function main() {
-  const command = process.argv[2];
+  // Bin scripts — only the 3 Qualia ones.
+  for (const f of QUALIA_BIN_FILES) {
+    safeUnlink(path.join(CLAUDE_DIR, "bin", f), counters);
+  }
 
-  if (command === 'update') {
-    await runUpdate();
-  } else if (command === 'verify') {
-    runVerify();
-  } else if (command === 'uninstall') {
-    await runUninstall();
-  } else {
-    await runInstall();
+  // Rules — all 4.
+  for (const f of QUALIA_RULE_FILES) {
+    safeUnlink(path.join(CLAUDE_DIR, "rules", f), counters);
   }
-}
 
-async function runInstall() {
-  log('');
-  log(`${c.cyan}\u2554${'═'.repeat(54)}\u2557${c.reset}`);
-  log(`${c.cyan}\u2551${c.reset}${c.bold}          QUALIA FRAMEWORK \u2014 INSTALLER                ${c.reset}${c.cyan}\u2551${c.reset}`);
-  log(`${c.cyan}\u255A${'═'.repeat(54)}\u255D${c.reset}`);
-  log('');
-
-  const profiles = loadProfiles();
-  const code = await prompt(`  Enter your employee code: `);
-  const profile = profiles[code.toUpperCase()];
-
-  if (!profile) {
-    log('');
-    fail(`Unknown code "${code}". Contact Fawzi for your employee code.`);
-    log(`${c.dim}  Available format: QS-NAME-YEAR${c.reset}`);
-    process.exit(1);
+  // Templates directory (entire).
+  safeRmDir(path.join(CLAUDE_DIR, "qualia-templates"), counters);
+
+  // Knowledge directory (optional preservation).
+  if (!preserveKnowledge) {
+    safeRmDir(path.join(CLAUDE_DIR, "knowledge"), counters);
   }
 
-  log('');
-  log(`  ${c.green}\u2192${c.reset} Welcome, ${c.bold}${profile.name}${c.reset}! Setting up your Qualia environment...`);
+  // Config + state files.
+  safeUnlink(path.join(CLAUDE_DIR, ".qualia-config.json"), counters);
+  safeUnlink(path.join(CLAUDE_DIR, ".qualia-last-update-check"), counters);
+  safeUnlink(path.join(CLAUDE_DIR, ".erp-api-key"), counters);
+  safeUnlink(path.join(CLAUDE_DIR, ".qualia-team.json"), counters);
+  safeUnlink(path.join(CLAUDE_DIR, "qualia-guide.md"), counters);
 
-  const TOTAL = 6;
+  // Traces directory.
+  safeRmDir(path.join(CLAUDE_DIR, ".qualia-traces"), counters);
 
-  // Step 1: Backup existing
-  step(1, TOTAL, 'Checking existing ~/.claude/ ...');
-  if (fs.existsSync(CLAUDE_DIR)) {
-    const date = new Date().toISOString().split('T')[0];
-    const backupDir = `${CLAUDE_DIR}.backup-${date}`;
-    if (!fs.existsSync(backupDir)) {
-      // Don't backup the whole thing — just the config files we'll overwrite
-      fs.mkdirSync(backupDir, { recursive: true });
-      for (const f of ['CLAUDE.md', 'settings.json', '.env.claude']) {
-        const src = path.join(CLAUDE_DIR, f);
-        if (fs.existsSync(src)) {
-          fs.copyFileSync(src, path.join(backupDir, f));
-        }
-      }
-      ok(`Config backed up to ${c.dim}~/.claude.backup-${date}/${c.reset}`);
-    } else {
-      ok('Backup already exists for today');
-    }
+  // Clean settings.json surgically.
+  cleanSettingsJson(counters);
+
+  // Summary.
+  console.log("");
+  console.log(`${TEAL}  ⬢ Uninstall complete${RESET}`);
+  console.log(`${DIM}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
+  console.log(`  ${DIM}Files removed:${RESET}       ${WHITE}${counters.filesRemoved}${RESET}`);
+  console.log(`  ${DIM}Directories removed:${RESET} ${WHITE}${counters.dirsRemoved}${RESET}`);
+  console.log(
+    `  ${DIM}settings.json:${RESET}       ${counters.settingsCleaned ? `${GREEN}cleaned ✓${RESET}` : `${DIM}not present${RESET}`}`
+  );
+  if (preserveKnowledge) {
+    console.log(`  ${DIM}Knowledge base:${RESET}      ${GREEN}preserved ✓${RESET}`);
   } else {
-    fs.mkdirSync(CLAUDE_DIR, { recursive: true });
-    ok('Created ~/.claude/');
+    console.log(`  ${DIM}Knowledge base:${RESET}      ${YELLOW}removed${RESET}`);
   }
 
-  // Step 2: Copy framework files
-  step(2, TOTAL, 'Installing framework files ...');
-
-  const dirs = ['skills', 'hooks', 'agents', 'rules', 'qualia-framework', 'scripts', 'knowledge'];
-  for (const dir of dirs) {
-    const src = path.join(FRAMEWORK_DIR, dir);
-    const dest = path.join(CLAUDE_DIR, dir);
-    if (fs.existsSync(src)) {
-      copyDirSync(src, dest);
+  if (counters.errors.length > 0) {
+    console.log("");
+    console.log(`  ${YELLOW}${counters.errors.length} warning(s):${RESET}`);
+    for (const err of counters.errors.slice(0, 5)) {
+      console.log(`    ${DIM}${err}${RESET}`);
     }
   }
 
-  // Copy standalone files (both .sh and .js for cross-platform)
-  for (const f of ['statusline-command.sh', 'statusline-command.js', 'askpass.sh']) {
-    const src = path.join(FRAMEWORK_DIR, f);
-    if (fs.existsSync(src)) {
-      fs.copyFileSync(src, path.join(CLAUDE_DIR, f));
+  console.log("");
+  console.log(
+    `  ${YELLOW}Manual step:${RESET} edit ${WHITE}~/.claude/CLAUDE.md${RESET} to remove the Qualia Framework section if desired.`
+  );
+  console.log("");
+}
+
+// ─── Team Management ────────────────────────────────────
+// External team file at ~/.claude/.qualia-team.json.
+// Falls back to embedded defaults in install.js.
+
+function getDefaultTeam() {
+  return {
+    "QS-FAWZI-01": { name: "Fawzi Goussous", role: "OWNER", description: "Company owner. Full access. Can push to main, approve deploys, edit secrets." },
+    "QS-HASAN-02": { name: "Hasan", role: "EMPLOYEE", description: "Developer. Feature branches only. Cannot push to main or edit .env files." },
+    "QS-MOAYAD-03": { name: "Moayad", role: "EMPLOYEE", description: "Developer. Feature branches only. Cannot push to main or edit .env files." },
+    "QS-RAMA-04": { name: "Rama", role: "EMPLOYEE", description: "Developer. Feature branches only. Cannot push to main or edit .env files." },
+    "QS-SALLY-05": { name: "Sally", role: "EMPLOYEE", description: "Developer. Feature branches only. Cannot push to main or edit .env files." },
+  };
+}
+
+function readTeamFile() {
+  const teamFile = path.join(CLAUDE_DIR, ".qualia-team.json");
+  try {
+    if (fs.existsSync(teamFile)) {
+      const data = JSON.parse(fs.readFileSync(teamFile, "utf8"));
+      if (data && typeof data === "object" && Object.keys(data).length > 0) return data;
     }
+  } catch {}
+  return null;
+}
+
+function writeTeamFile(team) {
+  if (!fs.existsSync(CLAUDE_DIR)) fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+  fs.writeFileSync(path.join(CLAUDE_DIR, ".qualia-team.json"), JSON.stringify(team, null, 2) + "\n");
+}
+
+function parseTeamArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--code" && argv[i + 1]) { args.code = argv[++i]; }
+    else if (argv[i] === "--name" && argv[i + 1]) { args.name = argv[++i]; }
+    else if (argv[i] === "--role" && argv[i + 1]) { args.role = argv[++i].toUpperCase(); }
   }
+  return args;
+}
 
-  // Make hooks executable
-  const hooksDir = path.join(CLAUDE_DIR, 'hooks');
-  if (fs.existsSync(hooksDir)) {
-    for (const f of fs.readdirSync(hooksDir)) {
-      if (f.endsWith('.sh')) {
-        fs.chmodSync(path.join(hooksDir, f), 0o755);
+function cmdTeam() {
+  const sub = process.argv[3];
+
+  switch (sub) {
+    case "list": {
+      banner();
+      console.log("");
+      const team = readTeamFile();
+      const source = team || getDefaultTeam();
+      const label = team ? "team file" : "embedded defaults";
+      console.log(`  ${DIM}Source: ${label}${RESET}`);
+      console.log("");
+      for (const [code, member] of Object.entries(source)) {
+        const roleColor = member.role === "OWNER" ? TEAL : WHITE;
+        console.log(`  ${WHITE}${code}${RESET}  ${roleColor}${member.role}${RESET}  ${DIM}${member.name}${RESET}`);
       }
+      console.log("");
+      break;
     }
-  }
-  // Make standalone scripts executable
-  for (const f of ['statusline-command.sh', 'statusline-command.js', 'askpass.sh']) {
-    const p = path.join(CLAUDE_DIR, f);
-    if (fs.existsSync(p)) try { fs.chmodSync(p, 0o755); } catch {}
-  }
-  // Make qualia-framework bin executable
-  const engineBin = path.join(CLAUDE_DIR, 'qualia-framework', 'bin');
-  if (fs.existsSync(engineBin)) {
-    for (const f of fs.readdirSync(engineBin)) {
-      const p = path.join(engineBin, f);
-      try { fs.chmodSync(p, 0o755); } catch {}
+
+    case "add": {
+      const args = parseTeamArgs(process.argv.slice(4));
+      if (!args.code || !args.name) {
+        console.log(`  ${RED}Usage:${RESET} qualia-framework team add --code QS-NAME-NN --name "Full Name" [--role EMPLOYEE|OWNER]`);
+        process.exit(1);
+      }
+      const team = readTeamFile() || getDefaultTeam();
+      const code = args.code.toUpperCase();
+      const role = args.role || "EMPLOYEE";
+      team[code] = {
+        name: args.name,
+        role,
+        description: role === "OWNER"
+          ? "Company owner. Full access. Can push to main, approve deploys, edit secrets."
+          : "Developer. Feature branches only. Cannot push to main or edit .env files.",
+      };
+      writeTeamFile(team);
+      console.log(`  ${GREEN}+${RESET} ${WHITE}${code}${RESET} ${DIM}(${args.name}, ${role})${RESET}`);
+      break;
     }
-  }
 
-  ok(`${countDir(path.join(CLAUDE_DIR, 'skills'), 'dirs')} skills`);
-  ok(`${countDir(hooksDir, 'files')} hooks (chmod +x)`);
-  ok(`${countDir(path.join(CLAUDE_DIR, 'agents'), 'files')} agents`);
-  ok(`${countDir(path.join(CLAUDE_DIR, 'rules'), 'files')} rule files`);
-  ok('qualia-framework');
-  ok('knowledge base');
-
-  // Step 3: Generate CLAUDE.md
-  step(3, TOTAL, 'Generating your CLAUDE.md ...');
-  const claudeMd = renderCLAUDEmd(profile);
-  fs.writeFileSync(path.join(CLAUDE_DIR, 'CLAUDE.md'), claudeMd);
-
-  const roleDesc = profile.role === 'OWNER' ? 'Full authority' :
-    `Feature branches${profile.permissions?.canDeploy ? ', can deploy' : ', no prod deploy'}`;
-  ok(`Identity: ${profile.name} \u2014 ${profile.role === 'OWNER' ? 'Founder' : 'Developer'} at Qualia Solutions`);
-  ok(`Role: ${profile.role} (${roleDesc})`);
-
-  // Step 4: Configure settings.json
-  step(4, TOTAL, 'Configuring settings.json ...');
-  const settingsPath = path.join(CLAUDE_DIR, 'settings.json');
-  const templateSettingsPath = path.join(TEMPLATES_DIR, 'settings.json');
-  const mergedSettings = mergeSettings(settingsPath, templateSettingsPath);
-
-  // Fix SUDO_ASKPASS to absolute path
-  mergedSettings.env.SUDO_ASKPASS = path.join(CLAUDE_DIR, 'askpass.sh');
-  mergedSettings.env.CLAUDE_ENV_FILE = path.join(CLAUDE_DIR, '.env.claude');
-
-  fs.writeFileSync(settingsPath, JSON.stringify(mergedSettings, null, 2) + '\n');
-  ok('Hooks wired');
-  ok('Preserved your existing API keys');
-  ok('Settings configured');
-
-  // Step 5: Environment
-  step(5, TOTAL, 'Setting up environment ...');
-  const envPath = path.join(CLAUDE_DIR, '.env.claude');
-  if (fs.existsSync(envPath)) {
-    ok('.env.claude already exists (preserved)');
-  } else {
-    fs.copyFileSync(path.join(TEMPLATES_DIR, 'env.claude.template'), envPath);
-    fs.chmodSync(envPath, 0o600);
-    warn(`Fill in your API keys: ${c.dim}~/.claude/.env.claude${c.reset}`);
-  }
+    case "remove": {
+      const code = (process.argv[4] || "").toUpperCase();
+      if (!code) {
+        console.log(`  ${RED}Usage:${RESET} qualia-framework team remove QS-NAME-NN`);
+        process.exit(1);
+      }
+      const team = readTeamFile();
+      if (!team || !team[code]) {
+        console.log(`  ${YELLOW}!${RESET} ${code} not found in team file.`);
+        process.exit(1);
+      }
+      delete team[code];
+      writeTeamFile(team);
+      console.log(`  ${RED}-${RESET} ${WHITE}${code}${RESET} removed`);
+      break;
+    }
 
-  // Create required directories
-  for (const d of ['projects', 'session-env', 'backups']) {
-    fs.mkdirSync(path.join(CLAUDE_DIR, d), { recursive: true });
+    default:
+      console.log(`  ${RED}Usage:${RESET} qualia-framework team <list|add|remove>`);
+      process.exit(1);
   }
+}
 
-  // Step 6: Verify
-  step(6, TOTAL, 'Verifying installation ...');
+// ─── Traces ─────────────────────────────────────────────
 
-  let hooksOk = 0;
-  const hooksTotal = fs.readdirSync(hooksDir).filter(f => f.endsWith('.sh')).length;
-  for (const f of fs.readdirSync(hooksDir)) {
-    if (!f.endsWith('.sh')) continue;
+function cmdTraces() {
+  banner();
+  console.log("");
+  const tracesDir = path.join(CLAUDE_DIR, ".qualia-traces");
+  if (!fs.existsSync(tracesDir)) {
+    console.log(`  ${DIM}No traces found. Traces are written by hooks during normal operation.${RESET}`);
+    console.log("");
+    return;
+  }
+  const files = fs.readdirSync(tracesDir).filter((f) => f.endsWith(".jsonl")).sort().reverse();
+  if (files.length === 0) {
+    console.log(`  ${DIM}No trace files found.${RESET}`);
+    console.log("");
+    return;
+  }
+  const latest = path.join(tracesDir, files[0]);
+  const lines = fs.readFileSync(latest, "utf8").trim().split("\n").slice(-20);
+  console.log(`  ${WHITE}Recent traces${RESET} ${DIM}(${files[0]})${RESET}`);
+  console.log("");
+  for (const line of lines) {
     try {
-      const stat = fs.statSync(path.join(hooksDir, f));
-      if (stat.mode & 0o111) hooksOk++;
+      const e = JSON.parse(line);
+      const color = e.result === "block" ? RED : e.result === "allow" ? GREEN : DIM;
+      const time = (e.timestamp || "").split("T")[1] || "";
+      const ts = time.split(".")[0] || "";
+      console.log(`  ${DIM}${ts}${RESET}  ${color}${e.result}${RESET}  ${WHITE}${e.hook}${RESET}  ${DIM}${e.duration_ms || 0}ms${RESET}`);
     } catch {}
   }
-  if (hooksOk === hooksTotal) {
-    ok(`${hooksOk}/${hooksTotal} hooks executable`);
-  } else {
-    warn(`${hooksOk}/${hooksTotal} hooks executable`);
-  }
+  console.log("");
+}
 
-  try {
-    JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-    ok('settings.json valid JSON');
-  } catch {
-    fail('settings.json invalid JSON!');
+// ─── Migrate ────────────────────────────────────────────
+
+function cmdMigrate() {
+  banner();
+  console.log("");
+
+  const settingsPath = path.join(CLAUDE_DIR, "settings.json");
+  if (!fs.existsSync(settingsPath)) {
+    console.log(`  ${RED}✗${RESET} No settings.json found. Run ${TEAL}qualia-framework install${RESET} first.`);
+    console.log("");
+    process.exit(1);
   }
 
-  if (fs.existsSync(path.join(CLAUDE_DIR, 'CLAUDE.md'))) {
-    ok('CLAUDE.md generated');
-  } else {
-    fail('CLAUDE.md missing!');
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+  } catch (e) {
+    console.log(`  ${RED}✗${RESET} Failed to parse settings.json: ${e.message}`);
+    process.exit(1);
   }
 
-  // Done
-  log('');
-  log(`${c.green}\u2554${'═'.repeat(54)}\u2557${c.reset}`);
-  log(`${c.green}\u2551${c.reset}${c.bold}  \u2713 INSTALLED \u2014 Run /qualia-start in Claude Code     ${c.reset}${c.green}\u2551${c.reset}`);
-  log(`${c.green}\u255A${'═'.repeat(54)}\u255D${c.reset}`);
-  log('');
-  log(`  ${c.dim}Update later: npx github:Qualiasolutions/qualia-framework update${c.reset}`);
-  log('');
-}
+  const cfg = readConfig();
+  const fromVersion = cfg.version || "unknown";
+  let changes = 0;
 
-async function runUpdate() {
-  log('');
-  log(`${c.cyan}\u25C6 Qualia Framework \u2014 Update${c.reset}`);
-  log('');
+  console.log(`  ${DIM}Current version:${RESET} ${WHITE}${fromVersion}${RESET}`);
+  console.log(`  ${DIM}Target version:${RESET}  ${WHITE}${PKG.version}${RESET}`);
+  console.log("");
 
-  if (!fs.existsSync(CLAUDE_DIR)) {
-    fail('No ~/.claude/ found. Run the installer first (without "update").');
-    process.exit(1);
-  }
+  // 1. Ensure all 8 hooks are wired (v2 missed block-env-edit and branch-guard)
+  const hd = path.join(CLAUDE_DIR, "hooks");
+  const nodeCmd = (hookFile) => `node "${path.join(hd, hookFile)}"`;
 
-  // Authenticate — always require code on update
-  const profiles = loadProfiles();
-  const code = await prompt(`  Enter your employee code: `);
-  const profile = profiles[code.toUpperCase()];
+  if (!settings.hooks) settings.hooks = {};
 
-  if (!profile) {
-    log('');
-    fail(`Unknown code "${code}". Contact Fawzi for your employee code.`);
-    process.exit(1);
+  // Check SessionStart hooks
+  if (!settings.hooks.SessionStart || !Array.isArray(settings.hooks.SessionStart)) {
+    settings.hooks.SessionStart = [{ matcher: ".*", hooks: [{ type: "command", command: nodeCmd("session-start.js"), timeout: 5 }] }];
+    changes++;
+    console.log(`  ${GREEN}+${RESET} Added SessionStart hook`);
   }
 
-  log(`  ${c.green}\u2192${c.reset} Updating for ${c.bold}${profile.name}${c.reset} (${profile.role})`);
-  log('');
+  // Check PreToolUse hooks — ensure all critical hooks are present
+  const requiredBashHooks = ["auto-update.js", "branch-guard.js", "pre-push.js", "pre-deploy-gate.js"];
+  const requiredEditHooks = ["block-env-edit.js", "migration-guard.js"];
 
-  // Count what's changing
-  const frameworkDirs = ['skills', 'hooks', 'agents', 'rules', 'qualia-framework', 'scripts', 'knowledge'];
-  const counts = {};
-  let totalFiles = 0;
+  if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
 
-  for (const dir of frameworkDirs) {
-    const src = path.join(FRAMEWORK_DIR, dir);
-    if (fs.existsSync(src)) {
-      const count = countFilesRecursive(src);
-      counts[dir] = count;
-      totalFiles += count;
+  // Find or create Bash matcher entry
+  let bashEntry = settings.hooks.PreToolUse.find(e => e.matcher === "Bash");
+  if (!bashEntry) {
+    bashEntry = { matcher: "Bash", hooks: [] };
+    settings.hooks.PreToolUse.push(bashEntry);
+  }
+  if (!bashEntry.hooks) bashEntry.hooks = [];
+
+  for (const hookFile of requiredBashHooks) {
+    const cmd = nodeCmd(hookFile);
+    const exists = bashEntry.hooks.some(h => h.command && h.command.includes(hookFile));
+    if (!exists) {
+      const hookDef = { type: "command", command: cmd, timeout: hookFile === "pre-deploy-gate.js" ? 180 : 5 };
+      if (hookFile === "branch-guard.js") hookDef.if = "Bash(git push*)";
+      if (hookFile === "pre-push.js") { hookDef.if = "Bash(git push*)"; hookDef.timeout = 15; }
+      if (hookFile === "pre-deploy-gate.js") hookDef.if = "Bash(vercel --prod*)";
+      bashEntry.hooks.push(hookDef);
+      changes++;
+      console.log(`  ${GREEN}+${RESET} Wired ${hookFile} into PreToolUse/Bash`);
     }
   }
 
-  // Show what will be updated
-  log(`  ${c.bold}Components to update:${c.reset}`);
-  for (const [dir, count] of Object.entries(counts)) {
-    log(`    ${c.dim}\u2022${c.reset} ${dir} (${count} files)`);
+  // Find or create Edit|Write matcher entry
+  let editEntry = settings.hooks.PreToolUse.find(e => e.matcher === "Edit|Write");
+  if (!editEntry) {
+    editEntry = { matcher: "Edit|Write", hooks: [] };
+    settings.hooks.PreToolUse.push(editEntry);
   }
-  log(`    ${c.bold}Total: ${totalFiles} files${c.reset}`);
-  log('');
+  if (!editEntry.hooks) editEntry.hooks = [];
 
-  // Update framework files
-  let updated = 0;
-  for (const dir of frameworkDirs) {
-    const src = path.join(FRAMEWORK_DIR, dir);
-    const dest = path.join(CLAUDE_DIR, dir);
-    if (fs.existsSync(src)) {
-      copyDirSync(src, dest);
-      updated++;
-      ok(`${dir} (${counts[dir]} files)`);
+  for (const hookFile of requiredEditHooks) {
+    const cmd = nodeCmd(hookFile);
+    const exists = editEntry.hooks.some(h => h.command && h.command.includes(hookFile));
+    if (!exists) {
+      const hookDef = { type: "command", command: cmd, timeout: hookFile === "migration-guard.js" ? 10 : 5 };
+      if (hookFile === "migration-guard.js") hookDef.if = "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)";
+      editEntry.hooks.push(hookDef);
+      changes++;
+      console.log(`  ${GREEN}+${RESET} Wired ${hookFile} into PreToolUse/Edit|Write`);
     }
   }
 
-  // Copy standalone files (both .sh and .js for cross-platform)
-  for (const f of ['statusline-command.sh', 'statusline-command.js', 'askpass.sh']) {
-    const src = path.join(FRAMEWORK_DIR, f);
-    if (fs.existsSync(src)) {
-      fs.copyFileSync(src, path.join(CLAUDE_DIR, f));
-      try { fs.chmodSync(path.join(CLAUDE_DIR, f), 0o755); } catch {}
-    }
+  // Check PreCompact hook
+  if (!settings.hooks.PreCompact) {
+    settings.hooks.PreCompact = [{ matcher: "compact", hooks: [{ type: "command", command: nodeCmd("pre-compact.js"), timeout: 15 }] }];
+    changes++;
+    console.log(`  ${GREEN}+${RESET} Added PreCompact hook`);
   }
 
-  // Re-chmod hooks
-  const hooksDir = path.join(CLAUDE_DIR, 'hooks');
-  if (fs.existsSync(hooksDir)) {
-    for (const f of fs.readdirSync(hooksDir)) {
-      if (f.endsWith('.sh')) try { fs.chmodSync(path.join(hooksDir, f), 0o755); } catch {}
+  // 2. Ensure env vars are up to date
+  if (!settings.env) settings.env = {};
+  const requiredEnv = {
+    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
+    CLAUDE_CODE_DISABLE_AUTO_MEMORY: "0",
+    MAX_MCP_OUTPUT_TOKENS: "25000",
+    CLAUDE_CODE_NO_FLICKER: "1",
+  };
+  for (const [k, v] of Object.entries(requiredEnv)) {
+    if (settings.env[k] !== v) {
+      settings.env[k] = v;
+      changes++;
+      console.log(`  ${GREEN}+${RESET} Set env.${k}`);
     }
   }
 
-  // Re-chmod engine bin
-  const engineBin = path.join(CLAUDE_DIR, 'qualia-framework', 'bin');
-  if (fs.existsSync(engineBin)) {
-    for (const f of fs.readdirSync(engineBin)) {
-      try { fs.chmodSync(path.join(engineBin, f), 0o755); } catch {}
-    }
+  // 3. Update status line if missing
+  if (!settings.statusLine) {
+    settings.statusLine = { type: "command", command: `node "${path.join(CLAUDE_DIR, "bin", "statusline.js")}"` };
+    changes++;
+    console.log(`  ${GREEN}+${RESET} Added status line`);
+  }
+
+  // 3b. Add next-devtools MCP if not present
+  if (!settings.mcpServers) settings.mcpServers = {};
+  if (!settings.mcpServers["next-devtools"]) {
+    settings.mcpServers["next-devtools"] = {
+      command: "npx",
+      args: ["next-devtools-mcp@0.3.10"],
+      disabled: false,
+    };
+    changes++;
+    console.log(`  ${GREEN}+${RESET} Added next-devtools MCP server`);
   }
 
-  // Regenerate CLAUDE.md for this person's role
-  const claudeMd = renderCLAUDEmd(profile);
-  fs.writeFileSync(path.join(CLAUDE_DIR, 'CLAUDE.md'), claudeMd);
-  ok(`CLAUDE.md regenerated for ${profile.name} (${profile.role})`);
+  // 4. Update config version
+  cfg.version = PKG.version;
+  cfg.migrated_at = new Date().toISOString().split("T")[0];
+  writeConfig(cfg);
+
+  // Write settings
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
 
-  // Merge settings.json hooks (add new hooks without overwriting user config)
-  const settingsPath = path.join(CLAUDE_DIR, 'settings.json');
-  const templateSettingsPath = path.join(TEMPLATES_DIR, 'settings.json');
-  if (fs.existsSync(settingsPath) && fs.existsSync(templateSettingsPath)) {
-    const mergedSettings = mergeSettings(settingsPath, templateSettingsPath);
-    mergedSettings.env.SUDO_ASKPASS = path.join(CLAUDE_DIR, 'askpass.sh');
-    mergedSettings.env.CLAUDE_ENV_FILE = path.join(CLAUDE_DIR, '.env.claude');
-    fs.writeFileSync(settingsPath, JSON.stringify(mergedSettings, null, 2) + '\n');
-    ok('settings.json hooks merged');
+  console.log("");
+  if (changes === 0) {
+    console.log(`  ${GREEN}✓${RESET} Already up to date — no migration needed.`);
+  } else {
+    console.log(`  ${GREEN}✓${RESET} Applied ${WHITE}${changes}${RESET} changes. Restart Claude Code to take effect.`);
   }
+  console.log("");
+}
 
-  // Clean up removed directories from old versions
-  for (const stale of ['commands', 'config', 'core', 'qualia-engine']) {
-    const p = path.join(CLAUDE_DIR, stale);
-    if (fs.existsSync(p)) {
-      fs.rmSync(p, { recursive: true, force: true });
-      ok(`removed stale ${stale}/`);
-    }
+// ─── Analytics ──────────────────────────────────────────
+
+function cmdAnalytics() {
+  banner();
+  console.log("");
+
+  const tracesDir = path.join(CLAUDE_DIR, ".qualia-traces");
+  if (!fs.existsSync(tracesDir)) {
+    console.log(`  ${DIM}No traces found. Analytics require hook telemetry data.${RESET}`);
+    console.log(`  ${DIM}Traces are collected automatically during normal framework use.${RESET}`);
+    console.log("");
+    return;
   }
 
-  log('');
-  log(`${c.green}\u25C6${c.reset} ${c.bold}Updated ${updated} components (${totalFiles} files)${c.reset}`);
-  log(`${c.dim}  .env.claude preserved. CLAUDE.md regenerated for ${profile.name}.${c.reset}`);
-  log('');
-}
+  const files = fs.readdirSync(tracesDir).filter(f => f.endsWith(".jsonl")).sort();
+  if (files.length === 0) {
+    console.log(`  ${DIM}No trace data yet.${RESET}`);
+    console.log("");
+    return;
+  }
 
-function countFilesRecursive(dir) {
-  let count = 0;
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    if (entry.isDirectory()) {
-      count += countFilesRecursive(path.join(dir, entry.name));
-    } else {
-      count++;
+  // Parse all traces
+  const traces = [];
+  for (const file of files) {
+    const lines = fs.readFileSync(path.join(tracesDir, file), "utf8").trim().split("\n");
+    for (const line of lines) {
+      try { traces.push(JSON.parse(line)); } catch {}
     }
   }
-  return count;
+
+  // Aggregate stats
+  const hookStats = {};
+  let totalBlocks = 0;
+  let totalAllows = 0;
+  let totalDuration = 0;
+
+  for (const t of traces) {
+    const hook = t.hook || "unknown";
+    if (!hookStats[hook]) hookStats[hook] = { allow: 0, block: 0, total_ms: 0 };
+    if (t.result === "block") { hookStats[hook].block++; totalBlocks++; }
+    else { hookStats[hook].allow++; totalAllows++; }
+    hookStats[hook].total_ms += t.duration_ms || 0;
+    totalDuration += t.duration_ms || 0;
+  }
+
+  // Verification outcomes (from traces that include verification data)
+  const verifications = traces.filter(t => t.hook === "state-transition" && t.extra && t.extra.verification);
+  const passes = verifications.filter(t => t.extra.verification === "pass").length;
+  const fails = verifications.filter(t => t.extra.verification === "fail").length;
+
+  // Gap cycle data
+  const gapTraces = traces.filter(t => t.hook === "state-transition" && t.extra && t.extra.gap_closure);
+  const totalGapCycles = gapTraces.length;
+
+  // Display
+  console.log(`  ${WHITE}Framework Analytics${RESET}`);
+  console.log(`  ${DIM}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
+  console.log("");
+  console.log(`  ${WHITE}Overview${RESET}`);
+  console.log(`  ${DIM}Trace files:${RESET}       ${WHITE}${files.length}${RESET} ${DIM}(${files[0]} → ${files[files.length - 1]})${RESET}`);
+  console.log(`  ${DIM}Total events:${RESET}      ${WHITE}${traces.length}${RESET}`);
+  console.log(`  ${DIM}Total blocks:${RESET}      ${RED}${totalBlocks}${RESET}`);
+  console.log(`  ${DIM}Total allows:${RESET}      ${GREEN}${totalAllows}${RESET}`);
+  console.log(`  ${DIM}Avg hook time:${RESET}     ${WHITE}${traces.length ? Math.round(totalDuration / traces.length) : 0}ms${RESET}`);
+  console.log("");
+
+  // Verification stats
+  if (passes + fails > 0) {
+    const rate = Math.round((passes / (passes + fails)) * 100);
+    console.log(`  ${WHITE}Verification Outcomes${RESET}`);
+    console.log(`  ${DIM}First-pass rate:${RESET}   ${rate >= 70 ? GREEN : rate >= 50 ? YELLOW : RED}${rate}%${RESET} ${DIM}(${passes} pass / ${fails} fail)${RESET}`);
+    console.log(`  ${DIM}Gap cycles:${RESET}        ${WHITE}${totalGapCycles}${RESET}`);
+    console.log("");
+  }
+
+  // Per-hook breakdown
+  console.log(`  ${WHITE}Per-Hook Breakdown${RESET}`);
+  const sorted = Object.entries(hookStats).sort((a, b) => (b[1].allow + b[1].block) - (a[1].allow + a[1].block));
+  for (const [hook, stats] of sorted) {
+    const total = stats.allow + stats.block;
+    const avg = Math.round(stats.total_ms / total);
+    const blockRate = stats.block > 0 ? ` ${RED}${stats.block} blocked${RESET}` : "";
+    console.log(`  ${DIM}${hook}:${RESET} ${WHITE}${total}${RESET} calls, ${DIM}avg ${avg}ms${RESET}${blockRate}`);
+  }
+  console.log("");
 }
 
-function runVerify() {
-  log('');
-  log(`${c.cyan}Qualia Framework \u2014 Verify${c.reset}`);
-  log('');
-
-  let pass = 0;
-  let total = 0;
-
-  const checks = [
-    ['CLAUDE.md', () => fs.existsSync(path.join(CLAUDE_DIR, 'CLAUDE.md'))],
-    ['settings.json', () => { try { JSON.parse(fs.readFileSync(path.join(CLAUDE_DIR, 'settings.json'), 'utf8')); return true; } catch { return false; } }],
-    ['hooks/', () => fs.existsSync(path.join(CLAUDE_DIR, 'hooks'))],
-    ['skills/', () => countDir(path.join(CLAUDE_DIR, 'skills'), 'dirs') > 50],
-    ['agents/', () => countDir(path.join(CLAUDE_DIR, 'agents'), 'files') > 15],
-    ['qualia-framework/', () => fs.existsSync(path.join(CLAUDE_DIR, 'qualia-framework', 'bin'))],
-    ['rules/', () => countDir(path.join(CLAUDE_DIR, 'rules'), 'files') >= 4],
-    ['.env.claude', () => fs.existsSync(path.join(CLAUDE_DIR, '.env.claude'))],
-  ];
-
-  for (const [name, check] of checks) {
-    total++;
-    if (check()) { ok(name); pass++; }
-    else { fail(name); }
-  }
-
-  log('');
-  if (pass === total) {
-    log(`${c.green}All ${total} checks passed.${c.reset}`);
-  } else {
-    log(`${c.yellow}${pass}/${total} checks passed.${c.reset}`);
-  }
-  log('');
+function cmdHelp() {
+  banner();
+  console.log("");
+  console.log(`  ${WHITE}Commands:${RESET}`);
+  console.log(`    qualia-framework ${TEAL}install${RESET}      Install or reinstall the framework`);
+  console.log(`    qualia-framework ${TEAL}update${RESET}       Update to the latest version`);
+  console.log(`    qualia-framework ${TEAL}version${RESET}      Show installed version + check for updates`);
+  console.log(`    qualia-framework ${TEAL}uninstall${RESET}    Clean removal from ~/.claude/ (${DIM}-y to skip prompts${RESET})`);
+  console.log(`    qualia-framework ${TEAL}migrate${RESET}      Migrate settings from v2 to v3`);
+  console.log(`    qualia-framework ${TEAL}team${RESET}         Manage team members (${DIM}list|add|remove${RESET})`);
+  console.log(`    qualia-framework ${TEAL}traces${RESET}       View recent hook telemetry`);
+  console.log(`    qualia-framework ${TEAL}analytics${RESET}    Show outcome scoring & gap cycle stats`);
+  console.log("");
+  console.log(`  ${WHITE}After install:${RESET}`);
+  console.log(`    ${TG}/qualia${RESET}          What should I do next?`);
+  console.log(`    ${TG}/qualia-new${RESET}      Set up a new project`);
+  console.log(`    ${TG}/qualia-plan${RESET}     Plan a phase`);
+  console.log(`    ${TG}/qualia-build${RESET}    Build it (parallel tasks)`);
+  console.log(`    ${TG}/qualia-verify${RESET}   Verify it works`);
+  console.log(`    ${TG}/qualia-design${RESET}   One-shot design fix`);
+  console.log(`    ${TG}/qualia-debug${RESET}    Structured debugging`);
+  console.log(`    ${TG}/qualia-review${RESET}   Production audit`);
+  console.log(`    ${TG}/qualia-ship${RESET}     Deploy to production`);
+  console.log(`    ${TG}/qualia-report${RESET}   Log your work`);
+  console.log("");
 }
 
-main().catch(err => {
-  console.error(`${c.red}Error:${c.reset}`, err.message);
-  process.exit(1);
-});
+
+// ─── Main ────────────────────────────────────────────────
+const cmd = process.argv[2];
+
+switch (cmd) {
+  case "install":
+    cmdInstall();
+    break;
+  case "version":
+  case "-v":
+  case "--version":
+    cmdVersion();
+    break;
+  case "update":
+  case "upgrade":
+    cmdUpdate();
+    break;
+  case "uninstall":
+  case "remove":
+    cmdUninstall().catch((e) => {
+      console.error(`${RED}  ✗ Uninstall failed: ${e.message}${RESET}`);
+      process.exit(1);
+    });
+    break;
+  case "team":
+    cmdTeam();
+    break;
+  case "traces":
+    cmdTraces();
+    break;
+  case "migrate":
+    cmdMigrate();
+    break;
+  case "analytics":
+  case "stats":
+    cmdAnalytics();
+    break;
+  default:
+    cmdHelp();
+}