qualia-framework 6.2.7 → 6.2.10

package/skills/qualia-fix/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: qualia-fix
+description: "Practical repair lane for broken existing behavior. Blends /qualia-debug root-cause discipline with /qualia-feature execution. Use when the user says 'fix this', 'bug', 'broken', 'error', 'failing test', 'regression', 'hotfix', 'not working', 'layout broken', 'slow page', or 'config is wrong'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+argument-hint: "[--quick|--frontend|--perf|--test|--no-commit] <symptom>"
+---
+
+# /qualia-fix - Repair Broken Existing Behavior
+
+Fix is the practical lane for "this used to work, or should work, and now it does not." It combines the evidence discipline of `/qualia-debug` with the small-work execution path of `/qualia-feature`.
+
+## Usage
+
+- `/qualia-fix {symptom}` - diagnose and repair a named problem
+- `/qualia-fix --quick {symptom}` - micro-fix, max 1 file, direct edit
+- `/qualia-fix --frontend {symptom}` - bias diagnostics toward layout, CSS, hydration, responsive, and visual bugs
+- `/qualia-fix --perf {symptom}` - bias diagnostics toward slow pages, wasteful renders, bundles, queries, and sequential awaits
+- `/qualia-fix --test {failing command}` - start from a failing test/build command
+- `/qualia-fix --no-commit {symptom}` - patch and verify, but leave changes uncommitted
+
+## When To Use
+
+- A failing test, build, typecheck, lint, deploy, or runtime path
+- A broken existing UI, route, form, API, config, or integration
+- A regression after recent work
+- A small bug report with enough detail to reproduce or inspect
+- A hotfix where the expected behavior is already known
+
+## When Not To Use
+
+- Net-new capability -> `/qualia-feature`
+- Phase-sized work or 5+ likely files -> `/qualia-plan`
+- Read-only audit -> `/qualia-review`
+- No concrete symptom and no failing command -> `/qualia-debug`
+- Visual craft/design quality with no functional bug -> `/qualia-polish`
+- Whole-site aesthetic pivot -> `/qualia-vibe`
+
+## Process
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js banner fix
+```
+
+### 1. Classify The Request
+
+Parse `$ARGUMENTS` into:
+
+- symptom
+- mode: quick | frontend | perf | test | general
+- expected behavior
+- observed behavior
+- named files/routes/tests if provided
+
+If the request is actually a new feature, stop and route:
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js end "ROUTED" "/qualia-feature"
+```
+
+If the request is phase-sized, stop and route:
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js end "ROUTED" "/qualia-plan"
+```
+
+### 2. Build The Feedback Loop
+
+Use the cheapest check that can prove the bug is real and later prove it is fixed.
+
+Prefer, in order:
+
+1. User-provided failing command
+2. Targeted test
+3. Typecheck or lint error
+4. Reproduction grep or route/component inspection
+5. Recent diff inspection
+
+Useful starting commands:
+
+```bash
+git status --short
+git diff --stat
+npm test -- --runInBand 2>/dev/null || npm test 2>/dev/null || true
+npx tsc --noEmit 2>&1 | head -40
+```
+
+For `--test`, run the exact command first and preserve the failing output.
+
+### 3. Find Root Cause
+
+Use a hard inspection budget of 12 Read/Grep/Bash calls before returning insufficient evidence.
+
+Root cause must include:
+
+- `file:line`
+- the specific bad assumption or broken contract
+- why the symptom follows from it
+
+No root cause, no patch. If evidence is insufficient, write the report and stop.
+
+### 4. Patch Minimally
+
+Patch rules:
+
+- Touch only files required by the root cause.
+- Default max: 3 files.
+- `--quick` max: 1 file.
+- If more than 3 files are required, stop and route to `/qualia-plan` or ask for permission to widen.
+- Do not include cleanup, refactors, formatting churn, or adjacent improvements.
+- Preserve unrelated user changes.
+
+### 5. Verify
+
+Re-run the feedback loop from Step 2. Then run the smallest broad safety check that matches the stack.
+
+Common verification:
+
+```bash
+npx tsc --noEmit
+npm test -- --runInBand 2>/dev/null || npm test 2>/dev/null || true
+```
+
+If verification fails, do not commit. Either repair the verification failure if it is the same root cause, or write the report with the remaining failure.
+
+### 6. Write FIX Report
+
+Create the report directory and write `.planning/reports/fix/FIX-{YYYY-MM-DD-HHMM}.md`:
+
+```bash
+mkdir -p .planning/reports/fix
+```
+
+```markdown
+# Fix Report - {YYYY-MM-DD HH:MM}
+
+**Symptom:** {user symptom}
+**Mode:** general | quick | frontend | perf | test
+**Outcome:** fixed | insufficient-evidence | partial
+
+## Feedback Loop
+- Initial failing check: `{command or inspection}`
+- Final passing check: `{command or inspection}`
+
+## Root Cause
+`{file}:{line}` - {one sentence}
+
+## Patch
+- Files changed: {list}
+- Change summary: {brief summary}
+
+## Verification
+- `{command}` - PASS|FAIL
+- `{command}` - PASS|FAIL
+
+## Remaining Notes
+- {adjacent issue not fixed, or "None"}
+```
+
+### 7. Commit
+
+Unless `--no-commit` was passed:
+
+```bash
+git add {specific changed files} .planning/reports/fix/FIX-{timestamp}.md
+git commit -m "fix: {short symptom/root-cause summary}"
+```
+
+Record state:
+
+```bash
+node ${QUALIA_BIN}/state.js transition --to note --notes "{short fix summary}" --tasks-done 1
+```
+
+### 8. Output
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js ok "Root cause: {file:line}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Files: {changed files}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Verification: {commands}"
+node ${QUALIA_BIN}/qualia-ui.js end "FIXED" "{next command if any}"
+```
+
+## Insufficient Evidence Return
+
+If no confident root cause after 12 inspection calls, write the same FIX report with:
+
+```markdown
+**Outcome:** insufficient-evidence
+
+## Narrowed To
+- Files examined: {list}
+- Ruled out: {list}
+- Remaining suspects: {list}
+
+## Recommended Next Diagnostic
+- {specific command or reproduction step}
+```
+
+Do not patch and do not commit speculative work.
+
+## Rules
+
+1. **Repair existing behavior only.** New work belongs in `/qualia-feature`.
+2. **Feedback loop first.** Know how the bug will be proven fixed before editing.
+3. **Root cause or stop.** No plausible patches.
+4. **Small patch.** Default max 3 files; quick max 1 file.
+5. **Report every run.** The FIX report becomes searchable repair memory.
+6. **Commit only after verification.** `--no-commit` is the only exception.

