qualia-framework 6.2.9 → 6.3.0

package/skills/qualia-fix/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: qualia-fix
+description: "Practical repair lane for broken existing behavior. Combines root-cause investigation with /qualia-feature execution discipline. 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 root-cause evidence gathering 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-review`
+- Visual craft/design quality with no functional bug -> `/qualia-polish`
+- Whole-site aesthetic pivot -> `/qualia-polish --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-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-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,27 +102,27 @@ 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
+The `/qualia-fix` skill should check `common-fixes.md` (`load fixes`) before
 investigating. The `/qualia-new` skill should check `client-prefs.md`
 (`load client`) when setting up client projects. The `/qualia-plan` skill
 should check `learned-patterns.md` (`load patterns`) when planning phases.

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.