qualia-framework 4.1.1 → 4.4.0

package/hooks/stop-session-log.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/stop-session-log.js — append a one-line session checkpoint
+// to ~/.claude/knowledge/daily-log/{YYYY-MM-DD}.md.
+//
+// Stop hook (fires when a Claude Code turn ends). This is the seed of the
+// memory layer (v4.2.0): every turn that produced something noteworthy gets a
+// line in today's daily log. Future versions will run an LLM "flush" job over
+// the daily log to promote durable knowledge into the wiki tier.
+//
+// Design constraints:
+//   • NEVER block — exit 0 always, even on internal failure.
+//   • Fast — under 100ms, no network, no LLM call. The log is mechanical.
+//   • Cheap to skip — if there's been no git activity since the last write,
+//     and we wrote a line within the last 5 minutes, we skip. Daily log
+//     stays scannable instead of becoming a turn-by-turn replay.
+//   • No PII / secrets — only project name, branch, phase, task counts,
+//     commit count. Never the contents of files or env vars.
+//
+// Format: append to today's file under a single H2 header per project:
+//
+//   ## qualia-framework
+//   - 14:32 · branch=feat/x · phase=2/4 · tasks=3/5 · commits=2 · touched=src/foo.ts,src/bar.ts
+//   - 16:08 · branch=feat/x · phase=2/4 · tasks=4/5 · commits=4
+//
+// Cross-platform (Windows/macOS/Linux). Zero shell dependencies.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+const _traceStart = Date.now();
+
+const KNOWLEDGE_DIR = path.join(os.homedir(), ".claude", "knowledge");
+const DAILY_DIR = path.join(KNOWLEDGE_DIR, "daily-log");
+const LAST_WRITE_FILE = path.join(os.homedir(), ".claude", ".qualia-last-session-log");
+const MIN_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+function _trace(result, extra) {
+  try {
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    fs.appendFileSync(
+      path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`),
+      JSON.stringify({
+        hook: "stop-session-log",
+        result,
+        timestamp: new Date().toISOString(),
+        duration_ms: Date.now() - _traceStart,
+        ...extra,
+      }) + "\n",
+    );
+  } catch {}
+}
+
+function git(args, opts = {}) {
+  try {
+    const r = spawnSync("git", args, {
+      encoding: "utf8",
+      timeout: 2000,
+      shell: process.platform === "win32",
+      ...opts,
+    });
+    if (r.status !== 0) return "";
+    return (r.stdout || "").trim();
+  } catch {
+    return "";
+  }
+}
+
+function readJson(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+try {
+  // ── Skip if too soon since last write ────────────────────
+  const now = Date.now();
+  let lastWrite = 0;
+  try {
+    if (fs.existsSync(LAST_WRITE_FILE)) {
+      lastWrite = parseInt(fs.readFileSync(LAST_WRITE_FILE, "utf8").trim(), 10) || 0;
+    }
+  } catch {}
+  if (now - lastWrite < MIN_INTERVAL_MS) {
+    _trace("skip", { reason: "interval", since_last_ms: now - lastWrite });
+    process.exit(0);
+  }
+
+  // ── Resolve project context ──────────────────────────────
+  // Operate from the cwd; if not a git repo, fall back to basename.
+  const cwd = process.cwd();
+  const repoRoot = git(["rev-parse", "--show-toplevel"], { cwd }) || cwd;
+  const project = path.basename(repoRoot);
+  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"], { cwd: repoRoot }) || "";
+
+  // Phase + task info from .planning/tracking.json (Qualia projects only).
+  let phase = "";
+  let tasks = "";
+  const tracking = readJson(path.join(repoRoot, ".planning", "tracking.json"));
+  if (tracking) {
+    const p = tracking.phase || 0;
+    const pt = tracking.total_phases || tracking.phase_total || 0;
+    if (pt > 0) phase = `${p}/${pt}`;
+    const td = tracking.tasks_done || 0;
+    const tt = tracking.tasks_total || 0;
+    if (tt > 0) tasks = `${td}/${tt}`;
+  }
+
+  // Commits in this session window — heuristic: commits in last 8 hours by us.
+  // (Stop fires per turn, so a tighter window misses session boundaries.)
+  const commitCount = (() => {
+    const out = git(["log", "--since=8.hours", "--pretty=oneline"], { cwd: repoRoot });
+    if (!out) return 0;
+    return out.split("\n").filter(Boolean).length;
+  })();
+
+  // Top 3 touched files (uncommitted) — useful for resuming next session.
+  const touched = (() => {
+    const out = git(["diff", "--name-only", "HEAD"], { cwd: repoRoot });
+    if (!out) return [];
+    return out.split("\n").filter(Boolean).slice(0, 3);
+  })();
+
+  // Skip if literally nothing happened — no commits, no diff, no phase progress.
+  if (commitCount === 0 && touched.length === 0 && !phase) {
+    _trace("skip", { reason: "no-activity" });
+    process.exit(0);
+  }
+
+  // ── Compose the line ─────────────────────────────────────
+  const time = new Date().toTimeString().slice(0, 5); // HH:MM, local time
+  const parts = [`${time}`];
+  if (branch) parts.push(`branch=${branch}`);
+  if (phase) parts.push(`phase=${phase}`);
+  if (tasks) parts.push(`tasks=${tasks}`);
+  if (commitCount > 0) parts.push(`commits=${commitCount}`);
+  if (touched.length > 0) parts.push(`touched=${touched.join(",")}`);
+  const line = `- ${parts.join(" · ")}`;
+
+  // ── Append to today's file ───────────────────────────────
+  if (!fs.existsSync(DAILY_DIR)) fs.mkdirSync(DAILY_DIR, { recursive: true });
+  const today = new Date().toISOString().split("T")[0];
+  const file = path.join(DAILY_DIR, `${today}.md`);
+
+  let existing = "";
+  try {
+    if (fs.existsSync(file)) existing = fs.readFileSync(file, "utf8");
+  } catch {}
+
+  const projectHeader = `## ${project}`;
+  if (!existing) {
+    const header = `# Daily log — ${today}\n\n_Auto-generated by Qualia Framework. Each entry is one Stop-hook checkpoint per project per session._\n\n${projectHeader}\n${line}\n`;
+    fs.writeFileSync(file, header);
+  } else if (!existing.includes(projectHeader)) {
+    fs.appendFileSync(file, `\n${projectHeader}\n${line}\n`);
+  } else {
+    // Append the line under the existing project header. Insert after the last
+    // line that belongs to this project's section (next ## or EOF).
+    const headerIdx = existing.indexOf(projectHeader);
+    const afterHeader = headerIdx + projectHeader.length;
+    const nextHeaderIdx = existing.indexOf("\n## ", afterHeader);
+    const insertAt = nextHeaderIdx === -1 ? existing.length : nextHeaderIdx;
+    // Trim trailing newlines in the section so our append lands on a clean line.
+    const before = existing.slice(0, insertAt).replace(/\n+$/, "");
+    const after = existing.slice(insertAt);
+    fs.writeFileSync(file, `${before}\n${line}\n${after}`);
+  }
+
+  fs.writeFileSync(LAST_WRITE_FILE, String(now));
+  _trace("logged", { project, branch, phase, tasks, commits: commitCount });
+  process.exit(0);
+} catch (err) {
+  _trace("error", { error: err && err.message ? err.message : String(err) });
+  // Stop hooks must never block the user — exit 0 even on internal error.
+  process.exit(0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "4.1.1",
+  "version": "4.4.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -23,7 +23,13 @@
   },
   "homepage": "https://github.com/Qualiasolutions/qualia-framework#readme",
   "scripts": {
-    "test": "node --test tests/runner.js"
+    "test": "npm run test:shell",
+    "test:state": "bash tests/state.test.sh",
+    "test:hooks": "bash tests/hooks.test.sh",
+    "test:bin": "bash tests/bin.test.sh",
+    "test:lib": "bash tests/lib.test.sh",
+    "test:statusline": "bash tests/statusline.test.sh",
+    "test:shell": "bash tests/statusline.test.sh && bash tests/state.test.sh && bash tests/hooks.test.sh && bash tests/bin.test.sh && bash tests/lib.test.sh"
   },
   "files": [
     "bin/",

package/skills/qualia-build/SKILL.md

@@ -32,9 +32,9 @@ cat .planning/phase-{N}-plan.md
 
 Parse: tasks, waves, file references.
 
-### 1b. Create Recovery Point
+### 1b. Create Recovery Reference
 
-Before executing any tasks, tag current HEAD for rollback:
+Before executing any tasks, record current HEAD for diagnosis. This is a reference, not an automatic rollback instruction.
 
 ```bash
 git tag -f "pre-build-phase-{N}" HEAD 2>/dev/null
@@ -44,10 +44,10 @@ git tag -f "pre-build-phase-{N}" HEAD 2>/dev/null
 node ~/.claude/bin/qualia-ui.js info "Recovery point: pre-build-phase-{N}"
 ```
 
-If a wave fails and the user needs to roll back:
+If a wave fails, stop and inspect `git status` plus the failed task output. Do not run destructive rollback commands automatically. Preserve user work, then either fix forward or ask before reverting specific files.
 ```bash
-git reset --hard pre-build-phase-{N}
-node ~/.claude/bin/state.js transition --to planned --force
+git status --short
+git diff --stat
 ```
 
 ### 2. Execute Waves

package/skills/qualia-debug/SKILL.md

@@ -40,7 +40,7 @@ node ~/.claude/bin/qualia-ui.js banner debug
 ### 2. Check Known Fixes First (cheap)
 
 ```bash
-cat ~/.claude/knowledge/common-fixes.md 2>/dev/null | grep -i "{symptom_keywords}"
+node ~/.claude/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.

package/skills/qualia-design/SKILL.md

@@ -59,6 +59,21 @@ Apply fixes to every HIGH and CRITICAL item. MEDIUM items fixed if cheap (same f
 
 Split target files into batches of 5. Spawn one Agent per batch IN THE SAME RESPONSE TURN (parallel execution). Each agent receives DESIGN.md inlined + its 5 files + the Design Quality Rubric from `rules/grounding.md`. Agents return their batch's critique table + the actual edits applied. The skill orchestrator fans in the results and runs the final verification (step 5).
 
+**Forked subagents (v4.2.0+):** if the current conversation already contains
+design taste discussion (font choices, palette discussion, motion preferences,
+or any color/typography critique threaded across multiple turns) AND
+`CLAUDE_AGENT_FORK_ENABLED=1` is set in `~/.claude/settings.json` (the v4.2.0
+default), prefer **forked subagents** over blank-context fan-out. Forks
+inherit the entire conversation history + share the prompt cache, so the
+batch agents see the 50k tokens of accumulated taste instead of a 2k-token
+compression. Anthropic shipped this in 2026-04 specifically to solve the
+"design subagent loses nuance" failure mode (NotebookLM 2026-04-25 source).
+Tell Claude explicitly: "spawn forked subagents to handle these batches in
+parallel." For variation-generation work (3 alternative homepage designs)
+forks are almost always the right call. For mechanical anti-pattern fixes
+(rip out `outline:none`, swap font tokens) blank context is fine — no
+nuance to inherit. When in doubt, fork — the cost is the same prompt cache.
+
 ```
 Agent(prompt="
 Read your role: builder for design transformation.

package/skills/qualia-flush/SKILL.md

@@ -0,0 +1,200 @@
+---
+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."
+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`, shipped in v4.2.0 foundation) appends
+mechanical session checkpoints to `~/.claude/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`.
+
+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 ~/.claude/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 ~/.claude/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
+`~/.claude/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/)
+```
+
+> **Subdirectory caveat:** the v4.2.0 loader resolves bare filenames at
+> `~/.claude/knowledge/{name}.md`. Subdirectory `concepts/` files are not
+> reachable via `knowledge.js load <name>` yet (deferred to v4.3.0). For
+> now, write durable concept files at the top level — flat structure is
+> fine, the index keeps it organized.
+
+### 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 ~/.claude/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-learn/SKILL.md

@@ -54,49 +54,45 @@ What did you learn?
 
 ### 2. Check for Duplicates
 
-Before saving, check if a similar entry already exists:
+Before saving, search the existing knowledge for a similar entry. Use the
+unified loader, **never** raw `cat` or `grep` directly — the loader handles
+missing-file edge cases and stays consistent across skills.
 
 ```bash
-# Search for the title (case-insensitive substring match)
-grep -i "{title keywords}" ~/.claude/knowledge/{type}.md 2>/dev/null
+node ~/.claude/bin/knowledge.js search "{title keywords}"
 ```
 
-If a near-match exists (title is similar to an existing entry):
+If a near-match exists:
 - Show the existing entry to the user
 - Ask: "A similar entry exists. Update it, create a new one, or skip?"
-- If update: replace the existing entry. If new: append. If skip: done.
+- If update: edit the file directly (find the entry by `**ID:**` line). If
+  new: continue to step 3. If skip: done.
 
-### 3. Format Entry
+### 3. Append the Entry
 
-Each entry gets a unique ID and ISO timestamp for dedup and ordering:
-
-```markdown
-
----
-
-### {Title}
-**ID:** {random 8-char hex, e.g. a3f7c1e9}
-**Date:** {ISO 8601, e.g. 2026-04-11}
-**Project:** {current project name or "general"}
-**Context:** {brief context — what you were building when you learned this}
-
-{The learning — be specific enough that future-you understands without context}
-```
-
-### 4. Append to Knowledge File
-
-Append-only — never overwrite the file, always add at the end:
+The loader's `append` subcommand handles ID generation, ISO date, project
+detection, and the canonical entry format — one call, no shell escaping
+concerns:
 
 ```bash
-# Append to the right file
-echo "{formatted entry}" >> ~/.claude/knowledge/{type}.md
+node ~/.claude/bin/knowledge.js append \
+  --type {pattern|fix|client} \
+  --title "{Title}" \
+  --body "{The learning — be specific enough that future-you understands without context}" \
+  --project "{current project name or 'general'}" \
+  --context "{brief context — what you were building when you learned this}"
 ```
 
-- Pattern → `~/.claude/knowledge/learned-patterns.md`
-- Fix → `~/.claude/knowledge/common-fixes.md`
-- Client pref → `~/.claude/knowledge/client-prefs.md`
+Type → file mapping (handled by the loader):
+- `pattern` → `learned-patterns.md`
+- `fix`     → `common-fixes.md`
+- `client`  → `client-prefs.md`
+
+The loader prints `appended {id} to {file}` on success. If the destination
+file does not exist, the loader creates it with a header — you do not need
+to bootstrap it.
 
-### 5. Confirm
+### 4. Confirm
 
 ```
 ⬢ Saved to {file}
@@ -105,13 +101,27 @@ echo "{formatted entry}" >> ~/.claude/knowledge/{type}.md
 
 ## Reading Knowledge
 
-Skills can read knowledge files for context:
+**Always use the loader.** Hardcoded `cat ~/.claude/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
-cat ~/.claude/knowledge/learned-patterns.md 2>/dev/null
-cat ~/.claude/knowledge/common-fixes.md 2>/dev/null
-cat ~/.claude/knowledge/client-prefs.md 2>/dev/null
+# Print the index (entry point — read this first)
+node ~/.claude/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
+
+# List everything available
+node ~/.claude/bin/knowledge.js list
+
+# Search across all files
+node ~/.claude/bin/knowledge.js search "RLS"
 ```
 
-The `/qualia-debug` skill should check `common-fixes.md` before investigating.
-The `/qualia-new` skill should check `client-prefs.md` when setting up client projects.
-The `/qualia-plan` skill should check `learned-patterns.md` when planning phases.
+The `/qualia-debug` 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-new/SKILL.md

@@ -94,7 +94,7 @@ Plus free-text: "Any brand colors or reference sites I should look at?"
 
 If client, ask name. Check saved prefs:
 ```bash
-cat ~/.claude/knowledge/client-prefs.md 2>/dev/null | grep -A 10 "{client name}"
+node ~/.claude/bin/knowledge.js search "{client name}"
 ```
 
 ### Step 5. Write PROJECT.md

package/skills/qualia-plan/SKILL.md

@@ -33,8 +33,9 @@ Spawn a planner agent to break the current phase into executable tasks, then val
 cat .planning/STATE.md 2>/dev/null
 cat .planning/ROADMAP.md 2>/dev/null
 cat .planning/PROJECT.md 2>/dev/null
-cat ~/.claude/knowledge/learned-patterns.md 2>/dev/null
-cat ~/.claude/knowledge/client-prefs.md 2>/dev/null
+node ~/.claude/bin/knowledge.js
+node ~/.claude/bin/knowledge.js load patterns
+node ~/.claude/bin/knowledge.js load client
 ```
 
 If no phase number given, use the current phase from STATE.md.