qualia-framework 5.9.1 → 6.2.7

package/bin/erp-retry.js

@@ -40,9 +40,17 @@ const http = require("http");
 const urlLib = require("url");
 
 const HOME = os.homedir();
-const QUEUE_FILE = path.join(HOME, ".claude", ".erp-retry-queue.json");
-const API_KEY_FILE = path.join(HOME, ".claude", ".erp-api-key");
-const CONFIG_FILE = path.join(HOME, ".claude", ".qualia-config.json");
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(HOME, ".claude");
+}
+
+const QUALIA_HOME = qualiaHome();
+const QUEUE_FILE = path.join(QUALIA_HOME, ".erp-retry-queue.json");
+const API_KEY_FILE = path.join(QUALIA_HOME, ".erp-api-key");
+const CONFIG_FILE = path.join(QUALIA_HOME, ".qualia-config.json");
 
 const MAX_GIVE_UP_ATTEMPTS = 10;
 const DEFAULT_TIMEOUT_MS = 5000;

package/bin/install.js

@@ -58,15 +58,17 @@ const DEFAULT_TEAM = {
 
 // Load team from external file, fall back to embedded defaults.
 function loadTeam() {
-  const teamFile = path.join(CLAUDE_DIR, ".qualia-team.json");
-  try {
-    if (fs.existsSync(teamFile)) {
-      const external = JSON.parse(fs.readFileSync(teamFile, "utf8"));
-      if (external && typeof external === "object" && Object.keys(external).length > 0) {
-        return external;
+  for (const home of [CLAUDE_DIR, CODEX_DIR]) {
+    const teamFile = path.join(home, ".qualia-team.json");
+    try {
+      if (fs.existsSync(teamFile)) {
+        const external = JSON.parse(fs.readFileSync(teamFile, "utf8"));
+        if (external && typeof external === "object" && Object.keys(external).length > 0) {
+          return external;
+        }
       }
-    }
-  } catch {}
+    } catch {}
+  }
   return DEFAULT_TEAM;
 }
 
@@ -123,6 +125,99 @@ function copyTree(src, dest) {
   }
 }
 
+function codexText(content) {
+  return String(content)
+    .replaceAll("~/.claude/", "~/.codex/")
+    .replaceAll("$HOME/.claude/", "$HOME/.codex/")
+    .replaceAll("${HOME}/.claude/", "${HOME}/.codex/")
+    .replaceAll("@~/.claude/", "@~/.codex/")
+    .replaceAll(".claude/", ".codex/");
+}
+
+function copyTextTransform(src, dest, transform) {
+  const destDir = path.dirname(dest);
+  if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+  const content = fs.readFileSync(src, "utf8");
+  fs.writeFileSync(dest, transform(content), "utf8");
+}
+
+function copyTreeTransform(src, dest, transform) {
+  if (!fs.existsSync(src)) return;
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name.startsWith(".")) continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyTreeTransform(srcPath, destPath, transform);
+    } else if (entry.isFile()) {
+      copyTextTransform(srcPath, destPath, transform);
+    }
+  }
+}
+
+function backupIfDifferent(dest, nextContent, label) {
+  if (!fs.existsSync(dest)) return false;
+  try {
+    const existing = fs.readFileSync(dest, "utf8");
+    if (existing === nextContent) return false;
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const bak = `${dest}.bak.${ts}`;
+    fs.copyFileSync(dest, bak);
+    ok(`Backed up existing ${label} -> ${path.basename(bak)}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function atomicWrite(dest, content, mode) {
+  const destDir = path.dirname(dest);
+  if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+  const tmp = `${dest}.tmp.${process.pid}`;
+  if (mode) fs.writeFileSync(tmp, content, { mode });
+  else fs.writeFileSync(tmp, content, "utf8");
+  fs.renameSync(tmp, dest);
+  if (mode) {
+    try { fs.chmodSync(dest, mode); } catch {}
+  }
+}
+
+function tomlString(value) {
+  return JSON.stringify(String(value == null ? "" : value));
+}
+
+function parseAgentMarkdown(content) {
+  const result = { name: "", description: "", body: content };
+  if (!content.startsWith("---\n")) return result;
+  const end = content.indexOf("\n---", 4);
+  if (end === -1) return result;
+  const fm = content.slice(4, end).trim().split(/\r?\n/);
+  for (const line of fm) {
+    const match = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/);
+    if (!match) continue;
+    const key = match[1];
+    const value = match[2].replace(/^["']|["']$/g, "").trim();
+    if (key === "name") result.name = value;
+    if (key === "description") result.description = value;
+  }
+  result.body = content.slice(end + "\n---".length).replace(/^\s+/, "");
+  return result;
+}
+
+function renderCodexAgentToml(markdown) {
+  const parsed = parseAgentMarkdown(markdown);
+  const body = parsed.body
+    .replaceAll("~/.claude/", "~/.codex/")
+    .replaceAll("@~/.claude/", "@~/.codex/");
+  const description = parsed.description || "Qualia Framework specialist agent.";
+  return [
+    `description = ${tomlString(description)}`,
+    `developer_instructions = ${tomlString(body)}`,
+    "",
+  ].join("\n");
+}
+
 // Surgically remove orphaned v2.6 install cruft from ~/.claude/ on upgrade.
 // v2.6 installed a separate ~/.claude/qualia-framework/ directory with workflows/,
 // references/, assets/, bin/qualia-tools.js. v3 doesn't use any of that — it was
@@ -286,7 +381,7 @@ function askTarget() {
     console.log(`  ${WHITE}Where would you like to install Qualia?${RESET}`);
     console.log("");
     console.log(`    ${TEAL}[1]${RESET} ${WHITE}Claude Code only${RESET}     ${DIM}— recommended, full feature set${RESET}`);
-    console.log(`    ${TEAL}[2]${RESET} ${WHITE}OpenAI Codex only${RESET}    ${DIM}— AGENTS.md (Codex's open standard)${RESET}`);
+    console.log(`    ${TEAL}[2]${RESET} ${WHITE}OpenAI Codex only${RESET}    ${DIM}— AGENTS.md + hooks + agents + runtime${RESET}`);
     console.log(`    ${TEAL}[3]${RESET} ${WHITE}Both${RESET}                 ${DIM}— max compatibility${RESET}`);
     console.log("");
 
@@ -486,9 +581,14 @@ async function main() {
       }
     }
   } catch {}
-  // v3.2.0: purge deprecated hooks from existing installs on upgrade.
-  // block-env-edit.js was retired — team now has full read/write on .env*.
-  const DEPRECATED_HOOKS = ["block-env-edit.js"];
+  // Purge deprecated hooks from existing installs on upgrade.
+  // - block-env-edit.js (v3.2.0): team now has full read/write on .env*.
+  // - pre-compact.js (v6.2.0): bot-committed STATE.md + tracking.json on
+  //   context compaction for ERP visibility. ERP never read tracking.json
+  //   from git, and state.js already provides crash-safe atomic writes with
+  //   a write-ahead journal (state.js:36-64) — the bot commit added no
+  //   durability, just history noise.
+  const DEPRECATED_HOOKS = ["block-env-edit.js", "pre-compact.js"];
   for (const f of DEPRECATED_HOOKS) {
     const p = path.join(hooksDest, f);
     try { if (fs.existsSync(p)) fs.unlinkSync(p); } catch {}
@@ -671,6 +771,18 @@ async function main() {
     );
     fs.chmodSync(path.join(binDest, "erp-retry.js"), 0o755);
     ok("erp-retry.js (ERP report retry queue — drained by session-start hook and erp-flush CLI)");
+    copy(
+      path.join(FRAMEWORK_DIR, "bin", "report-payload.js"),
+      path.join(binDest, "report-payload.js")
+    );
+    fs.chmodSync(path.join(binDest, "report-payload.js"), 0o755);
+    ok("report-payload.js (Framework -> ERP report payload builder)");
+    copy(
+      path.join(FRAMEWORK_DIR, "bin", "project-snapshot.js"),
+      path.join(binDest, "project-snapshot.js")
+    );
+    fs.chmodSync(path.join(binDest, "project-snapshot.js"), 0o755);
+    ok("project-snapshot.js (ERP/admin project progress snapshot)");
   } catch (e) {
     warn(`scripts — ${e.message}`);
   }
@@ -835,7 +947,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       try { fs.chmodSync(configFile, 0o600); } catch {}
     } catch {}
     log(`${YELLOW}!${RESET} ERP key not configured — reports won't upload until set.`);
-    log(`${DIM}  Set with:${RESET} ${TEAL}qualia-framework set-erp-key <key>${RESET}`);
+    log(`${DIM}  Set with:${RESET} ${TEAL}printf '%s' "$QUALIA_ERP_KEY" | qualia-framework set-erp-key${RESET}`);
     log(`${DIM}  or:${RESET} ${TEAL}export QUALIA_ERP_KEY=...${RESET} ${DIM}then re-install.${RESET}`);
     log(`${DIM}  Get a key from Fawzi.${RESET}`);
   }
