qualia-framework 4.1.1 → 4.4.0

package/skills/qualia-postmortem/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: qualia-postmortem
+description: "Self-healing AI layer — when /qualia-verify returns FAIL, identify which agent/rule/skill should have caught the failure and propose a delta to that file so the same class of bug never recurs. Trigger on 'postmortem', 'why did the framework miss this', 'self-heal', 'qualia-postmortem', or auto-invoked by /qualia-verify on FAIL with --auto."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+---
+
+# /qualia-postmortem — Self-Healing AI Layer
+
+When the verifier finds a gap, fixing the **code** alone is not enough.
+The framework let the bug through — that means a rule, agent prompt,
+plan-checker check, or skill instruction was insufficient. This skill
+runs after a verify FAIL and asks: *which file in the AI layer should
+have caught this, and what delta would catch the next one like it?*
+
+This is Cole Medin's **pillar 5** from the parallel-worktrees playbook
+(NotebookLM 2026-04-25): "anytime we encounter a bug in a pull request,
+we don't just fix the bug and move on, we fix the underlying system that
+allowed for the bug." Without this loop, the same class of bug ships in
+PR-3, PR-7, PR-11 of every project.
+
+## When to run
+
+- **Manually:** `/qualia-postmortem` after any verify FAIL where the gap
+  feels preventable — i.e. a rule could have flagged it, a builder
+  instruction could have steered around it, a plan-checker rule could
+  have rejected the plan that produced it.
+- **Auto:** `/qualia-verify --auto` will invoke this skill on every FAIL
+  before the gap-closure loop fires. The postmortem write happens before
+  the user re-plans, so the next planner spawn benefits from the
+  updated AI layer immediately.
+
+## Inputs
+
+- `--phase N` (default: current phase from STATE.md)
+- `--apply` (optional) — apply the proposed delta to disk. Without
+  `--apply`, the skill writes `.planning/phase-{N}-postmortem.md` for
+  human review and stops there.
+- `--report-only` (optional) — just emit the analysis, write nothing.
+
+If invoked from `/qualia-verify --auto`, default to writing the
+postmortem report but **not** applying — applying touches the AI layer
+itself, which is high-stakes. The user reviews and types `/qualia-learn`
+or applies manually.
+
+## Process
+
+### 1. Load the failure
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner postmortem 2>/dev/null || true
+
+PHASE="${PHASE:-$(node ~/.claude/bin/state.js check 2>/dev/null | node -e 'let s=""; process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.parse(s).phase)}catch{console.log("")}})')}"
+[ -z "$PHASE" ] && { echo "QUALIA: Could not resolve current phase. Pass --phase N explicitly."; exit 1; }
+
+VERIFY_FILE=".planning/phase-${PHASE}-verification.md"
+PLAN_FILE=".planning/phase-${PHASE}-plan.md"
+
+[ -f "$VERIFY_FILE" ] || { echo "QUALIA: $VERIFY_FILE missing — nothing to post-mortem."; exit 1; }
+[ -f "$PLAN_FILE" ] || echo "QUALIA: $PLAN_FILE missing — analysis will be partial."
+```
+
+Read both files. The verification report tells you *what failed*. The
+plan tells you *what was supposed to happen*. The gap between them is
+where the AI layer fell short.
+
+### 2. Read the AI layer
+
+The framework's prompts live in three places. Load all three so you can
+match a finding to the file most likely responsible:
+
+```bash
+# Agent prompts (planner, builder, plan-checker, verifier, etc.)
+ls ~/.claude/agents/
+# Skill descriptions (qualia-plan, qualia-build, qualia-verify, etc.)
+ls ~/.claude/skills/
+# Project rules + grounding
+ls ~/.claude/rules/
+# Already-curated knowledge
+node ~/.claude/bin/knowledge.js
+```
+
+You don't read all of them — you read the ones whose job description
+matches the failure. Use this lookup:
+
+| Failure shape | Likely AI-layer owner |
+|---|---|
+| Builder produced a stub / placeholder | `agents/builder.md` (Read Before Write, no-stub rule) |
+| Plan listed Validation: `test -f file.ts` only — missed behavior check | `agents/plan-checker.md` (Rule 8: at least one grep-match or command-exit per task) |
+| Wave 2 task ran before wave 1 committed | `agents/planner.md` (dependency graph) |
+| Build passed locally, broke in CI | `rules/deployment.md` or a missing pre-deploy-gate scan |
+| RLS missing on new table | `rules/security.md` + `agents/builder.md` (security persona handling) |
+| Design regression — fonts off, contrast fail | `rules/frontend.md` + `skills/qualia-design/SKILL.md` |
+| Migration unsafe (DROP without IF EXISTS, etc.) | `hooks/migration-guard.js` |
+| Verifier missed it | `agents/verifier.md` — most embarrassing case, address with extra care |
+
+### 3. Diagnose
+
+For **each** gap in the verification report (process them one at a time
+when there are multiple), produce a four-field analysis:
+
+```markdown
+## Gap: {gap title from verification report}
+
+**Severity:** {CRITICAL | HIGH | MEDIUM | LOW}  (from verifier's rubric)
+**Owner file:** `agents/builder.md` (or rules/X.md, skills/Y/SKILL.md, etc.)
+**Why it slipped:**
+  Quote the relevant section of the owner file. Show the gap. The owner
+  file SHOULD have prevented this — either the rule wasn't there, or it
+  was there but not enforceable, or a rule was there but the agent was
+  free to ignore it.
+
+**Proposed delta:**
+  Concrete diff for the owner file. New line, edited section, or rule
+  addition. Keep it minimal — one new sentence is better than a new
+  paragraph. The goal is "the next planner/builder spawn catches this
+  class of bug."
+```
+
+### 4. Write the postmortem report
+
+```bash
+cat > .planning/phase-${PHASE}-postmortem.md <<'EOF'
+# Phase {N} Postmortem
+
+**Phase:** {N}
+**Verify result:** FAIL ({gap_count} gaps)
+**Date:** {ISO date}
+**Run ID:** {short uid}
+
+## Findings
+
+{one ## Gap section per gap, format from step 3}
+
+## Cumulative AI-layer drift
+
+{If multiple postmortems exist for this project, group recurring owner
+files: "agents/builder.md has been flagged 3 times this milestone — its
+no-stub rule may need reinforcement or wave-2 stubs need a hard hook."}
+
+## Apply?
+
+To apply all proposed deltas:
+  /qualia-postmortem --apply --phase {N}
+
+To save the recurring patterns to knowledge instead (recommended for
+project-spanning lessons):
+  /qualia-learn  (pick the relevant entries from this report)
+
+EOF
+```
+
+### 5. (Optional) Apply
+
+If invoked with `--apply`, walk each "Proposed delta" and use the Edit
+tool to make the literal change to the owner file. After every edit, run
+the framework's own type/test gates (`node --test tests/runner.js` if you
+modified anything in `bin/`, `agents/`, or `rules/`) to confirm no
+regression.
+
+If a proposed delta is to a `~/.claude/agents/X.md` file (the installed
+copy), edit that copy directly — the user re-running the installer will
+overwrite it next release, so also flag a TODO in the postmortem report
+saying "this delta should be PR'd back to the framework repo at
+`agents/X.md`" so it survives reinstall.
+
+### 6. Promote durable lessons to the knowledge layer
+
+For lessons that apply across projects (e.g. "Supabase RLS must be in
+the same migration as the table — applying it later creates a window
+where data is unprotected"), append to the curated tier so future
+builders pick it up:
+
+```bash
+node ~/.claude/bin/knowledge.js append \
+  --type pattern \
+  --title "{lesson title}" \
+  --body "{lesson body}" \
+  --project "{project name from .planning/PROJECT.md or 'general' if cross-project}" \
+  --context "Postmortem from phase ${PHASE}, verify FAIL on {date}"
+```
+
+### 7. Summarize
+
+```
+⬢ Postmortem complete — phase {N}
+  {G} gaps analyzed
+  Owner files implicated:
+    - agents/builder.md (gap 1, gap 3)
+    - rules/security.md (gap 2)
+  Report: .planning/phase-${PHASE}-postmortem.md
+  {if --apply: deltas applied; framework reinstall TODO'd}
+  {if no --apply: review and run --apply OR /qualia-learn the patterns}
+```
+
+## Style
+
+- **Be charitable.** The framework didn't fail because someone was
+  careless. It failed because a contract wasn't tight enough. Frame
+  every finding as "the contract was X; it should have been Y."
+- **Keep deltas surgical.** A 2-line addition to a rule is durable; a
+  paragraph rewrite is brittle. Smaller deltas survive future framework
+  updates.
+- **Don't reach.** If a gap genuinely doesn't map to an AI-layer file
+  (e.g. it's an external service outage), say so explicitly — don't
+  invent a rule to retroactively own it.
+- **Rate limit yourself.** Don't propose more than 3 deltas per
+  postmortem. If there are 8 gaps, the top 3 by severity get deltas; the
+  rest get noted but not deltad. Otherwise the AI layer becomes a museum
+  of edge cases.
+
+## Anti-patterns
+
+- **Re-fixing the same code as the verifier.** This skill is about the
+  AI layer, not the codebase. The gap-closure loop (`/qualia-plan
+  {N} --gaps`) handles the code. Postmortem only touches `agents/`,
+  `rules/`, `skills/`, and the knowledge layer.
+- **Auto-applying deltas to `~/.claude/agents/X.md` without flagging a
+  framework PR TODO.** That edit lasts until the next reinstall. Always
+  note the TODO so the lesson reaches the framework repo.
+- **Promoting every postmortem finding to knowledge.** Most are
+  project-specific contract tightening — they belong in the project's
+  AI-layer files, not in cross-project knowledge. Only generalizable
+  patterns get appended via `knowledge.js`.
+
+## Output contract
+
+The skill writes `.planning/phase-{N}-postmortem.md` and either applies
+deltas (with `--apply`) or stops with a summary that points the user at
+the next step (`--apply` to apply, or `/qualia-learn` to promote
+specific patterns). No follow-up prompts. Idempotent: re-running on the
+same phase appends `### Re-run {timestamp}` to the existing report
+rather than overwriting.

package/skills/qualia-quick/SKILL.md

@@ -24,7 +24,7 @@ node ~/.claude/bin/qualia-ui.js banner quick
 2. **Build:** Do it directly — read before write, MVP only
 3. **Verify:** Run `npx tsc --noEmit`, test locally
 4. **Commit:** Atomic commit with clear message
-5. **Update:** Update tracking.json notes field
+5. **Update:** Record the work through `state.js`
 
 End with:
 ```bash

package/skills/qualia-report/SKILL.md

@@ -134,7 +134,7 @@ SUBMITTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 # returns a generic 401 that is hard to diagnose.
 if [ "$ERP_ENABLED" = "true" ] && [ -z "$API_KEY" ] && [ "$DRY_RUN" != "true" ]; then
   node ~/.claude/bin/qualia-ui.js warn "ERP API key missing (~/.claude/.erp-api-key is empty or unreadable). Skipping upload."
-  node ~/.claude/bin/qualia-ui.js info "Ask Fawzi for the ERP key, save to ~/.claude/.erp-api-key, then re-run /qualia-report --upload-only."
+  node ~/.claude/bin/qualia-ui.js info "Ask Fawzi for the ERP key, run 'qualia-framework set-erp-key <key>', then run 'qualia-framework erp-ping'."
   ERP_ENABLED="false"
 fi
 

package/skills/qualia-review/SKILL.md

@@ -29,8 +29,9 @@ node ~/.claude/bin/qualia-ui.js banner review
 ### 0. Load Context
 
 ```bash
-cat ~/.claude/knowledge/common-fixes.md 2>/dev/null
-cat ~/.claude/knowledge/learned-patterns.md 2>/dev/null
+node ~/.claude/bin/knowledge.js
+node ~/.claude/bin/knowledge.js load fixes
+node ~/.claude/bin/knowledge.js load patterns
 ```
 
 Detect project shape:

package/skills/qualia-ship/SKILL.md

@@ -37,13 +37,14 @@ VERIFICATION=$(echo "$STATE" | node -e "try{const d=JSON.parse(require('fs').rea
 #   verified+pass — final phase verified; skipping polish is allowed for hotfixes
 # Anything else (setup, planned, built, shipped, handed_off, verified+fail) is refused.
 if [ "$STATUS" != "polished" ] && ! { [ "$STATUS" = "verified" ] && [ "$VERIFICATION" = "pass" ]; }; then
+  if [ "${QUALIA_SHIP_FORCE:-0}" = "1" ]; then
+    node ~/.claude/bin/qualia-ui.js warn "Forced ship from state '$STATUS' (verification: ${VERIFICATION:-none}). Record the reason in the final report."
+  else
   node ~/.claude/bin/qualia-ui.js fail "Cannot ship from state '$STATUS' (verification: ${VERIFICATION:-none})."
   node ~/.claude/bin/qualia-ui.js info "Run /qualia-polish first, or /qualia-verify {phase} if verification is still pending."
-  node ~/.claude/bin/qualia-ui.js info "Override: add --force to the skill invocation (hotfix escape hatch, use with care)."
-  # The --force escape hatch exists for production hotfixes where the polished
-  # state was never reached. The operator is expected to have read and
-  # understood the pending verification findings.
+  node ~/.claude/bin/qualia-ui.js info "Hotfix override: set QUALIA_SHIP_FORCE=1 only when the user explicitly approved it."
   exit 1
+  fi
 fi
 ```
 
@@ -53,7 +54,8 @@ Run in sequence. Auto-fix failures (up to 2 attempts).
 
 ```bash
 npx tsc --noEmit          # TypeScript — must pass
-npx eslint . --max-warnings 0   # Lint — auto-fix first
+if node -e "const p=require('./package.json');process.exit(p.scripts&&p.scripts.lint?0:1)"; then npm run lint; fi
+if node -e "const p=require('./package.json');process.exit(p.scripts&&p.scripts.test?0:1)"; then npm test; fi
 npm run build             # Build — must succeed
 ```
 
@@ -130,15 +132,15 @@ wrangler deploy            # Cloudflare Workers
 
 ### 5. Post-Deploy Verification
 
-Read the deployed URL from `tracking.json.deployed_url` — set by the deploy tool's output parser, or passed via `--url` to this skill. Do NOT use a `{domain}` placeholder — that expects the LLM to hallucinate the URL, which is exactly the kind of silent fail the state guard above prevents.
+Read the deployed URL from `tracking.json.deployed_url` or from an explicit user-provided URL. Do NOT use a `{domain}` placeholder — that expects the LLM to hallucinate the URL, which is exactly the kind of silent fail the state guard above prevents.
 
 ```bash
-# Read URL from tracking.json (set by /qualia-handoff or previous ship), or
-# let the operator pass it as an argument. Never assume a placeholder.
-URL=$(node -e "try{const t=JSON.parse(require('fs').readFileSync('.planning/tracking.json','utf8'));process.stdout.write(t.deployed_url||'')}catch{}")
+# If the user invoked `/qualia-ship --url ...`, set QUALIA_SHIP_URL to that
+# exact value before running this block. Otherwise use tracking.json.
+URL="${QUALIA_SHIP_URL:-$(node -e 'try{const t=JSON.parse(require("fs").readFileSync(".planning/tracking.json","utf8"));process.stdout.write(t.deployed_url||"")}catch{}')}"
 if [ -z "$URL" ]; then
   node ~/.claude/bin/qualia-ui.js warn "No deployed_url in tracking.json — parse it from the deploy command output (vercel/supabase/wrangler all print the URL on success)."
-  node ~/.claude/bin/qualia-ui.js info "Re-run with: /qualia-ship --url https://your-site.com"
+  node ~/.claude/bin/qualia-ui.js info "Re-run with: /qualia-ship --url https://your-site.com, then export that value as QUALIA_SHIP_URL for this check."
   exit 1
 fi
 

package/skills/qualia-verify/SKILL.md

@@ -19,6 +19,7 @@ Spawn a verifier agent to check if the phase goal was achieved. Does NOT trust b
 `/qualia-verify` — verify the current built phase
 `/qualia-verify {N}` — verify specific phase
 `/qualia-verify {N} --auto` — verify + auto-chain: PASS → next phase (or milestone close); FAIL → gap closure; gap limit → halt with escalation
+`/qualia-verify {N} --adversarial` — run a SECOND verifier in fresh context with an adversarial prompt ("find what's wrong, not what's right"). Union the findings. Recommended for high-stakes phases (Handoff milestone, payment/auth/migration code) where a biased single-pass review would silently approve a bad change. v4.3.0+.
 
 ## Process
 
@@ -80,6 +81,52 @@ Drive the running dev server and test the routes this phase touched. Append a '#
 
 Wait for both the main verifier and the QA browser agent before moving to step 3. If Playwright MCP is unavailable, the QA browser agent returns BLOCKED — that's not a phase failure, just a note in the report.
 
+### 2c. Adversarial Second Opinion (--adversarial flag, optional)
+
+When `--adversarial` is in the args, OR when the current milestone is
+`Handoff` OR the phase plan touches files matching `auth|payment|migration|rls|service_role`, spawn a SECOND verifier in fresh context with an
+adversarial prompt. This is the "kid-grading-their-own-homework"
+mitigation — a single verifier instance trained on the same rubric the
+planner+builder optimized against gets ~70% fewer real findings than a
+fresh-context adversarial pass (Cole Medin, NotebookLM 2026-04-25, citing
+PR-acceptance studies).
+
+```bash
+node ~/.claude/bin/qualia-ui.js spawn verifier "Adversarial pass — find what's wrong"
+```
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/verifier.md
+Grounding + rubrics: @~/.claude/rules/grounding.md
+
+You are an ADVERSARIAL reviewer. Your job is to find what's WRONG with
+this phase, not to confirm it works. Assume the previous verifier missed
+something. Use the same Severity Rubric, the same evidence-citation
+requirement, but bias your search toward edge cases the cooperative
+verifier would skip:
+  • What untested error path exists?
+  • What input would crash this?
+  • What concurrent access pattern is unhandled?
+  • What downstream consumer breaks if this contract changes?
+  • Where is a security assumption (auth, RLS, secrets) implicit
+    instead of enforced?
+
+Project conventions: @.planning/PROJECT.md
+Phase plan: @.planning/phase-{N}-plan.md
+Cooperative verifier's report (do NOT re-find what they found, find
+what they MISSED): @.planning/phase-{N}-verification.md
+
+Append a '## Adversarial Findings' section to the verification file.
+Empty section is fine if you genuinely found nothing — better that than
+inventing findings to look productive.
+", subagent_type="qualia-verifier", description="Adversarial verify phase {N}")
+```
+
+Findings from the adversarial pass merge into the main verification
+report. The combined PASS/FAIL is the union: if either pass found a
+CRITICAL or HIGH gap, the phase is FAIL.
+
 ### 3. Present Results
 
 Read the verification report. Present:
@@ -102,6 +149,19 @@ Then for each gap:
 node ~/.claude/bin/qualia-ui.js fail "{gap description}"
 ```
 
+**Self-healing layer (v4.3.0+):** before re-planning the gaps, run a
+postmortem so the framework itself learns from the miss. This is Cole
+Medin's pillar 5: don't just fix the bug, fix the AI-layer file that
+should have caught it. The postmortem writes a report to
+`.planning/phase-{N}-postmortem.md` for review — it does NOT auto-apply
+deltas to agents/rules unless the user runs `/qualia-postmortem --apply`
+explicitly. Without this loop, the same class of bug ships in PR-3, PR-7,
+PR-11 of the next project.
+
+```
+/qualia-postmortem --phase {N}
+```
+
 End:
 ```bash
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} GAPS FOUND" "/qualia-plan {N} --gaps"

package/templates/help.html

@@ -297,7 +297,7 @@
   <div class="header-content">
     <h1><span>Qualia</span> Framework</h1>
     <p>Plan, build, verify, ship. The AI-powered workflow for Qualia Solutions.</p>
-    <div class="version">{{VERSION}} &middot; 26 skills</div>
+    <div class="version">{{VERSION}} &middot; 28 skills</div>
   </div>
 </div>
 
@@ -328,7 +328,7 @@
 
   <!-- Skills -->
   <section>
-    <h2>Skills (26)</h2>
+    <h2>Skills (28)</h2>
 
     <!-- Road (core flow) -->
     <div class="cmd-group">
@@ -336,7 +336,7 @@
       <p class="cmd-group-note">The seven steps every project walks through.</p>
       <div class="commands">
         <div class="cmd"><span class="cmd-name">/qualia-new</span><span class="cmd-desc">Set up a new project from scratch &mdash; deep questioning, parallel research, REQUIREMENTS.md, ROADMAP.md, approval gate. Use when starting any new client project.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-plan</span><span class="cmd-desc">Plan the current phase &mdash; spawns planner, validates with plan-checker in a revision loop (max 3), optionally runs discuss/research first. Use when ready to plan a phase.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-plan</span><span class="cmd-desc">Plan the current phase &mdash; spawns planner, validates with plan-checker in a revision loop (max 2), optionally runs discuss/research first. Use when ready to plan a phase.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-build</span><span class="cmd-desc">Execute the current phase &mdash; spawns builder subagents per task with wave-based parallelization. Fresh context per task.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-verify</span><span class="cmd-desc">Goal-backward verification &mdash; checks if the phase ACTUALLY works, not just if tasks completed. Spawns verifier agent.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-polish</span><span class="cmd-desc">Design and UX pass &mdash; anti-AI-slop, genuine craft, responsive, accessible. Run after all phases are verified.</span></div>
@@ -365,7 +365,6 @@
         <div class="cmd"><span class="cmd-name">/qualia-debug</span><span class="cmd-desc">Structured debugging &mdash; symptom gathering, diagnosis confirmation, root cause analysis. Trigger on 'debug', 'find bug', 'fix error', 'something is broken'.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-review</span><span class="cmd-desc">Production audit with scored diagnostics. Runs real commands, scores findings by severity. Trigger on 'review', 'audit', 'code review', 'security check'.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-optimize</span><span class="cmd-desc">Deep optimization pass &mdash; reads .planning/ AND codebase to find performance, design, UI, backend, and frontend issues. Spawns parallel specialist agents. Supports --perf, --ui, --backend, --alignment, --fix flags.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-polish</span><span class="cmd-desc">Design and UX pass &mdash; anti-AI-slop, genuine craft, responsive, accessible. Run after all phases are verified.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-test</span><span class="cmd-desc">Generate or run tests for client projects. Trigger on 'write tests', 'add tests', 'test this', 'test coverage'.</span></div>
       </div>
     </div>
@@ -387,6 +386,7 @@
       <p class="cmd-group-note">Persist learnings and log work.</p>
       <div class="commands">
         <div class="cmd"><span class="cmd-name">/qualia-learn</span><span class="cmd-desc">Save a learning, pattern, fix, or client preference to the knowledge base. Persists across projects and sessions.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-flush</span><span class="cmd-desc">Promote raw daily logs into curated knowledge concepts. Use weekly or when session logs contain durable lessons.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-report</span><span class="cmd-desc">Generate session report and commit to repo. Mandatory before clock-out.</span></div>
       </div>
     </div>
@@ -418,6 +418,7 @@
       <p class="cmd-group-note">Extend the framework itself.</p>
       <div class="commands">
         <div class="cmd"><span class="cmd-name">/qualia-skill-new</span><span class="cmd-desc">Author a new Qualia skill or agent. Generates the SKILL.md, registers it in the right location, and optionally ships to the framework repo.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-postmortem</span><span class="cmd-desc">Analyze a verification failure and turn the lesson into a framework improvement.</span></div>
       </div>
     </div>
   </section>
@@ -430,8 +431,13 @@
         <div class="cmd"><span class="cmd-name">qualia-framework install</span><span class="cmd-desc">Install or reinstall the framework.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework update</span><span class="cmd-desc">Update to the latest version.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework version</span><span class="cmd-desc">Show installed version + check for updates.</span></div>
+        <div class="cmd"><span class="cmd-name">qualia-framework uninstall</span><span class="cmd-desc">Clean removal from ~/.claude/ while preserving user-owned settings.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework migrate</span><span class="cmd-desc">Upgrade legacy settings.json to the current hook layout.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework analytics</span><span class="cmd-desc">Hook telemetry, verification pass rates, gap cycles.</span></div>
+        <div class="cmd"><span class="cmd-name">qualia-framework set-erp-key</span><span class="cmd-desc">Save and enable the ERP API key.</span></div>
+        <div class="cmd"><span class="cmd-name">qualia-framework erp-ping</span><span class="cmd-desc">Verify ERP connectivity and API key health.</span></div>
+        <div class="cmd"><span class="cmd-name">qualia-framework doctor</span><span class="cmd-desc">Health-check installed files, hooks, settings, and knowledge layer.</span></div>
+        <div class="cmd"><span class="cmd-name">qualia-framework flush</span><span class="cmd-desc">Run the non-interactive knowledge flush.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework team</span><span class="cmd-desc">List, add, or remove team members.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework traces</span><span class="cmd-desc">View recent hook activity.</span></div>
       </div>
@@ -470,11 +476,11 @@
   <section>
     <h2>Rules</h2>
     <ul class="rules">
-      <li><span class="rule-icon">1</span> Feature branches only &mdash; never push to main</li>
+      <li><span class="rule-icon">1</span> Feature branches by default &mdash; OWNER overrides must be explicit</li>
       <li><span class="rule-icon">2</span> Read before write &mdash; understand files before editing</li>
       <li><span class="rule-icon">3</span> MVP first &mdash; build what's asked, nothing extra</li>
       <li><span class="rule-icon">4</span> /qualia-report before clock-out &mdash; mandatory, enforced by ERP</li>
-      <li><span class="rule-icon">5</span> No .env edits &mdash; ask Fawzi for secrets</li>
+      <li><span class="rule-icon">5</span> Secrets through approved flows &mdash; use set-erp-key or ask Fawzi</li>
       <li><span class="rule-icon">6</span> Stuck 30+ minutes? Ask Fawzi</li>
     </ul>
   </section>
@@ -536,7 +542,7 @@
 <div class="footer">
   <strong>Welcome to the future with Qualia.</strong><br>
   Qualia Solutions &mdash; Nicosia, Cyprus
-  <span class="footer-version">qualia-framework {{VERSION}} &middot; 26 skills</span>
+  <span class="footer-version">qualia-framework {{VERSION}} &middot; 28 skills</span>
 </div>
 
 </body>

package/templates/knowledge/agents.md

@@ -0,0 +1,71 @@
+# Memory Layer — How This Works
+
+You are operating inside the **Qualia Framework memory layer**. This file
+describes the system you're in so you can navigate it deliberately. Read this
+once at session start.
+
+## What's here
+
+`~/.claude/knowledge/` is the project-spanning memory tier. It holds three
+kinds of files, each with a clear purpose. Treat the structure as a contract.
+
+```
+~/.claude/knowledge/
+├── agents.md              ← this file (system overview)
+├── index.md               ← entry point — start here when answering questions
+├── daily-log/
+│   └── YYYY-MM-DD.md      ← raw session checkpoints (auto-written by Stop hook)
+├── concepts/              ← (future) promoted, durable patterns
+├── connections/           ← (future) cross-references between concepts
+├── learned-patterns.md    ← curated patterns from /qualia-learn
+├── common-fixes.md        ← recurring fix recipes
+├── supabase-patterns.md   ← Supabase-specific patterns
+├── voice-agent-patterns.md
+├── deployment-map.md
+└── employees.md           ← team roster
+```
+
+## How to use it
+
+**To answer a question that might be in memory:**
+1. Read `index.md` first. It tells you which file is likely to have what you
+   need. Do **not** scan every file — that defeats the index.
+2. Follow the index to one or two specific files. Read those.
+3. If the answer is not there, say so and (when the user agrees) add it via
+   `/qualia-learn`.
+
+**To remember something new:**
+- Use `/qualia-learn`. It writes to the right tier (pattern vs. fix vs.
+  client preference) and updates the index.
+- Do not write to these files directly without an explicit user instruction —
+  the index will fall out of sync.
+
+**Do not pretend something is in memory if it is not.** Better to say
+"INSUFFICIENT EVIDENCE: searched index.md and learned-patterns.md, no entry
+matches" than to hallucinate a recalled pattern. The grounding protocol
+(`~/.claude/rules/grounding.md`) applies here too.
+
+## Tiers
+
+The memory layer follows a Karpathy-style **raw → wiki** progression. Most of
+this is still being built — v4.2.0 ships the daily-log raw tier; v4.3.0 will
+add the LLM-driven flush job that promotes raw entries into concepts and
+connections.
+
+| Tier | Files | How it's written | When to read |
+|------|-------|------------------|--------------|
+| Raw | `daily-log/*.md` | Stop hook (auto, mechanical) | Resuming a recent session, debugging a regression |
+| Curated | `learned-patterns.md`, `common-fixes.md`, `*-patterns.md` | `/qualia-learn` (manual, deliberate) | Answering "how do we usually do X?" |
+| Index | `index.md` | `/qualia-learn` updates it; auto-rebuilt by `bin/knowledge.js` | Always read first |
+
+## Cross-cutting rules
+
+- **Stale data is dangerous.** If a memory file has not been touched in
+  months and the codebase has changed, the memory may be lying. Verify
+  current state in the actual files before recommending anything based on
+  memory.
+- **Project memory ≠ global memory.** Project-specific decisions belong in
+  that project's `.planning/` directory, not here. This directory is for
+  patterns that apply across multiple projects.
+- **Never put secrets here.** API keys, tokens, passwords — never. The
+  knowledge layer is plain markdown checked into a non-encrypted directory.

package/templates/knowledge/index.md

@@ -0,0 +1,47 @@
+# Knowledge Index
+
+Entry point for `~/.claude/knowledge/`. When answering a question, **read this
+file first**, then jump to the specific file(s) that match.
+
+> Auto-maintained by `/qualia-learn`. Do not hand-edit unless the file is out
+> of sync (e.g. after a manual move). Last manual edit: framework install.
+
+## What's where
+
+| If the user asks about… | Read… |
+|--------------------------|-------|
+| "How do we usually X?" / patterns we've used before | `learned-patterns.md` |
+| Recurring bug + fix recipes | `common-fixes.md` |
+| Supabase auth, RLS, migrations, edge functions | `supabase-patterns.md` |
+| Retell, ElevenLabs, voice agent flows | `voice-agent-patterns.md` |
+| Where a project is deployed, env vars, domains | `deployment-map.md` |
+| Who is on the team, their role, their access | `employees.md` |
+| What I worked on yesterday / last week | `daily-log/YYYY-MM-DD.md` |
+| Memory layer architecture itself | `agents.md` |
+
+## Daily log conventions
+
+`daily-log/YYYY-MM-DD.md` is raw, mechanical, and append-only. Each line is a
+single Stop-hook checkpoint with project, branch, phase, task counts, commit
+count, and up to 3 touched files. **Do not promote daily-log content into the
+curated tier by hand** — the upcoming `bin/knowledge-flush.js` will do that
+deliberately. Hand-promoted entries break the source-of-truth invariant.
+
+## Adding new knowledge
+
+Use `/qualia-learn` with the type that matches:
+
+- `pattern` → `learned-patterns.md`
+- `fix` → `common-fixes.md`
+- `client preference` → the relevant project's `.planning/`, **not** this
+  directory
+- `team member info` → `employees.md`
+
+If a new top-level file is needed (e.g. a new technology stack), update this
+index in the same commit.
+
+## Empty / new-install state
+
+If a tier file does not exist yet, that means we have not learned anything in
+that domain yet. Don't pretend we have. Either say "no entries" or, if the
+user is asking you to learn it now, run `/qualia-learn`.