qualia-framework 6.2.9 → 6.2.10

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

package/skills/qualia-new/SKILL.md

@@ -43,7 +43,7 @@ Initialize a project with the **entire arc mapped from kickoff to handoff**. All
 ### Step 0. Banner
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner new
+node ${QUALIA_BIN}/qualia-ui.js banner new
 ```
 
 Banner only. Do NOT ask anything yet. The next thing the user sees is the project-shape gate — not a free-text "tell me what to build". Shape gate first, content second, because the shape drives the question set.
@@ -122,7 +122,7 @@ If "More questions": re-invoke `/qualia-discuss` for additional rounds. Otherwis
 
 ### Step 5. Detect Project Type
 
-From questioning answers, infer type → `website` | `ai-agent` | `voice-agent` | `mobile-app` | `null`. If matched, `cat ~/.claude/qualia-templates/projects/{type}.md` gives suggested milestone arc. Store `template_type` for Step 13.
+From questioning answers, infer type → `website` | `ai-agent` | `voice-agent` | `mobile-app` | `null`. If matched, `cat ${QUALIA_TEMPLATES}/projects/{type}.md` gives suggested milestone arc. Store `template_type` for Step 13.
 
 ### Step 6. Design Direction (frontend only)
 
@@ -140,7 +140,7 @@ Plus free-text: "Any brand colors or reference sites I should look at?"
 
 If client, ask name. Check saved prefs:
 ```bash
-node ~/.claude/bin/knowledge.js search "{client name}"
+node ${QUALIA_BIN}/knowledge.js search "{client name}"
 ```
 
 ### Step 8. Write PROJECT.md
@@ -159,11 +159,11 @@ The domain glossary is the single highest-leverage piece of substrate — every
 
 ```bash
 # Copy template
-cp ~/.claude/qualia-templates/CONTEXT.md .planning/CONTEXT.md
+cp ${QUALIA_TEMPLATES}/CONTEXT.md .planning/CONTEXT.md
 
 # Initialize ADR folder with the template available for reference
 mkdir -p .planning/decisions
-cp ~/.claude/qualia-templates/decisions/ADR-template.md .planning/decisions/_template.md
+cp ${QUALIA_TEMPLATES}/decisions/ADR-template.md .planning/decisions/_template.md
 ```
 
 Then **seed the glossary from the questioning answers**. For each domain term that came up during the Step 4 `/qualia-discuss` interview — entities, actions, statuses, key nouns the user repeatedly said — add an entry to `.planning/CONTEXT.md` under `## Language` with:
@@ -252,7 +252,7 @@ git commit -m "docs: DESIGN.md — direction commit + OKLCH palette + tokens"
 Only `/qualia-new --quick` skips this step.
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner research
+node ${QUALIA_BIN}/qualia-ui.js banner research
 mkdir -p .planning/research
 ```
 
@@ -275,7 +275,7 @@ git commit -m "docs: research synthesis (4 dimensions, multi-milestone scope)"
 
 Show key findings:
 ```bash
-node ~/.claude/bin/qualia-ui.js ok "Research complete"
+node ${QUALIA_BIN}/qualia-ui.js ok "Research complete"
 ```
 Display top 3 from SUMMARY.md (stack recommendation, table stakes, top pitfall).
 
@@ -300,7 +300,7 @@ Gather any additional requirements the user wants that research missed.
 ### Step 13. Run Roadmapper
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner roadmap
+node ${QUALIA_BIN}/qualia-ui.js banner roadmap
 ```
 
 **Roadmapper output branches on `PROJECT_TYPE`:**
@@ -315,7 +315,7 @@ Spawn the roadmapper with `<project_type>$PROJECT_TYPE</project_type>` in the pr
 Render the branded journey ladder:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js journey-tree .planning/JOURNEY.md
+node ${QUALIA_BIN}/qualia-ui.js journey-tree .planning/JOURNEY.md
 ```
 
 This shows M1..M{N} as a vertical ladder: shipped milestones get a green dot, current gets a teal diamond with `[CURRENT]` tag, future get dim open circles. Handoff gets `[FINAL]` tag. Why-now + phase sketch render under current and final.
@@ -345,9 +345,9 @@ git commit -m "docs: journey + requirements + milestone 1 roadmap ({N} milestone
 **After approval, show the progressive-detail reminder explicitly:**
 
 ```bash
-node ~/.claude/bin/qualia-ui.js info "Milestone 1 is fully planned now."
-node ~/.claude/bin/qualia-ui.js info "Milestones 2..{N-1} are sketched (names + one-line goals)."
-node ~/.claude/bin/qualia-ui.js info "Full phase detail for each later milestone gets written when /qualia-milestone opens it."
+node ${QUALIA_BIN}/qualia-ui.js info "Milestone 1 is fully planned now."
+node ${QUALIA_BIN}/qualia-ui.js info "Milestones 2..{N-1} are sketched (names + one-line goals)."
+node ${QUALIA_BIN}/qualia-ui.js info "Full phase detail for each later milestone gets written when /qualia-milestone opens it."
 ```
 
 (Skip this block when `--full-detail` was used — all milestones are already fully planned in that case.)
@@ -368,7 +368,7 @@ git commit -m "chore: environment setup" 2>/dev/null
 If invoked with `--auto`, skip straight into building Milestone 1:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js info "Auto mode — chaining into /qualia-plan 1"
+node ${QUALIA_BIN}/qualia-ui.js info "Auto mode — chaining into /qualia-plan 1"
 ```
 
 Then inline-invoke `/qualia-plan 1`. That skill will chain into `/qualia-build 1 → /qualia-verify 1 → /qualia-plan 2 → ...` until Milestone 1's last phase verifies, at which point the chain pauses at the milestone boundary and asks:
@@ -380,7 +380,7 @@ Then inline-invoke `/qualia-plan 1`. That skill will chain into `/qualia-build 1
 **Without `--auto`**, end with a clear pointer:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "JOURNEY READY" "/qualia-plan 1"
+node ${QUALIA_BIN}/qualia-ui.js end "JOURNEY READY" "/qualia-plan 1"
 ```
 
 Show summary:

package/skills/qualia-optimize/REFERENCE.md

@@ -258,7 +258,7 @@ Constraints:
 )
 ```
 
-After all 3 return, present a comparison table to the user (see SKILL.md Step 5b). User picks 1, 2, 3, or hybrid. Then a single synthesizer agent writes the Refactor RFC to `.planning/REFACTOR-{slug}.md` honoring the user's pick.
+After all 3 return, present a comparison table to the user (see SKILL.md Step 5b). User picks 1, 2, 3, or hybrid. Then a single synthesizer agent writes the Refactor RFC to `.planning/reports/refactor/REFACTOR-{slug}.md` honoring the user's pick.
 
 **Token cost**: ~6K per variant × 3 variants = ~18K for the fan-out. Cached prefix (CONTEXT.md + ADRs + candidate block) is shared across the 3 spawns, so effective cost is closer to ~12K. The output rfc-pick stage adds ~3K. Total per-deepening-candidate: ~15K — well within Qualia's per-skill budget.