package/skills/qualia-flush/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-flush
-description: "Promote daily-log raw entries to the curated knowledge tier — Karpathy-style raw→wiki flush. Reads ~/.claude/knowledge/daily-log/*.md, identifies recurring patterns and decisions, writes them to ~/.claude/knowledge/concepts/{topic}.md, updates index.md. Trigger on 'flush memory', 'promote learnings', 'consolidate logs', 'qualia-flush', 'process daily logs', or run weekly."
+description: "Promote daily-log raw entries to the curated knowledge tier — Karpathy-style raw→wiki flush. Reads ${QUALIA_KNOWLEDGE}/daily-log/*.md, identifies recurring patterns and decisions, writes them to ${QUALIA_KNOWLEDGE}/concepts/{topic}.md, updates index.md. Trigger on 'flush memory', 'promote learnings', 'consolidate logs', 'qualia-flush', 'process daily logs', or run weekly."
 allowed-tools:
   - Bash
   - Read
@@ -14,11 +14,11 @@ allowed-tools:
 
 Closes the **raw → wiki** loop in the Qualia memory layer. The Stop hook
 (`hooks/stop-session-log.js`) appends mechanical session checkpoints to
-`~/.claude/knowledge/daily-log/{date}.md`.
+`${QUALIA_KNOWLEDGE}/daily-log/{date}.md`.
 Those entries accumulate but stay raw — they describe what happened, not
 what to do about it. This skill reads the recent daily-log entries with an
 LLM (you) and writes durable concepts that the builder, planner, and
-debug skills will surface later via `node ~/.claude/bin/knowledge.js`.
+debug skills will surface later via `node ${QUALIA_BIN}/knowledge.js`.
 
 Inspired by Karpathy's LLM knowledge bases and Cole Medin's self-evolving
 Claude memory pattern (NotebookLM, 2026-04-25). Both run a daily/weekly
