qualia-framework 6.2.10 → 6.4.0

package/tests/state.test.sh

@@ -4,9 +4,40 @@
 
 PASS=0
 FAIL=0
-# Resolve STATE_JS to an ABSOLUTE path so `cd` inside subshells doesn't break it.
-STATE_JS="$(cd "$(dirname "$0")/../bin" && pwd)/state.js"
-FRAMEWORK_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+# Windows portability — coerce shell-native MSYS paths (/d/a/..., /tmp/...) to
+# Windows-native form (D:/a/..., C:/Users/.../Temp/...) before they get
+# interpolated into Node `$NODE -e` snippets. Without coercion, Node receives
+# the MSYS string literally and resolves it against the current drive, yielding
+# non-existent paths like `D:\tmp\tmp.XXX\.planning\tracking.json`.
+#
+# Mechanism: `cygpath -m` is the canonical MSYS path converter and is present
+# on Git Bash / MSYS2 (Windows GitHub runners use Git Bash for `shell: bash`).
+# `pwd -W` doesn't work because bash's builtin pwd doesn't accept -W, and
+# /usr/bin/pwd's -W support varies by MSYS distribution.
+# On Linux/macOS, cygpath doesn't exist — fall through to plain pwd.
+_pwd_native() {
+  local p
+  p=$(pwd)
+  if command -v cygpath >/dev/null 2>&1; then
+    cygpath -m "$p" 2>/dev/null || echo "$p"
+  else
+    echo "$p"
+  fi
+}
+_mktemp_native() {
+  local d
+  d=$(mktemp -d) || return 1
+  if command -v cygpath >/dev/null 2>&1; then
+    cygpath -m "$d" 2>/dev/null || echo "$d"
+  else
+    echo "$d"
+  fi
+}
+
+# Resolve STATE_JS to an ABSOLUTE Windows-native path so `cd` inside subshells
+# doesn't break it.
+STATE_JS="$(cd "$(dirname "$0")/../bin" && _pwd_native)/state.js"
+FRAMEWORK_DIR="$(cd "$(dirname "$0")/.." && _pwd_native)"
 STATE_LEDGER_JS="$FRAMEWORK_DIR/bin/state-ledger.js"
 NODE="${NODE:-node}"
 
