qualia-framework 5.4.0 → 5.8.0

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

@@ -1,290 +0,0 @@
-# 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.

package/docs/install-redesign-pilot.md

@@ -1,234 +0,0 @@
-# Install Redesign — Pilot Results (v5.1.0)
-
-Captured output and timing measurements for the three install-target
-scenarios, run on Linux 6.19 / Node 22 / non-TTY (piped stdin).
-
-All three scenarios pass cleanly. Total installer wall-clock cost
-remains under 200ms; the live-progress lifecycle adds negligible
-overhead because most file copies finish under 50ms (sub-50ms ops skip
-the "doing" state and go straight to `✓`).
-
-## Method
-
-```bash
-TMP=$(mktemp -d)
-START=$(date +%s%N)
-printf 'QS-FAWZI-01\n<CHOICE>\n' | HOME="$TMP" node bin/install.js > log.txt 2>&1
-END=$(date +%s%N)
-echo "wall-clock: $(( (END-START)/1000000 ))ms"
-```
-
-ANSI codes stripped from the captured logs below for readability. The
-real install renders the same lines with OKLCH-tinted teal / dim white
-/ green / yellow per `bin/qualia-ui.js`.
-
-## Scenario 1 — Claude Code only (target=1, the default)
-
-**Wall-clock:** 99ms · **Lines:** 202 · **Result:** `~/.claude/` populated
-(11 entries: agents, bin, CLAUDE.md, hooks, knowledge, qualia-guide.md,
-qualia-references, qualia-templates, rules, settings.json, skills),
-`~/.codex/` not created.
-
-```
-  ⬢  Q U A L I A
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Framework v5.1.0  ·  Qualia Solutions
-  Plan → Build → Verify → Ship
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  Enter install code: QS-FAWZI-01
-
-  ✓ Welcome, Fawzi Goussous
-    Role: OWNER
-
-  Where would you like to install Qualia?
-
-    [1] Claude Code only     — recommended, full feature set
-    [2] OpenAI Codex only    — AGENTS.md (Codex's open standard)
-    [3] Both                 — max compatibility
-
-  Choice [1]: 1
-
-    Target: Claude Code
-
-  ▸ Skills
-  ────────────────────────────────────────
-  ✓ qualia
-  ✓ qualia-build
-  ✓ qualia-debug
-  ... (33 skills total) ...
-  ✓ zoho-workflow
-  └─ 33 skills · 4ms
-
-  ▸ Agents
-  ────────────────────────────────────────
-  ✓ builder.md
-  ... (9 agents total) ...
-  ✓ visual-evaluator.md
-  └─ 9 agents · 0ms
-
-  ▸ Rules
-  ────────────────────────────────────────
-  ... (10 rules) ...
-  └─ 10 rules · 0ms
-
-  ▸ Hooks                    (12 wired)
-  ▸ Templates                (16 entries, recursive)
-  ▸ Knowledge layer          (initialized on first install)
-  ▸ References               (methodology docs)
-  ▸ Configuration            (CLAUDE.md role substituted)
-  ▸ Scripts                  (state.js, qualia-ui.js, etc.)
-  ▸ Knowledge Base           (learned-patterns / common-fixes / client-prefs)
-  ▸ ERP Integration          (key opt-in)
-
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  ⬢  INSTALLED
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  Fawzi Goussous  ·  OWNER  ·  v5.1.0
-
-  Targets   Claude Code
-  Time      99ms
-
-  Skills    33     Agents  9     Hooks   12
-  Rules     10     Scripts 7     Templates 16
-
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Quick Start
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  1. Restart Claude Code (loads new settings)
-  2. cd into any project and run claude
-  3. Try /qualia-new — kickoff a new project
-
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Welcome to the future with Qualia.
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## Scenario 2 — Codex only (target=2)
-
-**Wall-clock:** 183ms (extra cost is the `which codex` probe via
-`spawnSync`) · **Lines:** 56 · **Result:** `~/.codex/AGENTS.md` written
-with `Role: OWNER` substituted, `~/.claude/` not touched.
-
-```
-  ⬢  Q U A L I A
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Framework v5.1.0  ·  Qualia Solutions
-  ...
-
-  Choice [1]: 2
-
-    Target: Codex
-
-  ▸ Codex
-  ────────────────────────────────────────
-  ✓ AGENTS.md (configured as OWNER)
-  └─ Codex install scope: AGENTS.md only — Codex's runtime does not currently
-     consume the framework's skills/hooks/agents on disk. AGENTS.md carries
-     the rules; commands route through Claude Code.
-
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  ⬢  INSTALLED
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  Fawzi Goussous  ·  OWNER  ·  v5.1.0
-
-  Targets   Codex
-  Time      183ms
-
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Quick Start
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  1. Open Codex in any project
-  2. Codex picks up ~/.codex/AGENTS.md automatically
-  3. Ask Codex about Qualia rules — they're in AGENTS.md
-```
-
-If `which codex` fails (CLI not installed), the section prints a soft
-warning before the file write; the AGENTS.md is still written so the
-user is set up for when they install Codex via
-`npm install -g @openai/codex`.
-
-## Scenario 3 — Both (target=3)
-
-**Wall-clock:** 193ms · **Lines:** 209 · **Result:** Both `~/.claude/`
-and `~/.codex/AGENTS.md` populated. Final summary shows
-`Targets   Claude Code · Codex`.
-
-The Claude install runs first (identical to Scenario 1), then the Codex
-section appends:
-
-```
-  ▸ Codex
-  ────────────────────────────────────────
-  ✓ AGENTS.md (configured as OWNER)
-  └─ Codex install scope: AGENTS.md only — ...
-```
-
-Final card:
-
-```
-  Targets   Claude Code · Codex
-  Time      193ms
-```
-
-## Backward compatibility — legacy single-line piped install
-
-```bash
-echo "QS-FAWZI-01" | npx qualia-framework install
-```
-
-still works untouched. The target prompt sees EOF on stdin, normalizes
-to `1` (Claude only). Confirmed by test 121 in `tests/bin.test.sh`.
-
-## TTY-degradation verification
-
-In non-TTY mode (output piped to a file), the live-progress primitives
-in `bin/qualia-ui.js` skip:
-
-- The Braille spinner (`spinner()`) — prints a one-shot `→ text` /
-  `✓ text` instead of an animated frame loop.
-- The cursor-up / clear-line overwrites (`step()`) — skips the
-  `⏳ doing` line and prints the result line directly when finalized.
-- Cursor hide/show escapes — never emitted.
-
-Verified by test 124: `grep` for bare `\r`, `?25` (hide-cursor), and
-`\[2K` (clear-line) on a piped install log returns nothing.
-
-## Timing budget
-
-| Scenario | Wall-clock | Lines emitted | Notes |
-|----------|------------|---------------|-------|
-| 1 — Claude only | 99ms | 202 | Baseline |
-| 2 — Codex only | 183ms | 56 | + `which codex` probe (~80ms on Node 22 / Linux) |
-| 3 — Both | 193ms | 209 | Claude + Codex back-to-back |
-
-The spec budget was "≤ 2× the current install time." v5.1 stays comfortably
-under it — the live updates and section timing add only the cost of the
-extra console.log calls (negligible) and a couple of `Date.now()` calls
-per section.
-
-## Known limitations / deferred to v5.2
-
-- **Codex skills/hooks/agents not mirrored.** Codex uses `.toml` agent
-  format and a different hook schema. AGENTS.md is the rule layer they
-  share; the rest stays Claude-only until Codex's on-disk surface
-  stabilizes for cross-mapping.
-- **Spinner cosmetics on `cmd.exe`.** Braille frames may render as
-  boxes on legacy `cmd.exe`. Modern Windows Terminal handles them. The
-  install completes correctly either way; this is purely cosmetic.
-- **`Time` row precision.** Sub-second installs show `Xms`; ≥1s installs
-  show `X.Ys`. Either format is grep-friendly (regex
-  `Time *[0-9]+(\.[0-9]+)?(ms|s)`).
-
-## What this enables
-
-A user piping `npx qualia-framework install` from a fresh box now has
-a one-keystroke choice between Claude-only (the recommended default)
-and shipping Qualia's rule layer to OpenAI Codex via the open AGENTS.md
-standard. The live-progress redesign means even a 5-second install
-feels like an intentional product, not a hung process. First impression
-matches the rest of the framework's polish.

package/docs/instruction-budget-audit.md

@@ -1,113 +0,0 @@
-# Instruction-Budget Audit
-
-> **Date:** 2026-05-06
-> **Trigger:** Re-study of *Skills and Strategies for Real Engineering with Claude Code* (Matt Pocock) and *Context and Tools: Mastering the AI Engineering Lifecycle* (Patrick Debois, Karpathy, Pocock, Mario Zechner).
-> **Question:** Does Qualia Framework actually honor the "load on demand, not always" promise written in `CLAUDE.md`?
-
-## Finding 1 — `~/.claude/rules/*.md` is loaded eagerly by Claude Code
-
-Claude Code auto-discovers and injects every Markdown file under `~/.claude/rules/` into the system prompt of every session. This is **harness behavior**, not framework behavior — there is no `@-import` declaration in `~/.claude/CLAUDE.md`, yet the rules appear in the system reminder verbatim.
-
-**Measured cost (2026-05-06 install):**
-
-| File | Lines | Notes |
-|---|---|---|
-| `design-reference.md` | 179 | Motion specs, WCAG checklist, breakpoints |
-| `design-rubric.md` | 157 | 8-dimension verifier rubric |
-| `design-laws.md` | 148 | OKLCH, color strategy, typography |
-| `frontend.md` | 118 | Brand standards |
-| `design-brand.md` | 114 | Brand register |
-| `design-product.md` | 114 | Product register |
-| `grounding.md` | 114 | Severity rubric, citation format |
-| `infrastructure.md` | 87 | Stack, MCP servers, CLIs |
-| `deployment.md` | 30 | Post-deploy checklist |
-| `speed.md` | 23 | Speed rules |
-| `context7.md` | 14 | Context7 trigger rule |
-| `security.md` | 12 | RLS, auth, secrets |
-| **Total** | **1110** | |
-
-At ~4 chars/line average that is **~28 KB injected on every session**, regardless of whether the user is touching frontend, backend, infra, or nothing.
-
-The rule files themselves are written under the assumption that a skill or agent will read them on demand (e.g., `agents/builder.md` line 139 says *"Security, design, and performance rules auto-load from `rules/*.md` based on the files you touch"*) — which is correct **inside subagent fork prompts** but **wrong for the user's main session**, where the harness loads them all preemptively.
-
-## Finding 2 — `CLAUDE.md` template is already disciplined
-
-The framework `CLAUDE.md` template is 24 lines and ends with the right note:
-
-> *"this file stays under 25 lines. Steering rules go into discoverable skills, not into the global system prompt. CLI preferences go into hooks. Stack/architecture details are trivially discoverable in package.json/config."*
-
-This part is healthy. The leak is in `rules/`, not `CLAUDE.md`.
-
-## Finding 3 — Skill dedup hypothesis was wrong
-
-A first pass suggested deleting `qualia-quick`, `qualia-road`, `qualia-help`, `qualia-handoff` as duplicates. Cross-reference check showed:
-
-- `qualia-quick` is referenced from `bin/install.js`, `hooks/session-start.js`, `templates/help.html`, `README.md`, `guide.md`, `skills/qualia-prd/SKILL.md`, `skills/qualia-task/SKILL.md` — load-bearing.
-- `qualia-road` is referenced from `CLAUDE.md`, `AGENTS.md`, `README.md`, `guide.md`, `skills/qualia-help/SKILL.md` description — load-bearing.
-- `qualia-help` opens an HTML reference — distinct purpose from `qualia-road` (terminal map).
-- `qualia-handoff` is the final delivery skill, referenced from `bin/state.js:490`, ship/verify, journey-demo — load-bearing.
-
-**Each skill has a job.** No deletion is safe in this PR. The right fix is *boundary clarity in descriptions* (so the LLM picks correctly), not deletion.
-
-## Recommended follow-ups (deferred to separate PRs)
-
-### R1 — Move design rules to a lazy folder *(big, risky)*
-
-```
-~/.claude/rules/                           # always-loaded (HARNESS)
-  ├── grounding.md       (114)             # KEEP — universal
-  ├── security.md         (12)             # KEEP — universal
-  ├── speed.md            (23)             # KEEP — universal
-  ├── context7.md         (14)             # KEEP — universal
-  └── infrastructure.md   (87)             # KEEP — universal stack
-                                            #   total: ~250 lines
-
-~/.claude/qualia-design/                    # explicit-load only
-  ├── design-laws.md     (148)
-  ├── design-brand.md    (114)
-  ├── design-product.md  (114)
-  ├── design-reference.md (179)
-  ├── design-rubric.md   (157)
-  ├── frontend.md        (118)
-  └── deployment.md       (30)             # post-deploy checklist; loaded by /qualia-ship
-                                            #   total: 860 lines, NOT auto-loaded
-```
-
-Skills/agents that need design rules `Read` them on demand (already the pattern in `agents/builder.md` and `agents/verifier.md`). The save: **~28 KB → ~6 KB injected per session, ~22 KB recovered.**
-
-Required changes:
-1. `bin/install.js` — install design rules to `~/.claude/qualia-design/` instead of `~/.claude/rules/`.
-2. Every skill/agent reference path `rules/design-*.md` → `qualia-design/design-*.md` or use `~/.claude/qualia-design/design-*.md` absolute.
-3. Update `hooks/session-start.js` `CRITICAL_FILES` health check.
-4. Migration step in `bin/install.js` to clean up old `~/.claude/rules/design-*.md` for existing installs.
-
-**Effort:** M-L. **Impact:** ~80% reduction in always-loaded substrate.
-
-### R2 — Skill description sharpening *(small, safe)*
-
-`qualia-quick` and `qualia-task` overlap in description. Tighten:
-- `qualia-quick`: "≤1 hour, 1 file, no plan, no spawn — just do it."
-- `qualia-task`: "1–3 hours, 1–5 files, fresh builder spawn, atomic commit, no phase plan."
-
-`qualia-road` and `qualia-help` overlap. Clarify:
-- `qualia-road`: "Terminal-rendered workflow map. Use over SSH or when no browser."
-- `qualia-help`: "Browser-rendered HTML reference. Default."
-
-### R3 — Per-skill versioning + eval harness *(carry-over from notebook 1, source 6 — Debois)*
-
-Each skill carries its own `version:` in frontmatter and a `tests/skills/{skill-name}.spec.sh` fixture. CI runs the fixture against the skill spec. Catches silent skill rot when CC behavior changes underneath.
-
-### R4 — MCP tier-list rule in `rules/speed.md` *(carry-over from notebook 1, source 5 — CLI vs MCP)*
-
-Codify the "CLI-first" principle. Reference the existing `/supabase` skill replacing 32 supabase MCP tools as the canonical example.
-
-## What changed in *this* PR
-
-This PR ships the changes that don't require user-state migration:
-
-1. **Citation enforcement preamble** in `agents/builder.md` and `agents/verifier.md` — closes notebook 2, source #9 (*Never Trust an LLM*). Builders and verifiers must cite `file:line — "quoted"` or write `INSUFFICIENT EVIDENCE`. No hedging, no narration.
-2. **`rules/architecture.md`** — net-new, deep-modules + scout-for-shallow-code from notebook 2 sources #5 + #12 (Pocock de-slop, codebase-not-ready-for-AI). Skill `/qualia-optimize --deepen` already exists; this rule formalizes the architectural taste it scouts for.
-3. **README warning** — "Never run Claude's `/init`" — direct users to `/qualia-new` or `/qualia-map`. Per notebook 2 sources #3 + #8.
-4. **This audit document** — anchors the deferred follow-ups so they don't get lost.
-
-The relocation in R1 is the biggest single win available; it is intentionally deferred so this PR stays small and reversible.