qualia-framework 6.2.9 → 6.2.10

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-resume/SKILL.md

@@ -35,18 +35,18 @@ Restore context and route to the right next action.
 ### 4. Present and Route
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner resume
-node ~/.claude/bin/qualia-ui.js info "Last session: {summary}"
+node ${QUALIA_BIN}/qualia-ui.js banner resume
+node ${QUALIA_BIN}/qualia-ui.js info "Last session: {summary}"
 ```
 
 If uncommitted changes:
 ```bash
-node ~/.claude/bin/qualia-ui.js warn "{N} uncommitted files"
+node ${QUALIA_BIN}/qualia-ui.js warn "{N} uncommitted files"
 ```
 
 End with the next command:
 ```bash
-node ~/.claude/bin/qualia-ui.js next "{next command}"
+node ${QUALIA_BIN}/qualia-ui.js next "{next command}"
 ```
 
 Clean up `.continue-here.md` after restoration (or offer to keep it).

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

@@ -33,14 +33,14 @@ 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
 ```
@@ -65,7 +65,7 @@ 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
 ```
@@ -90,14 +90,27 @@ Before high-stakes phases, run alignment skills against `.planning/CONTEXT.md` (
 ## Auxiliary commands
 ```
 Lost?        → /qualia        (state router — tells you the next command)
+Health?      → /qualia-doctor (install, state, contracts, memory, ERP queue)
 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)
+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-resume (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)
+Debug why?   → /qualia-debug  (feedback-loop-first investigation when evidence is unclear)
 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-debug   (evidence first, no guessing)
+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-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,9 +24,9 @@ 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
 
@@ -39,11 +39,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."
+  node ${QUALIA_BIN}/qualia-ui.js fail "Cannot ship from state '$STATUS' (verification: ${VERIFICATION:-none})."
+  node ${QUALIA_BIN}/qualia-ui.js info "Run /qualia-polish first, or /qualia-verify {phase} if verification is still pending."
+  node ${QUALIA_BIN}/qualia-ui.js info "Hotfix override: set QUALIA_SHIP_FORCE=1 only when the user explicitly approved it."
   exit 1
   fi
 fi
@@ -76,7 +76,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 +84,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 +92,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 +100,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 +140,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 +151,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 +162,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"
 ```

package/skills/qualia-skill-new/SKILL.md

@@ -16,7 +16,7 @@ You are about to create a reusable slash command. Skills are the leverage of the
 ## Process
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner skill-new
+node ${QUALIA_BIN}/qualia-ui.js banner skill-new
 ```
 
 ### 1. Scope Decision
@@ -30,7 +30,7 @@ options:
   - label: "Framework skill (ships to the team)"
     description: "Edit qualia-framework repo. Everyone gets it on next update."
   - label: "Local skill (just me)"
-    description: "Lives only in ~/.claude/skills/. Not shared."
+    description: "Lives only in ${QUALIA_SKILLS}/. Not shared."
   - label: "Agent instead of a skill"
     description: "This is a subagent role, not a slash command. Creates agents/{name}.md."
 ```
@@ -51,11 +51,11 @@ fi
 echo "${FRAMEWORK_DIR:-UNRESOLVED}"
 ```
 
-If the command prints `UNRESOLVED`, ask the user: *"Where is your qualia-framework checkout? (absolute path, or type 'local' to save only to ~/.claude/)"*. If they type `local`, downgrade the scope to Local. Otherwise store the answer as `${FRAMEWORK_DIR}` for the rest of the session.
+If the command prints `UNRESOLVED`, ask the user: *"Where is your qualia-framework checkout? (absolute path, or type 'local' to save only to ${QUALIA_HOME}/)"*. If they type `local`, downgrade the scope to Local. Otherwise store the answer as `${FRAMEWORK_DIR}` for the rest of the session.
 
 **Framework** → target: `${FRAMEWORK_DIR}/skills/{name}/SKILL.md`
-**Local** → target: `~/.claude/skills/{name}/SKILL.md`
-**Agent** → target: `${FRAMEWORK_DIR}/agents/{name}.md` (framework) or `~/.claude/agents/{name}.md` (local)
+**Local** → target: `${QUALIA_SKILLS}/{name}/SKILL.md`
+**Agent** → target: `${FRAMEWORK_DIR}/agents/{name}.md` (framework) or `${QUALIA_AGENTS}/{name}.md` (local)
 
 ### 2. Gather Requirements
 