@@ -907,7 +1019,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       "⬢ Feature branches only — never push to main",
       "⬢ Read before write — no exceptions",
       "⬢ MVP first — build what's asked, nothing extra",
-      "⬢ tracking.json syncs to ERP on every push",
+      "⬢ tracking.json is local telemetry — no git pollution",
     ],
   };
 
@@ -961,14 +1073,11 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
         ],
       },
     ],
-    PreCompact: [
-      {
-        matcher: "compact",
-        hooks: [
-          { type: "command", command: nodeCmd("pre-compact.js"), timeout: 15, statusMessage: "⬢ Saving state..." },
-        ],
-      },
-    ],
+    // v6.2.0: PreCompact intentionally empty. The qualiaHooks loop in the
+    // settings.json merge below still iterates over this key, so legacy
+    // Qualia-owned pre-compact.js entries get stripped from existing user
+    // settings on upgrade. Nothing new is wired in.
+    PreCompact: [],
     Stop: [
       {
         matcher: ".*",
@@ -991,7 +1100,15 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       if (kept.length > 0) cleaned.push({ ...block, hooks: kept });
     }
     // Append our canonical blocks after the preserved user ones.
-    settings.hooks[event] = [...cleaned, ...qualiaHooks[event]];
+    const merged = [...cleaned, ...qualiaHooks[event]];
+    if (merged.length > 0) {
+      settings.hooks[event] = merged;
+    } else {
+      // No hooks left for this event (e.g. PreCompact after v6.2.0 removal) —
+      // drop the key entirely rather than leaving an empty array sitting in
+      // settings.json.
+      delete settings.hooks[event];
+    }
   }
 
   // Permissions stay permissive; Qualia policy enforcement happens in hooks so
