wicked-brain 0.3.5 → 0.4.1

package/README.md

@@ -33,6 +33,7 @@ Your documents  ──>  Structured chunks  ──>  Synthesized wiki  ──>
 
 - **Chunks** are source-faithful extractions with rich metadata (entities, themes, tags)
 - **Wiki articles** are LLM-synthesized concepts with `[[backlinks]]` to source chunks
+- **Links carry confidence** — confirmed connections rank higher, contradictions surface for review
 - **Every claim traces back** to a specific file you can read, edit, or delete
 
 The brain is plain markdown on your filesystem. Open it in Obsidian, VS Code, or `cat`. No black box.
@@ -75,6 +76,12 @@ npx wicked-brain
 
 That's it. The installer detects your AI CLIs and drops in the skills. First time you use any skill, it walks you through setup.
 
+To install into a non-standard CLI config path:
+
+```bash
+npx wicked-brain --path=~/alt-configs/.claude
+```
+
 Or install via [agent-skills-cli](https://github.com/Karanjot786/agent-skills-cli):
 
 ```bash
@@ -111,7 +118,7 @@ Every operation uses **progressive loading** — the agent never pulls more than
 | **Connections** | None (just similarity scores) | Explicit `[[backlinks]]` between concepts |
 | **Auditability** | Low (why did it retrieve this?) | High (every claim links to a source file) |
 | **Infrastructure** | Vector DB + embedding pipeline + retrieval service | One SQLite file + markdown |
-| **Maintenance** | Re-embed on changes, tune thresholds | Agent self-heals via lint and enhance |
+| **Maintenance** | Re-embed on changes, tune thresholds | Agent self-heals via lint, enhance, and confidence tracking |
 | **Cost to start** | Embedding API calls for entire corpus | Zero (deterministic chunking is free) |
 | **Ideal scale** | Millions of documents | 100 - 10,000 high-signal documents |
 
@@ -119,16 +126,24 @@ Every operation uses **progressive loading** — the agent never pulls more than
 
 | Skill | What it does |
 |---|---|
-| `wicked-brain:init` | Set up a new brain (auto-triggers on first use) |
+| `wicked-brain:init` | Set up a new brain — creates directory structure, then onboards your project in parallel |
 | `wicked-brain:ingest` | Add source files — text extracted deterministically, binary docs read via LLM vision |
 | `wicked-brain:search` | Parallel search across your brain and linked brains |
 | `wicked-brain:read` | Progressive loading: depth 0 (stats), depth 1 (summary), depth 2 (full content) |
 | `wicked-brain:query` | Answer questions with source citations |
 | `wicked-brain:compile` | Synthesize wiki articles from chunks |
-| `wicked-brain:lint` | Find broken links, orphan chunks, inconsistencies |
-| `wicked-brain:enhance` | Identify and fill knowledge gaps |
-| `wicked-brain:status` | Brain health, stats, orientation |
+| `wicked-brain:lint` | Find broken links, orphan chunks, inconsistencies, tag synonyms, low-confidence links; auto-fix where possible |
+| `wicked-brain:enhance` | Identify and fill knowledge gaps with inferred content |
+| `wicked-brain:memory` | Store and recall experiential learnings across sessions (working / episodic / semantic tiers) |
+| `wicked-brain:status` | Brain health, stats, convergence debt detection, contradiction hotspots |
+| `wicked-brain:confirm` | Confirm or contradict a brain link — adjusts confidence score and tracks evidence |
+| `wicked-brain:synonyms` | Manage search synonym mappings; auto-suggest from search misses and tag frequency |
 | `wicked-brain:server` | Manage the background search server (auto-triggered) |
+| `wicked-brain:configure` | Write brain-aware context into your CLI's config (CLAUDE.md, GEMINI.md, etc.) |
+| `wicked-brain:batch` | Generate scripts for bulk operations — avoids burning context on repetitive tool calls |
+| `wicked-brain:retag` | Backfill synonym-expanded tags across all chunks for better search recall |
+| `wicked-brain:update` | Check npm for updates and reinstall skills across all detected CLIs |
+| `wicked-brain:lsp` | Universal code intelligence via LSP — hover, go-to-definition, diagnostics, completions |
 
 ## Multi-Brain Federation
 
@@ -169,7 +184,7 @@ Modern LLMs read PDF, DOCX, PPTX, and XLSX natively. When you ingest a binary do
 
 ## Architecture
 
-**~500 lines of server JavaScript** (SQLite FTS5 + file watcher) + **~900 lines of skill markdown** (agent instructions).
+**~300 lines of server JavaScript** (SQLite FTS5 + file watcher) + **~1,400 lines of skill markdown** (agent instructions).
 
 That's the entire system. Compare that to a typical RAG stack:
 
@@ -182,7 +197,7 @@ Typical RAG:                          wicked-brain:
 - Re-ranking model                    - LLM reasoning
 - Orchestration layer                 - Skills (markdown)
 ─────────────────                     ─────────────────
-~5,000+ lines, 10+ deps              ~1,400 lines, 1 dep
+~5,000+ lines, 10+ deps              ~1,700 lines, 1 dep
 ```
 
 ## Supported CLIs
@@ -194,6 +209,8 @@ Typical RAG:                          wicked-brain:
 | GitHub Copilot CLI | Supported |
 | Cursor | Supported |
 | Codex | Supported |
+| Kiro | Supported |
+| Antigravity | Supported |
 
 Skills use only universally available operations (read files, write files, run shell commands, grep). No CLI-specific features.
 

package/install.mjs

@@ -2,7 +2,7 @@
 // wicked-brain installer — detects CLIs and installs skills + agents
 
 import { existsSync, mkdirSync, cpSync, readdirSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { join, resolve, basename } from "node:path";
 import { homedir } from "node:os";
 import { argv } from "node:process";
 import { fileURLToPath } from "node:url";
@@ -12,56 +12,55 @@ const skillsSource = join(__dirname, "skills");
 const home = homedir();
 
 const CLI_TARGETS = [
-  { name: "claude", dir: join(home, ".claude", "skills"), agentDir: join(home, ".claude", "agents"), platform: "claude" },
-  { name: "gemini", dir: join(home, ".gemini", "skills"), agentDir: join(home, ".gemini", "agents"), platform: "gemini" },
-  { name: "copilot", dir: join(home, ".github", "skills"), agentDir: join(home, ".github", "agents"), platform: "copilot" },
-  { name: "codex", dir: join(home, ".codex", "skills"), agentDir: join(home, ".codex", "agents"), platform: "codex" },
-  { name: "cursor", dir: join(home, ".cursor", "skills"), agentDir: join(home, ".cursor", "agents"), platform: "cursor" },
-  { name: "kiro", dir: join(home, ".kiro", "skills"), agentDir: join(home, ".kiro", "agents"), platform: "kiro" },
-  { name: "antigravity", dir: join(home, ".antigravity", "skills"), agentDir: join(home, ".antigravity", "rules"), platform: "antigravity" },
+  { name: "claude",      dir: join(home, ".claude", "skills"),      agentDir: join(home, ".claude", "agents"),      agentSubdir: "agents", platform: "claude" },
+  { name: "gemini",      dir: join(home, ".gemini", "skills"),      agentDir: join(home, ".gemini", "agents"),      agentSubdir: "agents", platform: "gemini" },
+  { name: "copilot",     dir: join(home, ".github", "skills"),      agentDir: join(home, ".github", "agents"),      agentSubdir: "agents", platform: "copilot" },
+  { name: "codex",       dir: join(home, ".codex", "skills"),       agentDir: join(home, ".codex", "agents"),       agentSubdir: "agents", platform: "codex" },
+  { name: "cursor",      dir: join(home, ".cursor", "skills"),      agentDir: join(home, ".cursor", "agents"),      agentSubdir: "agents", platform: "cursor" },
+  { name: "kiro",        dir: join(home, ".kiro", "skills"),        agentDir: join(home, ".kiro", "agents"),        agentSubdir: "agents", platform: "kiro" },
+  { name: "antigravity", dir: join(home, ".antigravity", "skills"), agentDir: join(home, ".antigravity", "rules"),  agentSubdir: "rules",  platform: "antigravity" },
 ];
 
-// Detect which CLIs are installed by checking if parent dir exists
-const detected = CLI_TARGETS.filter((t) => {
-  const parentDir = resolve(t.dir, "..");
-  return existsSync(parentDir);
-});
-
 console.log("wicked-brain installer\n");
 
-if (detected.length === 0) {
-  console.log("No supported AI CLIs detected. Supported: claude, gemini, copilot, codex, cursor, kiro, antigravity");
-  console.log("Install skills manually by copying the skills/ directory.");
-  process.exit(1);
-}
-
-console.log(`Detected CLIs: ${detected.map((d) => d.name).join(", ")}\n`);
-
-// Allow filtering via --cli flag or custom --path
 const args = argv.slice(2);
+const argValue = (a) => a.split("=")[1];
 const cliArg = args.find((a) => a.startsWith("--cli="));
 const pathArg = args.find((a) => a.startsWith("--path="));
 
 let targets;
 
 if (pathArg) {
-  const rawPath = pathArg.split("=")[1].replace(/^~/, home);
-  const customPath = resolve(rawPath);
-  const dirName = customPath.split(/[\\/]/).pop().replace(/^\./, ""); // e.g. ".claude" → "claude"
+  const rawPath = argValue(pathArg);
+  if (!rawPath) {
+    console.error("Error: --path requires a value (e.g. --path=~/.claude)");
+    process.exit(1);
+  }
+  const customPath = resolve(rawPath.replace(/^~/, home));
+  // Strip leading dot to match CLI_TARGETS names (e.g. ".claude" → "claude")
+  const dirName = basename(customPath).replace(/^\./, "");
   const knownPlatform = CLI_TARGETS.find((t) => t.name === dirName);
-  // Use platform's agent subdir name (e.g. antigravity uses "rules"), default to "agents"
-  const agentSubdirName = knownPlatform
-    ? knownPlatform.agentDir.split(/[\\/]/).pop()
-    : "agents";
+  const agentSubdir = knownPlatform?.agentSubdir ?? "agents";
   targets = [{
     name: dirName,
     dir: join(customPath, "skills"),
-    agentDir: join(customPath, agentSubdirName),
+    agentDir: join(customPath, agentSubdir),
     platform: knownPlatform?.platform ?? dirName,
   }];
   console.log(`Custom path: ${customPath}\n`);
 } else {
-  const cliFilter = cliArg ? cliArg.split("=")[1].split(",") : null;
+  // Detect which CLIs are installed by checking if parent dir exists
+  const detected = CLI_TARGETS.filter((t) => existsSync(resolve(t.dir, "..")));
+
+  if (detected.length === 0) {
+    console.log("No supported AI CLIs detected. Supported: claude, gemini, copilot, codex, cursor, kiro, antigravity");
+    console.log("Install skills manually by copying the skills/ directory.");
+    process.exit(1);
+  }
+
+  console.log(`Detected CLIs: ${detected.map((d) => d.name).join(", ")}\n`);
+
+  const cliFilter = cliArg ? argValue(cliArg).split(",") : null;
   targets = cliFilter ? detected.filter((d) => cliFilter.includes(d.name)) : detected;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "type": "module",
   "description": "Digital brain as skills for AI coding CLIs — no vector DB, no embeddings, no infrastructure",
   "keywords": [

package/server/bin/wicked-brain-server.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createServer } from "node:http";
-import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { argv, pid, exit } from "node:process";
 import { FileWatcher } from "../lib/file-watcher.mjs";
@@ -15,9 +15,27 @@ function getArg(name) {
 }
 
 const brainPath = resolve(getArg("brain") || ".");
-const port = parseInt(getArg("port") || "4242", 10);
+const preferredPort = parseInt(getArg("port") || "4242", 10);
 const configPath = join(brainPath, "brain.json");
 
+/** Find a free TCP port starting from `start`. */
+function findFreePort(start) {
+  return new Promise((resolve, reject) => {
+    const tryPort = (p) => {
+      const probe = createServer();
+      probe.once("error", (err) => {
+        if (err.code === "EADDRINUSE") tryPort(p + 1);
+        else reject(err);
+      });
+      probe.once("listening", () => {
+        probe.close(() => resolve(p));
+      });
+      probe.listen(p, "127.0.0.1");
+    };
+    tryPort(start);
+  });
+}
+
 // Read brain config
 let brainId = "unknown";
 try {
@@ -66,9 +84,33 @@ const actions = {
   forward_links: (p) => ({ links: db.forwardLinks(p.id) }),
   stats: () => db.stats(),
   candidates: (p) => ({ candidates: db.candidates(p) }),
+  symbols: async (p) => {
+    // Prefer LSP workspace symbols (structured, language-aware)
+    const lspResult = await lsp.workspaceSymbols({ query: p.name || p.query || "" });
+    if (lspResult.symbols && lspResult.symbols.length > 0) {
+      return {
+        results: lspResult.symbols.map(s => ({
+          id: `${s.file}::${s.name}`,
+          name: s.name,
+          type: s.kind,
+          file_path: s.file,
+          line_start: s.line,
+        })),
+        source: "lsp",
+      };
+    }
+    // Fall back to FTS-based symbol search
+    return { ...db.symbols(p), source: "fts" };
+  },
+  dependents: (p) => db.dependents(p),
+  refs: async (p) => lsp.references(p),
   access_log: (p) => db.accessLog(p.id),
   recent_memories: (p) => ({ memories: db.recentMemories(p) }),
   contradictions: () => ({ links: db.contradictions() }),
+  confirm_link: (p) => db.confirmLink(p.source_id, p.target_path, p.verdict),
+  link_health: () => db.linkHealth(),
+  tag_frequency: () => ({ tags: db.tagFrequency() }),
+  search_misses: (p) => ({ misses: db.searchMisses(p) }),
   // LSP actions
   "lsp-health": () => lsp.health(),
   "lsp-symbols": (p) => lsp.symbols(p),
@@ -123,9 +165,10 @@ const server = createServer((req, res) => {
 });
 
 // Read project directories from config
+const metaConfigPath = join(brainPath, "_meta", "config.json");
 let projects = [];
 try {
-  const metaConfig = JSON.parse(readFileSync(join(brainPath, "_meta", "config.json"), "utf-8"));
+  const metaConfig = JSON.parse(readFileSync(metaConfigPath, "utf-8"));
   projects = metaConfig.projects || [];
 } catch {}
 
@@ -136,6 +179,18 @@ watcher.onFileChange((relPath, absPath, content, eventType) => {
   lsp.handleFileChange(relPath, absPath, content, eventType);
 });
 
+const port = await findFreePort(preferredPort);
+
+// Write actual port back to config so skills can always find the server
+try {
+  let metaConfig = {};
+  try { metaConfig = JSON.parse(readFileSync(metaConfigPath, "utf-8")); } catch {}
+  metaConfig.server_port = port;
+  writeFileSync(metaConfigPath, JSON.stringify(metaConfig, null, 2) + "\n");
+} catch (err) {
+  console.error(`Warning: could not write port to config: ${err.message}`);
+}
+
 server.listen(port, () => {
   console.log(`wicked-brain-server running on port ${port} (brain: ${brainId}, pid: ${pid})`);
   watcher.start();

package/server/lib/sqlite-search.mjs

@@ -2,6 +2,16 @@ import Database from "better-sqlite3";
 import { parseWikilinks } from "./wikilinks.mjs";
 import { statSync } from "node:fs";
 
+/**
+ * Extracts body text from a document, stripping YAML frontmatter.
+ * Falls back to the raw content if no frontmatter is detected.
+ */
+function extractBodyExcerpt(content, maxLen = 300) {
+  const match = content.match(/^---\n[\s\S]*?\n---\n?([\s\S]*)/);
+  const body = match ? match[1] : content;
+  return body.trim().slice(0, maxLen);
+}
+
 function escapeFtsQuery(query) {
   return query
     .trim()
@@ -14,6 +24,9 @@ function escapeFtsQuery(query) {
 /** Weight factor for backlink count in search ranking (PageRank-lite). */
 const BACKLINK_WEIGHT = 0.5;
 
+/** Weight factor for average backlink confidence in search ranking. */
+const CONFIDENCE_WEIGHT = 0.3;
+
 /** Weight factor for access count in search ranking. */
 const SEARCH_ACCESS_WEIGHT = 0.1;
 
@@ -63,7 +76,9 @@ export class SqliteSearch {
         target_path TEXT NOT NULL,
         target_brain TEXT,
         rel TEXT,
-        link_text TEXT
+        link_text TEXT,
+        confidence REAL DEFAULT 0.5,
+        evidence_count INTEGER DEFAULT 0
       );
 
       CREATE INDEX IF NOT EXISTS idx_links_source ON links(source_id);
@@ -76,6 +91,12 @@ export class SqliteSearch {
       );
       CREATE INDEX IF NOT EXISTS idx_access_doc ON access_log(doc_id);
       CREATE INDEX IF NOT EXISTS idx_access_session ON access_log(session_id);
+
+      CREATE TABLE IF NOT EXISTS search_misses (
+        query TEXT NOT NULL,
+        searched_at INTEGER NOT NULL,
+        session_id TEXT
+      );
     `);
 
     this.#migrate();
@@ -114,8 +135,23 @@ export class SqliteSearch {
       currentVersion = 1;
     }
 
-    // Future migrations go here:
-    // if (currentVersion < 2) { ... currentVersion = 2; }
+    // Migration 2: add confidence + evidence_count to links, add search_misses table
+    if (currentVersion < 2) {
+      try { this.#db.prepare(`SELECT confidence FROM links LIMIT 0`).get(); } catch {
+        this.#db.exec(`ALTER TABLE links ADD COLUMN confidence REAL DEFAULT 0.5`);
+      }
+      try { this.#db.prepare(`SELECT evidence_count FROM links LIMIT 0`).get(); } catch {
+        this.#db.exec(`ALTER TABLE links ADD COLUMN evidence_count INTEGER DEFAULT 0`);
+      }
+      this.#db.exec(`
+        CREATE TABLE IF NOT EXISTS search_misses (
+          query TEXT NOT NULL,
+          searched_at INTEGER NOT NULL,
+          session_id TEXT
+        )
+      `);
+      currentVersion = 2;
+    }
 
     // Persist the current version
     this.#db.exec(`DELETE FROM _schema_version`);
@@ -132,8 +168,16 @@ export class SqliteSearch {
     }
   }
 
+  /** Extract YAML frontmatter block from content if present. Returns null if none. */
+  static #extractFrontmatter(content) {
+    const m = content.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+    return m ? m[1] : null;
+  }
+
   index(doc) {
-    const { id, path, content, frontmatter = null } = doc;
+    const { id, path, content } = doc;
+    // Auto-extract frontmatter from content when not provided explicitly
+    const frontmatter = doc.frontmatter ?? SqliteSearch.#extractFrontmatter(content);
     const brainId = this.#brainId;
     const indexedAt = Date.now();
 
@@ -209,8 +253,10 @@ export class SqliteSearch {
           d.path,
           d.brain_id,
           snippet(documents_fts, 2, '<b>', '</b>', '…', 32) AS snippet,
+          SUBSTR(d.content, 1, 1000) AS raw_content,
           COALESCE(link_count.cnt, 0) AS backlink_count,
-          COALESCE(ac.cnt, 0) AS access_count
+          COALESCE(ac.cnt, 0) AS access_count,
+          COALESCE(link_conf.avg_conf, 0.5) AS avg_backlink_confidence
         FROM documents_fts f
         JOIN documents d ON d.id = f.id
         LEFT JOIN (
@@ -218,6 +264,11 @@ export class SqliteSearch {
           FROM links
           GROUP BY target_path
         ) link_count ON d.path = link_count.target_path
+        LEFT JOIN (
+          SELECT target_path, AVG(confidence) AS avg_conf
+          FROM links
+          GROUP BY target_path
+        ) link_conf ON d.path = link_conf.target_path
         LEFT JOIN (
           SELECT doc_id, COUNT(*) AS cnt
           FROM access_log
@@ -225,10 +276,15 @@ export class SqliteSearch {
         ) ac ON d.id = ac.doc_id
         WHERE documents_fts MATCH ?
         ${sinceClause}
-        ORDER BY (f.rank - (COALESCE(link_count.cnt, 0) * ${BACKLINK_WEIGHT}) - (COALESCE(ac.cnt, 0) * ${SEARCH_ACCESS_WEIGHT}))
+        ORDER BY (f.rank - (COALESCE(link_count.cnt, 0) * ${BACKLINK_WEIGHT}) - (COALESCE(ac.cnt, 0) * ${SEARCH_ACCESS_WEIGHT}) - (COALESCE(link_conf.avg_conf, 0.5) * ${CONFIDENCE_WEIGHT}))
         LIMIT ? OFFSET ?
       `)
-      .all(escaped, ...sinceParams, limit, offset);
+      .all(escaped, ...sinceParams, limit, offset)
+      .map((row) => {
+        const body_excerpt = extractBodyExcerpt(row.raw_content ?? "");
+        delete row.raw_content;
+        return { ...row, body_excerpt };
+      });
 
     const countRow = this.#db
       .prepare(
@@ -241,6 +297,13 @@ export class SqliteSearch {
 
     const total_matches = countRow ? countRow.cnt : 0;
 
+    // Log search miss when no results returned
+    if (total_matches === 0) {
+      this.#db.prepare(
+        `INSERT INTO search_misses (query, searched_at, session_id) VALUES (?, ?, ?)`
+      ).run(query, Date.now(), session_id ?? null);
+    }
+
     // Log access for each returned document if session_id provided
     if (session_id && rows.length > 0) {
       const logAccess = this.#db.prepare(
@@ -460,6 +523,222 @@ export class SqliteSearch {
       .all();
   }
 
+  /**
+   * Confirm or contradict a link, adjusting its confidence score.
+   * verdict: "confirm" → confidence += 0.1 (capped at 1.0)
+   * verdict: "contradict" → confidence -= 0.2 (floored at 0.0)
+   * Returns the updated link row, or null if no matching link was found.
+   */
+  confirmLink(sourceId, targetPath, verdict) {
+    const link = this.#db.prepare(`
+      SELECT rowid, confidence, evidence_count
+      FROM links
+      WHERE source_id = ? AND target_path = ?
+      LIMIT 1
+    `).get(sourceId, targetPath);
+
+    if (!link) return null;
+
+    let newConfidence;
+    if (verdict === "confirm") {
+      newConfidence = Math.min(link.confidence + 0.1, 1.0);
+    } else if (verdict === "contradict") {
+      newConfidence = Math.max(link.confidence - 0.2, 0.0);
+    } else {
+      throw new Error(`Unknown verdict: ${verdict}. Expected "confirm" or "contradict".`);
+    }
+
+    this.#db.prepare(`
+      UPDATE links
+      SET confidence = ?, evidence_count = evidence_count + 1
+      WHERE rowid = ?
+    `).run(newConfidence, link.rowid);
+
+    return this.#db.prepare(`
+      SELECT source_id, target_path, confidence, evidence_count
+      FROM links
+      WHERE rowid = ?
+    `).get(link.rowid);
+  }
+
+  /**
+   * Returns link health statistics for the lint skill.
+   * - broken_links: links where target_path doesn't exist in documents table
+   * - low_confidence_links: links where confidence < 0.3
+   * - total_links: total link count
+   * - avg_confidence: average confidence across all links
+   */
+  linkHealth() {
+    const totalsRow = this.#db.prepare(`
+      SELECT COUNT(*) AS total_links, AVG(confidence) AS avg_confidence
+      FROM links
+    `).get();
+
+    const brokenRow = this.#db.prepare(`
+      SELECT COUNT(*) AS cnt
+      FROM links l
+      WHERE NOT EXISTS (
+        SELECT 1 FROM documents d WHERE d.path = l.target_path
+      )
+    `).get();
+
+    const lowConfRow = this.#db.prepare(`
+      SELECT COUNT(*) AS cnt
+      FROM links
+      WHERE confidence < 0.3
+    `).get();
+
+    return {
+      total_links: totalsRow.total_links ?? 0,
+      avg_confidence: totalsRow.avg_confidence ?? null,
+      broken_links: brokenRow.cnt ?? 0,
+      low_confidence_links: lowConfRow.cnt ?? 0,
+    };
+  }
+
+  /**
+   * Returns tag frequency data for synonym detection.
+   * Parses frontmatter from all documents and extracts `contains` arrays.
+   * Returns [{tag, count}] sorted by count descending.
+   */
+  tagFrequency() {
+    const rows = this.#db.prepare(`
+      SELECT frontmatter FROM documents WHERE frontmatter IS NOT NULL
+    `).all();
+
+    const counts = new Map();
+
+    for (const row of rows) {
+      const fm = row.frontmatter;
+      // Match: contains: tag1 tag2 tag3  (space-separated inline)
+      // or contains: ["tag1","tag2"]  (JSON array)
+      // or multi-line YAML list (- tag per line)
+      // Note: \S required after contains: to avoid matching block-list headers
+      const inlineMatch = fm.match(/^contains:[ \t]+(\S.*)$/m);
+      if (inlineMatch) {
+        const raw = inlineMatch[1].trim();
+        let tags = [];
+        // Try JSON array first
+        if (raw.startsWith("[")) {
+          try {
+            tags = JSON.parse(raw).map(String);
+          } catch {
+            tags = raw.replace(/[\[\]"]/g, "").split(/[\s,]+/).filter(Boolean);
+          }
+        } else {
+          tags = raw.split(/\s+/).filter(Boolean);
+        }
+        for (const tag of tags) {
+          counts.set(tag, (counts.get(tag) ?? 0) + 1);
+        }
+      }
+
+      // Also handle YAML block list: lines starting with "  - tag" after "contains:"
+      const blockMatch = fm.match(/^contains:\s*\n((?:\s+-\s+.+\n?)+)/m);
+      if (!inlineMatch && blockMatch) {
+        const listLines = blockMatch[1].match(/^\s+-\s+(.+)$/gm) || [];
+        for (const line of listLines) {
+          const tag = line.replace(/^\s+-\s+/, "").trim();
+          if (tag) counts.set(tag, (counts.get(tag) ?? 0) + 1);
+        }
+      }
+    }
+
+    return Array.from(counts.entries())
+      .map(([tag, count]) => ({ tag, count }))
+      .sort((a, b) => b.count - a.count);
+  }
+
+  /**
+   * Symbol lookup: FTS search for a symbol name, returning structured results
+   * with file path and position extracted from chunk frontmatter.
+   * Used as fallback when no LSP server is running.
+   */
+  symbols({ name, limit = 10 }) {
+    const escaped = escapeFtsQuery(name);
+    if (!escaped) return { results: [] };
+
+    const rows = this.#db.prepare(`
+      SELECT d.id, d.path, d.frontmatter, d.content
+      FROM documents_fts f
+      JOIN documents d ON d.id = f.id
+      WHERE documents_fts MATCH ?
+      ORDER BY rank
+      LIMIT ?
+    `).all(escaped, limit * 4); // overfetch — we may skip rows with no source_path
+
+    const seen = new Set();
+    const results = [];
+
+    for (const row of rows) {
+      if (results.length >= limit) break;
+      const fm = row.frontmatter || SqliteSearch.#extractFrontmatter(row.content) || "";
+      const sourcePathMatch = fm.match(/^source_path:\s*(.+)$/m);
+      const sourcePath = sourcePathMatch ? sourcePathMatch[1].trim() : null;
+      const key = `${sourcePath ?? row.path}::${name}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      results.push({
+        id: key,
+        name,
+        type: "unknown",
+        file_path: sourcePath,
+        chunk_path: row.path,
+        line_start: null,
+      });
+    }
+
+    return { results };
+  }
+
+  /**
+   * Dependent files: find all files (by source_path) that mention the given name.
+   * Purely FTS-based — no LSP required.
+   */
+  dependents({ name, limit = 20 }) {
+    const escaped = escapeFtsQuery(name);
+    if (!escaped) return { files: [] };
+
+    const rows = this.#db.prepare(`
+      SELECT d.frontmatter, d.content, d.path
+      FROM documents_fts f
+      JOIN documents d ON d.id = f.id
+      WHERE documents_fts MATCH ?
+      LIMIT ?
+    `).all(escaped, limit * 5);
+
+    const files = new Map(); // source_path → {file_path, chunk_path}
+    for (const row of rows) {
+      if (files.size >= limit) break;
+      const fm = row.frontmatter || SqliteSearch.#extractFrontmatter(row.content) || "";
+      const m = fm.match(/^source_path:\s*(.+)$/m);
+      const sourcePath = m ? m[1].trim() : null;
+      if (sourcePath && !files.has(sourcePath)) {
+        files.set(sourcePath, row.path);
+      }
+    }
+
+    return { files: [...files.keys()] };
+  }
+
+  /**
+   * Retrieve logged search misses.
+   * @param {object} opts
+   * @param {number} [opts.limit=50]
+   * @param {string} [opts.since] - ISO 8601 timestamp
+   */
+  searchMisses({ limit = 50, since = null } = {}) {
+    const sinceClause = since ? `WHERE searched_at >= ?` : "";
+    const sinceParams = since ? [new Date(since).getTime()] : [];
+    return this.#db.prepare(`
+      SELECT query, searched_at, session_id
+      FROM search_misses
+      ${sinceClause}
+      ORDER BY searched_at DESC
+      LIMIT ?
+    `).all(...sinceParams, limit);
+  }
+
   close() {
     this.#db.close();
   }

package/server/lib/wikilinks.mjs

@@ -7,6 +7,7 @@ const KNOWN_RELS = new Set([
   "caused-by",
   "extends",
   "depends-on",
+  "questions",
 ]);
 
 export function parseWikilinks(text) {

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain-server",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "type": "module",
   "description": "SQLite FTS5 search server for wicked-brain digital knowledge bases",
   "keywords": [

package/skills/wicked-brain-compile/SKILL.md

@@ -86,6 +86,26 @@ file, update `authored_at` and `source_hashes`).
 Read uncovered chunks (frontmatter + body) to understand their content.
 Group them by topic/concept.
 
+## Step 3.5: Identify Cluster Persona
+
+For each concept cluster identified in Step 3, analyze the chunk tags and content
+to select the most appropriate synthesis persona:
+
+| Chunk tags/content signals | Persona | Focus |
+|---------------------------|---------|-------|
+| architecture, system-design, components, topology | Architect | Emphasize component relationships, trade-offs, scalability |
+| testing, quality, coverage, assertions | QE Specialist | Emphasize test strategies, edge cases, quality metrics |
+| security, auth, encryption, vulnerabilities | Security Analyst | Emphasize threat models, attack surfaces, mitigations |
+| api, endpoints, contracts, integration | API Designer | Emphasize interface contracts, versioning, consumer experience |
+| operations, deployment, monitoring, incidents | SRE | Emphasize reliability, observability, runbooks |
+| data, schema, migration, storage | Data Engineer | Emphasize data integrity, schema evolution, performance |
+| Default (no strong signal) | Generalist | Balanced synthesis across all dimensions |
+
+When writing the wiki article in Step 4, adopt this persona's perspective:
+- Frame the article's structure around the persona's priorities
+- Include a "Considerations" section written from the persona's viewpoint
+- Add the persona to the article's frontmatter: `synthesis_persona: {persona_name}`
+
 ## Step 4: Write wiki articles
 
 For each concept cluster, write a wiki article to `{brain_path}/wiki/concepts/{concept-name}.md`
@@ -96,6 +116,7 @@ or `{brain_path}/wiki/topics/{topic-name}.md`:
 authored_by: llm
 authored_at: {ISO timestamp}
 confidence: {average of source chunk confidences, rounded to 2 decimals}
+synthesis_persona: generalist
 source_chunks:
   - {chunk-path-1}
   - {chunk-path-2}
@@ -122,6 +143,55 @@ explicit lineage trail so the brain can track how concepts evolve over time.
 - [[brain-id::cross-brain-concept]] (if applicable)
 ```
 
+## Step 4.5: Consensus Compilation (high-importance clusters only)
+
+A cluster is "high-importance" when it has:
+- 5+ source chunks, OR
+- Source chunks with backlink_count >= 3 (check via backlinks API), OR
+- Source chunks spanning 3+ distinct path prefixes (cross-cutting concern)
+
+For high-importance clusters, enhance the article with a second perspective:
+
+1. After writing the initial article with the primary persona (Step 4), identify
+   a **contrasting** persona that would view the same content differently:
+   - Architect ↔ SRE (design vs. operational reality)
+   - QE Specialist ↔ Developer (testing rigor vs. implementation pragmatism)
+   - Security Analyst ↔ API Designer (lockdown vs. usability)
+   - For other combinations, choose the most relevant contrasting view.
+
+2. Re-read the source chunks from the contrasting persona's perspective.
+
+3. Add a "## Alternative Perspectives" section to the article:
+   ```
+   ## Alternative Perspectives
+
+   ### {Contrasting Persona} View
+
+   {2-3 paragraphs examining the topic from the contrasting perspective.
+    Highlight where this view agrees with the primary synthesis, and where
+    it raises different priorities or concerns.}
+
+   ### Points of Tension
+
+   {Bullet list of specific disagreements or trade-offs between the two views.
+    Use typed wikilinks where relevant:}
+   - [[questions::wiki/concepts/{related-concept}]] — {what the tension is about}
+   ```
+
+4. Update the article frontmatter to reflect consensus compilation:
+   ```yaml
+   synthesis_persona: {primary_persona}
+   contrasting_persona: {secondary_persona}
+   consensus: true
+   ```
+
+If the cluster does NOT meet the high-importance threshold, skip this step
+(the single-persona article from Step 4 is sufficient).
+
+Note: The `questions` typed link (`[[questions::wiki/concepts/X]]`) is recognized
+by the brain server's wikilink parser alongside existing types (contradicts,
+supersedes, supports, caused-by, extends, depends-on).
+
 ## Step 5: Index new articles
 
 For each article written:

package/skills/wicked-brain-confirm/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: wicked-brain:confirm
+description: |
+  Confirm or contradict a brain link, adjusting its confidence score.
+  Increases confidence when a link is confirmed by evidence, decreases it
+  when contradicted. Tracks evidence_count for audit purposes.
+
+  Use when: "confirm this link", "contradict this connection", "adjust link
+  confidence", "mark link as confirmed", "this link is wrong".
+---
+
+# wicked-brain:confirm
+
+You adjust the confidence score of a brain link based on user feedback.
+
+## Cross-Platform Notes
+
+Commands in this skill work on macOS, Linux, and Windows. `curl` is available
+on Windows 10+ and macOS/Linux — it is used here for API calls.
+
+For the brain path default:
+- macOS/Linux: ~/.wicked-brain
+- Windows: %USERPROFILE%\.wicked-brain
+
+## Config
+
+Read `_meta/config.json` for brain path and server port.
+If it doesn't exist, trigger wicked-brain:init.
+
+## Parameters
+
+- **source_id** (required): the ID of the source document that contains the link
+- **target_path** (required): the target path the link points to
+- **verdict** (required): `confirm` or `contradict`
+
+## Process
+
+### Step 1: Validate parameters
+
+Ensure `source_id`, `target_path`, and `verdict` are provided.
+`verdict` must be exactly `"confirm"` or `"contradict"`.
+
+### Step 2: Submit the verdict to the server
+
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"confirm_link","params":{"source_id":"{source_id}","target_path":"{target_path}","verdict":"{verdict}"}}'
+```
+
+### Step 3: Report the result
+
+If the response contains a `confidence` value, report back to the user:
+
+- What the verdict was (`confirmed` or `contradicted`)
+- The updated confidence score (e.g., `0.6`)
+- The evidence_count (how many times this link has been evaluated)
+
+Example success response:
+```
+Link {source_id} → {target_path} {verdict}ed.
+Updated confidence: {confidence} (based on {evidence_count} evaluations)
+```
+
+If the API returns `null` (link not found), report:
+```
+No link found from {source_id} to {target_path}.
+Use wicked-brain:search to verify the source document ID and target path.
+```
+
+If the API returns an error, report the error message.
+
+### Step 4: Log the action
+
+Append an event to `{brain_path}/_meta/log.jsonl`:
+
+```json
+{"ts":"{ISO}","op":"link_{verdict}","source_id":"{source_id}","target_path":"{target_path}","confidence":{new_confidence},"evidence_count":{evidence_count},"author":"agent:confirm"}
+```
+
+Use your Write tool or append via shell:
+- macOS/Linux: `echo '...' >> {brain_path}/_meta/log.jsonl`
+- Windows PowerShell: `Add-Content -Path "{brain_path}\_meta\log.jsonl" -Value '...'`

package/skills/wicked-brain-ingest/SKILL.md

@@ -25,7 +25,7 @@ For the brain path default:
 
 ## Config
 
-Read `_meta/config.json` for brain path and server port.
+Read `{brain_path}/_meta/config.json` for brain path and server port.
 If it doesn't exist, trigger wicked-brain:init.
 
 ## Parameters
@@ -34,6 +34,20 @@ If it doesn't exist, trigger wicked-brain:init.
 
 ## Process
 
+### Step 0: Ensure server is running
+
+Before doing anything else, health-check the server:
+
+```bash
+curl -s -f -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"health","params":{}}'
+```
+
+If this fails (connection refused or non-2xx), invoke `wicked-brain:server` to start it
+before continuing. Re-read `_meta/config.json` after the server starts to get the
+actual port it bound to.
+
 ### Step 1: Assess scope
 
 Determine if the source is a single file or a directory.
@@ -169,9 +183,8 @@ Instead, write a batch script and run it. This preserves context and is dramatic
 
 ```javascript
 #!/usr/bin/env node
-import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, renameSync } from "node:fs";
 import { join, extname, basename, relative } from "node:path";
-import { createHash } from "node:crypto";
 
 const BRAIN = "{brain_path}";
 const PORT = {port};
@@ -273,7 +286,6 @@ async function removeOldChunks(name) {
     }
   }
   // Archive the old directory
-  const { renameSync } = await import("node:fs");
   renameSync(chunkDir, `${chunkDir}.archived-${ts}`);
   console.log(`  Archived old chunks: ${name}`);
 }
@@ -345,17 +357,17 @@ function walk(dir, callback) {
 
 console.log(`Ingesting from ${SOURCE_DIR}...`);
 
+// Collect files first, then process serially so every ingestFile is awaited
+const textFiles = [];
 walk(SOURCE_DIR, (filePath) => {
   const ext = extname(filePath).toLowerCase();
-  if (TEXT_EXT.has(ext)) {
-    try { ingestFile(filePath); } catch (e) { console.error(`  Error: ${filePath}: ${e.message}`); }
-  } else if (BINARY_EXT.has(ext)) {
-    binaryFiles.push(filePath);
-  }
+  if (TEXT_EXT.has(ext)) textFiles.push(filePath);
+  else if (BINARY_EXT.has(ext)) binaryFiles.push(filePath);
 });
 
-// Wait for all index operations
-await new Promise(r => setTimeout(r, 1000));
+for (const filePath of textFiles) {
+  try { await ingestFile(filePath); } catch (e) { console.error(`  Error: ${filePath}: ${e.message}`); }
+}
 
 console.log(`\nDone: ${totalFiles} files, ${totalChunks} chunks indexed`);
 if (binaryFiles.length > 0) {

package/skills/wicked-brain-init/SKILL.md

@@ -10,7 +10,7 @@ description: |
 
 # wicked-brain:init
 
-You initialize a new digital brain on the filesystem.
+You initialize a new digital brain on the filesystem and get it fully operational.
 
 ## Cross-Platform Notes
 
@@ -38,23 +38,16 @@ Ask these questions (provide defaults):
    - Default (Windows): `%USERPROFILE%\.wicked-brain`
 2. "What should this brain be called?" — Default: directory name
 
-### Step 2: Dispatch onboard agent (fire and continue)
+### Step 2: Check for existing brain
 
-Immediately dispatch the `wicked-brain-onboard` agent for the current project — don't wait for Steps 3–6 to finish first.
+If `{brain_path}/_meta/config.json` already exists, tell the user:
+"A brain already exists at `{brain_path}`. Do you want to re-initialize it (keeps existing chunks) or pick a different path?"
 
-Pass it:
-- `brain_path`: the path confirmed in Step 1
-- `project_path`: the current working directory
-
-**Sequencing rationale:** Onboard starts with a read-only scanning phase (Glob, Grep, Read across the project). That scanning takes meaningful time. Steps 3–6 below are fast — just creating a handful of files and directories. They will complete well before onboard finishes scanning and reaches its write phase (where it needs `brain_path` dirs to exist). So it is safe to fire onboard now and proceed immediately with Steps 3–6; the brain dirs will be in place long before onboard needs them.
-
-Continue with Steps 3–6 immediately after dispatching.
+Stop and wait for their answer before continuing.
 
 ### Step 3: Create directory structure
 
-Use your native Write/mkdir tools to create these directories and files.
-
-Directories to create (create each with its parent directories):
+Use your native Write tool to create these directories (write a `.gitkeep` placeholder in each):
 - `{brain_path}/raw`
 - `{brain_path}/chunks/extracted`
 - `{brain_path}/chunks/inferred`
@@ -99,21 +92,36 @@ Write to `{brain_path}/_meta/config.json`:
 }
 ```
 
+`server_port: 4242` is the *preferred* port. The server will find a free port starting
+from this value on startup and write the actual port back to this file. You do not
+need to find a free port manually.
+
 ### Step 6: Initialize the event log
 
 Use your Write tool to create an empty file at `{brain_path}/_meta/log.jsonl`.
 
-Shell equivalents if needed:
+### Step 7: Start the server
+
+Invoke `wicked-brain:server` to start the server against this brain path.
+The server will pick a free port and write it back to `_meta/config.json`.
+
 ```bash
-# macOS/Linux
-touch {brain_path}/_meta/log.jsonl
-```
-```powershell
-# Windows PowerShell
-New-Item -ItemType File -Force -Path "{brain_path}\_meta\log.jsonl"
+npx wicked-brain-server --brain {brain_path} &
 ```
 
-### Step 7: Confirm
+Wait for the health check to confirm it's up before continuing.
+
+### Step 8: Ingest the project
+
+Invoke `wicked-brain:ingest` with:
+- `brain_path`: `{brain_path}`
+- `source`: the current working directory
+
+This indexes the project files so the brain is immediately queryable.
+
+### Step 9: Confirm
 
 Tell the user:
-"Brain initialized at `{brain_path}`. Onboarding agent is running in the background to index the project."
+"Brain `{name}` is ready at `{brain_path}` — {N} files ingested, {M} chunks indexed.
+
+Run `/wicked-brain-compile` to synthesize wiki articles from the indexed content."

package/skills/wicked-brain-lint/SKILL.md

@@ -80,6 +80,58 @@ For each wiki article with source_hashes in frontmatter:
 ### Missing frontmatter
 Check each chunk has required frontmatter fields (source, chunk_id, confidence, indexed_at).
 
+### Tag synonym candidates
+
+Call the server to get all tag frequencies:
+
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"tag_frequency","params":{}}'
+```
+
+The response contains `tags: [{tag, count}]`. Identify potential synonyms:
+
+1. **Substring pairs**: if tag A is a substring of tag B (e.g., "auth" is a substring
+   of "authentication"), they may be synonyms. Flag pairs where both appear in the brain.
+
+2. **Edit distance ≤ 2**: tags that differ by at most 2 character insertions, deletions,
+   or substitutions (e.g., "authentification" vs "authentication") may be typos or synonyms.
+
+For each candidate pair, report as `info` severity with type `synonym_candidate`:
+- **path**: `_meta` (brain-level issue, not file-specific)
+- **message**: `Possible synonym: "{tagA}" ({countA} uses) and "{tagB}" ({countB} uses) — consider merging`
+- **fix**: `Run wicked-brain:retag to consolidate tags`
+
+Only report pairs where both tags have at least 1 use.
+
+### Link confidence report
+
+Call the server for link health:
+
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"link_health","params":{}}'
+```
+
+The response contains:
+- `broken_links`: count of links whose target is not in the index
+- `low_confidence_links`: count of links with confidence < 0.3
+- `total_links`: total link count
+- `avg_confidence`: average confidence across all links
+
+Report findings:
+
+- If `broken_links > 0`: severity `error`, type `broken_link`:
+  `{broken_links} links point to targets not in the index. Use wicked-brain:search to verify targets.`
+
+- If `low_confidence_links > 0`: severity `warning`, type `low_confidence`:
+  `{low_confidence_links} links have confidence < 0.3. Use wicked-brain:confirm to evaluate them.`
+
+- Always include summary stats in the report:
+  `Total links: {total_links}, avg confidence: {avg_confidence:.2f}`
+
 ## Pass 2: Semantic analysis
 
 Read a sample of chunks and wiki articles. Check:

package/skills/wicked-brain-search/SKILL.md

@@ -37,6 +37,25 @@ If it doesn't exist, trigger wicked-brain:init.
 
 ## Process
 
+### Step 0: Load synonyms (optional)
+
+Check if `{brain_path}/_meta/synonyms.json` exists using the Read tool.
+If it exists, parse it. Format:
+```json
+{
+  "jwt": ["json web token", "auth token"],
+  "auth": ["authentication", "authorization"],
+  "k8s": ["kubernetes"]
+}
+```
+
+When searching, expand the query: if any word in the query matches a synonym key,
+add the synonym values as additional OR terms.
+
+Example: query "jwt validation" → search for "jwt validation" first, then also
+search for "json web token validation" and "auth token validation" if initial
+results are sparse (fewer than 3 results).
+
 ### Step 1: Discover brains to search
 
 Use the Read tool on `{brain_path}/brain.json` to get parents and links.
@@ -101,7 +120,21 @@ After all subagents return:
 3. Sort by score descending
 4. Tag each result with its brain origin
 
-### Step 4: Return at requested depth
+### Step 4: Log search miss (if applicable)
+
+If the merged results have 0 matches across all brains, the query is a "search miss."
+Log it so the brain can learn:
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"search_misses","params":{"query":"{original_query}","session_id":"{session_id}"}}'
+```
+
+Note: This logging happens server-side automatically when search returns 0 results.
+The explicit call here is only needed if synonym-expanded searches found results
+but the original query did not.
+
+### Step 5: Return at requested depth
 
 **Depth 0 (default):**
 ```

package/skills/wicked-brain-status/SKILL.md

@@ -78,8 +78,64 @@ Depth 0 plus:
 - List the top 10 most common tags
 - Flag any staleness warnings (sources modified after last ingest)
 
+**Convergence Debt:**
+Detect chunks that are frequently accessed but have never been compiled into wiki articles:
+
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"candidates","params":{"mode":"promote","limit":50}}'
+```
+
+For each result where `access_count >= 5` and `session_diversity >= 3`, check whether any wiki article references it. Use the Grep tool on `{brain_path}/wiki/` searching for the chunk path string. If no wiki article references it, flag it as convergence debt:
+
+```
+⚠ Convergence debt: {path} (accessed {access_count} times across {session_diversity} sessions, no wiki citation)
+```
+
+If any convergence debt exists, suggest running `wicked-brain:compile` to promote high-value chunks.
+
+**Contradiction Hotspots:**
+Detect path prefixes that concentrate multiple contradictions:
+
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"contradictions","params":{}}'
+```
+
+Group the returned contradiction links by path prefix: take the first two path segments of each linked path (e.g., a path `chunks/extracted/auth/session.md` yields prefix `chunks/extracted/auth/`). If any prefix has 2 or more contradiction links, flag it as a hotspot:
+
+```
+⚠ Contradiction hotspot: {prefix} ({N} contradictions) — consider dispatching wicked-brain:compile or manual review
+```
+
 **Depth 2:**
 Depth 1 plus:
 - Read `_meta/log.jsonl` fully for recent activity (last 7 days)
 - List coverage gaps (chunks with no wiki article referencing them)
 - Full linked brain details
+
+**Link Health (Depth 2 only):**
+Check link integrity and surface knowledge gaps using two additional API calls.
+
+Get link health:
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"link_health","params":{}}'
+```
+
+Report:
+- Total links checked and number of broken links
+- Links with confidence below 0.5 (low confidence links)
+- Average confidence score across all links
+
+Get recent search misses:
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"search_misses","params":{"limit":20}}'
+```
+
+Report the top recurring search miss queries to identify knowledge gaps. If a query appears multiple times, that topic is a strong candidate for ingestion or wiki article creation.

package/skills/wicked-brain-synonyms/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: wicked-brain:synonyms
+description: |
+  Manage the brain's synonym map for search expansion. Add, remove, or review
+  synonym mappings. Can also auto-suggest synonyms from search miss data and
+  tag frequency analysis.
+
+  Use when: "add synonym", "manage synonyms", "brain synonyms",
+  "why can't I find X", "search isn't finding".
+---
+
+# wicked-brain:synonyms
+
+You manage the brain's synonym map for improved search recall.
+
+## Cross-Platform Notes
+
+Commands in this skill work on macOS, Linux, and Windows. When a command has
+platform differences, alternatives are shown. Your native tools (Read, Write,
+Grep, Glob) work everywhere — prefer them over shell commands when possible.
+
+For the brain path default:
+- macOS/Linux: ~/.wicked-brain
+- Windows: %USERPROFILE%\.wicked-brain
+
+## Config
+
+Read `_meta/config.json` for brain path and server port.
+If it doesn't exist, trigger wicked-brain:init.
+
+## Synonym File
+
+Location: `{brain_path}/_meta/synonyms.json`
+
+Format:
+```json
+{
+  "jwt": ["json web token", "auth token"],
+  "auth": ["authentication", "authorization"]
+}
+```
+
+Keys are the short/common form. Values are expansions to try when the key
+appears in a search query. The search skill reads this file before executing
+queries and automatically expands sparse results using these mappings.
+
+## Commands
+
+### Add a synonym
+
+Parameters: `term`, `expansions` (comma-separated list)
+
+1. Read `{brain_path}/_meta/synonyms.json` using the Read tool (or start with `{}` if the file does not exist).
+2. Parse the JSON.
+3. If the key already exists, merge the new expansions with the existing list (deduplicate).
+4. If the key is new, add it with the provided expansions as an array.
+5. Write the updated JSON back using the Write tool.
+6. Confirm: `Synonym added: "{term}" → [{expansions}]`
+
+### Remove a synonym
+
+Parameters: `term`
+
+1. Read `{brain_path}/_meta/synonyms.json` using the Read tool.
+2. Parse the JSON.
+3. Delete the key matching `term`. If the key does not exist, report that and stop.
+4. Write the updated JSON back using the Write tool.
+5. Confirm: `Synonym removed: "{term}"`
+
+### Review synonyms
+
+No parameters.
+
+Read `{brain_path}/_meta/synonyms.json` using the Read tool and display the
+current synonym map in a readable table:
+
+```
+Synonym map ({N} entries):
+
+  jwt           → json web token, auth token
+  auth          → authentication, authorization
+  k8s           → kubernetes
+```
+
+If the file does not exist, report: "No synonyms defined yet. Use 'add synonym' to create mappings."
+
+### Auto-suggest
+
+Analyze search misses and tag frequency to surface candidate synonym mappings
+for user review.
+
+**Step 1: Get recent search misses**
+
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"search_misses","params":{"limit":50}}'
+```
+
+**Step 2: Get tag frequency**
+
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"tag_frequency","params":{}}'
+```
+
+**Step 3: Cross-reference and suggest**
+
+For each search miss query:
+- Check whether any word in the query is a substring of an existing tag or vice versa.
+  Example: miss query "k8s deploy" — tag "kubernetes" contains "k8s" as a known abbreviation.
+- If a match is found, propose: `"{miss_word}" → ["{tag}"]`
+
+For tags that appear to be alternate forms of each other (e.g., "auth" and
+"authentication" both present as tags), suggest consolidating them:
+- `"auth" → ["authentication"]`
+
+**Step 4: Present suggestions for approval**
+
+List all suggestions in a numbered table before writing anything:
+
+```
+Suggested synonyms (review before applying):
+
+  1. "k8s"    → ["kubernetes"]         (from search miss: "k8s deploy")
+  2. "auth"   → ["authentication"]     (tag consolidation)
+```
+
+Ask: "Apply all, apply some (specify numbers), or cancel?"
+
+Only write to `synonyms.json` after explicit user approval. Merge approved
+suggestions with any existing entries using the same add-synonym logic above.