qualia-framework 3.2.0 → 3.3.0

package/hooks/session-start.js

@@ -18,6 +18,7 @@ const HOME = os.homedir();
 const UI = path.join(HOME, ".claude", "bin", "qualia-ui.js");
 const STATE_FILE = path.join(".planning", "STATE.md");
 const CONTINUE_HERE = ".continue-here.md";
+const NOTIF_FILE = path.join(HOME, ".claude", ".qualia-update-available.json");
 
 function runUi(...args) {
   if (!fs.existsSync(UI)) return;
@@ -45,46 +46,6 @@ function getNextCommand() {
   }
 }
 
-function maybeShowUpdateBanner() {
-  // Sticky framework update notification for EMPLOYEEs. Populated by
-  // auto-update.js when it detects a newer qualia-framework version on npm.
-  // OWNER auto-updates silently, so this file is never created for Fawzi.
-  try {
-    const notifFile = path.join(HOME, ".claude", ".qualia-update-available.json");
-    if (!fs.existsSync(notifFile)) return;
-
-    const cfg = readConfig();
-    // Belt-and-suspenders: even if a stale notification exists, OWNER never sees it.
-    if (cfg.role === "OWNER") {
-      try { fs.unlinkSync(notifFile); } catch {}
-      return;
-    }
-
-    const notif = JSON.parse(fs.readFileSync(notifFile, "utf8"));
-
-    // If the user has already updated (cfg.version >= notif.latest), clear the file.
-    if (cfg.version && notif.latest) {
-      const cmp = (a, b) => {
-        const pa = String(a).split(".").map(Number);
-        const pb = String(b).split(".").map(Number);
-        for (let i = 0; i < 3; i++) {
-          if ((pa[i] || 0) > (pb[i] || 0)) return 1;
-          if ((pa[i] || 0) < (pb[i] || 0)) return -1;
-        }
-        return 0;
-      };
-      if (cmp(cfg.version, notif.latest) >= 0) {
-        try { fs.unlinkSync(notifFile); } catch {}
-        return;
-      }
-    }
-
-    runUi("update", notif.current || cfg.version || "?", notif.latest || "?");
-  } catch {
-    // Never fail the session start.
-  }
-}
-
 function fallbackText() {
   // If qualia-ui.js is missing, emit plain text. Keeps the session informative
   // even on a broken install.
@@ -105,10 +66,22 @@ function fallbackText() {
   }
 }
 