@@ -1025,7 +1142,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   fs.writeFileSync(settingsTmp, JSON.stringify(settings, null, 2));
   fs.renameSync(settingsTmp, settingsPath);
 
-  ok("Hooks: session-start, auto-update, branch-guard, pre-push, migration-guard, deploy-gate, pre-compact, git-guardrails, stop-session-log, vercel-account-guard, env-empty-guard, supabase-destructive-guard");
+  ok("Hooks: session-start, auto-update, branch-guard, pre-push, migration-guard, deploy-gate, git-guardrails, stop-session-log, vercel-account-guard, env-empty-guard, supabase-destructive-guard");
   ok("Status line + spinner configured");
   ok("Environment variables + permissions");
 
@@ -1104,9 +1221,9 @@ function printSummary({ member, target, claudeInstalled }) {
     console.log(`  ${TEAL}3.${RESET} ${WHITE}Try${RESET} ${TEAL}${BOLD}${firstCmd}${RESET} ${DIM}— ${firstCmdHint}${RESET}`);
   } else {
     // Codex-only path
-    console.log(`  ${TEAL}1.${RESET} ${WHITE}Open Codex in any project${RESET}`);
-    console.log(`  ${TEAL}2.${RESET} ${WHITE}Codex picks up${RESET} ${TEAL}~/.codex/AGENTS.md${RESET} ${DIM}automatically${RESET}`);
-    console.log(`  ${TEAL}3.${RESET} ${WHITE}Ask Codex${RESET} ${DIM}about Qualia rules — they're in AGENTS.md${RESET}`);
+    console.log(`  ${TEAL}1.${RESET} ${WHITE}Restart Codex${RESET} ${DIM}(loads hooks + agents)${RESET}`);
+    console.log(`  ${TEAL}2.${RESET} ${WHITE}Open Codex in any project${RESET}`);
+    console.log(`  ${TEAL}3.${RESET} ${WHITE}Use Qualia commands${RESET} ${DIM}from AGENTS.md with ~/.codex/bin + hooks wired${RESET}`);
   }
   console.log("");
   console.log(`  ${DIM}New project?${RESET}    ${TEAL}/qualia-new${RESET}`);
