qualia-framework 6.1.0 → 6.2.9

package/bin/cli.js

@@ -4,6 +4,7 @@ const { spawnSync } = require("child_process");
 const path = require("path");
 const fs = require("fs");
 const readline = require("readline");
+const os = require("os");
 
 const TEAL = "\x1b[38;2;0;206;209m";
 const TG = "\x1b[38;2;0;170;175m";
@@ -15,22 +16,77 @@ 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 CLAUDE_DIR = path.join(os.homedir(), ".claude");
+const CODEX_DIR = path.join(os.homedir(), ".codex");
 const PKG = require("../package.json");
 const CONFIG_FILE = path.join(CLAUDE_DIR, ".qualia-config.json");
+const CODEX_CONFIG_FILE = path.join(CODEX_DIR, ".qualia-config.json");
+
+function installedHomes() {
+  const homes = [];
+  if (fs.existsSync(CONFIG_FILE)) homes.push(CLAUDE_DIR);
+  if (fs.existsSync(CODEX_CONFIG_FILE)) homes.push(CODEX_DIR);
+  return homes.length > 0 ? homes : [CLAUDE_DIR];
+}
+
+function primaryInstallHome() {
+  return installedHomes()[0];
+}
+
+function configFileForHome(home) {
+  return path.join(home, ".qualia-config.json");
+}
 
 function readConfig() {
+  const configFile = fs.existsSync(CONFIG_FILE) ? CONFIG_FILE : CODEX_CONFIG_FILE;
   try {
-    return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+    return JSON.parse(fs.readFileSync(configFile, "utf8"));
   } catch {
     return {};
   }
 }
 