@@ -47,7 +47,7 @@ all projects. Show a one-line preview before writing anything destructive.
 ### 1. Banner + check the floor
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner flush 2>/dev/null || true
+node ${QUALIA_BIN}/qualia-ui.js banner flush 2>/dev/null || true
 
 # Resolve the knowledge dir. Fail loud if it doesn't exist — flush is
 # meaningless without a daily-log to read.
@@ -112,7 +112,7 @@ Things to **NOT** promote:
 For each thing worth promoting, use the loader's `append`:
 
 ```bash
-node ~/.claude/bin/knowledge.js append \
+node ${QUALIA_BIN}/knowledge.js append \
   --type {pattern|fix|client} \
   --title "{Concise title — what's the recurring thing?}" \
   --body "{The promoted lesson. Be specific. Include the project name(s) and dates where this pattern was observed so future you can verify.}" \
@@ -122,13 +122,13 @@ node ~/.claude/bin/knowledge.js append \
 
 For a brand-new topic that doesn't fit pattern/fix/client (e.g. a Stripe
 integration approach worth its own file), Write to
-`~/.claude/knowledge/concepts/{topic}.md`. Then **update `index.md`** so the
+`${QUALIA_KNOWLEDGE}/concepts/{topic}.md`. Then **update `index.md`** so the
 new file is reachable — list it under "What's where" with one line:
 
 ```bash
 # After writing concepts/stripe-checkout.md:
-node ~/.claude/bin/knowledge.js path stripe-checkout
-# Returned path = ~/.claude/knowledge/stripe-checkout.md  (NOTE: top-level, not concepts/)
+node ${QUALIA_BIN}/knowledge.js path stripe-checkout
+# Returned path = ${QUALIA_KNOWLEDGE}/stripe-checkout.md  (NOTE: top-level, not concepts/)
 ```
 
 > **Loader behavior:** `knowledge.js load <name>` resolves bare names by walking
@@ -181,7 +181,7 @@ Format:
 - **Mass-promoting everything:** if you found "promotions" for 90% of
   daily-log entries, you're labeling, not promoting. Be selective.
 - **Re-promoting on every flush:** before appending, run
-  `node ~/.claude/bin/knowledge.js search "{title keywords}"` to check if
+  `node ${QUALIA_BIN}/knowledge.js search "{title keywords}"` to check if
   the pattern already exists. If it does, either update it (find by `**ID:**`
   line) or skip — never duplicate.
 - **Hand-writing to `learned-patterns.md` etc. directly:** always go

package/skills/qualia-handoff/SKILL.md

@@ -31,7 +31,7 @@ Every Handoff milestone must produce these. They are checked against in `REQUIRE
 ## Process
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner handoff
+node ${QUALIA_BIN}/qualia-ui.js banner handoff
 ```
 
 ### 1. Verify Production URL (Deliverable 1)
@@ -39,13 +39,13 @@ node ~/.claude/bin/qualia-ui.js banner handoff
 ```bash
 URL=$(node -e "const t=JSON.parse(require('fs').readFileSync('.planning/tracking.json','utf8'));console.log(t.deployed_url||'')")
 if [ -z "$URL" ]; then
-  node ~/.claude/bin/qualia-ui.js fail "No deployed_url — run /qualia-ship first"
+  node ${QUALIA_BIN}/qualia-ui.js fail "No deployed_url — run /qualia-ship first"
   exit 1
 fi
 HTTP=$(curl -s -o /dev/null -w "%{http_code}" "$URL")
 LATENCY=$(curl -s -o /dev/null -w "%{time_total}" "$URL")
 AUTH=$(curl -s -o /dev/null -w "%{http_code}" "$URL/api/auth/callback" 2>/dev/null || echo "N/A")
-node ~/.claude/bin/qualia-ui.js ok "URL: $URL (HTTP $HTTP, ${LATENCY}s, auth:$AUTH)"
+node ${QUALIA_BIN}/qualia-ui.js ok "URL: $URL (HTTP $HTTP, ${LATENCY}s, auth:$AUTH)"
 ```
 
 If HTTP is not 2xx or latency > 1.0s → halt; deliverable fails.
@@ -119,7 +119,7 @@ git push
 ### 5. Update State
 
 ```bash