@@ -23,7 +54,7 @@ trap cleanup EXIT
 # Prints the absolute path to the new tmp dir (does NOT cd).
 make_project() {
   local TMP
-  TMP=$(mktemp -d)
+  TMP=$(_mktemp_native)
   TMP_DIRS+=("$TMP")
   (
     cd "$TMP" || exit 1
@@ -75,6 +106,47 @@ Goal: Test goal
 PLAN
 }
 
+make_valid_contract() {
+  local dir="$1"
+  local phase="${2:-1}"
+  cat > "$dir/.planning/phase-${phase}-contract.json" <<'JSON'
+{
+  "version": 1,
+  "phase": 1,
+  "goal": "Test goal",
+  "why": "Exercise machine evidence",
+  "generated_at": "2026-05-23T00:00:00.000Z",
+  "generated_by": "manual",
+  "source_plan_hash": "",
+  "success_criteria": ["Machine check passes"],
+  "tasks": [
+    {
+      "id": "T1",
+      "title": "Machine check",
+      "wave": 1,
+      "depends_on": [],
+      "persona": "none",
+      "files_modify": [],
+      "files_create": [],
+      "files_delete": [],
+      "acceptance_criteria": ["Node command exits 0"],
+      "action": "Run deterministic evidence check",
+      "context_files": [],
+      "verification": [
+        {
+          "type": "command-exit",
+          "command": "node",
+          "args": ["-e", "process.exit(0)"],
+          "expected_exit": 0,
+          "timeout_ms": 5000
+        }
+      ]
+    }
+  ]
+}
+JSON
+}
+
 echo "=== state.js Behavioral Tests ==="
 echo ""
 
@@ -88,7 +160,7 @@ fi
 echo "basic I/O:"
 
 # 1. cmdInit produces valid tracking.json + STATE.md
-TMP=$(mktemp -d); TMP_DIRS+=("$TMP")
+TMP=$(_mktemp_native); TMP_DIRS+=("$TMP")
 (
   cd "$TMP" || exit 1
   $NODE "$STATE_JS" init \
@@ -149,7 +221,7 @@ else
 fi
 
 # 3. cmdCheck with no project → ok:false NO_PROJECT, exit 1
-TMP2=$(mktemp -d); TMP_DIRS+=("$TMP2")
+TMP2=$(_mktemp_native); TMP_DIRS+=("$TMP2")
 OUT=$(cd "$TMP2" && $NODE "$STATE_JS" check 2>&1)
 CHECK_EXIT=$?
 if [ "$CHECK_EXIT" -eq 1 ] \
@@ -213,6 +285,33 @@ else
   fail_case "built → verified(pass) auto-advance" "exit=$EXIT out=$OUT"
 fi
 
+# 6b. verified(pass) refuses when a contract exists but machine evidence is missing
+TMP=$(make_project)
+make_valid_plan "$TMP" 1
+make_valid_contract "$TMP" 1
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 1 --tasks-total 1 >/dev/null 2>&1)
+echo "result: PASS" > "$TMP/.planning/phase-1-verification.md"
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass 2>&1)
+EXIT=$?
+if [ "$EXIT" -ne 0 ] && echo "$OUT" | grep -q '"error": "MISSING_EVIDENCE"'; then
+  pass "verified(pass) refuses missing machine evidence when contract exists"
+else
+  fail_case "verified(pass) missing evidence guard" "exit=$EXIT out=$OUT"
+fi
+
+# 6c. verified(pass) succeeds after contract-runner writes passing evidence
+(cd "$TMP" && $NODE "$FRAMEWORK_DIR/bin/contract-runner.js" .planning/phase-1-contract.json >/dev/null 2>&1)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"ok": true' \
+   && echo "$OUT" | grep -q '"phase": 2'; then
+  pass "verified(pass) accepts passing machine evidence"
+else
+  fail_case "verified(pass) with machine evidence" "exit=$EXIT out=$OUT"
+fi
+
 # 7. built → verified(fail) stays on phase 1, records verification=fail
 TMP=$(make_project)
 make_valid_plan "$TMP" 1
@@ -946,7 +1045,7 @@ else
 fi
 
 # 49. First-time init (no existing tracking.json) sets lifetime to zeros