-function writeConfig(cfg) {
-  if (!fs.existsSync(CLAUDE_DIR)) fs.mkdirSync(CLAUDE_DIR, { recursive: true });
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
-  try { fs.chmodSync(CONFIG_FILE, 0o600); } catch {}
+function readConfigAt(home) {
+  try {
+    return JSON.parse(fs.readFileSync(configFileForHome(home), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(cfg, home = primaryInstallHome()) {
+  if (!fs.existsSync(home)) fs.mkdirSync(home, { recursive: true });
+  const configFile = configFileForHome(home);
+  fs.writeFileSync(configFile, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+  try { fs.chmodSync(configFile, 0o600); } catch {}
+}
+
+function installTargetForUpdate() {
+  const hasClaude = fs.existsSync(CONFIG_FILE);
+  const hasCodex = fs.existsSync(CODEX_CONFIG_FILE);
+  if (hasClaude && hasCodex) return "3";
+  if (hasCodex) return "2";
+  return "1";
+}
+
+function isCodexHome(home) {
+  return path.basename(home) === ".codex";
+}
+
+function installLabel(home) {
+  return isCodexHome(home) ? "Codex" : "Claude Code";
+}
+
+function hasQualiaArtifacts(home) {
+  return fs.existsSync(configFileForHome(home))
+    || fs.existsSync(path.join(home, "bin", "state.js"))
+    || fs.existsSync(path.join(home, "hooks", "session-start.js"))
+    || fs.existsSync(path.join(home, "skills", "qualia-new"));
+}
+
+function frameworkHomes() {
+  const homes = [CLAUDE_DIR, CODEX_DIR].filter(hasQualiaArtifacts);
+  return homes.length > 0 ? homes : [CLAUDE_DIR];
 }
 
 function banner() {
@@ -50,6 +106,12 @@ function cmdVersion() {
   const cfg = readConfig();
 
   console.log(`  ${DIM}Installed:${RESET}  ${WHITE}${PKG.version}${RESET}`);
+  const surfaces = installedHomes()
+    .filter((home) => fs.existsSync(configFileForHome(home)))
+    .map((home) => path.basename(home) === ".codex" ? "Codex" : "Claude Code");
+  if (surfaces.length > 0) {
+    console.log(`  ${DIM}Targets:${RESET}    ${WHITE}${surfaces.join(" · ")}${RESET}`);
+  }
   if (cfg.installed_by) {
     console.log(`  ${DIM}User:${RESET}       ${WHITE}${cfg.installed_by}${RESET} ${DIM}(${cfg.role})${RESET}`);
   }
@@ -103,8 +165,9 @@ function cmdUpdate() {
   console.log("");
 
   try {
+    const target = installTargetForUpdate();
     const r = spawnSync("npx", ["qualia-framework@latest", "install"], {
-      input: cfg.code + "\n",
+      input: `${cfg.code}\n${target}\n`,
       stdio: ["pipe", "inherit", "inherit"],
       shell: process.platform === "win32",  // npx is a .cmd shim on Windows — must go through shell
       timeout: 120000,
@@ -122,12 +185,12 @@ function cmdUpdate() {
 }
 
 // ─── 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.).
+// Surgical removal of the Qualia Framework from installed homes.
+// Preserves CLAUDE.md / AGENTS.md (user may have customized them), Codex
+// config.toml, and non-Qualia hook entries in settings.json / hooks.json.
 // --yes / -y skips the confirmation prompt for scripted use.
 
-// Current Qualia hook filenames — only these are removed from ~/.claude/hooks/,
+// Current Qualia hook filenames — only these are removed from hooks/,
 // any other hooks the user dropped in there are left alone. The LEGACY set
 // lists hooks that were shipped by older framework versions but have since
 // been removed; uninstall still tries to clean them so old installs get a
@@ -139,7 +202,6 @@ const QUALIA_HOOK_FILES = [
   "pre-push.js",
   "migration-guard.js",
   "pre-deploy-gate.js",
-  "pre-compact.js",
   "git-guardrails.js",
   "stop-session-log.js",
   "env-empty-guard.js",
@@ -148,6 +210,7 @@ const QUALIA_HOOK_FILES = [
 ];
 const QUALIA_LEGACY_HOOK_FILES = [
   "block-env-edit.js", // removed in v3.2.0
+  "pre-compact.js", // removed in v6.2.0 — state.js journal makes bot-commits redundant
 ];
 
 // Qualia agents — only these are removed.
@@ -162,6 +225,7 @@ const QUALIA_AGENT_FILES = [
   "roadmapper.md",
   "visual-evaluator.md",
 ];
+const QUALIA_CODEX_AGENT_FILES = QUALIA_AGENT_FILES.map((f) => f.replace(/\.md$/, ".toml"));
 
 // Qualia bin scripts.
 const QUALIA_BIN_FILES = [
@@ -174,12 +238,15 @@ const QUALIA_BIN_FILES = [
   "agent-runs.js",
   "slop-detect.mjs",
   "erp-retry.js",
+  "report-payload.js",
+  "project-snapshot.js",
 ];
 
 // Qualia rules — security, deployment, infra, grounding, plus the v4.5.0 design substrate.
 // frontend.md and design-reference.md are kept for backward compat; new projects use design-laws/brand/product/rubric.
 const QUALIA_RULE_FILES = [
   "security.md", "deployment.md", "infrastructure.md", "grounding.md",
+  "speed.md", "architecture.md", "trust-boundary.md", "one-opinion.md",
   "frontend.md", "design-reference.md",
   "design-laws.md", "design-brand.md", "design-product.md", "design-rubric.md",
 ];
@@ -219,46 +286,55 @@ function safeRmDir(p, counters) {
   }
 }
 
-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;
-  }
-
-  // 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/"));
+function isQualiaCommand(cmd) {
+  return typeof cmd === "string"
+    && (cmd.includes("qualia")
+      || cmd.includes(".claude/hooks/")
+      || cmd.includes(".claude/bin/")
+      || cmd.includes(".codex/hooks/")
+      || cmd.includes(".codex/bin/"));
+}
 
-  const filterHookArray = (arr) => {
-    if (!Array.isArray(arr)) return arr;
-    return arr
+function cleanHookBlocks(root, hookKey) {
+  if (!root || typeof root !== "object" || !root[hookKey] || typeof root[hookKey] !== "object") return false;
+  let changed = false;
+  for (const key of Object.keys(root[hookKey])) {
+    const arr = root[hookKey][key];
+    if (!Array.isArray(arr)) continue;
+    const cleaned = arr
       .map((entry) => {
         if (!entry || !Array.isArray(entry.hooks)) return entry;
         const hooks = entry.hooks.filter((h) => !isQualiaCommand(h && h.command));
+        if (hooks.length !== entry.hooks.length) changed = true;
         return { ...entry, hooks };
       })
       .filter((entry) => Array.isArray(entry.hooks) && entry.hooks.length > 0);
-  };
-
-  if (settings.hooks && typeof settings.hooks === "object") {
-    // Iterate every hook event key, not a hardcoded subset — future hook
-    // events added by Claude Code or the framework get cleaned automatically.
-    for (const key of Object.keys(settings.hooks)) {
-      const cleaned = filterHookArray(settings.hooks[key]);
-      if (cleaned && cleaned.length > 0) {
-        settings.hooks[key] = cleaned;
-      } else {
-        delete settings.hooks[key];
-      }
+    if (cleaned.length > 0) {
+      root[hookKey][key] = cleaned;
+    } else {
+      delete root[hookKey][key];
+      changed = true;
     }
-    // If hooks is now empty, remove it entirely.
-    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
   }
+  if (Object.keys(root[hookKey]).length === 0) {
+    delete root[hookKey];
+    changed = true;
+  }
+  return changed;
+}
+
+function cleanSettingsJson(home, counters) {
+  const settingsPath = path.join(home, "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;
+  }
+
+  cleanHookBlocks(settings, "hooks");
 
   // Status line — only drop it if it points at our renderer.
   if (settings.statusLine && typeof settings.statusLine === "object") {
@@ -282,19 +358,40 @@ function cleanSettingsJson(counters) {
   }
 }
 
+function cleanCodexHooksJson(home, counters) {
+  const hooksPath = path.join(home, "hooks.json");
+  if (!fs.existsSync(hooksPath)) return;
+  let hooksJson;
+  try {
+    hooksJson = JSON.parse(fs.readFileSync(hooksPath, "utf8"));
+  } catch (e) {
+    counters.errors.push(`hooks.json: ${e.message}`);
+    return;
+  }
+  cleanHookBlocks(hooksJson, "hooks");
+  try {
+    fs.writeFileSync(hooksPath, JSON.stringify(hooksJson, null, 2) + "\n");
+    counters.hooksJsonCleaned = true;
+  } catch (e) {
+    counters.errors.push(`hooks.json write: ${e.message}`);
+  }
+}
+
 async function cmdUninstall() {
   banner();
 
   const args = process.argv.slice(3);
   const skipConfirm = args.includes("-y") || args.includes("--yes");
 
+  const homes = frameworkHomes();
   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(`  ${DIM}No Qualia config found at${RESET} ${WHITE}${CONFIG_FILE}${RESET} ${DIM}or${RESET} ${WHITE}${CODEX_CONFIG_FILE}${RESET}`);
   }
+  console.log(`  ${DIM}Targets:${RESET} ${WHITE}${homes.map(installLabel).join(" · ")}${RESET}`);
   console.log("");
 
   if (!skipConfirm) {
@@ -320,62 +417,60 @@ async function cmdUninstall() {
   console.log(`  ${DIM}Removing framework files...${RESET}`);
   console.log("");
 
-  const counters = { filesRemoved: 0, dirsRemoved: 0, settingsCleaned: false, errors: [] };
+  const counters = { filesRemoved: 0, dirsRemoved: 0, settingsCleaned: false, hooksJsonCleaned: false, errors: [] };
 
-  // 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);
+  for (const home of homes) {
+    const skillsDir = path.join(home, "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) {
+      counters.errors.push(`${installLabel(home)} skills scan: ${e.message}`);
     }
-  } catch (e) {
-    counters.errors.push(`skills scan: ${e.message}`);
-  }
 
-  // Agents — only the Qualia ones.
-  for (const f of QUALIA_AGENT_FILES) {
-    safeUnlink(path.join(CLAUDE_DIR, "agents", f), counters);
-  }
+    const agentFiles = isCodexHome(home)
+      ? [...QUALIA_CODEX_AGENT_FILES, ...QUALIA_AGENT_FILES]
+      : QUALIA_AGENT_FILES;
+    for (const f of agentFiles) {
+      safeUnlink(path.join(home, "agents", f), counters);
+    }
 
-  // Hooks — current set plus any legacy hook filenames from older versions.
-  for (const f of [...QUALIA_HOOK_FILES, ...QUALIA_LEGACY_HOOK_FILES]) {
-    safeUnlink(path.join(CLAUDE_DIR, "hooks", f), counters);
-  }
+    for (const f of [...QUALIA_HOOK_FILES, ...QUALIA_LEGACY_HOOK_FILES]) {
+      safeUnlink(path.join(home, "hooks", f), counters);
+    }
 
-  // Bin scripts — only the Qualia ones.
-  for (const f of QUALIA_BIN_FILES) {
-    safeUnlink(path.join(CLAUDE_DIR, "bin", f), counters);
-  }
+    for (const f of QUALIA_BIN_FILES) {
+      safeUnlink(path.join(home, "bin", f), counters);
+    }
 
-  // Rules — all 4.
-  for (const f of QUALIA_RULE_FILES) {
-    safeUnlink(path.join(CLAUDE_DIR, "rules", f), counters);
-  }
+    for (const f of QUALIA_RULE_FILES) {
+      safeUnlink(path.join(home, "rules", f), counters);
+    }
 
-  // Templates directory (entire).
-  safeRmDir(path.join(CLAUDE_DIR, "qualia-templates"), counters);
+    safeRmDir(path.join(home, "qualia-templates"), counters);
+    safeRmDir(path.join(home, "qualia-design"), counters);
+    safeRmDir(path.join(home, "qualia-references"), counters);
 
-  // Knowledge directory (optional preservation).
-  if (!preserveKnowledge) {
-    safeRmDir(path.join(CLAUDE_DIR, "knowledge"), counters);
-  }
+    if (!preserveKnowledge) {
+      safeRmDir(path.join(home, "knowledge"), counters);
+    }
 
-  // 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);
+    safeUnlink(path.join(home, ".qualia-config.json"), counters);
+    safeUnlink(path.join(home, ".qualia-last-update-check"), counters);
+    safeUnlink(path.join(home, ".erp-api-key"), counters);
+    safeUnlink(path.join(home, ".qualia-team.json"), counters);
+    safeUnlink(path.join(home, "qualia-guide.md"), counters);
 
-  // Traces directory.
-  safeRmDir(path.join(CLAUDE_DIR, ".qualia-traces"), counters);
+    safeRmDir(path.join(home, ".qualia-traces"), counters);
 
-  // Clean settings.json surgically.
-  cleanSettingsJson(counters);
+    if (isCodexHome(home)) cleanCodexHooksJson(home, counters);
+    else cleanSettingsJson(home, counters);
+  }
 
   // Summary.
   console.log("");
@@ -386,6 +481,9 @@ async function cmdUninstall() {
   console.log(
     `  ${DIM}settings.json:${RESET}       ${counters.settingsCleaned ? `${GREEN}cleaned ✓${RESET}` : `${DIM}not present${RESET}`}`
   );
+  console.log(
+    `  ${DIM}hooks.json:${RESET}          ${counters.hooksJsonCleaned ? `${GREEN}cleaned ✓${RESET}` : `${DIM}not present${RESET}`}`
+  );
   if (preserveKnowledge) {
     console.log(`  ${DIM}Knowledge base:${RESET}      ${GREEN}preserved ✓${RESET}`);
   } else {
@@ -401,14 +499,13 @@ async function cmdUninstall() {
   }
 
   console.log("");
-  console.log(
-    `  ${YELLOW}Manual step:${RESET} edit ${WHITE}~/.claude/CLAUDE.md${RESET} to remove the Qualia Framework section if desired.`
-  );
+  console.log(`  ${YELLOW}Manual step:${RESET} edit ${WHITE}~/.claude/CLAUDE.md${RESET} or ${WHITE}~/.codex/AGENTS.md${RESET} if you want to remove the global instruction text.`);
   console.log("");
 }
 
 // ─── Team Management ────────────────────────────────────
-// External team file at ~/.claude/.qualia-team.json.
+// External team file at the active install home. Falls back to ~/.claude before
+// install for backward compatibility.
 // Falls back to embedded defaults in install.js.
 
 function getDefaultTeam() {
@@ -422,19 +519,23 @@ function getDefaultTeam() {
 }
 
 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 {}
+  for (const home of installedHomes()) {
+    const teamFile = path.join(home, ".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");
+  for (const home of installedHomes()) {
+    if (!fs.existsSync(home)) fs.mkdirSync(home, { recursive: true });
+    fs.writeFileSync(path.join(home, ".qualia-team.json"), JSON.stringify(team, null, 2) + "\n");
+  }
 }
 
 function parseTeamArgs(argv) {
@@ -456,7 +557,7 @@ function cmdTeam() {
       console.log("");
       const team = readTeamFile();
       const source = team || getDefaultTeam();
-      const label = team ? "team file" : "embedded defaults";
+      const label = team ? "installed team file" : "embedded defaults";
       console.log(`  ${DIM}Source: ${label}${RESET}`);
       console.log("");
       for (const [code, member] of Object.entries(source)) {
@@ -516,7 +617,7 @@ function cmdTeam() {
 function cmdTraces() {
   banner();
   console.log("");
-  const tracesDir = path.join(CLAUDE_DIR, ".qualia-traces");
+  const tracesDir = path.join(primaryInstallHome(), ".qualia-traces");
   if (!fs.existsSync(tracesDir)) {
     console.log(`  ${DIM}No traces found. Traces are written by hooks during normal operation.${RESET}`);
     console.log("");
@@ -552,6 +653,15 @@ function cmdMigrate() {
 
   const settingsPath = path.join(CLAUDE_DIR, "settings.json");
   if (!fs.existsSync(settingsPath)) {
+    if (fs.existsSync(CODEX_CONFIG_FILE)) {
+      const hooksPath = path.join(CODEX_DIR, "hooks.json");
+      if (fs.existsSync(hooksPath)) {
+        console.log(`  ${GREEN}✓${RESET} Codex install uses ${WHITE}~/.codex/hooks.json${RESET}; no Claude settings migration is needed.`);
+        console.log(`  ${DIM}Refresh Codex wiring with:${RESET} ${TEAL}npx qualia-framework@latest install${RESET}`);
+        console.log("");
+        process.exit(0);
+      }
+    }
     console.log(`  ${RED}✗${RESET} No settings.json found. Run ${TEAL}qualia-framework install${RESET} first.`);
     console.log("");
     process.exit(1);
@@ -667,23 +777,22 @@ function cmdMigrate() {
     }
   }
 
-  // Check PreCompact hook
-  if (!settings.hooks.PreCompact || !Array.isArray(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`);
-  } else {
-    let compactEntry = settings.hooks.PreCompact.find(e => e.matcher === "compact");
-    if (!compactEntry) {
-      compactEntry = { matcher: "compact", hooks: [] };
-      settings.hooks.PreCompact.push(compactEntry);
-    }
-    if (!compactEntry.hooks) compactEntry.hooks = [];
-    const exists = compactEntry.hooks.some(h => extractScriptName(h.command) === "pre-compact.js");
-    if (!exists) {
-      compactEntry.hooks.push({ type: "command", command: nodeCmd("pre-compact.js"), timeout: 15, statusMessage: "⬢ Saving state..." });
+  // PreCompact: pre-compact.js was removed in v6.2.0 (state.js already provides
+  // crash-safe atomic writes with a write-ahead journal — the bot commit added
+  // no durability). Strip any legacy entry; drop the event key if it's empty.
+  if (Array.isArray(settings.hooks.PreCompact)) {
+    const beforeLen = settings.hooks.PreCompact.length;
+    settings.hooks.PreCompact = settings.hooks.PreCompact
+      .map(block => {
+        if (!block || !Array.isArray(block.hooks)) return block;
+        return { ...block, hooks: block.hooks.filter(h => extractScriptName(h && h.command) !== "pre-compact.js") };
+      })
+      .filter(block => Array.isArray(block.hooks) && block.hooks.length > 0);
+    const removed = beforeLen !== settings.hooks.PreCompact.length || settings.hooks.PreCompact.length === 0;
+    if (settings.hooks.PreCompact.length === 0) delete settings.hooks.PreCompact;
+    if (removed) {
       changes++;
-      console.log(`  ${GREEN}+${RESET} Wired pre-compact.js into PreCompact`);
+      console.log(`  ${GREEN}-${RESET} Removed legacy pre-compact.js from PreCompact`);
     }
   }
 
@@ -764,7 +873,7 @@ function cmdAnalytics() {
   banner();
   console.log("");
 
-  const tracesDir = path.join(CLAUDE_DIR, ".qualia-traces");
+  const tracesDir = path.join(primaryInstallHome(), ".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}`);
@@ -854,11 +963,12 @@ async function cmdErpPing() {
   banner();
   console.log("");
 
+  const installHome = primaryInstallHome();
   const cfg = readConfig();
   const args = new Set(process.argv.slice(3));
   const erpUrl = (cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net";
   let erpEnabled = !(cfg.erp && cfg.erp.enabled === false);
-  const keyFile = path.join(CLAUDE_DIR, ".erp-api-key");
+  const keyFile = path.join(installHome, ".erp-api-key");
 
   console.log(`  ${DIM}URL:${RESET}       ${WHITE}${erpUrl}${RESET}`);
   console.log(`  ${DIM}Enabled:${RESET}   ${erpEnabled ? `${GREEN}yes${RESET}` : `${YELLOW}no (erp.enabled=false)${RESET}`}`);
@@ -989,17 +1099,21 @@ function cmdSetErpKey() {
   banner();
   console.log("");
 
-  const keyFile = path.join(CLAUDE_DIR, ".erp-api-key");
+  const homes = installedHomes();
   const rawArgs = process.argv.slice(3);
   const clear = rawArgs.includes("--clear");
 
-  if (!fs.existsSync(CLAUDE_DIR)) fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+  for (const home of homes) {
+    if (!fs.existsSync(home)) fs.mkdirSync(home, { recursive: true });
+  }
 
   if (clear) {
-    try { fs.unlinkSync(keyFile); } catch {}
-    const cfg = readConfig();
-    cfg.erp = { ...(cfg.erp || {}), enabled: false, url: (cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net", api_key_file: ".erp-api-key" };
-    writeConfig(cfg);
+    for (const home of homes) {
+      try { fs.unlinkSync(path.join(home, ".erp-api-key")); } catch {}
+      const cfg = readConfigAt(home);
+      cfg.erp = { ...(cfg.erp || {}), enabled: false, url: (cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net", api_key_file: ".erp-api-key" };
+      writeConfig(cfg, home);
+    }
     console.log(`  ${GREEN}✓${RESET} ERP key removed and ERP disabled.`);
     console.log("");
     return;
@@ -1036,19 +1150,21 @@ function cmdSetErpKey() {
     console.log(`  ${YELLOW}!${RESET} Key looks short (${key.length} bytes). Saving anyway.`);
   }
 
-  fs.writeFileSync(keyFile, key, { mode: 0o600 });
-  try { fs.chmodSync(keyFile, 0o600); } catch {}
-
-  const cfg = readConfig();
-  cfg.erp = {
-    ...(cfg.erp || {}),
-    enabled: true,
-    url: (cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net",
-    api_key_file: ".erp-api-key",
-  };
-  writeConfig(cfg);
+  for (const home of homes) {
+    const keyFile = path.join(home, ".erp-api-key");
+    fs.writeFileSync(keyFile, key, { mode: 0o600 });
+    try { fs.chmodSync(keyFile, 0o600); } catch {}
+    const cfg = readConfigAt(home);
+    cfg.erp = {
+      ...(cfg.erp || {}),
+      enabled: true,
+      url: (cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net",
+      api_key_file: ".erp-api-key",
+    };
+    writeConfig(cfg, home);
+  }
 
-  console.log(`  ${GREEN}✓${RESET} ERP key saved to ${WHITE}${keyFile}${RESET}`);
+  console.log(`  ${GREEN}✓${RESET} ERP key saved to ${WHITE}${homes.map((h) => path.join(h, ".erp-api-key")).join(", ")}${RESET}`);
   console.log(`  ${DIM}Verify with:${RESET} ${TEAL}qualia-framework erp-ping${RESET}`);
   console.log("");
 }
@@ -1066,7 +1182,7 @@ function cmdSetErpKey() {
 // retry stranded reports on demand (e.g., after the ERP came back online,
 // or after rotating the API key). All args pass through.
 function cmdErpFlush() {
-  const retryScript = path.join(CLAUDE_DIR, "bin", "erp-retry.js");
+  const retryScript = path.join(primaryInstallHome(), "bin", "erp-retry.js");
   if (!fs.existsSync(retryScript)) {
     console.log(`  ${RED}✗${RESET} erp-retry.js not installed at ${retryScript}`);
     console.log(`  ${DIM}Run: npx qualia-framework@latest install${RESET}`);
@@ -1084,8 +1200,25 @@ function cmdErpFlush() {
   process.exit(r.status || 0);
 }
 
+function cmdProjectSnapshot() {
+  const snapshotScript = path.join(primaryInstallHome(), "bin", "project-snapshot.js");
+  const localSnapshotScript = path.join(__dirname, "project-snapshot.js");
+  const script = fs.existsSync(snapshotScript) ? snapshotScript : localSnapshotScript;
+  if (!fs.existsSync(script)) {
+    console.log(`  ${RED}✗${RESET} project-snapshot.js not available`);
+    console.log(`  ${DIM}Run: npx qualia-framework@latest install${RESET}`);
+    process.exit(1);
+  }
+  const args = process.argv.slice(3);
+  const r = spawnSync(process.execPath, [script, ...args], {
+    stdio: "inherit",
+    shell: false,
+  });
+  process.exit(typeof r.status === "number" ? r.status : 1);
+}
+
 function cmdFlush() {
-  const flushScript = path.join(CLAUDE_DIR, "bin", "knowledge-flush.js");
+  const flushScript = path.join(primaryInstallHome(), "bin", "knowledge-flush.js");
   if (!fs.existsSync(flushScript)) {
     console.log(`  ${RED}✗${RESET} knowledge-flush.js not installed at ${flushScript}`);
     console.log(`  ${DIM}Run: npx qualia-framework@latest install${RESET}`);
@@ -1111,70 +1244,71 @@ function cmdDoctor() {
     if (!ok) issues.push({ label, hint });
   }
 
-  // ── Critical files (the same set session-start.js validates) ──
-  const criticalFiles = [
-    path.join(CLAUDE_DIR, "rules", "grounding.md"),
-    path.join(CLAUDE_DIR, "rules", "security.md"),
-    path.join(CLAUDE_DIR, "rules", "frontend.md"),
-    path.join(CLAUDE_DIR, "rules", "deployment.md"),
-    path.join(CLAUDE_DIR, "bin", "state.js"),
-    path.join(CLAUDE_DIR, "bin", "qualia-ui.js"),
-    path.join(CLAUDE_DIR, "bin", "statusline.js"),
-    path.join(CLAUDE_DIR, "bin", "knowledge.js"),
-    path.join(CLAUDE_DIR, "bin", "knowledge-flush.js"),
-    path.join(CLAUDE_DIR, "bin", "erp-retry.js"),
-    path.join(CLAUDE_DIR, "CLAUDE.md"),
-    CONFIG_FILE,
-  ];
-  for (const f of criticalFiles) {
-    check(
-      `${path.relative(CLAUDE_DIR, f) || f}`,
-      fs.existsSync(f),
-      "run: npx qualia-framework@latest install",
-    );
-  }
+  const homes = installedHomes().filter((home) => fs.existsSync(configFileForHome(home)));
+  if (homes.length === 0) {
+    check("Qualia install", false, "run: npx qualia-framework@latest install");
+  }
+
+  for (const home of homes) {
+    const label = path.basename(home) === ".codex" ? "Codex" : "Claude";
+    const coreFiles = [
+      "rules/grounding.md",
+      "rules/security.md",
+      "rules/deployment.md",
+      "bin/state.js",
+      "bin/qualia-ui.js",
+      "bin/statusline.js",
+      "bin/knowledge.js",
+      "bin/knowledge-flush.js",
+      "bin/erp-retry.js",
+      "bin/report-payload.js",
+      "bin/project-snapshot.js",
+      "knowledge/agents.md",
+      "knowledge/index.md",
+      "knowledge/daily-log",
+      ".qualia-config.json",
+    ];
+    if (label === "Claude") coreFiles.push("CLAUDE.md", "settings.json");
+    else coreFiles.push("AGENTS.md", "config.toml", "hooks.json", "agents/planner.toml", "skills/qualia-new/SKILL.md");
+
+    for (const rel of coreFiles) {
+      check(`${label} ${rel}`, fs.existsSync(path.join(home, rel)), "run: npx qualia-framework@latest install");
+    }
 
-  // ── Hooks ─────────────────────────────────────────────
-  for (const h of QUALIA_HOOK_FILES) {
-    check(
-      `hooks/${h}`,
-      fs.existsSync(path.join(CLAUDE_DIR, "hooks", h)),
-      "reinstall: npx qualia-framework@latest install",
-    );
-  }
+    for (const h of QUALIA_HOOK_FILES) {
+      check(`${label} hooks/${h}`, fs.existsSync(path.join(home, "hooks", h)), "reinstall: npx qualia-framework@latest install");
+    }
 
-  // ── Knowledge layer ────────────────────────────────────
-  const knowledgeFiles = [
-    path.join(CLAUDE_DIR, "knowledge", "agents.md"),
-    path.join(CLAUDE_DIR, "knowledge", "index.md"),
-    path.join(CLAUDE_DIR, "knowledge", "daily-log"),
-  ];
-  for (const f of knowledgeFiles) {
-    check(
-      `knowledge/${path.basename(f)}${fs.existsSync(f) && fs.statSync(f).isDirectory() ? "/" : ""}`,
-      fs.existsSync(f),
-      "reinstall to initialize the memory layer: npx qualia-framework@latest install",
-    );
-  }
+    if (label === "Claude" && fs.existsSync(path.join(home, "settings.json"))) {
+      try {
+        const settings = JSON.parse(fs.readFileSync(path.join(home, "settings.json"), "utf8"));
+        for (const ev of ["SessionStart", "PreToolUse", "Stop"]) {
+          const blocks = (settings.hooks || {})[ev] || [];
+          const hasQualia = blocks.some((b) =>
+            (b.hooks || []).some((h) => typeof h.command === "string" && h.command.includes(".claude")),
+          );
+          check(`Claude settings.json hooks.${ev}`, hasQualia, "reinstall to wire hooks");
+        }
+        check("Claude settings.json statusLine", !!(settings.statusLine && settings.statusLine.command && settings.statusLine.command.includes("statusline.js")), "reinstall to wire statusline");
+      } catch (e) {
+        check("Claude settings.json parseable", false, e.message);
+      }
+    }
 
-  // ── settings.json hook wiring ──────────────────────────
-  const settingsPath = path.join(CLAUDE_DIR, "settings.json");
-  if (fs.existsSync(settingsPath)) {
-    try {
-      const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
-      const wantEvents = ["SessionStart", "PreToolUse", "PreCompact", "Stop"];
-      for (const ev of wantEvents) {
-        const blocks = (settings.hooks || {})[ev] || [];
-        const hasQualia = blocks.some((b) =>
-          (b.hooks || []).some((h) => typeof h.command === "string" && h.command.includes(".claude")),
-        );
-        check(`settings.json hooks.${ev}`, hasQualia, "reinstall to wire hooks");
+    if (label === "Codex" && fs.existsSync(path.join(home, "hooks.json"))) {
+      try {
+        const hooksJson = JSON.parse(fs.readFileSync(path.join(home, "hooks.json"), "utf8"));
+        for (const ev of ["SessionStart", "PreToolUse", "Stop"]) {
+          const blocks = (hooksJson.hooks || {})[ev] || [];
+          const hasQualia = blocks.some((b) =>
+            (b.hooks || []).some((h) => typeof h.command === "string" && h.command.includes(".codex")),
+          );
+          check(`Codex hooks.json ${ev}`, hasQualia, "reinstall to wire Codex hooks");
+        }
+      } catch (e) {
+        check("Codex hooks.json parseable", false, e.message);
       }
-    } catch (e) {
-      check("settings.json parseable", false, e.message);
     }
-  } else {
-    check("settings.json", false, "Claude Code never ran here? Open Claude once first");
   }
 
   // ── Version vs. installed ──────────────────────────────
@@ -1289,7 +1423,7 @@ function cmdHelp() {
   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}uninstall${RESET}    Clean removal from installed Claude/Codex homes (${DIM}-y to skip prompts${RESET})`);
   console.log(`    qualia-framework ${TEAL}migrate${RESET}      Wire current hook + env layout into ~/.claude/settings.json`);
   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`);
@@ -1298,6 +1432,7 @@ function cmdHelp() {
   console.log(`    qualia-framework ${TEAL}set-erp-key${RESET}  Save/enable the ERP API key`);
   console.log(`    qualia-framework ${TEAL}erp-ping${RESET}     Verify ERP connectivity + API key`);
   console.log(`    qualia-framework ${TEAL}erp-flush${RESET}    Retry queued ERP report uploads (${DIM}show|clear${RESET})`);
+  console.log(`    qualia-framework ${TEAL}project-snapshot${RESET} Export/upload ERP admin project progress snapshot (${DIM}--write|--upload${RESET})`);
   console.log(`    qualia-framework ${TEAL}doctor${RESET}       Health-check the install (files, hooks, settings)`);
   console.log(`    qualia-framework ${TEAL}flush${RESET}        Promote daily-log → curated knowledge (memory layer)`);
   console.log("");
@@ -1367,6 +1502,10 @@ switch (cmd) {
   case "erp-retry":
     cmdErpFlush();
     break;
+  case "project-snapshot":
+  case "snapshot":
+    cmdProjectSnapshot();
+    break;
   case "doctor":
   case "health":
   case "health-check":