qualia-framework 6.2.9 → 6.3.0

package/skills/{qualia-vibe/scripts/tokens.mjs → qualia-polish/scripts/vibe-tokens.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * tokens.mjs — read/write design tokens for /qualia-vibe.
+ * tokens.mjs — read/write design tokens for /qualia-polish --vibe.
  *
  * Commands:
  *   tokens.mjs sync --design .planning/DESIGN.md [--write]
@@ -36,13 +36,13 @@ function hasFlag(name) {
 const CMD = argv[2];
 
 if (!CMD || CMD === "--help" || CMD === "-h") {
-  console.log(`tokens.mjs — design-token utility for /qualia-vibe
+  console.log(`tokens.mjs — design-token utility for /qualia-polish --vibe
 
 Usage:
   tokens.mjs sync --design <path> [--write]
   tokens.mjs propose-variants --product <path> --design <path> --count <N>
 
-See skills/qualia-vibe/SKILL.md.
+See skills/qualia-polish/SKILL.md.
 `);
   exit(0);
 }
@@ -268,7 +268,7 @@ function cmdSync() {
       ``,
       `## §sync — auto-synced from code (${stamp})`,
       ``,
-      `<!-- Generated by /qualia-vibe --sync --write. Reflects values actually present in code at sync time. -->`,
+      `<!-- Generated by /qualia-polish --vibe --sync --write. Reflects values actually present in code at sync time. -->`,
       ``,
       "```css",
       `:root {`,
@@ -307,7 +307,7 @@ function cmdProposeVariants() {
 
   // Emit a structured scaffold the LLM uses to generate variants.
   const scaffold = {
-    instruction: `Generate exactly ${count} aesthetic-direction variants for /qualia-vibe --variants. Each variant must be opinionated and concrete — no "modern minimal" hedging. Variants must be meaningfully different from each other AND from the current direction.`,
+    instruction: `Generate exactly ${count} aesthetic-direction variants for /qualia-polish --vibe --variants. Each variant must be opinionated and concrete — no "modern minimal" hedging. Variants must be meaningfully different from each other AND from the current direction.`,
     context: {
       product_md: product.slice(0, 4000),
       current_direction_lines: design
@@ -323,7 +323,7 @@ function cmdProposeVariants() {
       "No purple-blue gradients.",
       "No bounce/elastic easing.",
       `Respect anti-references from PRODUCT.md if present.`,
-      "Each variant should be commit-able as-is — concrete enough that /qualia-vibe can apply it without further questions.",
+      "Each variant should be commit-able as-is — concrete enough that /qualia-polish --vibe can apply it without further questions.",
     ],
   };
 

package/skills/qualia-postmortem/SKILL.md

@@ -53,9 +53,9 @@ or applies manually.
 ### 1. Load the failure
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner postmortem 2>/dev/null || true
+node ${QUALIA_BIN}/qualia-ui.js banner postmortem 2>/dev/null || true
 
-PHASE="${PHASE:-$(node ~/.claude/bin/state.js check 2>/dev/null | node -e 'let s=""; process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.parse(s).phase)}catch{console.log("")}})')}"
+PHASE="${PHASE:-$(node ${QUALIA_BIN}/state.js check 2>/dev/null | node -e 'let s=""; process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.parse(s).phase)}catch{console.log("")}})')}"
 [ -z "$PHASE" ] && { echo "QUALIA: Could not resolve current phase. Pass --phase N explicitly."; exit 1; }
 
 VERIFY_FILE=".planning/phase-${PHASE}-verification.md"
@@ -76,13 +76,13 @@ match a finding to the file most likely responsible:
 
 ```bash
 # Agent prompts (planner, builder, plan-checker, verifier, etc.)
-ls ~/.claude/agents/
+ls ${QUALIA_AGENTS}/
 # Skill descriptions (qualia-plan, qualia-build, qualia-verify, etc.)
-ls ~/.claude/skills/
+ls ${QUALIA_SKILLS}/
 # Project rules + grounding
-ls ~/.claude/rules/
+ls ${QUALIA_RULES}/
 # Already-curated knowledge
-node ~/.claude/bin/knowledge.js
+node ${QUALIA_BIN}/knowledge.js
 ```
 
 You don't read all of them — you read the ones whose job description
@@ -163,7 +163,7 @@ the framework's own type/test gates (`node --test tests/runner.js` if you
 modified anything in `bin/`, `agents/`, or `rules/`) to confirm no
 regression.
 
-If a proposed delta is to a `~/.claude/agents/X.md` file (the installed
+If a proposed delta is to a `${QUALIA_AGENTS}/X.md` file (the installed
 copy), edit that copy directly — the user re-running the installer will
 overwrite it next release, so also flag a TODO in the postmortem report
 saying "this delta should be PR'd back to the framework repo at
@@ -177,7 +177,7 @@ where data is unprotected"), append to the curated tier so future
 builders pick it up:
 
 ```bash
-node ~/.claude/bin/knowledge.js append \
+node ${QUALIA_BIN}/knowledge.js append \
   --type pattern \
   --title "{lesson title}" \
   --body "{lesson body}" \
@@ -220,7 +220,7 @@ node ~/.claude/bin/knowledge.js append \
   AI layer, not the codebase. The gap-closure loop (`/qualia-plan
   {N} --gaps`) handles the code. Postmortem only touches `agents/`,
   `rules/`, `skills/`, and the knowledge layer.
-- **Auto-applying deltas to `~/.claude/agents/X.md` without flagging a
+- **Auto-applying deltas to `${QUALIA_AGENTS}/X.md` without flagging a
   framework PR TODO.** That edit lasts until the next reinstall. Always
   note the TODO so the lesson reaches the framework repo.
 - **Promoting every postmortem finding to knowledge.** Most are

package/skills/qualia-report/SKILL.md

@@ -24,11 +24,11 @@ This is not a task-completion ceremony. The report records what happened during
 ### Step 0 — Pre-flight (graceful)
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner report
+node ${QUALIA_BIN}/qualia-ui.js banner report
 
 # Sanity checks — soft failures only, never block the report
-test -d .git || node ~/.claude/bin/qualia-ui.js warn "Not a git repo — local commit will be skipped, ERP upload will still try"
-test -f .planning/tracking.json || node ~/.claude/bin/qualia-ui.js warn "No tracking.json yet — ERP payload will use defaults"
+test -d .git || node ${QUALIA_BIN}/qualia-ui.js warn "Not a git repo — local commit will be skipped, ERP upload will still try"
+test -f .planning/tracking.json || node ${QUALIA_BIN}/qualia-ui.js warn "No tracking.json yet — ERP payload will use defaults"
 
 DRY_RUN="${DRY_RUN:-false}"
 echo "$ARGUMENTS" | grep -q -- '--dry-run' && DRY_RUN="true"
@@ -101,11 +101,11 @@ Per-project sequential ID (QS-REPORT-01, 02, ...). State.js owns the counter —
 ```bash
 PEEK=""
 [ "$DRY_RUN" = "true" ] && PEEK="--peek"
-CLIENT_REPORT_ID=$(node ~/.claude/bin/state.js next-report-id $PEEK 2>/dev/null \
+CLIENT_REPORT_ID=$(node ${QUALIA_BIN}/state.js next-report-id $PEEK 2>/dev/null \
   | node -e "try{const j=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(j.report_id||'')}catch{}")
 
 if [ -z "$CLIENT_REPORT_ID" ]; then
-  node ~/.claude/bin/qualia-ui.js fail "Could not allocate report ID. Try: cat .planning/tracking.json (is it valid JSON?)"
+  node ${QUALIA_BIN}/qualia-ui.js fail "Could not allocate report ID. Try: cat .planning/tracking.json (is it valid JSON?)"
   exit 1
 fi
 ```
@@ -116,10 +116,10 @@ fi
 if [ "$DRY_RUN" != "true" ] && [ -d .git ]; then
   mkdir -p .planning/reports
   git add .planning/reports/report-{date}.md .planning/tracking.json
-  git commit -m "report: $CLIENT_REPORT_ID session {YYYY-MM-DD}" || node ~/.claude/bin/qualia-ui.js warn "Nothing to commit (clean tree?)"
+  git commit -m "report: $CLIENT_REPORT_ID session {YYYY-MM-DD}" || node ${QUALIA_BIN}/qualia-ui.js warn "Nothing to commit (clean tree?)"
   git push 2>&1 | tail -3
   PUSH_EXIT=${PIPESTATUS[0]}
-  [ "$PUSH_EXIT" != "0" ] && node ~/.claude/bin/qualia-ui.js warn "git push failed — report committed locally but not pushed. ERP upload will still try."
+  [ "$PUSH_EXIT" != "0" ] && node ${QUALIA_BIN}/qualia-ui.js warn "git push failed — report committed locally but not pushed. ERP upload will still try."
 fi
 ```
 
@@ -136,12 +136,12 @@ The full payload-builder + 3-attempt-retry logic lives unchanged from v4 — see
 
 ```bash
 if [ "$DRY_RUN" != "true" ]; then
-  node ~/.claude/bin/state.js transition --to activity --notes "Session report $CLIENT_REPORT_ID generated" 2>/dev/null
+  node ${QUALIA_BIN}/state.js transition --to activity --notes "Session report $CLIENT_REPORT_ID generated" 2>/dev/null
 fi
 
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js ok "Report $CLIENT_REPORT_ID complete."
-node ~/.claude/bin/qualia-ui.js info "Shift report submitted. You can clock out now."
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js ok "Report $CLIENT_REPORT_ID complete."
+node ${QUALIA_BIN}/qualia-ui.js info "Shift report submitted. You can clock out now."
 ```
 
 ## Common errors (read this when something goes wrong)
@@ -149,7 +149,7 @@ node ~/.claude/bin/qualia-ui.js info "Shift report submitted. You can clock out
 | Symptom | Likely cause | Self-service fix |
 |---|---|---|
 | "Could not allocate report ID" | tracking.json missing/corrupt | `cat .planning/tracking.json` to inspect, or restore from `git checkout HEAD -- .planning/tracking.json` |
-| "ERP API key missing" | `~/.claude/.erp-api-key` empty | `printf '%s' "$QUALIA_ERP_KEY" \| qualia-framework set-erp-key` (ask Fawzi for the key) |
+| "ERP API key missing" | `${QUALIA_HOME}/.erp-api-key` empty | `printf '%s' "$QUALIA_ERP_KEY" \| qualia-framework set-erp-key` (ask Fawzi for the key) |
 | "ERP auth failed (401)" | Key revoked or wrong | Ask Fawzi for a fresh key |
 | "ERP upload failed after 3 attempts" | ERP down or network issue | Local commit is safe. Re-run `/qualia-report` later. |
 | "git push failed" | Auth or network or upstream issue | `git push` manually, see the error, fix, re-run |
@@ -163,7 +163,7 @@ The Step 6 payload + retry logic. Inlined to avoid a script-file fetch on every
 ERP_URL=$(node -e "try{const c=JSON.parse(require('fs').readFileSync(require('os').homedir()+'/.claude/.qualia-config.json','utf8'));console.log(c.erp?.url||'https://portal.qualiasolutions.net')}catch{console.log('https://portal.qualiasolutions.net')}")
 ERP_ENABLED=$(node -e "try{const c=JSON.parse(require('fs').readFileSync(require('os').homedir()+'/.claude/.qualia-config.json','utf8'));console.log(c.erp?.enabled!==false)}catch{console.log('true')}")
 
-API_KEY=$(cat ~/.claude/.erp-api-key 2>/dev/null)
+API_KEY=$(cat ${QUALIA_HOME}/.erp-api-key 2>/dev/null)
 REPORT_FILE=".planning/reports/report-{date}.md"
 SUBMITTED_BY=$(git config user.name || echo "unknown")
 SUBMITTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
@@ -181,7 +181,7 @@ IDEMPOTENCY_KEY=$(node -e "
 
 # Guard: API key required for upload (otherwise curl posts an empty bearer)
 if [ "$ERP_ENABLED" = "true" ] && [ -z "$API_KEY" ] && [ "$DRY_RUN" != "true" ]; then
-  node ~/.claude/bin/qualia-ui.js warn "ERP API key missing (~/.claude/.erp-api-key). Run: printf '%s' \"\$QUALIA_ERP_KEY\" | qualia-framework set-erp-key"
+  node ${QUALIA_BIN}/qualia-ui.js warn "ERP API key missing (${QUALIA_HOME}/.erp-api-key). Run: printf '%s' \"\$QUALIA_ERP_KEY\" | qualia-framework set-erp-key"
   ERP_ENABLED="false"
 fi
 
@@ -190,7 +190,7 @@ fi
 PAYLOAD=$(
   SUBMITTED_BY="$SUBMITTED_BY" SUBMITTED_AT="$SUBMITTED_AT" \
   CLIENT_REPORT_ID="$CLIENT_REPORT_ID" REPORT_FILE="$REPORT_FILE" \
-  node ~/.claude/bin/report-payload.js
+  node ${QUALIA_BIN}/report-payload.js
 )
 
 # --dry-run: print and stop
@@ -216,19 +216,19 @@ if [ "$ERP_ENABLED" = "true" ]; then
 
     if [ "$HTTP_CODE" = "200" ]; then
       ERP_REPORT_ID=$(echo "$BODY" | node -e "try{process.stdout.write(JSON.parse(require('fs').readFileSync(0,'utf8')).report_id||'')}catch{}")
-      node ~/.claude/bin/qualia-ui.js ok "Uploaded as $CLIENT_REPORT_ID (ERP: ${ERP_REPORT_ID:-none})"
+      node ${QUALIA_BIN}/qualia-ui.js ok "Uploaded as $CLIENT_REPORT_ID (ERP: ${ERP_REPORT_ID:-none})"
       break
     fi
     if [ "$HTTP_CODE" = "401" ] || [ "$HTTP_CODE" = "422" ]; then
-      node ~/.claude/bin/qualia-ui.js warn "ERP rejected ($HTTP_CODE) — $([ "$HTTP_CODE" = "401" ] && echo "API key invalid, ask Fawzi" || echo "schema mismatch:")"
+      node ${QUALIA_BIN}/qualia-ui.js warn "ERP rejected ($HTTP_CODE) — $([ "$HTTP_CODE" = "401" ] && echo "API key invalid, ask Fawzi" || echo "schema mismatch:")"
       [ "$HTTP_CODE" = "422" ] && echo "$BODY" | head -3
       break
     fi
-    [ $ATTEMPT -lt 3 ] && { SLEEP=$((1 * 3 ** (ATTEMPT - 1))); node ~/.claude/bin/qualia-ui.js warn "Attempt $ATTEMPT failed (HTTP ${HTTP_CODE:-timeout}), retrying in ${SLEEP}s..."; sleep $SLEEP; }
+    [ $ATTEMPT -lt 3 ] && { SLEEP=$((1 * 3 ** (ATTEMPT - 1))); node ${QUALIA_BIN}/qualia-ui.js warn "Attempt $ATTEMPT failed (HTTP ${HTTP_CODE:-timeout}), retrying in ${SLEEP}s..."; sleep $SLEEP; }
   done
 
   # If all 3 in-process attempts failed, enqueue the report into the persistent
-  # retry queue (~/.claude/.erp-retry-queue.json). session-start.js drains it on
+  # retry queue (${QUALIA_HOME}/.erp-retry-queue.json). session-start.js drains it on
   # the next Claude Code launch; `qualia-framework erp-flush` drains it on demand.
   # This replaces the prior "will appear after retry" message which was a lie —
   # no retry mechanism existed before v5.9.
@@ -256,13 +256,13 @@ if [ "$ERP_ENABLED" = "true" ]; then
         process.exit(1);
       }
     " 2>/dev/null && {
-      node ~/.claude/bin/qualia-ui.js warn "ERP upload failed after 3 attempts — $CLIENT_REPORT_ID enqueued for auto-retry on next session"
-      node ~/.claude/bin/qualia-ui.js info "Drain manually with: qualia-framework erp-flush"
+      node ${QUALIA_BIN}/qualia-ui.js warn "ERP upload failed after 3 attempts — $CLIENT_REPORT_ID enqueued for auto-retry on next session"
+      node ${QUALIA_BIN}/qualia-ui.js info "Drain manually with: qualia-framework erp-flush"
     } || {
-      node ~/.claude/bin/qualia-ui.js warn "ERP upload failed after 3 attempts AND queue enqueue failed. $CLIENT_REPORT_ID is committed locally — re-run /qualia-report later to retry."
+      node ${QUALIA_BIN}/qualia-ui.js warn "ERP upload failed after 3 attempts AND queue enqueue failed. $CLIENT_REPORT_ID is committed locally — re-run /qualia-report later to retry."
     }
   fi
 fi
 
-[ "$ERP_ENABLED" != "true" ] && node ~/.claude/bin/qualia-ui.js info "ERP upload skipped (disabled). $CLIENT_REPORT_ID committed locally."
+[ "$ERP_ENABLED" != "true" ] && node ${QUALIA_BIN}/qualia-ui.js info "ERP upload skipped (disabled). $CLIENT_REPORT_ID committed locally."
 ```

package/skills/qualia-research/SKILL.md

@@ -30,7 +30,7 @@ Targeted research on domain, library, or integration for a specific phase. Narro
 ### 1. Determine Phase
 
 ```bash
-node ~/.claude/bin/state.js check 2>/dev/null
+node ${QUALIA_BIN}/state.js check 2>/dev/null
 ```
 
 Phase N from args, or current phase from STATE.md.
@@ -55,7 +55,7 @@ Wait for answer. Answer defines research question.
 
 ```
 Agent(prompt="
-Role: @~/.claude/agents/researcher.md
+Role: @${QUALIA_AGENTS}/researcher.md
 
 <dimension>phase-specific</dimension>
 
@@ -86,8 +86,8 @@ Include: recommendation, rationale, versions, code examples, alternatives, pitfa
 Read `.planning/phase-{N}-research.md`. Present findings:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js ok "Research complete"
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js ok "Research complete"
 ```
 
 Show:
@@ -116,7 +116,7 @@ git commit -m "docs(phase-{N}): research findings"
 ### 8. Route
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "PHASE {N} RESEARCH DONE" "/qualia-plan {N}"
+node ${QUALIA_BIN}/qualia-ui.js end "PHASE {N} RESEARCH DONE" "/qualia-plan {N}"
 ```
 
 ## Rules

package/skills/qualia-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-review
-description: "Production audit with scored diagnostics. Runs real commands, scores findings by severity. Trigger on 'review', 'audit', 'code review', 'security check', 'production check'."
+description: "Read-only production audit with scored diagnostics. Runs real commands, scores findings by severity, writes REVIEW.md, and routes repair work to /qualia-fix, /qualia-polish, or /qualia-optimize. Trigger on 'review', 'audit', 'code review', 'security check', 'production check'."
 allowed-tools:
   - Bash
   - Read
@@ -14,6 +14,15 @@ allowed-tools:
 
 Runs real diagnostic commands and scores every finding. Not a checklist — an executable audit.
 
+Review is detection only. It never patches code. If the user wants the findings repaired, route by finding type:
+
+| Finding type | Next command |
+|---|---|
+| Broken existing behavior, failing test, security leak, config error | `/qualia-fix` |
+| Visual design quality or responsive polish | `/qualia-polish` |
+| Broad performance, architecture, or alignment opportunities | `/qualia-optimize` |
+| New missing capability | `/qualia-feature` or `/qualia-plan` |
+
 ## Usage
 
 - `/qualia-review` — Full audit (security + quality + performance)
@@ -23,15 +32,15 @@ Runs real diagnostic commands and scores every finding. Not a checklist — an e
 ## Process
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner review
+node ${QUALIA_BIN}/qualia-ui.js banner review
 ```
 
 ### 0. Load Context
 
 ```bash
-node ~/.claude/bin/knowledge.js
-node ~/.claude/bin/knowledge.js load fixes
-node ~/.claude/bin/knowledge.js load patterns
+node ${QUALIA_BIN}/knowledge.js
+node ${QUALIA_BIN}/knowledge.js load fixes
+node ${QUALIA_BIN}/knowledge.js load patterns
 ```
 
 Detect project shape:
@@ -127,7 +136,11 @@ grep -rn "const.*=.*await" --include="*.tsx" --include="*.ts" app/ src/ 2>/dev/n
 
 ### 4. Score and Report
 
-Write to `.planning/REVIEW.md`:
+Create the report directory and write to `.planning/reports/review/REVIEW.md`:
+
+```bash
+mkdir -p .planning/reports/review
+```
 
 ```markdown
 # Production Review — {YYYY-MM-DD}
@@ -156,6 +169,9 @@ Write to `.planning/REVIEW.md`:
 
 ## Verdict
 {PASS: no critical/high | FAIL: N blockers — fix before /qualia-ship}
+
+## Recommended Next Command
+{`/qualia-fix`, `/qualia-polish`, `/qualia-optimize`, `/qualia-feature`, or `none`} — {one-line reason}
 ```
 
 **Scoring (deterministic — see `rules/grounding.md` for full rubric):**
@@ -173,11 +189,11 @@ Quick reference (computed from the formula — verified):
 - 4+ CRITICAL → 1
 
 ```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js info "Security: {score}/5 ({n} findings)"
-node ~/.claude/bin/qualia-ui.js info "Quality:  {score}/5 ({n} findings)"
-node ~/.claude/bin/qualia-ui.js info "Perf:     {score}/5 ({n} findings)"
-node ~/.claude/bin/qualia-ui.js end "REVIEW: {PASS|FAIL}" "{next command}"
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js info "Security: {score}/5 ({n} findings)"
+node ${QUALIA_BIN}/qualia-ui.js info "Quality:  {score}/5 ({n} findings)"
+node ${QUALIA_BIN}/qualia-ui.js info "Perf:     {score}/5 ({n} findings)"
+node ${QUALIA_BIN}/qualia-ui.js end "REVIEW: {PASS|FAIL}" "{recommended next command}"
 ```
 
 ## Rules
@@ -185,5 +201,5 @@ node ~/.claude/bin/qualia-ui.js end "REVIEW: {PASS|FAIL}" "{next command}"
 1. **Run every command.** Don't skip scans because "the code looks clean."
 2. **Every finding gets a severity.** No prose — CRITICAL/HIGH/MEDIUM/LOW.
 3. **Every finding gets a fix suggestion.** Not just "this is bad" — say what to do.
-4. **Review detects. It does NOT fix.** This is an audit, not a refactor. Tell the user what to fix.
+4. **Review detects. It does NOT fix.** This is an audit, not a refactor. Route repair to `/qualia-fix`, design repair to `/qualia-polish`, and broad improvement to `/qualia-optimize`.
 5. **CRITICAL or HIGH = deploy blocker.** `/qualia-ship` checks for these.

package/skills/qualia-road/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-road
-description: "TERMINAL workflow map — Project → Journey → Milestones → Phases → Tasks. Use this in headless/SSH/no-browser sessions or when the user asks for the road in chat. For the HTML reference (default when a browser is available), use /qualia-help. Triggers: 'how does Qualia work', 'what's the workflow', 'show me the road', 'what command does X', 'how do projects flow', 'in terminal please', SSH context."
+description: "TERMINAL workflow map — Project → Journey → Milestones → Phases → Tasks. Use this in headless/SSH/no-browser sessions or when the user asks for the road in chat. Triggers: 'how does Qualia work', 'what's the workflow', 'show me the road', 'what command does X', 'how do projects flow', 'in terminal please', SSH context."
 disable-model-invocation: true
 allowed-tools:
   - Read
@@ -33,29 +33,29 @@ Done.
 ```
 
 ## Design as a thread
-Every road agent loads `PRODUCT.md + DESIGN.md + design-laws.md` substrate. Builders run `slop-detect` on every frontend commit. Verifiers score 8 design dimensions per phase.
+Every road agent loads `PRODUCT.md + DESIGN.md + design-laws.md` substrate. Builders run `slop-detect` on every frontend commit. Verifiers score 9 design dimensions per phase, including visual system and graphics.
 
 ## /qualia-polish is scope-adaptive
 ```
 /qualia-polish src/components/Button.tsx     ~30s component touch-up
 /qualia-polish app/dashboard                 ~3m  section pass
 /qualia-polish                               ~12m whole app, fan-out
-/qualia-polish --redesign                    ~30m ground-up redesign
+/qualia-polish --redesign                    ~30m ground-up redesign + complex visual concept
 /qualia-polish --critique                    read-only scored audit
 /qualia-polish --quick                       ~1m  gates only
 ```
 
-## Design pivots — /qualia-vibe (v6.1+)
+## Design pivots — /qualia-polish --vibe
 ```
-/qualia-vibe                              fast aesthetic pivot: ONE proposed direction, swap tokens, keep layout (~3 min)
-/qualia-vibe brutalist                    explicit pivot to named direction
-/qualia-vibe --variants 3                 opt-in menu (uses AskUserQuestion; default flow is one-opinion)
-/qualia-vibe --extract https://stripe.com reverse-engineer DESIGN.md from a reference URL
-/qualia-vibe --extract ./inspo.png        same, from a local screenshot
-/qualia-vibe --sync                       show drift between code (CSS vars, Tailwind config) and DESIGN.md
-/qualia-vibe --sync --write               patch DESIGN.md to match code, commit
+/qualia-polish --vibe                              fast aesthetic pivot: ONE proposed direction, swap tokens, keep layout (~3 min)
+/qualia-polish --vibe brutalist                    explicit pivot to named direction
+/qualia-polish --vibe --variants 3                 opt-in menu (rare; default flow is one-opinion)
+/qualia-polish --vibe --extract https://stripe.com reverse-engineer DESIGN.md from a reference URL
+/qualia-polish --vibe --extract ./inspo.png        same, from a local screenshot
+/qualia-polish --vibe --sync                       show drift between code (CSS vars, Tailwind config) and DESIGN.md
+/qualia-polish --vibe --sync --write               patch DESIGN.md to match code, commit
 ```
-`/qualia-vibe` is for the WHOLE-SITE aesthetic. For surgical component-level fixes use `/qualia-polish` (component or section scope). For ground-up structural redesign use `/qualia-polish --redesign`.
+`/qualia-polish --vibe` is for the WHOLE-SITE aesthetic. For surgical component-level fixes use `/qualia-polish` (component or section scope). For ground-up structural redesign use `/qualia-polish --redesign`.
 
 ## /qualia-polish --loop — autonomous visual QA
 ```
@@ -65,39 +65,47 @@ Every road agent loads `PRODUCT.md + DESIGN.md + design-laws.md` substrate. Buil
 /qualia-polish --loop {url} --reduced-motion              force prefers-reduced-motion
 /qualia-polish --loop --routes /a,/b,/c                   multi-route sweep
 ```
-Screenshots at 3 viewports (375/768/1440), scores 8 design dimensions using vision, fixes issues, re-screenshots, loops until all dims >= 3 or kill-switch triggers. Per-iteration git commits for clean revert.
+Screenshots at 3 viewports (375/768/1440), scores 9 design dimensions using vision, fixes issues, re-screenshots, loops until all dims >= 3 or kill-switch triggers. Per-iteration git commits for clean revert.
 
 ## Deterministic-enforcement skills
 ```
-/qualia-hook-gen       convert a CLAUDE.md/rules instruction into a deterministic pre-tool-use hook
 /qualia-optimize --deepen   spawns 3 parallel interface-design variants per candidate (Step 5b)
 ```
-`/qualia-hook-gen` reduces lifetime token cost (each migrated rule frees ~50-200 tokens per request). `/qualia-optimize --deepen` produces dramatically better refactor RFCs because 3 radically-different interfaces are surfaced and the human picks/hybridizes.
+`/qualia-optimize --deepen` produces dramatically better refactor RFCs because 3 radically-different interfaces are surfaced and the human picks/hybridizes.
 
 ## Alignment substrate
 Before high-stakes phases, run alignment skills against `.planning/CONTEXT.md` (domain glossary) and `.planning/decisions/` (ADRs):
 
 ```
 /qualia-discuss            → relentless one-question interview, updates CONTEXT.md inline
-/qualia-zoom               → map an unfamiliar code area using glossary terms
 /qualia-optimize --deepen  → find shallow modules, propose Ousterhout-style refactors
 /qualia-test --tdd         → vertical-slice red→green→refactor for one feature
-/qualia-issues             → break a phase plan into independent GH issues
-/qualia-triage             → label + route open issues (ready-for-agent vs human)
 /qualia-map                → adapt Qualia to an existing brownfield repo's conventions (5th onboarding agent)
 ```
 
 ## Auxiliary commands
 ```
 Lost?        → /qualia        (state router — tells you the next command)
-Stuck/weird? → /qualia-idk    (diagnostic — spawns plan-view + code-view agents in parallel)
-Single feature? → /qualia-feature (auto-scoped: inline for trivia, fresh spawn for 1-5 files)
-Paused?      → /qualia-resume (restore from .continue-here.md or STATE.md)
+Health?      → /qualia-doctor (install, state, contracts, memory, ERP queue)
+Stuck/weird? → /qualia        (diagnostic branch — scans planning + code when state alone is insufficient)
+Broken thing? → /qualia-fix     (root cause, minimal patch, verify, report)
+Single feature? → /qualia-feature (new capability: inline for trivia, fresh spawn for 1-5 files)
+Paused?      → /qualia        (restore from .continue-here.md or STATE.md)
 End of day?  → /qualia-report (mandatory before clock-out; writes ERP payload)
-Debug bug?   → /qualia-debug  (feedback-loop-first investigation)
 Unsure plan? → /qualia-discuss (capture decisions before planning)
 ```
 
+## Outside-road command boundaries
+```
+Need a repair?       → /qualia-fix       (mutates code, proves fix)
+Need an investigation? → /qualia-review  (read-only audit) or /qualia-fix (known broken behavior)
+Need an audit?       → /qualia-review    (detect-only, scored findings)
+Need improvement map? → /qualia-optimize (report/RFC, broad opportunities)
+Need visual quality? → /qualia-polish    (style/layout/accessibility)
+Need new aesthetic?  → /qualia-polish --vibe (tokens only, layout preserved)
+Need new capability? → /qualia-feature   (small net-new work)
+```
+
 ## Human gates
 Journey approval after `/qualia-new`, then one at each milestone boundary via `/qualia-milestone`. `--auto` runs everything between gates automatically.
 

package/skills/qualia-ship/SKILL.md

@@ -16,7 +16,7 @@ Full deployment pipeline with quality gates.
 ## Process
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner ship
+node ${QUALIA_BIN}/qualia-ui.js banner ship
 ```
 
 ### 0. State Guard — refuse to ship from an invalid state
@@ -24,14 +24,22 @@ node ~/.claude/bin/qualia-ui.js banner ship
 `/qualia-ship` is a terminal operation — it writes a deployed tag, bumps counters, and produces a verified URL. It must NEVER run on an unpolished, unverified, or malformed project.
 
 ```bash
-STATE=$(node ~/.claude/bin/state.js check 2>/dev/null)
+STATE=$(node ${QUALIA_BIN}/state.js check 2>/dev/null)
 if [ -z "$STATE" ]; then
-  node ~/.claude/bin/qualia-ui.js fail "No project loaded. Run /qualia-new first or cd to a Qualia-managed project."
+  node ${QUALIA_BIN}/qualia-ui.js fail "No project loaded. Run /qualia-new first or cd to a Qualia-managed project."
   exit 1
 fi
 
 STATUS=$(echo "$STATE" | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(d.status||'')}catch{}")
 VERIFICATION=$(echo "$STATE" | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(d.verification||'')}catch{}")
+NEXT_COMMAND=$(echo "$STATE" | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(d.next_command||'/qualia')}catch{process.stdout.write('/qualia')}")
+ROLE=$(node -e "try{const fs=require('fs'),path=require('path'),os=require('os');const h=process.env.QUALIA_HOME||path.dirname(process.env.QUALIA_BIN||path.join(os.homedir(),'.claude','bin'));const c=JSON.parse(fs.readFileSync(path.join(h,'.qualia-config.json'),'utf8'));process.stdout.write((c.role||'').toUpperCase())}catch{}")
+
+if [ "${QUALIA_SHIP_FORCE:-0}" = "1" ] && [ "$ROLE" != "OWNER" ]; then
+  node ${QUALIA_BIN}/qualia-ui.js fail "Owner override is OWNER-only."
+  node ${QUALIA_BIN}/qualia-ui.js info "Run $NEXT_COMMAND."
+  exit 1
+fi
 
 # Valid ship-from states:
 #   polished     — /qualia-polish ran cleanly; ready for deploy
@@ -39,12 +47,11 @@ VERIFICATION=$(echo "$STATE" | node -e "try{const d=JSON.parse(require('fs').rea
 # Anything else (setup, planned, built, shipped, handed_off, verified+fail) is refused.
 if [ "$STATUS" != "polished" ] && ! { [ "$STATUS" = "verified" ] && [ "$VERIFICATION" = "pass" ]; }; then
   if [ "${QUALIA_SHIP_FORCE:-0}" = "1" ]; then
-    node ~/.claude/bin/qualia-ui.js warn "Forced ship from state '$STATUS' (verification: ${VERIFICATION:-none}). Record the reason in the final report."
+    node ${QUALIA_BIN}/qualia-ui.js warn "Forced ship from state '$STATUS' (verification: ${VERIFICATION:-none}). Record the reason in the final report."
   else
-  node ~/.claude/bin/qualia-ui.js fail "Cannot ship from state '$STATUS' (verification: ${VERIFICATION:-none})."
-  node ~/.claude/bin/qualia-ui.js info "Run /qualia-polish first, or /qualia-verify {phase} if verification is still pending."
-  node ~/.claude/bin/qualia-ui.js info "Hotfix override: set QUALIA_SHIP_FORCE=1 only when the user explicitly approved it."
-  exit 1
+    node ${QUALIA_BIN}/qualia-ui.js fail "Ship refused from state '$STATUS' (verification: ${VERIFICATION:-none})."
+    node ${QUALIA_BIN}/qualia-ui.js info "Run $NEXT_COMMAND."
+    exit 1
   fi
 fi
 ```
@@ -64,7 +71,7 @@ On failure:
 1. Summarize what failed in plain language
 2. Auto-fix
 3. Re-run the gate
-4. If still failing after 2 attempts: tell the employee, suggest `/qualia-debug`
+4. If still failing after 2 attempts: tell the employee, suggest `/qualia-fix`
 
 ### 2. Security Check — full depth
 
@@ -76,7 +83,7 @@ SEC_FAIL=0
 # CRITICAL: service_role in client-facing code
 HITS=$(grep -rn "service_role" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | grep -v "\.server\.\|[\\/]server[\\/]\|[\\/]app[\\/]api[\\/]\|route\.\|middleware\.")
 if [ -n "$HITS" ]; then
-  node ~/.claude/bin/qualia-ui.js fail "service_role leaked to client code:"
+  node ${QUALIA_BIN}/qualia-ui.js fail "service_role leaked to client code:"
   echo "$HITS" | head -5
   SEC_FAIL=1
 fi
@@ -84,7 +91,7 @@ fi
 # CRITICAL: hardcoded secrets
 HITS=$(grep -rn "sk_live\|sk_test\|SUPABASE_SERVICE_ROLE\|eyJhbGciOi" --include="*.ts" --include="*.tsx" --include="*.js" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | grep -v "\.env")
 if [ -n "$HITS" ]; then
-  node ~/.claude/bin/qualia-ui.js fail "Hardcoded secret found:"
+  node ${QUALIA_BIN}/qualia-ui.js fail "Hardcoded secret found:"
   echo "$HITS" | head -5
   SEC_FAIL=1
 fi
@@ -92,7 +99,7 @@ fi
 # CRITICAL: dangerouslySetInnerHTML / eval
 HITS=$(grep -rn "dangerouslySetInnerHTML\|eval(" --include="*.ts" --include="*.tsx" --include="*.js" app/ components/ src/ 2>/dev/null | grep -v node_modules)
 if [ -n "$HITS" ]; then
-  node ~/.claude/bin/qualia-ui.js fail "Dangerous innerHTML/eval pattern:"
+  node ${QUALIA_BIN}/qualia-ui.js fail "Dangerous innerHTML/eval pattern:"
   echo "$HITS" | head -5
   SEC_FAIL=1
 fi
@@ -100,13 +107,13 @@ fi
 # CRITICAL: .env files tracked in git
 HITS=$(git ls-files | grep -i "\.env" | grep -v "\.example\|\.template\|\.sample")
 if [ -n "$HITS" ]; then
-  node ~/.claude/bin/qualia-ui.js fail ".env files tracked in git:"
+  node ${QUALIA_BIN}/qualia-ui.js fail ".env files tracked in git:"
   echo "$HITS"
   SEC_FAIL=1
 fi
 
 if [ $SEC_FAIL -ne 0 ]; then
-  node ~/.claude/bin/qualia-ui.js fail "Security check failed. Fix findings above or run /qualia-review for full audit."
+  node ${QUALIA_BIN}/qualia-ui.js fail "Security check failed. Fix findings above or run /qualia-review for full audit."
   exit 1
 fi
 ```
@@ -140,8 +147,8 @@ Read the deployed URL from `tracking.json.deployed_url` or from an explicit user
 # exact value before running this block. Otherwise use tracking.json.
 URL="${QUALIA_SHIP_URL:-$(node -e 'try{const t=JSON.parse(require("fs").readFileSync(".planning/tracking.json","utf8"));process.stdout.write(t.deployed_url||"")}catch{}')}"
 if [ -z "$URL" ]; then
-  node ~/.claude/bin/qualia-ui.js warn "No deployed_url in tracking.json — parse it from the deploy command output (vercel/supabase/wrangler all print the URL on success)."
-  node ~/.claude/bin/qualia-ui.js info "Re-run with: /qualia-ship --url https://your-site.com, then export that value as QUALIA_SHIP_URL for this check."
+  node ${QUALIA_BIN}/qualia-ui.js warn "No deployed_url in tracking.json — parse it from the deploy command output (vercel/supabase/wrangler all print the URL on success)."
+  node ${QUALIA_BIN}/qualia-ui.js info "Re-run with: /qualia-ship --url https://your-site.com, then export that value as QUALIA_SHIP_URL for this check."
   exit 1
 fi
 
@@ -151,7 +158,7 @@ HTTP_CODE=$(echo "$RESP" | awk '{print $1}')
 LATENCY=$(echo "$RESP" | awk '{print $2}')
 
 if [ "$HTTP_CODE" != "200" ]; then
-  node ~/.claude/bin/qualia-ui.js fail "Post-deploy check failed: HTTP $HTTP_CODE at $URL"
+  node ${QUALIA_BIN}/qualia-ui.js fail "Post-deploy check failed: HTTP $HTTP_CODE at $URL"
   exit 1
 fi
 
@@ -162,18 +169,18 @@ AUTH_CODE=$(curl -sS -o /dev/null -w "%{http_code}" --max-time 10 "$URL/api/auth
 ### 6. Report
 
 ```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js ok "URL: $URL"
-node ~/.claude/bin/qualia-ui.js ok "Status: HTTP $HTTP_CODE"
-node ~/.claude/bin/qualia-ui.js ok "Latency: ${LATENCY}s"
-[ "$AUTH_CODE" = "200" ] || [ "$AUTH_CODE" = "401" ] && node ~/.claude/bin/qualia-ui.js ok "Auth endpoint responds (HTTP $AUTH_CODE)"
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js ok "URL: $URL"
+node ${QUALIA_BIN}/qualia-ui.js ok "Status: HTTP $HTTP_CODE"
+node ${QUALIA_BIN}/qualia-ui.js ok "Latency: ${LATENCY}s"
+[ "$AUTH_CODE" = "200" ] || [ "$AUTH_CODE" = "401" ] && node ${QUALIA_BIN}/qualia-ui.js ok "Auth endpoint responds (HTTP $AUTH_CODE)"
 ```
 
 ```bash
-node ~/.claude/bin/state.js transition --to shipped --deployed-url "$URL"
+node ${QUALIA_BIN}/state.js transition --to shipped --deployed-url "$URL"
 ```
 Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "SHIPPED" "/qualia-handoff"
+node ${QUALIA_BIN}/qualia-ui.js end "SHIPPED" "/qualia-handoff"
 ```