-TMP=$(mktemp -d); TMP_DIRS+=("$TMP")
+TMP=$(_mktemp_native); TMP_DIRS+=("$TMP")
 (cd "$TMP" && $NODE "$STATE_JS" init \
   --project "FreshProject" \
   --phases '[{"name":"P1","goal":"G1"}]' \

package/skills/qualia-debug/SKILL.md

@@ -1,193 +0,0 @@
----
-name: qualia-debug
-description: "Investigation lane for unclear bugs and weird behavior. Parses symptoms, runs diagnostic scans, identifies root cause, and either reports insufficient evidence or routes actionable repair work to /qualia-fix. Trigger on 'debug', 'find bug', 'why is this broken', 'something is weird', 'investigate', 'root cause', 'not sure what's failing', 'CSS issue', 'slow page', 'performance'."
-allowed-tools:
-  - Bash
-  - Read
-  - Edit
-  - Write
-  - Grep
-  - Glob
-  - Agent
----
-
-# /qualia-debug — Investigative Debugging (one-shot)
-
-Parse the symptom. Run diagnostics. Find root cause. Write report, or route to `/qualia-fix` when the repair is actionable. **One-shot — no mandatory user questions.**
-
-## Usage
-
-- `/qualia-debug {symptom}` — investigate a specific symptom
-- `/qualia-debug` — no symptom given: investigate recently-changed files for obvious bugs
-- `/qualia-debug --frontend {symptom}` — layout/z-index/overflow bias
-- `/qualia-debug --perf {symptom}` — performance bias
-
-If the user says "fix it" and the expected behavior is known, prefer `/qualia-fix`. Debug is for uncertainty; fix is for repair.
-
-## Tool Budget
-
-Max 10 Read/Grep/Bash calls for investigation. If you haven't narrowed to root cause in 10, return `INSUFFICIENT EVIDENCE after 10 steps. Narrowed to: {files}. Recommend: {next diagnostic}.` Do not keep guessing.
-
-## Process
-
-```bash
-node ${QUALIA_BIN}/qualia-ui.js banner debug
-```
-
-### 1. Parse Symptom from $ARGUMENTS
-
-- If arguments provided → that's the symptom. Extract: what's broken, where (file/page/feature), when (on click? on load? after change?).
-- If arguments empty → run `git diff HEAD~3 --stat` to find recently-touched files. Treat those as the suspect set. Symptom = "something in recent changes".
-
-### 2. Check Known Fixes First (cheap)
-
-```bash
-node ${QUALIA_BIN}/knowledge.js search "{symptom_keywords}"
-```
-
-If a known fix matches, apply it and jump to step 5 (verify). Known fixes are pre-verified patterns — no need to re-investigate.
-
-### 3. Diagnostic Scan
-
-Run the scan matching the symptom type. All commands in a scan block run as parallel Bash calls in a single response turn.
-
-**General mode (default):**
-```bash
-# Compile errors
-npx tsc --noEmit 2>&1 | grep "error TS" | head -20
-
-# Empty catch / swallowed errors
-grep -rn "catch\s*{}\|catch\s*(.*)\s*{\s*}" --include="*.ts" --include="*.tsx" app/ components/ src/ lib/ 2>/dev/null | head -10
-
-# Recent console.error or thrown errors
-grep -rn "console\.error\|throw new" --include="*.ts" --include="*.tsx" app/ components/ src/ lib/ 2>/dev/null | head -10
-
-# Broken imports
-npx tsc --noEmit 2>&1 | grep -i "Cannot find module\|has no exported"
-```
-
-**Frontend mode (`--frontend`):**
-```bash
-# Stacking context audit (z-index issues)
-grep -rn "z-index\|z-\[" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null | head -20
-
-# Overflow candidates (horizontal scroll, clipping)
-grep -rn "100vw\|overflow.*hidden\|overflow-x\|position.*fixed" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null | head -15
-
-# Fixed dimensions breaking mobile
-grep -rn "width:.*[0-9]\+px\|height:.*[0-9]\+px\|w-\[[0-9]\+px\|h-\[[0-9]\+px" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null | grep -v "min-\|max-" | head -10
-
-# Flex/grid blowout candidates
-grep -rn "flex\|grid" --include="*.tsx" app/ components/ src/ 2>/dev/null | grep -v "min-w-0\|minmax(0" | wc -l
-```
-
-**Perf mode (`--perf`):**
-```bash
-# Sequential awaits that should be Promise.all
-grep -rn "const.*=.*await" --include="*.tsx" --include="*.ts" app/ src/ 2>/dev/null | grep -v "Promise.all\|Promise.allSettled" | head -15
-
-# Large files
-find app/ components/ src/ -name "*.tsx" -o -name "*.ts" 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -10
-
-# Missing next/image
-grep -rn "<img " --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null | grep -v "next/image" | wc -l
-
-# No dynamic imports (possible big bundles)
-grep -rn "import(\|next/dynamic" --include="*.tsx" --include="*.ts" app/ src/ 2>/dev/null | wc -l
-
-# Client-boundary usage
-grep -rln "'use client'" --include="*.tsx" app/ components/ src/ 2>/dev/null | wc -l
-```
-
-### 4. Form Hypothesis + Route or Apply Minimal Fix
-
-From the diagnostic output, state the root cause in one sentence with `file:line` citation. No hedging — either you have evidence or you write `INSUFFICIENT EVIDENCE` and return (step 6).
-
-If the user explicitly asked for repair and the fix is <= 3 files, route to `/qualia-fix {symptom}` with the root cause summary. If this debug invocation is already mid-repair, apply the minimal fix here for backward compatibility.
-
-Apply the minimal fix:
-- Only edit files whose contents caused the symptom
-- One concept per commit — don't fold in cleanup
-- Don't refactor adjacent code
-- If the fix touches > 3 files, stop and ask the user first (major refactor disguised as a debug)
-
-### 5. Verify Fix
-
-```bash
-# TypeScript still compiles?
-npx tsc --noEmit 2>&1 | grep -c "error TS"   # Expect 0
-
-# Symptom reproduction — ideally a grep that would have matched the bug
-# and now returns empty:
-grep -rn "{pattern that represented the bug}" {scope} 2>/dev/null
-```
-
-If the verification fails, revert and return to step 3 with narrower hypothesis.
-
-### 6. Write DEBUG Report
-
-Create the report directory and write to `.planning/reports/debug/DEBUG-{YYYY-MM-DD-HHMM}.md`:
-
-```bash
-mkdir -p .planning/reports/debug
-```
-
-```markdown
-# Debug Report — {YYYY-MM-DD HH:MM}
-
-**Symptom:** {user description or "recent changes" if no args}
-**Mode:** general | frontend | perf
-**Tool calls used:** {N}/10
-
-## Investigation
-- Diagnostic scans run: {list}
-- Files examined: {list}
-- Patterns searched: {list}
-
-## Root Cause
-{file:line} — "{quoted problematic code}" — {explanation of why it caused the symptom}
-
-## Fix Applied
-- Files: {list}
-- Diff summary: {one paragraph}
-- Verification: {commands run + results}
-
-## Related Observations
-- {any adjacent issues noticed but NOT fixed in this debug pass}
-```
-
-### 7. Commit
-
-```bash
-git add {specific files you changed}
-git commit -m "fix: {what was broken and why}"
-```
-
-## INSUFFICIENT EVIDENCE Return
-
-If you exhaust the 10-call budget without a confident root cause:
-
-```markdown
-# Debug Report — {YYYY-MM-DD HH:MM}
-
-**Symptom:** {description}
-**Outcome:** INSUFFICIENT EVIDENCE after 10 inspection steps
-
-## Narrowed To
-- Files examined: {list}
-- Ruled out: {list}
-- Remaining suspects: {list}
-
-## Recommended Next Diagnostic
-- {specific next step for the user — e.g., "run `npm run dev` and watch browser console for the specific error", or "add console.log at file:line and reproduce"}
-```
-
-Do NOT apply a speculative fix. Return the report and stop.
-
-## Rules
-
-- **No mandatory questions.** This is one-shot. If symptom args are missing, investigate recent changes.
-- **Root cause or INSUFFICIENT EVIDENCE** — no "probably" fixes.
-- **Minimal fix only.** One concept, one commit. No refactors dressed as debug. Prefer `/qualia-fix` for explicit repair requests.
-- **Tool budget is hard.** 10 calls, then stop.
-- **Every investigation gets a DEBUG report in `.planning/reports/debug/`** — creates a searchable record without cluttering the root.

package/skills/qualia-flush/SKILL.md

@@ -1,198 +0,0 @@
----
-name: qualia-flush
-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
-  - Write
-  - Edit
-  - Grep
-  - Glob
----
-
-# /qualia-flush — Promote Raw Daily Logs to Curated Concepts
-
-Closes the **raw → wiki** loop in the Qualia memory layer. The Stop hook
-(`hooks/stop-session-log.js`) appends mechanical session checkpoints to
-`${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 ${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
-flush that promotes raw observations into structured wiki articles. We do
-the same — manually-triggered, internal-data only, no vector DB.
-
-## When to run
-
-- **Manually:** `/qualia-flush` whenever the daily-log feels rich. Once a week
-  is the recommended cadence. More than once a day is wasteful — the
-  signal-to-noise ratio is too low at single-day windows.
-- **CLI runner:** `qualia-framework flush` wraps the cron-friendly
-  `bin/knowledge-flush.js` non-interactive runner.
-
-## Inputs
-
-- `--days N` (optional, default 14) — how many days of daily-log to consider
-- `--project NAME` (optional) — only flush entries for one project
-- `--dry-run` (optional) — print the proposed writes, don't touch disk
-
-If the user invokes the skill bare (no args), default to `--days 14` and
-all projects. Show a one-line preview before writing anything destructive.
-
-## Process
-
-### 1. Banner + check the floor
-
-```bash
-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.
-KNOWLEDGE_DIR="$HOME/.claude/knowledge"
-DAILY_DIR="$KNOWLEDGE_DIR/daily-log"
-if [ ! -d "$DAILY_DIR" ]; then
-  echo "QUALIA: No daily-log at $DAILY_DIR — Stop hook hasn't run yet, or knowledge layer wasn't initialized."
-  echo "Run: npx qualia-framework@latest install"
-  exit 1
-fi
-
-# Default 14-day window. Date math is cross-platform-safe with Node.
-WINDOW_DAYS="${WINDOW_DAYS:-14}"
-node -e "
-  const d = new Date();
-  d.setDate(d.getDate() - $WINDOW_DAYS);
-  console.log(d.toISOString().split('T')[0]);
-" > /tmp/qualia-flush-cutoff
-CUTOFF=$(cat /tmp/qualia-flush-cutoff)
-```
-
-### 2. Collect the daily-log entries in window
-
-```bash
-# Iterate every file in daily-log/ whose name (YYYY-MM-DD.md) is >= CUTOFF.
-# Concatenate them into one stream so the LLM (you) can scan as one corpus.
-ls "$DAILY_DIR"/*.md 2>/dev/null | while read -r f; do
-  base=$(basename "$f" .md)
-  if [ "$base" \> "$CUTOFF" ] || [ "$base" = "$CUTOFF" ]; then
-    echo "=== $base ==="
-    cat "$f"
-    echo ""
-  fi
-done
-```
-
-You now have the raw stream. Read it.
-
-### 3. Identify what's worth promoting
-
-Read every entry. Group by project. Look for these signals — these are
-the things that promote into the wiki:
-
-| Signal in raw entry | What to extract | Goes to |
-|---|---|---|
-| Same fix appears in 2+ sessions | A common fix recipe | `common-fixes.md` (via `knowledge.js append --type fix`) |
-| A pattern shows up in 3+ projects | A reusable pattern | `learned-patterns.md` (via `knowledge.js append --type pattern`) |
-| A client-name or project preference recurs | A client preference | `client-prefs.md` (via `knowledge.js append --type client`) |
-| A new technology/library used successfully | A stack note | `concepts/{tech}.md` (new file, Write directly) |
-| A recurring failure mode (verify-fail, regression) | A pitfall | `learned-patterns.md` framed as "anti-pattern: …" |
-
-Things to **NOT** promote:
-- Single-occurrence quirks (they're noise until they recur).
-- Bare commit/branch info — that's already in git, no value duplicating.
-- Anything containing secrets, tokens, customer PII. The knowledge layer
-  is plain markdown, never put secrets here.
-- Entries from `--dry-run` runs of other skills (they'll show as activity
-  but didn't actually do anything).
-
-### 4. Write the promotions
-
-For each thing worth promoting, use the loader's `append`:
-
-```bash
-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.}" \
-  --project "{specific project, or 'general' if cross-project}" \
-  --context "Promoted by /qualia-flush from daily-log entries on {dates}"
-```
-
-For a brand-new topic that doesn't fit pattern/fix/client (e.g. a Stripe
-integration approach worth its own file), Write to
-`${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 ${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
-> top-level + subdirectories (`concepts/`, `daily-log/`) for an exact match.
-> Write durable entries to `concepts/{topic}.md`; the loader will find them.
-
-### 5. Mark the window as flushed
-
-Write a stamp file so subsequent flushes can default to "since the last
-flush" instead of "last 14 days":
-
-```bash
-date -u +%Y-%m-%dT%H:%M:%SZ > "$HOME/.claude/.qualia-last-flush"
-```
-
-### 6. Summarize
-
-Print to the user, in plain language:
-
-- N daily-log files scanned (date range)
-- M promotions written (with file:title for each)
-- K things considered but not promoted (single-occurrence — wait for them to recur)
-
-Format:
-
-```
-⬢ Flushed daily-log {start} → {end} ({N} files, {total entries} entries)
-  Promoted to wiki:
-    + learned-patterns.md  "Supabase RLS in same migration"  (3 sessions, 2 projects)
-    + common-fixes.md      "next/font crash on Vercel"       (2 sessions)
-    + concepts/voice-agent-call-state.md  (new file)
-  Skipped {K} single-occurrence entries — will revisit if they recur.
-```
-
-## Style
-
-- **Be conservative.** False-positive promotions (writing noise as if it's a
-  pattern) pollute the wiki and erode trust. Better to skip a candidate and
-  let it recur next week than to inflate the curated tier.
-- **Cite your sources.** Every promoted entry should reference the
-  daily-log dates that sourced it, in the `--context` field. If a future
-  flush wants to update it, the trail is there.
-- **Keep titles short.** `--title "Supabase RLS same migration"` not `"You should always remember that when working with Supabase you need to..."`. The body is for nuance.
-- **Don't promote private projects across boundaries.** A pattern from
-  Project A is fine to promote as cross-project ONLY if it generalizes.
-  Client-specific things stay client-specific (`--type client --project X`).
-
-## Anti-patterns
-
-- **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 ${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
-  through `knowledge.js append` so the canonical entry format and ID
-  generation stay consistent. This skill is the only sanctioned promoter,
-  but even it uses the loader for writes.
-
-## Output contract
-
-If invoked with `--dry-run`, print the proposed writes and exit without
-touching disk. Otherwise, after step 6 returns the summary, the skill is
-done — no follow-up prompts. The user sees the summary and the wiki tier
-has new entries that are immediately reachable to every other skill via
-the loader.

package/skills/qualia-help/SKILL.md

@@ -1,74 +0,0 @@
----
-name: qualia-help
-description: "Open the BROWSER HTML reference for the Qualia Framework — themed page with all commands, rules, services, and the road. The default when a browser is available. For terminal-only output (SSH, headless), use /qualia-road. Triggers: 'help', 'how does this work', 'show me the commands', 'qualia help', 'reference', 'open the docs'."
-allowed-tools:
-  - Bash
-  - Read
----
-
-# /qualia-help — Framework Reference
-
-Opens a Qualia-themed HTML reference guide in your default browser.
-
-## Process
-
-### 1. Generate the HTML
-
-```bash
-# Read the template and inject the current version.
-# Prefer .qualia-config.json; fall back to the framework package.json; last resort is the
-# literal string "latest" so the UI never lies about a specific version.
-VERSION=$(node -e "
-  const fs = require('fs'), path = require('path'), os = require('os');
-  const cfg = path.join(os.homedir(), '.claude', '.qualia-config.json');
-  const pkg = path.join(os.homedir(), '.claude', 'qualia-framework', 'package.json');
-  try { const v = JSON.parse(fs.readFileSync(cfg,'utf8')).version; if (v) { console.log(v); process.exit(0); } } catch {}
-  try { const v = JSON.parse(fs.readFileSync(pkg,'utf8')).version; if (v) { console.log('v'+v); process.exit(0); } } catch {}
-  console.log('latest');
-" 2>/dev/null || echo "latest")
-TEMPLATE="$HOME/.claude/qualia-templates/help.html"
-OUTPUT="/tmp/qualia-help.html"
-
-# If template doesn't exist in the user home, check the installed framework copy.
-if [ ! -f "$TEMPLATE" ]; then
-  for CANDIDATE in "$HOME/.claude/qualia-framework/templates/help.html"; do
-    if [ -f "$CANDIDATE" ]; then TEMPLATE="$CANDIDATE"; break; fi
-  done
-fi
-```
-
-### 2. Inject version and open
-
-```bash
-# Replace {{VERSION}} placeholder with actual version
-sed "s/{{VERSION}}/$VERSION/g" "$TEMPLATE" > "$OUTPUT"
-
-# Open in default browser (cross-platform)
-if command -v xdg-open &>/dev/null; then
-  xdg-open "$OUTPUT"          # Linux
-elif command -v open &>/dev/null; then
-  open "$OUTPUT"               # macOS
-elif command -v start &>/dev/null; then
-  start "$OUTPUT"              # Windows (Git Bash)
-else
-  echo "Open this file in your browser: $OUTPUT"
-fi
-```
-
-### 3. Confirm
-
-```bash
-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.
-
-## Notes
-
-- The HTML file is self-contained — no external dependencies except Google Fonts
-- Works offline after first load (fonts cache)
-- Qualia-themed: dark background, teal accents, Outfit + Inter fonts
-- Shows: The Road, all commands grouped, verification scoring, rules, stack, GitHub orgs
-- Version is injected dynamically from .qualia-config.json