-node ~/.claude/bin/state.js transition --to handed_off
+node ${QUALIA_BIN}/state.js transition --to handed_off
 ```
 
 Do NOT manually edit STATE.md or tracking.json — state.js handles both.
@@ -131,11 +131,11 @@ Trigger the final `/qualia-report`. This uploads the closing state to the ERP wi
 In `--auto` mode, inline-invoke `/qualia-report` now. In guided mode, show the next step:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js ok "Production URL verified"
-node ~/.claude/bin/qualia-ui.js ok "Documentation updated"
-node ~/.claude/bin/qualia-ui.js ok "Client assets archived + handoff doc written"
-node ~/.claude/bin/qualia-ui.js ok "Ready for final ERP report"
-node ~/.claude/bin/qualia-ui.js end "DELIVERED" "/qualia-report"
+node ${QUALIA_BIN}/qualia-ui.js ok "Production URL verified"
+node ${QUALIA_BIN}/qualia-ui.js ok "Documentation updated"
+node ${QUALIA_BIN}/qualia-ui.js ok "Client assets archived + handoff doc written"
+node ${QUALIA_BIN}/qualia-ui.js ok "Ready for final ERP report"
+node ${QUALIA_BIN}/qualia-ui.js end "DELIVERED" "/qualia-report"
 ```
 
 ## Rules

package/skills/qualia-help/SKILL.md

@@ -58,9 +58,9 @@ fi
 ### 3. Confirm
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner router
-node ~/.claude/bin/qualia-ui.js ok "Reference guide opened in browser"
-node ~/.claude/bin/qualia-ui.js info "File: /tmp/qualia-help.html"
+node ${QUALIA_BIN}/qualia-ui.js banner router
+node ${QUALIA_BIN}/qualia-ui.js ok "Reference guide opened in browser"
+node ${QUALIA_BIN}/qualia-ui.js info "File: /tmp/qualia-help.html"
 ```
 
 If the browser does not open automatically, tell the user the file path so they can open it manually.

package/skills/qualia-hook-gen/SKILL.md

@@ -128,7 +128,7 @@ Two scopes:
 | Scope | Action |
 |---|---|
 | `--scope project` (default for project rules) | Add the patch to `.claude/settings.json` in the project root |
-| `--scope global` | Add to `~/.claude/settings.json`. Use only if rule applies to ALL projects |
+| `--scope global` | Add to `${QUALIA_HOME}/settings.json`. Use only if rule applies to ALL projects |
 
 Use the existing settings-merge logic from `bin/install.js:756-778` (preserves user fields, atomic write, backup-before-overwrite).
 

package/skills/qualia-idk/SKILL.md

@@ -29,8 +29,8 @@ Run `/qualia` first when the user knows what they're trying to do. Run `/qualia-
 ### Step 0. Banner
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner router
-node ~/.claude/bin/qualia-ui.js spawn "diagnostic" "Reading planning and codebase in isolation..."
+node ${QUALIA_BIN}/qualia-ui.js banner router
+node ${QUALIA_BIN}/qualia-ui.js spawn "diagnostic" "Reading planning and codebase in isolation..."
 ```
 
 Say: **"Let me take a proper look."**
@@ -143,8 +143,8 @@ If one of these maps to an existing Qualia command, use it:
 ### Step 4. Close
 
 ```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js end "DIAGNOSED" "{top-recommended action if it's a command, else leave blank}"
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js end "DIAGNOSED" "{top-recommended action if it's a command, else leave blank}"
 ```
 
 ## Rules

package/skills/qualia-issues/SKILL.md

@@ -34,7 +34,7 @@ This skill cannot work meaningfully without:
 
 ### 1. Determine phase
 
-Phase number from `$ARGUMENTS` if provided, else current from `node ~/.claude/bin/state.js check`.
+Phase number from `$ARGUMENTS` if provided, else current from `node ${QUALIA_BIN}/state.js check`.
 
 ### 2. Load substrate
 
@@ -138,7 +138,7 @@ Filed {date}. Status: open queue.
 git add .planning/phase-{N}-issues.md
 git commit -m "docs(phase-{N}): externalize {N_slices} slices to GH issue queue"
 
-node ~/.claude/bin/qualia-ui.js end "QUEUE FILED" "/qualia-triage"
+node ${QUALIA_BIN}/qualia-ui.js end "QUEUE FILED" "/qualia-triage"
 ```
 
 ## Rules

package/skills/qualia-learn/SKILL.md

@@ -12,7 +12,7 @@ allowed-tools:
 
 # /qualia-learn — Save Knowledge
 
-Persist learnings across projects and sessions. Saved to `~/.claude/knowledge/`.
+Persist learnings across projects and sessions. Saved to `${QUALIA_KNOWLEDGE}/`.
 
 ## Usage
 