@@ -73,13 +73,13 @@ Before writing, read two existing skills that are structurally similar:
 
 ```bash
 # Short direct-action skill reference:
-cat ~/.claude/skills/qualia-learn/SKILL.md
+cat ${QUALIA_SKILLS}/qualia-learn/SKILL.md
 
 # Skill-that-spawns-an-agent reference:
-cat ~/.claude/skills/qualia-plan/SKILL.md
+cat ${QUALIA_SKILLS}/qualia-plan/SKILL.md
 
 # Interactive wizard reference:
-cat ~/.claude/skills/qualia-new/SKILL.md
+cat ${QUALIA_SKILLS}/qualia-new/SKILL.md
 ```
 
 Pick the closest pattern and copy its structure.
@@ -114,7 +114,7 @@ description: "{one sentence}. {trigger phrases}"
 ### N. Update State (only if this skill changes project state)
 
 ```bash
-node ~/.claude/bin/state.js transition --to {status} ...
+node ${QUALIA_BIN}/state.js transition --to {status} ...
 ```
 Do NOT manually edit STATE.md or tracking.json.
 ```
@@ -131,7 +131,7 @@ Spawn a fresh subagent to simulate running the skill — does it make sense with
 
 ```
 Agent(prompt="
-Read this skill: @~/.claude/skills/{name}/SKILL.md
+Read this skill: @${QUALIA_SKILLS}/{name}/SKILL.md
 
 Pretend the user just said '{one of the trigger phrases}'. Walk through what you would do, step by step. Flag anything ambiguous or missing.
 ", subagent_type="general-purpose", description="Test skill {name}")
@@ -143,8 +143,8 @@ Fix any ambiguity the test agent found.
 
 ```bash
 # Framework skill — copy to local .claude for immediate testing
-mkdir -p ~/.claude/skills/{name}
-cp "${FRAMEWORK_DIR}/skills/{name}/SKILL.md" ~/.claude/skills/{name}/SKILL.md
+mkdir -p ${QUALIA_SKILLS}/{name}
+cp "${FRAMEWORK_DIR}/skills/{name}/SKILL.md" ${QUALIA_SKILLS}/{name}/SKILL.md
 
 # Verify it parses
 node -e "const fs=require('fs');const os=require('os');const path=require('path');const c=fs.readFileSync(path.join(os.homedir(),'.claude/skills/{name}/SKILL.md'),'utf8');if(!c.includes('---'))throw new Error('missing frontmatter');if(!c.match(/^name:\s*\S/m))throw new Error('missing name');if(!c.match(/^description:\s*\S/m))throw new Error('missing description');console.log('OK')"
@@ -168,6 +168,6 @@ Remind the user to run `npx qualia-framework@latest update` on their other machi
 - ❌ **Description without triggers** — the skill won't fire
 - ❌ **Multiple commands in one skill** — split into two skills
 - ❌ **Direct file writes instead of state.js** — always use state.js for STATE.md/tracking.json
-- ❌ **Hardcoded project paths** — use `.planning/` relative or `~/.claude/` absolute, never `/home/specific-user/`
+- ❌ **Hardcoded project paths** — use `.planning/` relative or `${QUALIA_HOME}/` absolute, never `/home/specific-user/`
 - ❌ **Skills that spawn agents without passing PROJECT.md and STATE.md context** — agents are blind by default
 - ❌ **Skills longer than ~150 lines** — split or move logic to an agent

package/skills/qualia-test/SKILL.md

@@ -25,7 +25,7 @@ Generate tests for client project code. Detect framework, classify targets, writ
 ## Process
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner test
+node ${QUALIA_BIN}/qualia-ui.js banner test
 ```
 
 ### 1. Detect Test Framework
@@ -118,10 +118,10 @@ npx vitest run --coverage 2>&1 | tail -30
 ### 5. Report
 
 ```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js info "Files tested: {N}"
-node ~/.claude/bin/qualia-ui.js ok "Passing: {pass}/{total}"
-node ~/.claude/bin/qualia-ui.js end "TESTS DONE"
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js info "Files tested: {N}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Passing: {pass}/{total}"
+node ${QUALIA_BIN}/qualia-ui.js end "TESTS DONE"
 ```
 
 If any tests fail, show the failures and offer to fix them.

package/skills/qualia-triage/SKILL.md

@@ -139,7 +139,7 @@ The loop continues until the queue empties or the user pauses.
 ### 7. Final report
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "QUEUE TRIAGED" "/qualia or /qualia-build {next}"
+node ${QUALIA_BIN}/qualia-ui.js end "QUEUE TRIAGED" "/qualia or /qualia-build {next}"
 ```
 
 ## Rules