+function maybeRenderUpdateBanner() {
+  // EMPLOYEE-only sticky banner. auto-update.js writes NOTIF_FILE when a new
+  // version is detected; we render it every session until the user actually
+  // runs `npx qualia-framework@latest install`. The file is cleared by
+  // auto-update.js once the install completes or the version catches up.
+  if (!fs.existsSync(NOTIF_FILE) || !fs.existsSync(UI)) return;
+  try {
+    const notif = JSON.parse(fs.readFileSync(NOTIF_FILE, "utf8"));
+    if (notif && notif.current && notif.latest) {
+      runUi("update", notif.current, notif.latest);
+    }
+  } catch {}
+}
+
 try {
-  // Sticky update notification — shown before anything else every session
-  // until the employee runs `npx qualia-framework@latest install`.
-  maybeShowUpdateBanner();
+  maybeRenderUpdateBanner();
 
   if (!fs.existsSync(UI)) {
     fallbackText();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -19,11 +19,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/QualiasolutionsCY/qualia-framework.git"
+    "url": "git+https://github.com/Qualiasolutions/qualia-framework.git"
   },
-  "homepage": "https://github.com/QualiasolutionsCY/qualia-framework#readme",
+  "homepage": "https://github.com/Qualiasolutions/qualia-framework#readme",
   "scripts": {
-    "test": "bash tests/hooks.test.sh && bash tests/state.test.sh && bash tests/bin.test.sh && bash tests/statusline.test.sh"
+    "test": "node --test tests/runner.js"
   },
   "files": [
     "bin/",
@@ -32,7 +32,9 @@
     "rules/",
     "skills/",
     "templates/",
+    "references/",
     "tests/",
+    "docs/",
     "CLAUDE.md",
     "guide.md"
   ],

package/references/questioning.md

@@ -0,0 +1,123 @@
+# Questioning Guide
+
+Project initialization is dream extraction, not requirements gathering. Help the user discover and articulate what they want. Collaborate, don't interrogate.
+
+## Philosophy
+
+**You are a thinking partner.**
+
+The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+
+Don't follow a script. Follow the thread.
+
+## The Goal
+
+By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
+
+- **Research** needs: what domain, what the user already knows, what unknowns exist
+- **Requirements** needs: clear vision to scope v1 features
+- **Roadmap** needs: clear vision to decompose into phases, what "done" looks like
+- **Plan-phase** needs: specific requirements to break into tasks
+- **Execute-phase** needs: success criteria to verify against
+
+A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
+
+## How to Question
+
+**Start open.** Let them dump their mental model. Don't interrupt with structure.
+
+**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
+
+**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
+
+**Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
+
+**Clarify ambiguity.** "When you say Z, do you mean A or B?"
+
+**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
+
+## Question Types
+
+Use as inspiration, not a checklist. Pick what's relevant to the thread.
+
+### Motivation — why this exists
+
+- "What prompted this?"
+- "What are you doing today that this replaces?"
+- "What would you do if this existed?"
+
+### Concreteness — what it actually is
+
+- "Walk me through using this"
+- "You said X — what does that actually look like?"
+- "Give me an example"
+
+### Clarification — what they mean
+
+- "When you say Z, do you mean A or B?"
+- "You mentioned X — tell me more about that"
+
+### Success — how you'll know it's working
+
+- "How will you know this is working?"
+- "What does done look like?"
+
+## Using AskUserQuestion
+
+Present concrete options the user can react to.
+
+**Good options:**
+- Interpretations of what they might mean
+- Specific examples to confirm or deny
+- Concrete choices that reveal priorities
+
+**Bad options:**
+- Generic categories ("Technical", "Business", "Other")
+- Leading options that presume an answer
+- Too many options (2-4 is ideal)
+
+**Example — vague answer "it should be fast":**
+
+- header: "Fast"
+- question: "Fast how?"
+- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
+
+**Example — following a thread "frustrated with current tools":**
+
+- header: "Frustration"
+- question: "What specifically frustrates you?"
+- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+## Context Checklist
+
+Mental checklist, not conversation structure. Check as you go; weave questions naturally.
+
+- [ ] What they're building (concrete enough to explain to a stranger)
+- [ ] Why it needs to exist (the problem or desire driving it)
+- [ ] Who it's for (even if just themselves)
+- [ ] What "done" looks like (observable outcomes)
+
+Four things. If they volunteer more, capture it.
+
+## Decision Gate
+
+When you could write a clear PROJECT.md:
+
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create PROJECT.md" — Let's move forward
+  - "Keep exploring" — I want to share more / ask me more
+
+If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally. Loop until approved.
+
+## Anti-Patterns
+
+- **Checklist walking** — Going through domains regardless of what they said
+- **Canned questions** — "What's your core value?" regardless of context
+- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
+- **Interrogation** — Firing questions without building on answers
+- **Rushing** — Minimizing questions to get to "the work"
+- **Shallow acceptance** — Taking vague answers without probing
+- **Premature constraints** — Asking about tech stack before understanding the idea
+- **User skills** — NEVER ask about user's technical experience. Claude builds.

package/rules/infrastructure.md

@@ -0,0 +1,87 @@
+---
+globs: ["*.env*", "vercel.json", "next.config.*", "supabase/**", "railway.*"]
+---
+
+# Infrastructure & Services
+
+Standard services across all Qualia projects. Use these unless the project explicitly specifies otherwise.
+
+## Database: Supabase (every project)
+- Every project uses Supabase for auth, database, and storage
+- **CLI:** `npx supabase` — migrations, type generation, local dev
+- **MCP:** Supabase MCP server is available in Claude Code for direct database operations
+- Always enable RLS on every table (see `rules/security.md`)
+- Use `lib/supabase/server.ts` for server-side, `lib/supabase/client.ts` for client-side
+- Run `npx supabase gen types` after schema changes
+- Migrations go in `supabase/migrations/` — never edit production directly
+
+## AI Models: OpenRouter (every project)
+- Use OpenRouter API for all LLM calls — it routes to the best-suited model per task
+- API key env var: `OPENROUTER_API_KEY`
+- Don't have a key? Ask Fawzi for one
+- Never hardcode a specific model provider (OpenAI, Anthropic, etc.) directly — always go through OpenRouter
+- Exception: if a client specifically requires a direct provider integration
+
+## Voice AI: Retell AI + ElevenLabs
+- **Retell AI** — primary voice agent platform. API key: `RETELL_API_KEY`
+- **ElevenLabs** — voice synthesis, cloning, streaming. API key: `ELEVENLABS_API_KEY`
+- **Telnyx** — telephony/SIP for voice agent phone numbers. API key: `TELNYX_API_KEY`
+- For new voice projects, default to Retell AI + ElevenLabs unless client specifies otherwise
+
+## Compute: Vercel + Railway
+- **Vercel** — primary hosting for all Next.js projects. Deploy via CLI only (see below)
+- **Railway** — secondary compute for long-running agents, background jobs, and agentic workloads that exceed Vercel's function timeout
+- **Railway CLI:** `railway` — deploy, logs, env management
+- **Railway MCP:** Railway MCP server is available in Claude Code for project management
+- Railway projects use Nixpacks (auto-detected) — check for `railway.json` or `railway.toml`
+
+## MCP Servers (available in Claude Code)
+- **Supabase MCP** — database queries, table management, migrations from within Claude Code
+- **Railway MCP** — project deployment, logs, environment variables from within Claude Code
+- **next-devtools MCP** — runtime error visibility for Next.js 16+ dev servers (optional, added by framework install)
+
+## CLIs (must be installed)
+- `npx supabase` — Supabase CLI (database, migrations, types)
+- `railway` — Railway CLI (deploy, logs, env)
+- `vercel` — Vercel CLI (deploy, env, link)
+- `gh` — GitHub CLI (PRs, issues, repos)
+
+## GitHub Organizations
+- **QualiasolutionsCY** — primary org for all Qualia Solutions projects
+- **SakaniQualia** — org for Sakani-related projects (real estate platform)
+- All repos are private by default
+- Branch protection: main/master require PR reviews (enforced by framework guards)
+
+## Vercel Teams (admin knowledge)
+- Qualia operates across **3 Vercel teams** — projects are distributed across them
+- Check which team a project belongs to before deploying: `vercel whoami` and `vercel link`
+- If a project isn't linked, link it first: `vercel link`
+
+## Deployment Rules
+- **NO auto-deploys from GitHub pushes** — all Vercel projects have GitHub integration auto-deploy DISABLED
+- Deploys happen ONLY via `vercel --prod` through the CLI (or `/qualia-ship`)
+- This is intentional — we control when things go live, not git push triggers
+- If you find a project with auto-deploy enabled, disable it: Vercel Dashboard → Project Settings → Git → Disable "Automatic Deployments"
+
+## Required Environment Variables (typical project)
+
+```bash
+# Supabase (every project)
+NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
+SUPABASE_SERVICE_ROLE_KEY=          # NEVER in client code
+
+# AI (if applicable)
+OPENROUTER_API_KEY=                 # ask Fawzi if you don't have one
+
+# Voice (if applicable)
+RETELL_API_KEY=
+ELEVENLABS_API_KEY=
+TELNYX_API_KEY=
+
+# Deployment
+VERCEL_ORG_ID=                      # from vercel link
+VERCEL_PROJECT_ID=                  # from vercel link
+```
+
+Always use `vercel env pull` to sync env vars locally. Never create `.env` manually from scratch.

package/skills/qualia/SKILL.md

@@ -47,6 +47,7 @@ Use the state.js JSON output plus gathered context:
 | `handed-off` | status == "handed_off" | → `/qualia-report` then done |
 | `blocked` | STATE.md lists blockers or same error 3+ times | → Analyze, suggest `/qualia-debug` |
 | `bug-loop` | Same files edited 3+ times, user frustrated | → Different approach, `/qualia-debug` |
+| `need-tests` | User mentions "tests", "coverage", "test this" | → `/qualia-test` |
 
 **Employee escalation:** If role is EMPLOYEE and situation is `gap-limit` or `bug-loop`, suggest: "Want to flag this for Fawzi?"
 

package/skills/qualia-build/SKILL.md

@@ -21,6 +21,24 @@ cat .planning/phase-{N}-plan.md
 
 Parse: tasks, waves, file references.
 
+### 1b. Create Recovery Point
+
+Before executing any tasks, tag current HEAD for rollback:
+
+```bash
+git tag -f "pre-build-phase-{N}" HEAD 2>/dev/null
+```
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "Recovery point: pre-build-phase-{N}"
+```
+
+If a wave fails and the user needs to roll back:
+```bash
+git reset --hard pre-build-phase-{N}
+node ~/.claude/bin/state.js transition --to planned --force
+```
+
 ### 2. Execute Waves
 
 ```bash

package/skills/qualia-design/SKILL.md

@@ -25,7 +25,7 @@ node ~/.claude/bin/qualia-ui.js banner design
 cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
 ```
 
-If DESIGN.md exists → use it. If not → use Qualia defaults: distinctive fonts, sharp accents, layered backgrounds, no card grids, no blue-purple gradients, full-width layouts.
+If DESIGN.md exists → it is law. Use exact values from sections 1-9 (Visual Theme, Color Palette, Typography, Components, Layout, Depth, Do's/Don'ts, Responsive, Agent Prompt Guide). If not → use Qualia defaults from `rules/frontend.md`: distinctive fonts, sharp accents, layered backgrounds, no card grids, no blue-purple gradients, full-width layouts.
 
 ### 2. Find Target Files
 
@@ -41,19 +41,25 @@ Evaluate each file on: AI slop detection, visual hierarchy, typography, color, s
 
 ### 4. Fix Everything
 
-**Typography:** Replace generic fonts (Inter, Arial) with distinctive ones. Proper type scale, line-height 1.5-1.7 body.
+Use exact values from DESIGN.md when available. Sections map to fixes:
 
-**Color:** Cohesive palette from DESIGN.md or brand. Sharp accent for CTAs. WCAG AA contrast.
+**Typography (§3):** Apply fonts from hierarchy table. Replace any generic fonts (Inter, Arial) with project fonts. Use exact weights, sizes, letter-spacing from the table. Body line-height 1.5-1.7.
 
-**Layout:** Full-width with fluid padding `clamp(1rem, 5vw, 4rem)`. NO hardcoded max-width caps. Prose gets `max-width: 65ch`.
+**Color (§2):** Apply palette from CSS variables. Replace scattered hex values with `var(--color-*)`. Verify contrast ratios listed in DESIGN.md.
 
-**Spacing:** Consistent scale (8px grid). Generous whitespace between sections, tight within groups.
+**Components (§4):** Match button, card, input, badge specs exactly — padding, radius, shadow, hover states.
 
-**Motion:** CSS transitions 200-300ms on hover/focus. Staggered entrance animations. `prefers-reduced-motion` respected.
+**Layout (§5):** Full-width with fluid padding `clamp(1rem, 5vw, 4rem)`. Apply spacing scale. NO hardcoded max-width caps. Prose gets `max-width: 65ch`.
 
-**States:** Loading skeleton/spinner on async ops. Error states on data fetches. Empty states on lists. Hover/focus/active/disabled on interactive elements.
+**Depth (§6):** Apply shadow levels from elevation table. Use brand-tinted shadows, not neutral gray.
 
-**Responsive:** Mobile-first. Touch targets 44x44px min. Stack on mobile, expand on desktop. No horizontal scroll.
+**Motion (§Motion):** CSS transitions 200-300ms on hover/focus. Staggered entrance animations. `prefers-reduced-motion` respected.
+
+**States:** Loading skeleton/spinner on async ops. Error states on data fetches. Empty states on lists. Hover/focus/active/disabled on every interactive element.
+
+**Responsive (§8):** Apply collapsing strategy from table. Mobile-first. Touch targets 44x44px min. No horizontal scroll.
+
+**Anti-Slop (§12):** Run grep patterns from the detection table. Every match = mandatory fix.
 
 **Kill:** Card grids → varied layouts. Generic heroes → distinctive. Blue-purple gradients → brand colors. Static pages → purposeful motion. Fixed widths → fluid.
 

package/skills/qualia-discuss/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: qualia-discuss
+description: "Capture phase decisions, trade-offs, and constraints BEFORE planning. Use for complex phases with regulatory, compliance, or architectural stakes. Creates .planning/phase-{N}-context.md that planner honors as locked input."
+---
+
+# /qualia-discuss — Phase Context Capture
+
+Before a complex phase gets planned, surface the decisions and trade-offs that must inform planning. Output: `.planning/phase-{N}-context.md` that the planner reads as locked input.
+
+## When to Use
+
+- Regulated domains (legal, medical, financial) where wrong choices have legal cost
+- Phases with architectural forks (e.g., "auth via middleware or RLS?")
+- Phases with external dependencies you want to lock first
+- Anytime the user says "wait, let's think about this one"
+
+## Process
+
+### 1. Determine Phase
+
+```bash
+node ~/.claude/bin/state.js check 2>/dev/null
+```
+
+If a phase number was passed as argument, use it. Otherwise use the current phase from STATE.md.
+
+### 2. Load Context
+
+```bash
+cat .planning/PROJECT.md 2>/dev/null
+cat .planning/ROADMAP.md 2>/dev/null
+cat .planning/research/SUMMARY.md 2>/dev/null
+```
+
+Identify:
+- Phase goal from ROADMAP.md
+- Requirements covered by this phase
+- Research flags for this phase (from SUMMARY.md)
+
+### 3. Open the Conversation
+
+Print the banner:
+```bash
+node ~/.claude/bin/qualia-ui.js banner discuss {N} "{phase name from ROADMAP.md}"
+```
+
+Ask inline (free text, not AskUserQuestion):
+
+**"We're about to plan {phase name}. The goal is: {goal from ROADMAP.md}. Before I hand this to the planner, what decisions, trade-offs, or constraints should be locked in?"**
+
+Wait for their response.
+
+### 4. Follow the Thread
+
+Based on their answer, dig into specifics:
+
+- If they mention a technology → "Why that one specifically?"
+- If they mention a constraint → "What happens if we don't honor this?"
+- If they mention a trade-off → "Which side do you want to land on, and why?"
+- If they mention a concern → "What's the worst case?"
+
+Use `AskUserQuestion` when there are clear interpretation forks. Free text otherwise.
+
+### 5. Capture Locked Decisions
+
+Build up a list of **locked decisions** — things the planner MUST honor. Each decision has:
+- The choice (what)
+- The rationale (why)
+- The source (who/when)
+
+Also capture:
+- **Discretion items** — things the planner can decide freely
+- **Deferred ideas** — good ideas that are NOT in this phase
+- **Risk flags** — things to watch during building
+- **Open questions** — things that still need resolution
+
+### 6. Decision Gate
+
+When you have enough context:
+
+- header: "Ready to lock?"
+- question: "Ready to lock these decisions and move to /qualia-plan {N}?"
+- options:
+  - "Lock it in" — Write phase-{N}-context.md and done
+  - "Keep exploring" — I have more to say
+
+Loop until "Lock it in".
+
+### 7. Write phase-{N}-context.md
+
+Use the template at `~/.claude/qualia-templates/phase-context.md`. Fill every section with concrete content.
+
+```bash
+# Write the file to .planning/phase-{N}-context.md
+```
+
+### 8. Commit
+
+```bash
+git add .planning/phase-{N}-context.md
+git commit -m "docs(phase-{N}): capture phase context before planning"
+```
+
+### 9. Route to Next
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "PHASE {N} CONTEXT LOCKED" "/qualia-plan {N}"
+```
+
+## Rules
+
+1. **One session, one phase.** Don't try to discuss phases 1 and 2 in the same invocation.
+2. **Locked decisions are NON-NEGOTIABLE.** The planner will honor them exactly. If you lock something you're not sure about, that's a mistake.
+3. **Don't redo research.** If the user asks a research question you don't know, suggest `/qualia-research {N}` instead.
+4. **Short context files are fine.** If the phase is simple, a 30-line context.md is better than a forced 200-line one.

package/skills/qualia-help/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: qualia-help
+description: "Open the Qualia Framework reference guide in the browser. A beautiful themed HTML page with all commands, rules, services, and the road. Trigger on 'help', 'how does this work', 'show me the commands', 'qualia help', 'reference'."
+---
+
+# /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
+VERSION=$(node -e "console.log(require(require('os').homedir() + '/.claude/.qualia-config.json').version || 'v3')" 2>/dev/null || echo "v3")
+TEMPLATE="$HOME/.claude/qualia-templates/help.html"
+OUTPUT="/tmp/qualia-help.html"
+
+# If template doesn't exist, check the framework install
+if [ ! -f "$TEMPLATE" ]; then
+  TEMPLATE="$(dirname "$(dirname "$(which qualia-framework 2>/dev/null || echo '')")")/templates/help.html"
+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 ~/.claude/bin/qualia-ui.js banner router
+node ~/.claude/bin/qualia-ui.js ok "Reference guide opened in browser"
+node ~/.claude/bin/qualia-ui.js info "File: /tmp/qualia-help.html"
+```
+
+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

package/skills/qualia-learn/SKILL.md

@@ -46,17 +46,40 @@ What did you learn?
 3. Client preference — client-specific requirement
 ```
 
-### 2. Format Entry
+### 2. Check for Duplicates
+
+Before saving, check if a similar entry already exists:
+
+```bash
+# Search for the title (case-insensitive substring match)
+grep -i "{title keywords}" ~/.claude/knowledge/{type}.md 2>/dev/null
+```
+
+If a near-match exists (title is similar to an existing entry):
+- 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.
+
+### 3. Format Entry
+
+Each entry gets a unique ID and ISO timestamp for dedup and ordering:
 
 ```markdown
-### {Title} ({date})
+
+---
+
+### {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}
 ```
 
-### 3. Append to Knowledge File
+### 4. Append to Knowledge File
+
+Append-only — never overwrite the file, always add at the end:
 
 ```bash
 # Append to the right file
@@ -67,7 +90,7 @@ echo "{formatted entry}" >> ~/.claude/knowledge/{type}.md
 - Fix → `~/.claude/knowledge/common-fixes.md`
 - Client pref → `~/.claude/knowledge/client-prefs.md`
 
-### 4. Confirm
+### 5. Confirm
 
 ```
 ⬢ Saved to {file}