qualia-framework 4.5.0 → 5.3.0

package/bin/qualia-ui.js

@@ -522,6 +522,210 @@ function cmdPlanSummary(planPath) {
   console.log(`  ${RULE_DIM}`);
 }
 
+// ─── v5.1: live-progress primitives (consumed by install.js) ─────────
+// Vanilla Node, zero deps. Auto-degrade to plain text when stdout is not
+// a TTY so piped install logs stay readable (no orphan escape sequences,
+// no \r overwrites, no spinner garbage).
+
+const IS_TTY = !!(process.stdout && process.stdout.isTTY);
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+function visibleLength(str) {
+  return String(str).replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+// ANSI: clear current line and move cursor to column 0
+function clearLine() {
+  process.stdout.write("\r\x1b[2K");
+}
+function hideCursor() { if (IS_TTY) process.stdout.write("\x1b[?25l"); }
+function showCursor() { if (IS_TTY) process.stdout.write("\x1b[?25h"); }
+
+// step(text) — prints "  ⏳ text" then returns a handle:
+//   .ok(suffix?)     → overwrites with "  ✓ text [suffix]"
+//   .warn(message)   → overwrites with "  ! text — message"
+//   .fail(message)   → overwrites with "  ✗ text — message"
+// In non-TTY mode, prints plain "  → text" then "  ✓ text" on a new line.
+function step(text) {
+  const indent = "  ";
+  if (!IS_TTY) {
+    // Skip the "doing" line in non-TTY mode — go straight to the result line
+    // when finalised. Avoids 2× line count in piped install logs.
+    let logged = false;
+    return {
+      ok(suffix) {
+        const tail = suffix ? ` ${DIM}${suffix}${RESET}` : "";
+        console.log(`${indent}${GREEN}✓${RESET} ${WHITE}${text}${RESET}${tail}`);
+        logged = true;
+      },
+      warn(msg) {
+        console.log(`${indent}${YELLOW}!${RESET} ${WHITE}${text}${RESET}${msg ? ` ${DIM}— ${msg}${RESET}` : ""}`);
+        logged = true;
+      },
+      fail(msg) {
+        console.log(`${indent}${RED}✗${RESET} ${WHITE}${text}${RESET}${msg ? ` ${DIM}— ${msg}${RESET}` : ""}`);
+        logged = true;
+      },
+      _logged() { return logged; },
+    };
+  }
+  process.stdout.write(`${indent}${DIM2}⏳${RESET} ${DIM}${text}${RESET}`);
+  return {
+    ok(suffix) {
+      clearLine();
+      const tail = suffix ? ` ${DIM}${suffix}${RESET}` : "";
+      process.stdout.write(`${indent}${GREEN}✓${RESET} ${WHITE}${text}${RESET}${tail}\n`);
+    },
+    warn(msg) {
+      clearLine();
+      process.stdout.write(`${indent}${YELLOW}!${RESET} ${WHITE}${text}${RESET}${msg ? ` ${DIM}— ${msg}${RESET}` : ""}\n`);
+    },
+    fail(msg) {
+      clearLine();
+      process.stdout.write(`${indent}${RED}✗${RESET} ${WHITE}${text}${RESET}${msg ? ` ${DIM}— ${msg}${RESET}` : ""}\n`);
+    },
+  };
+}
+
+// spinner(text) — Braille spinner, ticks every 100ms.
+//   stop({ status: "ok"|"warn"|"fail", message? })
+// Non-TTY → prints "  → text" then "  ✓ text" / "  ! text" / "  ✗ text" on stop.
+function spinner(text) {
+  const indent = "  ";
+  if (!IS_TTY) {
+    return {
+      stop(result) {
+        const r = result || { status: "ok" };
+        if (r.status === "warn") {
+          console.log(`${indent}${YELLOW}!${RESET} ${WHITE}${text}${RESET}${r.message ? ` ${DIM}— ${r.message}${RESET}` : ""}`);
+        } else if (r.status === "fail" || r.status === "error") {
+          console.log(`${indent}${RED}✗${RESET} ${WHITE}${text}${RESET}${r.message ? ` ${DIM}— ${r.message}${RESET}` : ""}`);
+        } else {
+          console.log(`${indent}${GREEN}✓${RESET} ${WHITE}${text}${RESET}${r.message ? ` ${DIM}${r.message}${RESET}` : ""}`);
+        }
+      },
+    };
+  }
+  // Windows cmd.exe historically had spotty Braille rendering; modern Win10+
+  // Terminal handles it fine. The fallback path is the non-TTY branch above
+  // (covers piped logs); for interactive cmd.exe we accept that cosmetic risk
+  // — install still completes correctly even if frames render as boxes.
+  let i = 0;
+  hideCursor();
+  const render = () => {
+    clearLine();
+    process.stdout.write(`${indent}${TEAL}${SPINNER_FRAMES[i]}${RESET} ${DIM}${text}${RESET}`);
+    i = (i + 1) % SPINNER_FRAMES.length;
+  };
+  render();
+  const handle = setInterval(render, 100);
+  return {
+    stop(result) {
+      clearInterval(handle);
+      clearLine();
+      const r = result || { status: "ok" };
+      const tail = r.message ? ` ${DIM}${r.message}${RESET}` : "";
+      let glyph = `${GREEN}✓${RESET}`;
+      if (r.status === "warn") glyph = `${YELLOW}!${RESET}`;
+      if (r.status === "fail" || r.status === "error") glyph = `${RED}✗${RESET}`;
+      process.stdout.write(`${indent}${glyph} ${WHITE}${text}${RESET}${tail}\n`);
+      showCursor();
+    },
+  };
+}
+
+// progress(current, total, label) → renders a discrete progress bar line.
+// Used by install.js for batch-copy phases (skills, templates) where step()
+// would be too noisy. Caller updates by re-invoking; in TTY mode each call
+// overwrites the previous line.
+function progress(current, total, label) {
+  const indent = "  ";
+  const width = 14;
+  const filled = total > 0 ? Math.round((current / total) * width) : 0;
+  const bar = `${TEAL}${"█".repeat(filled)}${DIM2}${"░".repeat(width - filled)}${RESET}`;
+  const line = `${indent}${bar} ${DIM}${current}/${total}${RESET} ${DIM}${label || ""}${RESET}`;
+  if (IS_TTY) {
+    clearLine();
+    process.stdout.write(line);
+    if (current >= total) process.stdout.write("\n");
+  } else if (current >= total) {
+    // Non-TTY: only emit the final line, avoid spamming the log per-tick.
+    console.log(line);
+  }
+}
+
+// box({title, lines, color}) — boxed multi-line panel.
+// color is an ANSI escape string (default TEAL).
+function box(opts) {
+  const title = opts.title || "";
+  const lines = Array.isArray(opts.lines) ? opts.lines : [];
+  const color = opts.color || TEAL;
+  const indent = "  ";
+  const inner = Math.max(visibleLength(title), ...lines.map(visibleLength));
+  const width = Math.max(40, inner + 4);
+  const top = "─".repeat(width - 2);
+  console.log(`${indent}${color}┌${top}┐${RESET}`);
+  if (title) {
+    const padTitle = " ".repeat(Math.max(0, width - 4 - visibleLength(title)));
+    console.log(`${indent}${color}│${RESET} ${BOLD}${WHITE}${title}${RESET}${padTitle} ${color}│${RESET}`);
+    console.log(`${indent}${color}├${top}┤${RESET}`);
+  }
+  for (const line of lines) {
+    const pad = " ".repeat(Math.max(0, width - 4 - visibleLength(line)));
+    console.log(`${indent}${color}│${RESET} ${line}${pad} ${color}│${RESET}`);
+  }
+  console.log(`${indent}${color}└${top}┘${RESET}`);
+}
+
+// kv(label, value, options?) — left-padded label, value rendered in
+// options.color (default WHITE). options.labelWidth pads label to column N.
+function kv(label, value, options) {
+  const opts = options || {};
+  const valueColor = opts.color || WHITE;
+  const labelWidth = opts.labelWidth || 12;
+  const padded = pad(`${DIM}${label}${RESET}`, labelWidth + visibleLength(`${DIM}${RESET}`));
+  console.log(`  ${padded}${valueColor}${value}${RESET}`);
+}
+
+// divider(width?) — variable-width dim divider.
+function divider(width) {
+  const w = width || 48;
+  console.log(`  ${DIM2}${"━".repeat(w)}${RESET}`);
+}
+
+// section(title, count?) — section header with optional right-aligned count.
+function section(title, count) {
+  console.log("");
+  const right = (count !== undefined && count !== null && count !== "")
+    ? ` ${TEAL}${count}${RESET} ${DIM}✓${RESET}`
+    : "";
+  console.log(`  ${TEAL}▸${RESET} ${WHITE}${BOLD}${title}${RESET}${right}`);
+  console.log(`  ${DIM2}${"─".repeat(40)}${RESET}`);
+}
+
+// sectionClose(summary) — single-line summary after a section completes.
+function sectionClose(summary) {
+  console.log(`  ${DIM2}└─${RESET} ${DIM}${summary}${RESET}`);
+}
+
+module.exports = {
+  // Color constants — exported so install.js doesn't redefine them.
+  colors: { TEAL, TEAL_DIM, DIM, DIM2, GREEN, WHITE, YELLOW, RED, BLUE, RESET, BOLD },
+  IS_TTY,
+  // Live-progress primitives
+  step,
+  spinner,
+  progress,
+  box,
+  kv,
+  divider,
+  section,
+  sectionClose,
+  // Existing helpers (kept exposed for reuse)
+  pad,
+  visibleLength,
+};
+
 function cmdUpdate(current, latest) {
   if (!current || !latest) return;
   console.log("");
@@ -535,7 +739,10 @@ function cmdUpdate(current, latest) {
   console.log("");
 }
 
-// ─── Main ────────────────────────────────────────────────
+// ─── Main (CLI dispatch — only when executed directly, not when required) ─
+if (require.main !== module) {
+  return;
+}
 const [cmd, ...rest] = process.argv.slice(2);
 switch (cmd) {
   case "banner":

package/bin/slop-detect.mjs

@@ -186,6 +186,11 @@ const SKIP_DIRS = new Set([
   "node_modules", ".next", "dist", "build", ".git", ".turbo",
   "coverage", ".cache", "out", ".vercel", ".vscode", ".idea",
   ".planning", ".qa-screenshots",
+  // v5.1: skip test fixtures by convention. Fixtures used as regression
+  // targets (e.g. /qualia-polish-loop's broken.html) intentionally violate
+  // the rules slop-detect enforces; scanning them flags real fixture bugs
+  // as production slop.
+  "fixtures", "__fixtures__",
 ]);
 
 function* walk(dir) {

package/bin/state.js

@@ -735,6 +735,22 @@ function cmdTransition(opts) {
 function cmdInit(opts) {
   if (!opts.project) return output(fail("MISSING_ARG", "--project required"));
 
+  // v5.0: Throwaway-name guard. The insights report documents the user
+  // accidentally creating a project literally named "test-name-only" instead
+  // of the real client name. Names matching common scratch/test patterns get
+  // a 1-line confirmation step (bypass with --force).
+  if (!opts.force) {
+    const SUSPICIOUS = /^(test|tmp|temp|foo|bar|baz|scratch|demo|sample|untitled|new[\W_-]?project|example)(\b|[\W_-])/i;
+    if (SUSPICIOUS.test(opts.project)) {
+      return output(
+        fail(
+          "SUSPICIOUS_NAME",
+          `Project name '${opts.project}' looks temporary/test-like. If this is the real client project name, re-run with --force. Otherwise re-run with the actual project name.`
+        )
+      );
+    }
+  }
+
   // Refuse to clobber an active project unless --force.
   // Lifetime preservation runs lower in this fn — but current-phase fields
   // (phase, status, wave, tasks_done, tasks_total, gap_cycles) ARE wiped
@@ -1173,7 +1189,24 @@ function cmdCloseMilestone(opts) {
   t.milestone_name = readNextMilestoneNameFromJourney(t.milestone);
   t.last_updated = new Date().toISOString();
 
-  writeTracking(t);
+  // v5.0 — journal-protected write. STATE.md is intentionally NOT mutated here
+  // (the next /qualia-milestone step calls `state.js init --force` which fully
+  // rewrites STATE.md for the new milestone). The journal still snapshots
+  // tracking.json so a crash mid-write can be detected and recovered by the
+  // next session via recoverFromJournal().
+  const backupTracking = (() => {
+    try { return fs.readFileSync(TRACKING_FILE, "utf8"); } catch { return null; }
+  })();
+  try {
+    writeJournal(null, backupTracking);
+    writeTracking(t);
+    clearJournal();
+  } catch (e) {
+    // Restore tracking.json from backup if write failed mid-way.
+    try { if (backupTracking) atomicWrite(TRACKING_FILE, backupTracking); } catch {}
+    clearJournal();
+    return output(fail("WRITE_ERROR", `close-milestone write failed: ${e.message}. tracking.json restored from backup.`));
+  }
 
   _trace("close-milestone", "allow", {
     closed_milestone: closedMilestone,

package/docs/install-redesign-builder-prompt.md

@@ -0,0 +1,290 @@
+# Qualia Framework — Install Redesign (v5.1.0 candidate)
+## Builder Agent Prompt
+
+**Hand this entire file to a fresh Claude Code session.** Self-contained — no context from the originating session is needed. Same pattern as `docs/playwright-loop-builder-prompt.md` which produced v5.0's polish-loop work.
+
+---
+
+## What you are building
+
+A redesigned installer for the Qualia Framework that:
+
+1. **Asks the user where to install** — Claude Code (`~/.claude/`), OpenAI Codex (`~/.codex/`), or both — and adapts the install per target
+2. **Shows real-time visual progress** during the install — what file is being read, what's being copied, what's being configured — not silent then suddenly done
+3. **Has top-notch cosmetics** throughout — every line of output is intentional and beautiful
+
+The current installer (`bin/install.js`, ~830 lines) is functional but minimal. It copies files in batches and prints section headers ("Skills", "Templates", "Hooks") with terse `✓ {name}` lines. Fawzi wants the install to FEEL like a polished product — like the framework is announcing itself with care, not just dumping files.
+
+## Why this matters
+
+- **First impression is the install.** Every Qualia user (Fawzi, Hasan, Moayad, Rama, Sally, future hires) experiences the framework first through `npx qualia-framework install`. A boring install signals a boring framework.
+- **Cross-tool reach.** v5.0.0 already produces `AGENTS.md` (the cross-vendor open standard adopted by Codex, Cursor, Aider, Continue). Codex users could already use the framework today — they just don't know it because the installer only writes to `~/.claude/`. Multi-target makes that explicit.
+- **Visual feedback is trust.** When the installer is silent for 5 seconds while it copies 32 skills + 12 hooks + 24 templates, the user wonders if it hung. Live progress makes the framework feel alive.
+
+## The repository you're working in
+
+`/home/qualia-new/qualia-framework` — the Qualia Framework npm package, currently at v5.0.0 on branch `feat/env-empty-guard` (locally, not yet pushed). 274 tests pass. v5.0.0 release is queued for tomorrow morning publish to npm.
+
+**Your work goes ON TOP of v5.0.0, as v5.1.0.** You'll bump version, add CHANGELOG entry, modify `bin/install.js`, possibly add `bin/install-cosmetics.js` helper, update tests.
+
+## Files to study before writing code
+
+1. `/home/qualia-new/qualia-framework/bin/install.js` — the current installer (~830 lines). Read it fully to understand the install phases (cleanup → CLAUDE.md/AGENTS.md → skills → agents → rules → hooks → settings.json → MCP → templates → knowledge layer → bin scripts → ERP config → final banner).
+2. `/home/qualia-new/qualia-framework/bin/qualia-ui.js` — the existing cosmetics helper (banners, dividers, end-cards, status). Reuse and extend; don't duplicate.
+3. `/home/qualia-new/qualia-framework/CLAUDE.md` and `AGENTS.md` — to understand what gets templated with `{{ROLE}}` for each install target
+4. `/home/qualia-new/qualia-framework/CHANGELOG.md` v5.0.0 entry — to match the writing style for v5.1.0
+5. `/home/qualia-new/qualia-framework/tests/bin.test.sh` — the install test patterns (lines ~440 onward have the install assertions you'll mirror)
+
+## The 3 deliverables
+
+### Deliverable 1 — Multi-target install (Claude Code / Codex / Both)
+
+**Behavior:**
+
+After the user enters their team code (existing flow), the installer asks:
+
+```
+  Where would you like to install Qualia?
+
+  [1] Claude Code only       (recommended — full feature set)
+  [2] OpenAI Codex only      (AGENTS.md + project-level rules)
+  [3] Both                   (max compatibility)
+
+  Choice [1]:
+```
+
+Default is `1` (Claude Code only) for backward-compat. The user types `1`/`2`/`3` and Enter.
+
+**Per-target install paths:**
+
+| Target | Directory | What gets installed |
+|---|---|---|
+| Claude Code | `~/.claude/` | Everything as today (skills/, agents/, hooks/, rules/, qualia-templates/, knowledge/, settings.json, CLAUDE.md, AGENTS.md, bin/, .qualia-config.json) |
+| Codex | `~/.codex/` (or wherever Codex config lives — research this) | A subset that Codex actually uses: `AGENTS.md` (the framework conventions), `instructions.md` if Codex uses one, possibly mirrored skills/ and templates/ if Codex's runtime supports skills (research this — it might not; in that case skip those) |
+| Both | both directories | Run the Claude Code install first, then the Codex install |
+
+**Critical research step you MUST do FIRST:**
+
+Use `WebFetch` or `Bash` to research Codex CLI's actual configuration layout:
+
+```bash
+# Check if user has codex installed
+which codex 2>/dev/null
+codex --version 2>/dev/null
+
+# Look for documented config paths
+ls ~/.codex/ 2>/dev/null
+ls ~/.config/codex/ 2>/dev/null
+```
+
+Search for: "OpenAI Codex CLI configuration directory", "Codex AGENTS.md", "Codex skills system" (if any).
+
+If Codex CLI is too thin to support a meaningful framework install (e.g., it only reads AGENTS.md and that's it), say so explicitly in your output — don't pretend to install more than makes sense. Write a clear note in the CHANGELOG entry: "Codex install writes AGENTS.md only — Codex's runtime does not currently support skills/hooks/agents on disk."
+
+**If Codex is not installed locally:**
+
+Don't crash. Show a soft warning:
+
+```
+⚠ Codex CLI not detected on this system.
+  Installing AGENTS.md to ~/.codex/AGENTS.md anyway — Codex will pick it up
+  when you install via `npm install -g @openai/codex`.
+```
+
+Then proceed with the Codex-side install (just the file writes).
+
+### Deliverable 2 — Real-time visual progress
+
+**Current installer:** prints section headers, then a batch of `✓ {name}` lines all at once when each section completes. Looks like nothing → nothing → blast of green checkmarks.
+
+**Redesigned installer:** every meaningful operation prints a "doing" line before, then updates to "done" after. Like a live activity log.
+
+**Pattern (use Unicode box-drawing for the progression):**
+
+```
+  ▸ Skills (32)
+  ─────────────────────────────────────────
+    ⏳ Reading skills/ from framework...
+    ✓ Reading skills/ from framework
+    ⏳ Copying qualia-build...
+    ✓ qualia-build (3 files)
+    ⏳ Copying qualia-discuss...
+    ✓ qualia-discuss (1 file)
+    ⏳ Copying qualia-issues...
+    ✓ qualia-issues (1 file)
+    ...
+    ✓ Skills installed (32 total)
+```
+
+Use ANSI escape sequences to OVERWRITE the `⏳` line with the `✓` line in place (cursor-up + clear-line) — so the output reads as a steadily-completing list, not a doubled set of lines.
+
+**For long ops (template recursive copy, knowledge layer init, settings.json merge):**
+
+Show a spinner that ticks every 100ms:
+
+```
+    ⠋ Merging settings.json (preserving 14 user keys)
+```
+
+Implement as a tiny helper `startSpinner(text)` returning `stop({ status: "ok" | "warn" | "error", message?: string })`. Don't pull in `ora` or any external dep — write ~30 lines of vanilla Node using `process.stdout.write` + an interval.
+
+**For each skill/agent/hook/rule/template copied:**
+
+The current `ok({name})` print becomes a 2-line lifecycle:
+
+1. Before copy: `⏳ {name}` (dim, with a working glyph)
+2. After copy: `✓ {name}` (green, replacing the line above)
+
+For very fast ops (single file, < 50ms) you can skip the "doing" state and go straight to ✓.
+
+**Enhancements to existing `bin/qualia-ui.js`:**
+
+Add these new helpers and export them:
+
+- `spinner(text)` → `{ stop(result) }` — animated spinner with cursor-hide/show
+- `step(text)` → returns a step-handle with `.ok(suffix?)`, `.warn(msg)`, `.fail(msg)` that overwrite the line
+- `progress(current, total, label)` — render a bar like `[████████░░] 8/10 — Skills`
+- `divider(width)` — variable-width dim divider
+- `box({title, lines, color})` — boxed section like the welcome banner
+- `kv(label, value, options?)` — left-padded label, right-aligned value, dim/highlight options
+
+Preserve all existing `qualia-ui.js` exports — additive only.
+
+### Deliverable 3 — Top-notch cosmetics throughout
+
+The full install output, end-to-end, should feel like a single intentional document. Specific things to fix:
+
+**The current install banner** (the welcome card at the top with `⬢ Q U A L I A`) is good. Keep its bones, but consider:
+- Subtle 2-color gradient on the title (teal → cyan) using truecolor escape
+- A breath of vertical space (one blank line above and below)
+- Version + framework subtitle aligned right of the hex glyph
+
+**Section separators** between phases (Skills, Agents, Rules, Hooks, Templates, etc.):
+- Currently: bold teal triangle + section name + dim divider
+- Upgrade: add a 2-letter status indicator at the right margin showing pass count, like `▸ Skills                    32 ✓`
+- After each section completes, show a one-line "section summary" with the count and elapsed time: `  └─ 32 skills · 0.3s`
+
+**Final summary card** (the "INSTALLED" banner at the end):
+- Currently: name + role + version + 7 metric kv lines + Quick Start
+- Upgrade: add a "Targets" row showing where you installed (`Claude Code · Codex · Both`)
+- Add a "Time" row showing total install duration
+- Add a contextual "First command to try" line based on whether the user has a `.planning/` already (suggest `/qualia` if they do, `/qualia-new` if not)
+
+**Color palette discipline:**
+- Match the existing OKLCH-tinted neutrals in `bin/qualia-ui.js`
+- Don't introduce new colors — extend the existing teal/green/dim/white system
+- Errors stay red (#ef4444), warns stay yellow (#eab308) — don't change these (muscle memory)
+
+**Glyph rules:**
+- ⬢ = brand mark, only for the welcome banner and final card
+- ▸ = section header
+- ✓ = success
+- ⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏ = spinner frames (Braille pattern dots)
+- ⏳ = pending/in-flight
+- ⚠ = warning
+- ✗ = error
+- └─ = section close
+- · = inline separator
+
+Don't introduce other glyphs without strong reason.
+
+## Hard constraints (non-negotiable)
+
+1. **Backward compatibility.** A user typing only their team code with no target choice (legacy stdin pipe `echo "QS-FAWZI-01" | npx qualia-framework install`) MUST still work — default to Claude Code only. Don't break the existing `bin.test.sh` install assertions.
+
+2. **No new external dependencies.** No `ora`, no `chalk`, no `ink`. Vanilla Node + ANSI escapes. The current installer is dependency-free; preserve that.
+
+3. **Cross-platform (Windows + macOS + Linux).** ANSI escapes work on modern Windows 10+ but verify the spinner doesn't break on `cmd.exe`. If `process.stdout.isTTY` is false (piped install), degrade gracefully — print plain `→ {name}` and `✓ {name}` lines instead of overwriting.
+
+4. **Atomic writes for new target paths.** When installing to `~/.codex/`, follow the same atomic-write (tmp + rename) pattern that v5.0 added for `settings.json` and CLAUDE.md.
+
+5. **Backups before overwrite** — same as v5.0's CLAUDE.md/settings.json discipline. If `~/.codex/AGENTS.md` exists with a different content hash than what we'd write, back it up to `~/.codex/AGENTS.md.bak.{ISO-timestamp}` before overwriting.
+
+6. **No surprise side effects.** Installing to Codex doesn't auto-install Codex CLI itself. If it's not present, write the files and tell the user to install Codex separately.
+
+7. **Slop-detect clean.** Run `node bin/slop-detect.mjs` on every modified `.md` file. The CHANGELOG and any new docs you write must pass.
+
+8. **Tests pass.** All 274 existing tests must continue to pass. Add new tests for: target selection (1/2/3 input), Codex install path creation, AGENTS.md backup-before-overwrite, spinner degradation when non-TTY, multi-target ("Both") flow.
+
+## Deliverables (the DONE definition)
+
+Return DONE only when all of these are true:
+
+1. ✅ `bin/install.js` modified to ask the install-target question after the team code prompt
+2. ✅ Codex-target install actually writes to `~/.codex/` (or whatever the research found is correct)
+3. ✅ All file copies have a "before/after" 2-line lifecycle (or single-line for sub-50ms ops)
+4. ✅ `bin/qualia-ui.js` extended with `spinner()`, `step()`, `progress()`, `box()`, `kv()` helpers
+5. ✅ Final summary card shows install targets, total time, and contextual first-command suggestion
+6. ✅ TTY-degraded mode works (test: `echo QS-FAWZI-01 | node bin/install.js > /tmp/log.txt`; the log should be readable, no orphaned escape codes)
+7. ✅ Backups for existing AGENTS.md / instructions.md in Codex target dir
+8. ✅ All 274 v5.0 tests still pass + at least 5 new tests for v5.1 multi-target
+9. ✅ `node bin/slop-detect.mjs` clean on all modified .md files
+10. ✅ `package.json` bumped to 5.1.0
+11. ✅ CHANGELOG.md has a v5.1.0 entry with the same writing style as the v5.0.0 entry, including:
+    - The "why this matters" framing (first impression, cross-tool reach, visual trust)
+    - The 3 deliverables
+    - The Codex install scope (whatever the research determined)
+    - Honest caveats (what doesn't work, what's deferred)
+12. ✅ `docs/install-redesign-pilot.md` documenting:
+    - The full install output captured for each target choice (1, 2, 3)
+    - Screenshots or terminal-recording converted to ANSI text
+    - Timing measurements
+    - Any TTY-degradation issues found
+
+## Self-test scenarios (run all 3 before declaring DONE)
+
+**Scenario 1 — Claude Code only.**
+```bash
+TMP=$(mktemp -d)
+echo -e "QS-FAWZI-01\n1\n" | HOME="$TMP" node bin/install.js > "$TMP/log.txt" 2>&1
+```
+- Verify: `~/.claude/` populated as today. `~/.codex/` does not exist or is empty.
+- Verify: `$TMP/log.txt` shows the new visual progress (every section has live updates).
+- Verify: total install time is ≤ 2× the current install time (live updates shouldn't more than double cost).
+
+**Scenario 2 — Codex only.**
+```bash
+TMP=$(mktemp -d)
+echo -e "QS-FAWZI-01\n2\n" | HOME="$TMP" node bin/install.js > "$TMP/log.txt" 2>&1
+```
+- Verify: `~/.codex/AGENTS.md` exists with `Role: OWNER` substituted.
+- Verify: `~/.claude/` is NOT populated (we picked target 2 only).
+- Verify: log shows "Codex CLI not detected — file written anyway" if `which codex` fails.
+
+**Scenario 3 — Both.**
+```bash
+TMP=$(mktemp -d)
+echo -e "QS-FAWZI-01\n3\n" | HOME="$TMP" node bin/install.js > "$TMP/log.txt" 2>&1
+```
+- Verify: both `~/.claude/` and `~/.codex/` populated correctly.
+- Verify: final summary card shows "Targets: Claude Code · Codex".
+
+## Things you MUST NOT do
+
+- Don't change the team-code prompt itself (existing format works, has tests, don't break them).
+- Don't add interactive yes/no prompts beyond the target-selection question — the install should still complete via stdin pipe with no extra input needed.
+- Don't change `~/.claude/` install behavior beyond cosmetics. The semantic install logic (which files go where) stays exactly as v5.0.
+- Don't wire Codex to any external API or auto-install. File copies only.
+- Don't bump major version (still 5.x). This is a minor (5.1.0).
+- Don't break the ERP API key save/load flow — `~/.claude/.erp-api-key` stays where it is.
+- Don't drop the EXPERIMENTAL Playwright caveat in the v5.0.0 CHANGELOG — preserve it as historical context.
+
+## Reference: where v5.0's similar work happened
+
+Look at how the polish-loop builder agent (commit `907312c`) handled a similar scope — building a flagship feature with self-tests, CHANGELOG, install assertions. Match its discipline:
+- Per-iteration commits during pilot scenarios (`qpl-N:` prefix style — yours could be `install-redesign-N:`)
+- Honest caveats in CHANGELOG (don't oversell)
+- Pilot results doc with concrete measurements
+- Trust-boundary comment in any new agent role file (none expected here, but if you create one, copy the pattern from `agents/builder.md` lines 11-17)
+
+## When you encounter unknowns
+
+- **Codex config layout** — the most likely unknown. If web search + local probing don't give a clear answer, write the simplest version (just `~/.codex/AGENTS.md`) and document it explicitly: "Codex install scope: AGENTS.md only. If Codex's runtime later supports skills/hooks on disk, the framework can extend this."
+- **TTY degradation edge cases** — if cmd.exe on Windows has issues, document and gate the spinner behind `process.platform !== "win32"` for the spinner specifically. The 2-line copy/✓ pattern should work everywhere.
+- **Existing install test breakage** — if you can't avoid breaking a test, the test was overspecified. Update the test, but document WHY in the commit message.
+
+## One last thing
+
+Fawzi (the framework owner, OWNER role) will read your output as the FIRST install he runs. He's tired tonight and trusting you to deliver. Honest reporting beats good-news theater. If something doesn't work cleanly, mark it experimental and say so — same discipline as the polish-loop EXPERIMENTAL Playwright caveat.
+
+When you finish, write your DONE report at `docs/install-redesign-pilot.md` (file already mentioned above) and return a tight summary: targets working, lines of code added/changed, test count, slop-detect status, any BLOCKED items.