@@ -39,7 +39,7 @@ Client-specific preferences, design choices, requirements.
 ## Process
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner learn
+node ${QUALIA_BIN}/qualia-ui.js banner learn
 ```
 
 ### 1. Classify
@@ -60,7 +60,7 @@ unified loader, **never** raw `cat` or `grep` directly — the loader handles
 missing-file edge cases and stays consistent across skills.
 
 ```bash
-node ~/.claude/bin/knowledge.js search "{title keywords}"
+node ${QUALIA_BIN}/knowledge.js search "{title keywords}"
 ```
 
 If a near-match exists:
@@ -76,7 +76,7 @@ detection, and the canonical entry format — one call, no shell escaping
 concerns:
 
 ```bash
-node ~/.claude/bin/knowledge.js append \
+node ${QUALIA_BIN}/knowledge.js append \
   --type {pattern|fix|client} \
   --title "{Title}" \
   --body "{The learning — be specific enough that future-you understands without context}" \
@@ -102,24 +102,24 @@ to bootstrap it.
 
 ## Reading Knowledge
 
-**Always use the loader.** Hardcoded `cat ~/.claude/knowledge/X.md` is an
+**Always use the loader.** Hardcoded `cat ${QUALIA_KNOWLEDGE}/X.md` is an
 anti-pattern — it makes new files invisible (this was v4.1.0 audit finding
 #3). The loader, by contrast, lets agents discover available knowledge via
 the index.
 
 ```bash
 # Print the index (entry point — read this first)
-node ~/.claude/bin/knowledge.js
+node ${QUALIA_BIN}/knowledge.js
 
 # Print a specific file (accepts aliases: patterns, fixes, client)
-node ~/.claude/bin/knowledge.js load patterns
-node ~/.claude/bin/knowledge.js load common-fixes.md
+node ${QUALIA_BIN}/knowledge.js load patterns
+node ${QUALIA_BIN}/knowledge.js load common-fixes.md
 
 # List everything available
-node ~/.claude/bin/knowledge.js list
+node ${QUALIA_BIN}/knowledge.js list
 
 # Search across all files
-node ~/.claude/bin/knowledge.js search "RLS"
+node ${QUALIA_BIN}/knowledge.js search "RLS"
 ```
 
 The `/qualia-debug` skill should check `common-fixes.md` (`load fixes`) before

package/skills/qualia-map/SKILL.md

@@ -46,7 +46,7 @@ If `ALREADY_MAPPED`, ask:
 ### 2. Banner
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner map
+node ${QUALIA_BIN}/qualia-ui.js banner map
 ```
 
 ### 3. Spawn 5 Mapper Agents (parallel)
@@ -175,7 +175,7 @@ git commit -m "docs: map existing codebase"
 ### 7. Route
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "CODEBASE MAPPED" "/qualia-new"
+node ${QUALIA_BIN}/qualia-ui.js end "CODEBASE MAPPED" "/qualia-new"
 ```
 
 ## What `/qualia-new` Does With This

package/skills/qualia-milestone/SKILL.md

@@ -29,7 +29,7 @@ Triggered after `/qualia-verify` passes on the LAST phase of the current milesto
 ### 1. Validate Readiness
 
 ```bash
-node ~/.claude/bin/state.js check
+node ${QUALIA_BIN}/state.js check
 ```
 
 `state.js close-milestone` enforces two guards:
@@ -67,7 +67,7 @@ Roadmapper prompt for the extension:
 
 ```
 Agent(prompt="
-Read your role: @~/.claude/agents/roadmapper.md
+Read your role: @${QUALIA_AGENTS}/roadmapper.md
 
 <mode>extend-demo-to-full</mode>
 <existing_journey>.planning/JOURNEY.md</existing_journey>
@@ -95,8 +95,8 @@ milestone when /qualia-milestone opens each one.
 **If "Demo only — close here":** treat the demo as a shipped-and-done project. Skip Steps 2-9 of the normal flow. Just run:
 
 ```bash
-node ~/.claude/bin/state.js close-milestone --force
-node ~/.claude/bin/qualia-ui.js end "DEMO SHIPPED" "/qualia-report"
+node ${QUALIA_BIN}/state.js close-milestone --force
+node ${QUALIA_BIN}/qualia-ui.js end "DEMO SHIPPED" "/qualia-report"
 ```
 
 In `--auto` mode, inline-invoke `/qualia-report` and stop.
@@ -104,7 +104,7 @@ In `--auto` mode, inline-invoke `/qualia-report` and stop.
 **If "Pause":** stop, show:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js info "Demo milestone left open. Run /qualia-milestone again when you decide."
+node ${QUALIA_BIN}/qualia-ui.js info "Demo milestone left open. Run /qualia-milestone again when you decide."
 ```
 
 If the demo branch did NOT fire (full project, or demo with multiple milestones already after extension), continue to Step 2.
@@ -112,8 +112,8 @@ If the demo branch did NOT fire (full project, or demo with multiple milestones
 ### 2. Banner + Confirm
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner milestone
-node ~/.claude/bin/qualia-ui.js journey-tree .planning/JOURNEY.md
+node ${QUALIA_BIN}/qualia-ui.js banner milestone
+node ${QUALIA_BIN}/qualia-ui.js journey-tree .planning/JOURNEY.md
 ```
 
 The journey-tree shows the user WHERE they are on the ladder before asking the close question. Read `.planning/JOURNEY.md` to find the next milestone's name + scope. Show:
@@ -152,7 +152,7 @@ Edit `.planning/REQUIREMENTS.md`:
 Closes current milestone's counters, appends a summary to `tracking.json` milestones[]:
 
 ```bash
-node ~/.claude/bin/state.js close-milestone
+node ${QUALIA_BIN}/state.js close-milestone
 ```
 
 If all phases are verified and ≥ 2 phases exist, this succeeds without `--force`. Otherwise add `--force` (rare — usually means the user is closing a preview/demo milestone).
@@ -180,7 +180,7 @@ Spawn the roadmapper with the next milestone's JOURNEY.md sketch as input:
 
 ```
 Agent(prompt="
-Read your role: @~/.claude/agents/roadmapper.md
+Read your role: @${QUALIA_AGENTS}/roadmapper.md
 
 <mode>next-milestone</mode>
 <journey_file>.planning/JOURNEY.md</journey_file>
@@ -198,7 +198,7 @@ Do NOT re-plan completed milestones. Do NOT create a new JOURNEY.md — the
 existing one stays the source of truth.
 
 After writing ROADMAP.md, update STATE.md via:
-  node ~/.claude/bin/state.js init --force \\
+  node ${QUALIA_BIN}/state.js init --force \\
     --project '{project}' --client '{client}' --type '{type}' \\
     --milestone_name '{next name}' \\
     --phases '<JSON: next milestone phases>' \\
@@ -221,8 +221,8 @@ git commit -m "milestone: close M{N} ({current name}) → open M{N+1} ({next nam
 **Case A: this WAS the Handoff milestone closing → project is done.**
 
 ```bash
-node ~/.claude/bin/qualia-ui.js milestone-complete {N} "Handoff" ""
-node ~/.claude/bin/qualia-ui.js end "PROJECT SHIPPED" "/qualia-report"
+node ${QUALIA_BIN}/qualia-ui.js milestone-complete {N} "Handoff" ""
+node ${QUALIA_BIN}/qualia-ui.js end "PROJECT SHIPPED" "/qualia-report"
 ```
 
 In `--auto` mode, inline-invoke `/qualia-report` and stop. No further chaining — the project is done.
@@ -230,7 +230,7 @@ In `--auto` mode, inline-invoke `/qualia-report` and stop. No further chaining
 **Case B: a non-final milestone just closed → next milestone is open.**
 
 ```bash
-node ~/.claude/bin/qualia-ui.js milestone-complete {N} "{current name}" "{next name}"
+node ${QUALIA_BIN}/qualia-ui.js milestone-complete {N} "{current name}" "{next name}"
 ```
 
 **In `--auto` mode**, pause here and ask (this is ONE of the two human gates in auto mode, the other being journey approval at `/qualia-new` time):
@@ -244,13 +244,13 @@ node ~/.claude/bin/qualia-ui.js milestone-complete {N} "{current name}" "{next n
 If "Continue": the auto-chain resumes. If "Pause": stop, show:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "M{N} CLOSED · M{N+1} READY" "/qualia-plan 1 --auto"
+node ${QUALIA_BIN}/qualia-ui.js end "M{N} CLOSED · M{N+1} READY" "/qualia-plan 1 --auto"
 ```
 
 **In guided mode**, always stop and show the next step regardless of position:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "M{N} CLOSED · M{N+1} OPEN" "/qualia-plan 1"
+node ${QUALIA_BIN}/qualia-ui.js end "M{N} CLOSED · M{N+1} OPEN" "/qualia-plan 1"
 ```
 
 ## What Stays, What Changes

package/skills/qualia-new/REFERENCE.md

@@ -9,7 +9,7 @@ Spawn all 4 as parallel `Agent()` calls in a single message. Each uses the same
 
 ```
 Agent(prompt="
-Read your role: @~/.claude/agents/researcher.md
+Read your role: @${QUALIA_AGENTS}/researcher.md
 
 <dimension>stack</dimension>
 <domain>{inferred domain from PROJECT.md}</domain>
@@ -19,7 +19,7 @@ Read your role: @~/.claude/agents/researcher.md
 ", subagent_type="qualia-researcher", description="Stack research")
 
 Agent(prompt="
-Read your role: @~/.claude/agents/researcher.md
+Read your role: @${QUALIA_AGENTS}/researcher.md
 
 <dimension>features</dimension>
 <domain>{inferred domain}</domain>
@@ -29,7 +29,7 @@ Read your role: @~/.claude/agents/researcher.md
 ", subagent_type="qualia-researcher", description="Features research")
 
 Agent(prompt="
-Read your role: @~/.claude/agents/researcher.md
+Read your role: @${QUALIA_AGENTS}/researcher.md
 
 <dimension>architecture</dimension>
 <domain>{inferred domain}</domain>
@@ -39,7 +39,7 @@ Read your role: @~/.claude/agents/researcher.md
 ", subagent_type="qualia-researcher", description="Architecture research")
 
 Agent(prompt="
-Read your role: @~/.claude/agents/researcher.md
+Read your role: @${QUALIA_AGENTS}/researcher.md
 
 <dimension>pitfalls</dimension>
 <domain>{inferred domain}</domain>
@@ -55,7 +55,7 @@ Spawn after all 4 researchers complete.
 
 ```
 Agent(prompt="
-Read your role: @~/.claude/agents/research-synthesizer.md
+Read your role: @${QUALIA_AGENTS}/research-synthesizer.md
 
 Merge the 4 research files at .planning/research/ into .planning/research/SUMMARY.md.
 This is a multi-milestone project -- the SUMMARY must suggest a FULL milestone arc
@@ -70,7 +70,7 @@ Spawn with full-journey mandate. If the user passed `--full-detail`, set `<full_
 
 ```
 Agent(prompt="
-Read your role: @~/.claude/agents/roadmapper.md
+Read your role: @${QUALIA_AGENTS}/roadmapper.md
 
 <task>
 Create the FULL JOURNEY for this project:
@@ -82,7 +82,7 @@ User-scoped v1 features:
 {list of features selected in Step 9, grouped by category}
 
 Template type: {template_type from config.json}
-If set, use ~/.claude/qualia-templates/projects/{type}.md as the milestone arc starting point.
+If set, use ${QUALIA_TEMPLATES}/projects/{type}.md as the milestone arc starting point.
 
 <full_detail>{true if --full-detail, else false}</full_detail>
   - false (default): Milestone 1 gets full phase detail; M2..M{N-1} stay as sketches. Detail fills in when each milestone opens via /qualia-milestone.
@@ -92,7 +92,7 @@ The final milestone MUST be named 'Handoff' with the fixed 4 phases
 (Polish, Content + SEO, Final QA, Handoff). Do not omit it.
 
 After writing, update STATE.md via:
-  node ~/.claude/bin/state.js init \
+  node ${QUALIA_BIN}/state.js init \
     --project '{name}' --client '{client}' --type '{type}' \
     --milestone_name '{Milestone 1 name}' \
     --phases '<JSON: Milestone 1 phases only>' \
@@ -103,7 +103,7 @@ After writing, update STATE.md via:
 
 ## Journey ladder format
 
-The branded journey ladder rendered in Step 11. Use `node ~/.claude/bin/qualia-ui.js journey-tree .planning/JOURNEY.md` for the programmatic version. The manual ASCII fallback format is below.
+The branded journey ladder rendered in Step 11. Use `node ${QUALIA_BIN}/qualia-ui.js journey-tree .planning/JOURNEY.md` for the programmatic version. The manual ASCII fallback format is below.
 
 ```
 ## Proposed Journey