qualia-framework 6.1.0 → 6.2.9

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,128 @@ 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, filenameFallback) {
+  const parsed = parseAgentMarkdown(markdown);
+  const body = parsed.body
+    .replaceAll("~/.claude/", "~/.codex/")
+    .replaceAll("@~/.claude/", "@~/.codex/");
+  const name = (parsed.name || filenameFallback || "").replace(/^qualia-/, "");
+  const description = parsed.description || "Qualia Framework specialist agent.";
+  return [
+    `name = ${tomlString(name)}`,
+    `description = ${tomlString(description)}`,
+    `developer_instructions = ${tomlString(body)}`,
+    "",
+  ].join("\n");
+}
+
+// Skills removed in past versions but still present in older installs.
+// Pruned from BOTH ~/.claude/skills/ and ~/.codex/skills/ on every install run
+// so the active surface matches what the framework currently ships.
+const DEPRECATED_SKILLS = [
+  "qualia-task",         // v5.7.0 — folded into qualia-feature
+  "qualia-quick",        // v5.7.0 — folded into qualia-feature
+  "qualia-polish-loop",  // v5.8.0 — folded into qualia-polish --loop
+  "qualia-design",       // v4 wave 2 — folded into scope-adaptive qualia-polish
+  "qualia-prd",          // v5.8.0 — surface cleanup
+];
+
+function pruneDeprecatedSkills(baseDir) {
+  const skillsDir = path.join(baseDir, "skills");
+  if (!fs.existsSync(skillsDir)) return [];
+  const removed = [];
+  for (const name of DEPRECATED_SKILLS) {
+    const target = path.join(skillsDir, name);
+    try {
+      if (fs.existsSync(target)) {
+        fs.rmSync(target, { recursive: true, force: true });
+        removed.push(name);
+      }
+    } catch {}
+  }
+  return removed;
+}
+
 // 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 +410,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("");
 
@@ -379,6 +503,8 @@ async function main() {
     .filter((d) => fs.statSync(path.join(skillsDir, d)).isDirectory());
 
   printSection("Skills");
+  const claudePruned = pruneDeprecatedSkills(CLAUDE_DIR);
+  for (const name of claudePruned) ok(`pruned deprecated: ${name}`);
   for (const skill of skills) {
     try {
       copy(
@@ -486,9 +612,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 +802,24 @@ 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)");
+    copy(
+      path.join(FRAMEWORK_DIR, "bin", "codex-goal.js"),
+      path.join(binDest, "codex-goal.js")
+    );
+    fs.chmodSync(path.join(binDest, "codex-goal.js"), 0o755);
+    ok("codex-goal.js (Codex /goal objective + token-budget suggester)");
   } catch (e) {
     warn(`scripts — ${e.message}`);
   }
@@ -835,7 +984,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 +1056,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 +1110,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 +1137,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 +1179,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 +1258,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 +1274,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 +1300,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 +1330,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 +1340,298 @@ 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",
+        "",
+        "# Codex's built-in status line is rendered at the bottom of the TUI.",
+        "# It takes an ARRAY of pre-defined segment names; Codex does NOT support",
+        "# custom-command status lines (unlike Claude's settings.json statusLine),",
+        "# so the Qualia phase/state info is rendered via the SessionStart banner",
+        "# at the top of the session instead. The segment list below mirrors the",
+        "# Codex default rich layout.",
+        "[tui]",
+        'status_line = ["model-with-reasoning", "task-progress", "current-dir", "git-branch", "context-used", "five-hour-limit", "weekly-limit"]',
+        "status_line_use_colors = true",
+        "",
+      ].join("\n"));
+      ok("config.toml (minimal Codex config)");
+    } else {
+      // Existing user config — append [tui] block only if absent. Leaves
+      // every other user setting untouched.
+      try {
+        const existing = fs.readFileSync(configToml, "utf8");
+        if (!/^\[tui\]/m.test(existing) && !/^status_line\s*=/m.test(existing)) {
+          const append = [
+            "",
+            "# Added by qualia-framework — Codex bottom status line.",
+            "[tui]",
+            'status_line = ["model-with-reasoning", "task-progress", "current-dir", "git-branch", "context-used", "five-hour-limit", "weekly-limit"]',
+            "status_line_use_colors = true",
+            "",
+          ].join("\n");
+          fs.appendFileSync(configToml, append);
+          ok("config.toml (appended [tui] status line block)");
+        } else {
+          log(`${DIM}config.toml (kept — user has customized)${RESET}`);
+        }
+      } catch {
+        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}`);
+  }
+
+  // Mirror the ERP API key from Claude → Codex so erp-retry/report-payload can
+  // post from Codex sessions without a separate provisioning step. The key
+  // resolver at runtime looks in $CODEX_DIR/.erp-api-key only; without this
+  // copy, every Codex ERP write 401s and the queue grows silently.
+  try {
+    const claudeKey = path.join(CLAUDE_DIR, ".erp-api-key");
+    const codexKey = path.join(CODEX_DIR, ".erp-api-key");
+    if (fs.existsSync(claudeKey) && !fs.existsSync(codexKey)) {
+      const key = fs.readFileSync(claudeKey, "utf8");
+      atomicWrite(codexKey, key, 0o600);
+      ok(".erp-api-key (mirrored from ~/.claude/)");
+    } else if (fs.existsSync(codexKey)) {
+      log(`${DIM}.erp-api-key (existing — preserved)${RESET}`);
+    }
+  } catch (e) {
+    warn(`Codex .erp-api-key — ${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",
+      "codex-goal.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, base);
+      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");
+    const codexPruned = pruneDeprecatedSkills(CODEX_DIR);
+    for (const name of codexPruned) ok(`pruned deprecated: ${name}`);
+    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)}"`;
+    // Codex's hook schema does NOT include an `if` field — only `command`,
+    // `commandWindows`, `timeout`, `async`, `statusMessage`. Filtering on
+    // tool_input.command happens inside each hook script (they read stdin
+    // JSON and `process.exit(0)` fast when the command doesn't match).
+    //
+    // Codex prints `statusMessage` for every entry in the matched group BEFORE
+    // running the hook. Including statusMessage on conditional hooks produced
+    // 8 lines of "Running PreToolUse hook: Qualia X..." on every Bash call
+    // even when 6 of the 8 immediately exited 0. We only set statusMessage on
+    // hooks that always do real work (auto-update + git-guardrails). The
+    // conditional hooks stay registered (so they still fire when applicable)
+    // but render silently.
+    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", command: nodeCmd("branch-guard.js"), timeout: 5 },
+              { type: "command", command: nodeCmd("pre-push.js"), timeout: 15 },
+              { type: "command", command: nodeCmd("pre-deploy-gate.js"), timeout: 180 },
+              { type: "command", command: nodeCmd("vercel-account-guard.js"), timeout: 8 },
+              { type: "command", command: nodeCmd("env-empty-guard.js"), timeout: 5 },
+              { type: "command", command: nodeCmd("supabase-destructive-guard.js"), timeout: 5 },
+            ],
+          },
+          {
+            matcher: "Edit|Write",
+            hooks: [
+              { type: "command", command: nodeCmd("migration-guard.js"), timeout: 10 },
+            ],
+          },
+        ],
+        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) {