qualia-framework 4.5.0 → 5.1.0

package/bin/install.js

@@ -3,10 +3,12 @@
 const { createInterface } = require("readline");
 const path = require("path");
 const fs = require("fs");
+const ui = require("./qualia-ui.js");
 
-// ─── Colors ──────────────────────────────────────────────
+// ─── Colors (kept for legacy log lines; new sections route through qualia-ui) ─
 const TEAL = "\x1b[38;2;0;206;209m";
 const DIM = "\x1b[38;2;80;90;100m";
+const DIM2 = "\x1b[38;2;70;80;90m";
 const GREEN = "\x1b[38;2;52;211;153m";
 const WHITE = "\x1b[38;2;220;225;230m";
 const YELLOW = "\x1b[38;2;234;179;8m";
@@ -14,8 +16,17 @@ const RED = "\x1b[38;2;239;68;68m";
 const RESET = "\x1b[0m";
 
 const CLAUDE_DIR = path.join(require("os").homedir(), ".claude");
+const CODEX_DIR = path.join(require("os").homedir(), ".codex");
 const FRAMEWORK_DIR = path.resolve(__dirname, "..");
 
+// Target IDs match the menu numbers shown to the user.
+const TARGET_CLAUDE_ONLY = "1";
+const TARGET_CODEX_ONLY = "2";
+const TARGET_BOTH = "3";
+
+// Total install timer — set in main(), read by the final summary card.
+const installStart = Date.now();
+
 // ─── Team codes ──────────────────────────────────────────
 const DEFAULT_TEAM = {
   "QS-FAWZI-01": {
@@ -64,16 +75,30 @@ const TEAM = loadTeam();
 let installed = 0;
 let errors = 0;
 
+// Per-section timer state. Started by printSection(), read by closeSection().
+let sectionStart = 0;
+let sectionLabel = "";
+let sectionCount = 0;
+
 function log(msg) {
   console.log(`  ${msg}`);
 }
 function ok(label) {
   installed++;
+  sectionCount++;
   log(`${GREEN}✓${RESET} ${label}`);
 }
 function warn(label) {
   errors++;
-  log(`${YELLOW}✗${RESET} ${label}`);
+  log(`${YELLOW}!${RESET} ${label}`);
+}
+// step(text) → handle returned by qualia-ui. Use for slow ops where the
+// "doing → done" lifecycle helps the user trust the install isn't hung.
+function step(text) {
+  return ui.step(text);
+}
+function spin(text) {
+  return ui.spinner(text);
 }
 function copy(src, dest) {
   const destDir = path.dirname(dest);
@@ -161,23 +186,135 @@ function printHeader() {
 }
 
 function printSection(title) {
+  // Close prior section if one was open (shows count + elapsed).
+  closeSection();
+  sectionStart = Date.now();
+  sectionLabel = title;
+  sectionCount = 0;
   console.log("");
   console.log(`  ${TEAL}▸${RESET} ${WHITE}${BOLD}${title}${RESET}`);
-  console.log(`  ${DIM}${"─".repeat(40)}${RESET}`);
+  console.log(`  ${DIM2}${"─".repeat(40)}${RESET}`);
+}
+
+function closeSection() {
+  if (!sectionLabel) return;
+  const elapsedMs = Date.now() - sectionStart;
+  const elapsed = elapsedMs >= 1000
+    ? `${(elapsedMs / 1000).toFixed(1)}s`
+    : `${elapsedMs}ms`;
+  if (sectionCount > 0) {
+    console.log(`  ${DIM2}└─${RESET} ${DIM}${sectionCount} ${sectionLabel.toLowerCase()} · ${elapsed}${RESET}`);
+  }
+  sectionLabel = "";
+  sectionCount = 0;
+}
+
+// ─── Prompt helpers ──────────────────────────────────────
+// Two prompts (team code, install target) need to coexist with two stdin
+// modes: interactive TTY and piped. The earlier two-readline approach
+// raced 'close' against the second question on piped installs (`echo CODE
+// | install.js` would EOF before the second question could attach a line
+// listener) — the target prompt always saw "" and defaulted to "1" even
+// when the user piped "CODE\n2\n".
+//
+// Fix: in piped mode, pre-buffer all stdin lines synchronously up front and
+// hand them out one by one. In TTY mode, use a shared readline.
+let SHARED_RL = null;
+let PIPED_LINES = null;
+let PIPED_INDEX = 0;
+const IS_INTERACTIVE = !!(process.stdin && process.stdin.isTTY);
+
+function getRl() {
+  if (!SHARED_RL) {
+    SHARED_RL = createInterface({ input: process.stdin, output: process.stdout });
+  }
+  return SHARED_RL;
+}
+function closeRl() {
+  if (SHARED_RL) { try { SHARED_RL.close(); } catch {} SHARED_RL = null; }
+}
+
+// Read every available stdin line into an array. Resolves immediately on
+// 'end'. Used only when stdin is piped (legacy `echo ... | install`).
+function bufferStdin() {
+  return new Promise((resolve) => {
+    let buf = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => { buf += chunk; });
+    process.stdin.on("end", () => {
+      const lines = buf.split(/\r?\n/);
+      // Trim a trailing empty entry from the final newline, but preserve
+      // intentional empties (so an empty target line still defaults to "1"
+      // rather than swallowing the team-code line).
+      if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+      resolve(lines);
+    });
+  });
+}
+
+function nextPipedLine() {
+  if (!PIPED_LINES) return "";
+  if (PIPED_INDEX >= PIPED_LINES.length) return "";
+  return PIPED_LINES[PIPED_INDEX++];
 }
 
-// ─── Prompt for code ─────────────────────────────────────
 function askCode() {
   return new Promise((resolve) => {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    if (!IS_INTERACTIVE) {
+      printHeader();
+      const line = nextPipedLine();
+      // Echo the prompt + answer for log readability.
+      process.stdout.write(`  ${WHITE}Enter install code:${RESET} ${line}\n`);
+      resolve(String(line || "").trim());
+      return;
+    }
+    const rl = getRl();
     printHeader();
     rl.question(`  ${WHITE}Enter install code:${RESET} `, (answer) => {
-      rl.close();
-      resolve(answer.trim());
+      resolve(String(answer || "").trim());
     });
   });
 }
 
+// ─── Prompt for install target (Claude / Codex / Both) ──
+// Backward-compat: a piped install with only the team code (single stdin
+// line) closes stdin before this prompt; we silently default to "1"
+// (Claude only) so existing scripts keep working untouched.
+function askTarget() {
+  return new Promise((resolve) => {
+    console.log("");
+    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}[3]${RESET} ${WHITE}Both${RESET}                 ${DIM}— max compatibility${RESET}`);
+    console.log("");
+
+    const normalize = (val) => {
+      const trimmed = String(val || "").trim();
+      // Empty or unrecognized → default to Claude only (preserves legacy
+      // single-line piped install: `echo CODE | npx qualia-framework install`).
+      if (trimmed === TARGET_CODEX_ONLY || trimmed === TARGET_BOTH) return trimmed;
+      return TARGET_CLAUDE_ONLY;
+    };
+
+    if (!IS_INTERACTIVE) {
+      const line = nextPipedLine();
+      process.stdout.write(`  ${WHITE}Choice [1]:${RESET} ${line}\n`);
+      resolve(normalize(line));
+      return;
+    }
+    const rl = getRl();
+    rl.question(`  ${WHITE}Choice [1]:${RESET} `, (answer) => resolve(normalize(answer)));
+  });
+}
+
+function targetLabel(t) {
+  if (t === TARGET_CODEX_ONLY) return "Codex";
+  if (t === TARGET_BOTH) return "Claude Code · Codex";
+  return "Claude Code";
+}
+
 // ─── Resolve team code (tolerates case + O/0 typo in suffix) ─
 // Accepts "qs-fawzi-01", "QS-FAWZI-01", "QS-FAWZI-O1" (letter O in the
 // numeric suffix), and returns the canonical key if found, else null.
@@ -196,6 +333,12 @@ function resolveTeamCode(input) {
 
 // ─── Main ────────────────────────────────────────────────
 async function main() {
+  // Piped install: drain stdin once up front. Avoids EOF/'close' racing
+  // ahead of the second prompt's 'line' listener (the bug v5.0 didn't have
+  // because v5.0 only had one prompt).
+  if (!IS_INTERACTIVE) {
+    PIPED_LINES = await bufferStdin();
+  }
   const rawCode = await askCode();
   const code = resolveTeamCode(rawCode);
   const member = code ? TEAM[code] : null;
@@ -211,7 +354,23 @@ async function main() {
   console.log("");
   const roleColor = member.role === "OWNER" ? TEAL : GREEN;
   console.log(`  ${GREEN}✓${RESET} ${WHITE}${BOLD}Welcome, ${member.name}${RESET}`);
-  console.log(`  ${DIM}  Role:${RESET} ${roleColor}${member.role}${RESET}  ${DIM}·${RESET}  ${DIM}Target:${RESET} ${WHITE}${CLAUDE_DIR}${RESET}`);
+  console.log(`  ${DIM}  Role:${RESET} ${roleColor}${member.role}${RESET}`);
+
+  // ─── Ask install target (Claude / Codex / Both) ────────
+  const target = await askTarget();
+  closeRl();
+  const installClaude = target === TARGET_CLAUDE_ONLY || target === TARGET_BOTH;
+  const installCodexTarget = target === TARGET_CODEX_ONLY || target === TARGET_BOTH;
+
+  console.log("");
+  console.log(`  ${DIM}  Target:${RESET} ${WHITE}${targetLabel(target)}${RESET}`);
+
+  if (!installClaude) {
+    // Codex-only path: skip the entire Claude install block. Jump straight
+    // to the Codex installer + final summary.
+    await installCodex(member, target);
+    return;
+  }
 
   // ─── Skills ──────────────────────────────────────────
   const skillsDir = path.join(FRAMEWORK_DIR, "skills");
@@ -226,6 +385,21 @@ async function main() {
         path.join(skillsDir, skill, "SKILL.md"),
         path.join(CLAUDE_DIR, "skills", skill, "SKILL.md")
       );
+      // Copy REFERENCE.md if the skill has one (progressive-disclosure pattern)
+      const refSrc = path.join(skillsDir, skill, "REFERENCE.md");
+      if (fs.existsSync(refSrc)) {
+        copy(refSrc, path.join(CLAUDE_DIR, "skills", skill, "REFERENCE.md"));
+      }
+      // v5.1: Copy scripts/ subfolder if present (e.g. qualia-polish-loop ships
+      // playwright-capture.mjs, loop.mjs, score.mjs that the skill invokes at
+      // runtime). Recursive — preserves nested files. fixtures/ also copied
+      // for self-test scenarios.
+      for (const sub of ["scripts", "fixtures"]) {
+        const subSrc = path.join(skillsDir, skill, sub);
+        if (fs.existsSync(subSrc) && fs.statSync(subSrc).isDirectory()) {
+          copyTree(subSrc, path.join(CLAUDE_DIR, "skills", skill, sub));
+        }
+      }
       ok(skill);
     } catch (e) {
       warn(`${skill} — ${e.message}`);
@@ -383,6 +557,17 @@ async function main() {
     claudeMd = claudeMd.replace("{{ROLE}}", member.role);
     claudeMd = claudeMd.replace("{{ROLE_DESCRIPTION}}", member.description);
     const claudeDest = path.join(CLAUDE_DIR, "CLAUDE.md");
+    // v5.0: backup existing CLAUDE.md before overwrite. Users may have added
+    // personal instructions; without a backup, re-install silently destroys
+    // them. .bak files are harmless and easy to clean up.
+    if (fs.existsSync(claudeDest)) {
+      const existing = fs.readFileSync(claudeDest, "utf8");
+      if (existing !== claudeMd) {
+        const ts = new Date().toISOString().replace(/[:.]/g, "-");
+        const bak = `${claudeDest}.bak.${ts}`;
+        try { fs.copyFileSync(claudeDest, bak); ok(`Backed up existing CLAUDE.md → ${path.basename(bak)}`); } catch {}
+      }
+    }
     fs.writeFileSync(claudeDest, claudeMd, "utf8");
     ok(`Configured as ${member.role}`);
   } catch (e) {
@@ -687,6 +872,8 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     "session-start.js", "auto-update.js", "branch-guard.js", "pre-push.js",
     "pre-deploy-gate.js", "migration-guard.js", "pre-compact.js",
     "git-guardrails.js", "stop-session-log.js",
+    // v5.0 — insights-driven destructive-op + wrong-account guards
+    "vercel-account-guard.js", "env-empty-guard.js", "supabase-destructive-guard.js",
   ]);
   const isQualiaHookCmd = (cmd) => {
     if (typeof cmd !== "string") return false;
@@ -713,6 +900,10 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
           { type: "command", if: "Bash(git push*)", command: nodeCmd("branch-guard.js"), timeout: 5, statusMessage: "⬢ Checking branch permissions..." },
           { type: "command", if: "Bash(git push*)", command: nodeCmd("pre-push.js"), timeout: 15, statusMessage: "⬢ Syncing tracking..." },
           { type: "command", if: "Bash(vercel --prod*)", command: nodeCmd("pre-deploy-gate.js"), timeout: 180, statusMessage: "⬢ Running quality gates..." },
+          // v5.0 hooks — insights-driven friction prevention
+          { type: "command", if: "Bash(vercel --prod*)|Bash(vercel deploy*)", command: nodeCmd("vercel-account-guard.js"), timeout: 8, statusMessage: "⬢ Verifying Vercel account..." },
+          { type: "command", if: "Bash(vercel env*)", command: nodeCmd("env-empty-guard.js"), timeout: 5, statusMessage: "⬢ Checking env value..." },
+          { type: "command", if: "Bash(supabase*)|Bash(npx supabase*)", command: nodeCmd("supabase-destructive-guard.js"), timeout: 5, statusMessage: "⬢ Checking Supabase safety..." },
         ],
       },
       {
@@ -773,56 +964,205 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     ok("MCP: next-devtools (runtime error visibility for Next.js projects)");
   }
 
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  // v5.0: backup existing settings.json before overwrite. The merge logic above
+  // preserves user fields, but a partial-write or merger bug could destroy MCP
+  // configs / custom permissions. Atomic write (tmp + rename) avoids partial
+  // writes; the .bak file is the recovery point if the merger ever misbehaves.
+  if (fs.existsSync(settingsPath)) {
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const bak = `${settingsPath}.bak.${ts}`;
+    try { fs.copyFileSync(settingsPath, bak); } catch {}
+  }
+  const settingsTmp = `${settingsPath}.tmp.${process.pid}`;
+  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");
+  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("Status line + spinner configured");
   ok("Environment variables + permissions");
 
+  // ─── Codex (optional second target) ──────────────────────
+  if (installCodexTarget) {
+    await installCodex(member, target);
+  }
+
   // ─── Summary ───────────────────────────────────────────
+  closeSection();
+  printSummary({ member, target, claudeInstalled: true });
+}
+
+// ─── Final summary card (shared by Claude / Codex / Both paths) ──
+function printSummary({ member, target, claudeInstalled }) {
+  const roleColor = member.role === "OWNER" ? TEAL : GREEN;
+  const totalMs = Date.now() - installStart;
+  const totalSec = totalMs >= 1000
+    ? `${(totalMs / 1000).toFixed(1)}s`
+    : `${totalMs}ms`;
+
   console.log("");
-  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log(`  ${DIM2}${RULE}${RESET}`);
   console.log(`  ${TEAL}${BOLD}⬢  INSTALLED${RESET}`);
-  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log(`  ${DIM2}${RULE}${RESET}`);
   console.log("");
   console.log(`  ${WHITE}${BOLD}${member.name}${RESET}  ${DIM}·${RESET}  ${roleColor}${member.role}${RESET}  ${DIM}·${RESET}  ${DIM}v${PKG_VERSION}${RESET}`);
   console.log("");
-  const agentCount = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')).length;
-  const hookCount = fs.readdirSync(hooksSource).length;
-  const ruleCount = fs.readdirSync(rulesDir).length;
-  const tmplCount = fs.readdirSync(tmplDir).length;
-  console.log(`  ${DIM}Skills${RESET}    ${TEAL}${skills.length}${RESET}     ${DIM}Agents${RESET}  ${TEAL}${agentCount}${RESET}     ${DIM}Hooks${RESET}   ${TEAL}${hookCount}${RESET}`);
-  const installedBinDir = path.join(CLAUDE_DIR, "bin");
-  const scriptCount = fs.existsSync(installedBinDir)
-    ? fs.readdirSync(installedBinDir).filter(f => f.endsWith('.js')).length
-    : 0;
-  console.log(`  ${DIM}Rules${RESET}     ${TEAL}${ruleCount}${RESET}     ${DIM}Scripts${RESET} ${TEAL}${scriptCount}${RESET}     ${DIM}Templates${RESET} ${TEAL}${tmplCount}${RESET}`);
+  console.log(`  ${DIM}Targets${RESET}   ${TEAL}${targetLabel(target)}${RESET}`);
+  console.log(`  ${DIM}Time${RESET}      ${TEAL}${totalSec}${RESET}`);
+
+  if (claudeInstalled) {
+    const agentsDir = path.join(FRAMEWORK_DIR, "agents");
+    const hooksSource = path.join(FRAMEWORK_DIR, "hooks");
+    const rulesDir = path.join(FRAMEWORK_DIR, "rules");
+    const tmplDir = path.join(FRAMEWORK_DIR, "templates");
+    const skillsDir = path.join(FRAMEWORK_DIR, "skills");
+    const skillCount = fs
+      .readdirSync(skillsDir)
+      .filter((d) => fs.statSync(path.join(skillsDir, d)).isDirectory()).length;
+    const agentCount = fs.readdirSync(agentsDir).filter((f) => f.endsWith(".md")).length;
+    const hookCount = fs.readdirSync(hooksSource).length;
+    const ruleCount = fs.readdirSync(rulesDir).length;
+    const tmplCount = fs.readdirSync(tmplDir).length;
+    const installedBinDir = path.join(CLAUDE_DIR, "bin");
+    const scriptCount = fs.existsSync(installedBinDir)
+      ? fs.readdirSync(installedBinDir).filter((f) => f.endsWith(".js")).length
+      : 0;
+    console.log("");
+    console.log(`  ${DIM}Skills${RESET}    ${TEAL}${skillCount}${RESET}     ${DIM}Agents${RESET}  ${TEAL}${agentCount}${RESET}     ${DIM}Hooks${RESET}   ${TEAL}${hookCount}${RESET}`);
+    console.log(`  ${DIM}Rules${RESET}     ${TEAL}${ruleCount}${RESET}     ${DIM}Scripts${RESET} ${TEAL}${scriptCount}${RESET}     ${DIM}Templates${RESET} ${TEAL}${tmplCount}${RESET}`);
+  }
 
   if (errors > 0) {
     console.log("");
     console.log(`  ${YELLOW}${errors} warning(s)${RESET} — check output above`);
   }
 
+  // Contextual first-command suggestion: if we're in a Qualia project,
+  // recommend /qualia (router); otherwise /qualia-new (kickoff).
+  const inProject = (() => {
+    try { return fs.existsSync(path.join(process.cwd(), ".planning")); }
+    catch { return false; }
+  })();
+  const firstCmd = inProject ? "/qualia" : "/qualia-new";
+  const firstCmdHint = inProject ? "router — tells you the next command" : "kickoff a new project";
+
   console.log("");
-  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log(`  ${DIM2}${RULE}${RESET}`);
   console.log(`  ${WHITE}${BOLD}Quick Start${RESET}`);
-  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log(`  ${DIM2}${RULE}${RESET}`);
   console.log("");
-  console.log(`  ${TEAL}1.${RESET} ${WHITE}Restart Claude Code${RESET} ${DIM}(loads new settings)${RESET}`);
-  console.log(`  ${TEAL}2.${RESET} ${WHITE}cd into any project${RESET} ${DIM}and run${RESET} ${TEAL}claude${RESET}`);
-  console.log(`  ${TEAL}3.${RESET} ${WHITE}Type${RESET} ${TEAL}${BOLD}/qualia${RESET} ${DIM}— it tells you what to do next${RESET}`);
+  if (claudeInstalled) {
+    console.log(`  ${TEAL}1.${RESET} ${WHITE}Restart Claude Code${RESET} ${DIM}(loads new settings)${RESET}`);
+    console.log(`  ${TEAL}2.${RESET} ${WHITE}cd into any project${RESET} ${DIM}and run${RESET} ${TEAL}claude${RESET}`);
+    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("");
   console.log(`  ${DIM}New project?${RESET}    ${TEAL}/qualia-new${RESET}`);
   console.log(`  ${DIM}Quick fix?${RESET}      ${TEAL}/qualia-quick${RESET}`);
   console.log(`  ${DIM}End of day?${RESET}     ${TEAL}/qualia-report${RESET} ${DIM}(mandatory)${RESET}`);
   console.log(`  ${DIM}Stuck?${RESET}          ${TEAL}/qualia${RESET}`);
   console.log("");
-  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log(`  ${DIM2}${RULE}${RESET}`);
   console.log(`  ${TEAL}${BOLD}Welcome to the future with Qualia.${RESET}`);
-  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log(`  ${DIM2}${RULE}${RESET}`);
   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.
+async function installCodex(member, target) {
+  console.log("");
+  console.log(`  ${TEAL}▸${RESET} ${WHITE}${BOLD}Codex${RESET}`);
+  console.log(`  ${DIM2}${"─".repeat(40)}${RESET}`);
+
+  // Detect Codex CLI; soft-warn if missing (file write still proceeds).
+  const { spawnSync } = require("child_process");
+  let codexDetected = false;
+  try {
+    const r = spawnSync("codex", ["--version"], {
+      encoding: "utf8",
+      timeout: 3000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    codexDetected = r.status === 0;
+  } catch { codexDetected = false; }
+
+  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}  when you install via:${RESET} ${TEAL}npm install -g @openai/codex${RESET}`);
+  }
+
+  // Make sure the dir exists.
+  if (!fs.existsSync(CODEX_DIR)) {
+    try {
+      fs.mkdirSync(CODEX_DIR, { recursive: true });
+    } catch (e) {
+      warn(`Codex — could not create ${CODEX_DIR}: ${e.message}`);
+      return;
+    }
+  }
+
+  // Render AGENTS.md with role substitution. Source is the same AGENTS.md
+  // already shipped in the framework root (it's the cross-vendor mirror of
+  // CLAUDE.md, kept under 25 lines per Pocock's instruction-budget rule).
+  let agentsContent;
+  try {
+    agentsContent = fs.readFileSync(path.join(FRAMEWORK_DIR, "AGENTS.md"), "utf8");
+    agentsContent = agentsContent
+      .replace("{{ROLE}}", member.role)
+      .replace("{{ROLE_DESCRIPTION}}", member.description);
+  } catch (e) {
+    warn(`Codex — could not read framework AGENTS.md: ${e.message}`);
+    return;
+  }
+
+  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);
+    sectionCount++;
+    ok(`AGENTS.md (configured as ${member.role})`);
+  } catch (e) {
+    warn(`Codex AGENTS.md — ${e.message}`);
+    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-only path: still need to write the role config and print summary.
+  if (target === TARGET_CODEX_ONLY) {
+    printSummary({ member, target, claudeInstalled: false });
+  }
+}
+
 main().catch((e) => {
   console.error(`${RED}  ✗ Installation failed: ${e.message}${RESET}`);
   process.exit(1);