@@ -1120,12 +1237,13 @@ function printSummary({ member, target, claudeInstalled }) {
   console.log("");
 }
 
-// ─── Codex install (writes AGENTS.md to ~/.codex/) ───────
-// Scope is intentionally minimal: AGENTS.md is the open standard adopted
-// by Codex / Cursor / Continue / Aider / Devin. Codex's runtime does not
-// today consume Claude-style skills/agents/hooks on disk in a way the
-// framework can map 1:1, so we write the convention file and document the
-// scope honestly. If Codex grows skill/hook support, we extend this here.
+// ─── Codex install ───────────────────────────────────────
+// Codex now has native support for AGENTS.md, ~/.codex/agents/*.toml, and
+// ~/.codex/hooks.json. Install the framework into those Codex-native surfaces,
+// plus the same local bin/rules/templates/knowledge substrate used by the
+// Claude install. The only thing intentionally not claimed is a Claude-style
+// persistent statusLine setting; Codex exposes hook status messages today, not
+// an equivalent global status-line command.
 async function installCodex(member, target) {
   console.log("");
   console.log(`  ${TEAL}▸${RESET} ${WHITE}${BOLD}Codex${RESET}`);
@@ -1145,7 +1263,7 @@ async function installCodex(member, target) {
 
   if (!codexDetected) {
     console.log(`  ${YELLOW}!${RESET} ${WHITE}Codex CLI not detected on this system${RESET}`);
-    console.log(`  ${DIM}  Installing AGENTS.md to ~/.codex/AGENTS.md anyway — Codex will pick it up${RESET}`);
+    console.log(`  ${DIM}  Installing Codex files to ~/.codex/ anyway — Codex will pick them up${RESET}`);
     console.log(`  ${DIM}  when you install via:${RESET} ${TEAL}npm install -g @openai/codex${RESET}`);
   }
 
@@ -1175,24 +1293,9 @@ async function installCodex(member, target) {
 
   const dest = path.join(CODEX_DIR, "AGENTS.md");
 
-  // Backup if existing differs (matches v5.0 CLAUDE.md / settings.json
-  // discipline — never silently destroy a hand-edited file).
-  if (fs.existsSync(dest)) {
-    try {
-      const existing = fs.readFileSync(dest, "utf8");
-      if (existing !== agentsContent) {
-        const ts = new Date().toISOString().replace(/[:.]/g, "-");
-        const bak = `${dest}.bak.${ts}`;
-        try { fs.copyFileSync(dest, bak); ok(`Backed up existing AGENTS.md → ${path.basename(bak)}`); } catch {}
-      }
-    } catch {}
-  }
-
-  // Atomic write: tmp + rename. Same pattern as settings.json above.
   try {
-    const tmp = `${dest}.tmp.${process.pid}`;
-    fs.writeFileSync(tmp, agentsContent, "utf8");
-    fs.renameSync(tmp, dest);
+    backupIfDifferent(dest, agentsContent, "AGENTS.md");
+    atomicWrite(dest, agentsContent);
     sectionCount++;
     ok(`AGENTS.md (configured as ${member.role})`);
   } catch (e) {
@@ -1200,10 +1303,235 @@ async function installCodex(member, target) {
     return;
   }
 
-  // Honest scope note.
-  console.log(`  ${DIM}└─${RESET} ${DIM}Codex install scope: AGENTS.md only — Codex's runtime does not currently${RESET}`);
-  console.log(`     ${DIM}consume the framework's skills/hooks/agents on disk. AGENTS.md carries${RESET}`);
-  console.log(`     ${DIM}the rules; commands route through Claude Code.${RESET}`);
+  // Codex treats config.toml as optional, but doctor reports a warning when it
+  // is absent. Create a minimal, parseable file on fresh Codex-only homes and
+  // leave existing user config untouched.
+  try {
+    const configToml = path.join(CODEX_DIR, "config.toml");
+    if (!fs.existsSync(configToml)) {
+      atomicWrite(configToml, [
+        "# Created by qualia-framework install.",
+        "# User settings can be added normally; Qualia runtime lives in AGENTS.md, hooks.json, agents/, and bin/.",
+        "",
+        "[features]",
+        "hooks = true",
+        "plugin_hooks = true",
+        "",
+      ].join("\n"));
+      ok("config.toml (minimal Codex config)");
+    } else {
+      log(`${DIM}config.toml (kept — user has customized)${RESET}`);
+    }
+  } catch (e) {
+    warn(`Codex config.toml — ${e.message}`);
+  }
+
+  // Save Codex-local role config. Hooks/scripts resolve their install home at
+  // runtime, so Codex-only installs must not depend on ~/.claude existing.
+  try {
+    const codexConfig = {
+      code: Object.entries(TEAM).find(([, m]) => m.name === member.name)?.[0] || "",
+      installed_by: member.name,
+      role: member.role,
+      version: require("../package.json").version,
+      installed_at: new Date().toISOString().split("T")[0],
+      erp: {
+        enabled: true,
+        url: "https://portal.qualiasolutions.net",
+        api_key_file: ".erp-api-key",
+      },
+    };
+    atomicWrite(path.join(CODEX_DIR, ".qualia-config.json"), JSON.stringify(codexConfig, null, 2) + "\n", 0o600);
+    ok(".qualia-config.json");
+  } catch (e) {
+    warn(`Codex config — ${e.message}`);
+  }
+
+  // Scripts
+  try {
+    const binDest = path.join(CODEX_DIR, "bin");
+    if (!fs.existsSync(binDest)) fs.mkdirSync(binDest, { recursive: true });
+    const scripts = [
+      "state.js",
+      "qualia-ui.js",
+      "statusline.js",
+      "knowledge.js",
+      "knowledge-flush.js",
+      "plan-contract.js",
+      "agent-runs.js",
+      "slop-detect.mjs",
+      "erp-retry.js",
+      "report-payload.js",
+      "project-snapshot.js",
+    ];
+    for (const script of scripts) {
+      const src = path.join(FRAMEWORK_DIR, "bin", script);
+      const out = path.join(binDest, script);
+      copy(src, out);
+      try { fs.chmodSync(out, 0o755); } catch {}
+    }
+    ok(`bin/ (${scripts.length} scripts)`);
+  } catch (e) {
+    warn(`Codex scripts — ${e.message}`);
+  }
+
+  // Agents: convert Claude markdown agents into Codex TOML agents.
+  try {
+    const agentsDir = path.join(FRAMEWORK_DIR, "agents");
+    const agentsDest = path.join(CODEX_DIR, "agents");
+    if (!fs.existsSync(agentsDest)) fs.mkdirSync(agentsDest, { recursive: true });
+    for (const file of fs.readdirSync(agentsDir)) {
+      if (!file.endsWith(".md")) continue;
+      const source = fs.readFileSync(path.join(agentsDir, file), "utf8");
+      const parsed = parseAgentMarkdown(source);
+      const base = parsed.name ? parsed.name.replace(/^qualia-/, "") : path.basename(file, ".md");
+      const out = path.join(agentsDest, `${base}.toml`);
+      const toml = renderCodexAgentToml(source);
+      backupIfDifferent(out, toml, `agents/${base}.toml`);
+      atomicWrite(out, toml);
+    }
+    ok("agents/*.toml");
+  } catch (e) {
+    warn(`Codex agents — ${e.message}`);
+  }
+
+  // Rules + lazy-loaded design substrate.
+  try {
+    const rulesDir = path.join(FRAMEWORK_DIR, "rules");
+    const rulesDest = path.join(CODEX_DIR, "rules");
+    if (!fs.existsSync(rulesDest)) fs.mkdirSync(rulesDest, { recursive: true });
+    for (const file of fs.readdirSync(rulesDir)) {
+      copy(path.join(rulesDir, file), path.join(rulesDest, file));
+    }
+    copyTree(path.join(FRAMEWORK_DIR, "qualia-design"), path.join(CODEX_DIR, "qualia-design"));
+    ok("rules/ + qualia-design/");
+  } catch (e) {
+    warn(`Codex rules/design — ${e.message}`);
+  }
+
+  // Skills are copied for reference and path parity, with ~/.claude command
+  // paths rewritten to ~/.codex so Codex-only installs do not depend on a
+  // Claude install existing.
+  try {
+    const skillsSrc = path.join(FRAMEWORK_DIR, "skills");
+    const skillsDest = path.join(CODEX_DIR, "skills");
+    for (const skill of fs.readdirSync(skillsSrc)) {
+      const src = path.join(skillsSrc, skill);
+      if (!fs.statSync(src).isDirectory()) continue;
+      copyTreeTransform(src, path.join(skillsDest, skill), codexText);
+    }
+    ok("skills/");
+  } catch (e) {
+    warn(`Codex skills — ${e.message}`);
+  }
+
+  // Templates + knowledge layer.
+  try {
+    const tmplDir = path.join(FRAMEWORK_DIR, "templates");
+    const tmplDest = path.join(CODEX_DIR, "qualia-templates");
+    if (!fs.existsSync(tmplDest)) fs.mkdirSync(tmplDest, { recursive: true });
+    for (const entry of fs.readdirSync(tmplDir, { withFileTypes: true })) {
+      if (entry.name.startsWith(".") || entry.name === "knowledge") continue;
+      const srcPath = path.join(tmplDir, entry.name);
+      const destPath = path.join(tmplDest, entry.name);
+      if (entry.isDirectory()) copyTreeTransform(srcPath, destPath, codexText);
+      else copyTextTransform(srcPath, destPath, codexText);
+    }
+    const referencesSrc = path.join(FRAMEWORK_DIR, "references");
+    if (fs.existsSync(referencesSrc)) {
+      copyTreeTransform(referencesSrc, path.join(CODEX_DIR, "qualia-references"), codexText);
+    }
+    const knowledgeSrc = path.join(FRAMEWORK_DIR, "templates", "knowledge");
+    const knowledgeDest = path.join(CODEX_DIR, "knowledge");
+    if (!fs.existsSync(path.join(knowledgeDest, "daily-log"))) {
+      fs.mkdirSync(path.join(knowledgeDest, "daily-log"), { recursive: true });
+    }
+    if (fs.existsSync(knowledgeSrc)) {
+      for (const file of fs.readdirSync(knowledgeSrc)) {
+        const out = path.join(knowledgeDest, file);
+        if (!fs.existsSync(out)) copyTextTransform(path.join(knowledgeSrc, file), out, codexText);
+      }
+    }
+    copyTextTransform(path.join(FRAMEWORK_DIR, "guide.md"), path.join(CODEX_DIR, "qualia-guide.md"), codexText);
+    ok("templates/ + knowledge/ + references/ + guide");
+  } catch (e) {
+    warn(`Codex templates/knowledge — ${e.message}`);
+  }
+
+  // Hooks: Codex reads ~/.codex/hooks.json. Use Codex-local hook script paths
+  // and statusMessage strings so the TUI surfaces Qualia activity inline.
+  try {
+    const hooksSource = path.join(FRAMEWORK_DIR, "hooks");
+    const hooksDest = path.join(CODEX_DIR, "hooks");
+    if (!fs.existsSync(hooksDest)) fs.mkdirSync(hooksDest, { recursive: true });
+    const hookFiles = fs.readdirSync(hooksSource).filter((f) => f.endsWith(".js"));
+    for (const file of hookFiles) {
+      const out = path.join(hooksDest, file);
+      copy(path.join(hooksSource, file), out);
+      try { fs.chmodSync(out, 0o755); } catch {}
+    }
+    const nodeCmd = (hookFile) => `node "${path.join(hooksDest, hookFile)}"`;
+    const qualiaHooks = {
+      hooks: {
+        SessionStart: [
+          { matcher: ".*", hooks: [{ type: "command", command: nodeCmd("session-start.js"), timeout: 5 }] },
+        ],
+        PreToolUse: [
+          {
+            matcher: "Bash",
+            hooks: [
+              { type: "command", command: nodeCmd("auto-update.js"), timeout: 5, statusMessage: "Qualia update check..." },
+              { type: "command", command: nodeCmd("git-guardrails.js"), timeout: 5, statusMessage: "Qualia git safety..." },
+              { type: "command", if: "Bash(git push*)", command: nodeCmd("branch-guard.js"), timeout: 5, statusMessage: "Qualia branch guard..." },
+              { type: "command", if: "Bash(git push*)", command: nodeCmd("pre-push.js"), timeout: 15, statusMessage: "Qualia tracking stamp..." },
+              { type: "command", if: "Bash(vercel --prod*)", command: nodeCmd("pre-deploy-gate.js"), timeout: 180, statusMessage: "Qualia deploy gate..." },
+              { type: "command", if: "Bash(vercel --prod*)|Bash(vercel deploy*)", command: nodeCmd("vercel-account-guard.js"), timeout: 8, statusMessage: "Qualia Vercel account..." },
+              { type: "command", if: "Bash(vercel env*)", command: nodeCmd("env-empty-guard.js"), timeout: 5, statusMessage: "Qualia env guard..." },
+              { type: "command", if: "Bash(supabase*)|Bash(npx supabase*)", command: nodeCmd("supabase-destructive-guard.js"), timeout: 5, statusMessage: "Qualia Supabase guard..." },
+            ],
+          },
+          {
+            matcher: "Edit|Write",
+            hooks: [
+              { type: "command", if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)", command: nodeCmd("migration-guard.js"), timeout: 10, statusMessage: "Qualia migration guard..." },
+            ],
+          },
+        ],
+        Stop: [
+          { matcher: ".*", hooks: [{ type: "command", command: nodeCmd("stop-session-log.js"), timeout: 5 }] },
+        ],
+      },
+    };
+    const hooksPath = path.join(CODEX_DIR, "hooks.json");
+    let hooksJson = { hooks: {} };
+    if (fs.existsSync(hooksPath)) {
+      try {
+        const parsed = JSON.parse(fs.readFileSync(hooksPath, "utf8"));
+        if (parsed && typeof parsed === "object") hooksJson = parsed;
+      } catch {}
+    }
+    if (!hooksJson.hooks || typeof hooksJson.hooks !== "object") hooksJson.hooks = {};
+    const isQualiaHookCmd = (cmd) => {
+      if (typeof cmd !== "string") return false;
+      return hookFiles.some((file) => cmd.includes(file));
+    };
+    for (const event of Object.keys(qualiaHooks.hooks)) {
+      const existing = Array.isArray(hooksJson.hooks[event]) ? hooksJson.hooks[event] : [];
+      const cleaned = [];
+      for (const block of existing) {
+        if (!block || !Array.isArray(block.hooks)) continue;
+        const kept = block.hooks.filter((h) => !isQualiaHookCmd(h && h.command));
+        if (kept.length > 0) cleaned.push({ ...block, hooks: kept });
+      }
+      hooksJson.hooks[event] = [...cleaned, ...qualiaHooks.hooks[event]];
+    }
+    const content = JSON.stringify(hooksJson, null, 2) + "\n";
+    backupIfDifferent(hooksPath, content, "hooks.json");
+    atomicWrite(hooksPath, content);
+    ok(`hooks.json + hooks/ (${hookFiles.length} hooks)`);
+  } catch (e) {
+    warn(`Codex hooks — ${e.message}`);
+  }
 
   // Codex-only path: still need to write the role config and print summary.
   if (target === TARGET_CODEX_ONLY) {

package/bin/knowledge-flush.js

@@ -5,8 +5,8 @@
 // CI/scheduled job) without an interactive Claude Code session. Closes the
 // memory loop end-to-end:
 //
-//   Stop hook (auto, every turn) → ~/.claude/knowledge/daily-log/{date}.md
-//   THIS SCRIPT (weekly cron)    → spawns `claude -p "/qualia-flush --days 7"`
+//   Stop hook (auto, every turn) → <install-home>/knowledge/daily-log/{date}.md
+//   THIS SCRIPT (weekly cron)    → spawns the installed agent CLI
 //   /qualia-flush                 → promotes raw → curated tier
 //   bin/knowledge.js (every spawn) → reads index.md → reaches the right file
 //
@@ -20,11 +20,11 @@
 //   0 3 * * 0 node ~/.claude/bin/knowledge-flush.js >> ~/.claude/.qualia-flush.log 2>&1
 //
 // Behavior:
-//   • If `claude` CLI isn't on PATH, exits 0 with a logged warning. Cron
+//   • If the required agent CLI isn't on PATH, exits 0 with a logged warning. Cron
 //     spam is worse than a missed flush — a real failure surfaces in the
 //     log file the user is presumably watching.
 //   • If the daily-log dir is empty (nothing to flush), exits 0 silently.
-//   • If `claude -p` returns non-zero, exits 1 with the error captured in
+//   • If the agent CLI returns non-zero, exits 1 with the error captured in
 //     the log so cron can be configured to alert on it.
 //   • Writes one structured JSONL line per run to ~/.claude/.qualia-flush.log
 //     so the user can audit "when did the last 5 flushes run, what did they
@@ -38,9 +38,17 @@ const os = require("os");
 const { spawnSync } = require("child_process");
 
 const HOME = os.homedir();
-const KNOWLEDGE_DIR = path.join(HOME, ".claude", "knowledge");
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(HOME, ".claude");
+}
+
+const QUALIA_HOME = qualiaHome();
+const KNOWLEDGE_DIR = path.join(QUALIA_HOME, "knowledge");
 const DAILY_DIR = path.join(KNOWLEDGE_DIR, "daily-log");
-const LOG_FILE = path.join(HOME, ".claude", ".qualia-flush.log");
+const LOG_FILE = path.join(QUALIA_HOME, ".qualia-flush.log");
 
 const _start = Date.now();
 
@@ -103,9 +111,11 @@ function dailyLogHasRecentEntries(windowDays) {
 }
 
 // ── Preflight ────────────────────────────────────────────
-const claudeBin = which("claude");
-if (!claudeBin) {
-  logEvent({ event: "skipped", reason: "claude-cli-not-on-path" });
+const IS_CODEX_INSTALL = path.basename(QUALIA_HOME) === ".codex";
+const agentCli = IS_CODEX_INSTALL ? "codex" : "claude";
+const agentBin = which(agentCli);
+if (!agentBin) {
+  logEvent({ event: "skipped", reason: `${agentCli}-cli-not-on-path` });
   // Exit 0 — a missing CLI on the host running cron is a config issue, not
   // a flush failure. Don't spam alerts.
   process.exit(0);
@@ -117,11 +127,13 @@ if (!dailyLogHasRecentEntries(days)) {
 }
 
 // ── Run ──────────────────────────────────────────────────
-// `claude -p "<prompt>"` runs a single non-interactive turn. The skill body
-// invocation matches what the user would type at the prompt.
+// `claude -p "<prompt>"` and `codex exec "<prompt>"` run a single
+// non-interactive turn. The skill body invocation matches what the user would
+// type at the prompt.
 const prompt = `/qualia-flush ${argv.join(" ")}`.trim();
 
-const result = spawnSync(claudeBin, ["-p", prompt], {
+const cliArgs = IS_CODEX_INSTALL ? ["exec", prompt] : ["-p", prompt];
+const result = spawnSync(agentBin, cliArgs, {
   encoding: "utf8",
   timeout: 5 * 60 * 1000, // 5 min hard cap — flush should never take this long
   shell: process.platform === "win32",
@@ -140,7 +152,7 @@ if (status !== 0) {
     stderr_tail: stderr.slice(-1000),
   });
   // Surface to stderr so cron's MAILTO sends an alert.
-  console.error(`knowledge-flush: claude -p exited ${status}`);
+  console.error(`knowledge-flush: ${agentCli} exited ${status}`);
   if (stderr) console.error(stderr.slice(-2000));
   process.exit(1);
 }