wicked-brain 0.1.2 → 0.3.2

package/server/lib/lsp-servers.mjs

@@ -0,0 +1,290 @@
+/**
+ * Known language servers map — 40+ servers covering 70+ extensions.
+ * Extensible via {brainPath}/_meta/lsp.json.
+ */
+
+import { readFileSync } from "node:fs";
+
+export const KNOWN_SERVERS = {
+  // Web
+  typescript: {
+    command: "typescript-language-server", args: ["--stdio"],
+    extensions: [".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs"],
+    install: { method: "npm", package: "typescript-language-server typescript" }
+  },
+  html: {
+    command: "html-languageserver", args: ["--stdio"],
+    extensions: [".html", ".htm"],
+    install: { method: "npm", package: "vscode-html-languageserver-bin" }
+  },
+  css: {
+    command: "css-languageserver", args: ["--stdio"],
+    extensions: [".css", ".scss", ".less"],
+    install: { method: "npm", package: "vscode-css-languageserver-bin" }
+  },
+  vue: {
+    command: "vue-language-server", args: ["--stdio"],
+    extensions: [".vue"],
+    install: { method: "npm", package: "@vue/language-server" }
+  },
+  svelte: {
+    command: "svelteserver", args: ["--stdio"],
+    extensions: [".svelte"],
+    install: { method: "npm", package: "svelte-language-server" }
+  },
+  json: {
+    command: "json-languageserver", args: ["--stdio"],
+    extensions: [".json", ".jsonc"],
+    install: { method: "npm", package: "vscode-json-languageserver" }
+  },
+  astro: {
+    command: "astro-ls", args: ["--stdio"],
+    extensions: [".astro"],
+    install: { method: "npm", package: "@astrojs/language-server" }
+  },
+  // Backend
+  python: {
+    command: "pyright-langserver", args: ["--stdio"],
+    extensions: [".py"],
+    install: { method: "npm", package: "pyright" }
+  },
+  go: {
+    command: "gopls", args: ["serve"],
+    extensions: [".go"],
+    install: { method: "go", package: "golang.org/x/tools/gopls" }
+  },
+  rust: {
+    command: "rust-analyzer", args: [],
+    extensions: [".rs"],
+    install: { method: "rustup", package: "rust-analyzer" }
+  },
+  java: {
+    command: "jdt-language-server", args: [],
+    extensions: [".java"],
+    install: { method: "manual", package: "Eclipse JDT LS — download from eclipse.org" }
+  },
+  csharp: {
+    command: "omnisharp", args: ["-lsp"],
+    extensions: [".cs"],
+    install: { method: "dotnet", package: "OmniSharp" }
+  },
+  cpp: {
+    command: "clangd", args: [],
+    extensions: [".c", ".cpp", ".cc", ".cxx", ".h", ".hpp"],
+    install: { method: "brew", package: "llvm" }
+  },
+  ruby: {
+    command: "ruby-lsp", args: ["--stdio"],
+    extensions: [".rb"],
+    install: { method: "gem", package: "ruby-lsp" }
+  },
+  php: {
+    command: "intelephense", args: ["--stdio"],
+    extensions: [".php"],
+    install: { method: "npm", package: "intelephense" }
+  },
+  kotlin: {
+    command: "kotlin-language-server", args: [],
+    extensions: [".kt", ".kts"],
+    install: { method: "brew", package: "kotlin-language-server" }
+  },
+  scala: {
+    command: "metals", args: [],
+    extensions: [".scala", ".sc"],
+    install: { method: "coursier", package: "metals" }
+  },
+  elixir: {
+    command: "elixir-ls", args: [],
+    extensions: [".ex", ".exs"],
+    install: { method: "mix", package: "elixir_ls" }
+  },
+  erlang: {
+    command: "erlang_ls", args: ["--stdio"],
+    extensions: [".erl"],
+    install: { method: "manual", package: "erlang_ls — build from source" }
+  },
+  // Systems
+  zig: {
+    command: "zls", args: [],
+    extensions: [".zig"],
+    install: { method: "brew", package: "zls" }
+  },
+  haskell: {
+    command: "haskell-language-server", args: ["--stdio"],
+    extensions: [".hs", ".lhs"],
+    install: { method: "ghcup", package: "hls" }
+  },
+  ocaml: {
+    command: "ocamllsp", args: [],
+    extensions: [".ml", ".mli"],
+    install: { method: "opam", package: "ocaml-lsp-server" }
+  },
+  // Scripting
+  lua: {
+    command: "lua-language-server", args: ["--stdio"],
+    extensions: [".lua"],
+    install: { method: "brew", package: "lua-language-server" }
+  },
+  perl: {
+    command: "pls", args: ["--stdio"],
+    extensions: [".pl", ".pm"],
+    install: { method: "cpan", package: "PLS" }
+  },
+  r: {
+    command: "R", args: ["--no-save", "--slave", "-e", "languageserver::run()"],
+    extensions: [".r", ".R"],
+    install: { method: "r", package: "languageserver" }
+  },
+  julia: {
+    command: "julia", args: ["--project=@.", "-e", "using LanguageServer; runserver()"],
+    extensions: [".jl"],
+    install: { method: "julia", package: "LanguageServer" }
+  },
+  bash: {
+    command: "bash-language-server", args: ["start"],
+    extensions: [".sh", ".bash"],
+    install: { method: "npm", package: "bash-language-server" }
+  },
+  // Data & Config
+  sql: {
+    command: "sql-language-server", args: ["up", "--stdio"],
+    extensions: [".sql"],
+    install: { method: "npm", package: "sql-language-server" }
+  },
+  graphql: {
+    command: "graphql-lsp", args: ["--stdio"],
+    extensions: [".graphql", ".gql"],
+    install: { method: "npm", package: "graphql-language-service-cli" }
+  },
+  terraform: {
+    command: "terraform-ls", args: ["serve"],
+    extensions: [".tf"],
+    install: { method: "brew", package: "terraform-ls" }
+  },
+  yaml: {
+    command: "yaml-language-server", args: ["--stdio"],
+    extensions: [".yaml", ".yml"],
+    install: { method: "npm", package: "yaml-language-server" }
+  },
+  toml: {
+    command: "taplo", args: ["lsp", "stdio"],
+    extensions: [".toml"],
+    install: { method: "cargo", package: "taplo-cli" }
+  },
+  xml: {
+    command: "lemminx", args: [],
+    extensions: [".xml", ".xsd", ".xsl"],
+    install: { method: "manual", package: "Eclipse LemMinX" }
+  },
+  // Mobile
+  swift: {
+    command: "sourcekit-lsp", args: [],
+    extensions: [".swift"],
+    install: { method: "manual", package: "Built into Xcode" }
+  },
+  dart: {
+    command: "dart", args: ["language-server", "--protocol=lsp"],
+    extensions: [".dart"],
+    install: { method: "brew", package: "dart" }
+  },
+  // Infra
+  dockerfile: {
+    command: "docker-langserver", args: ["--stdio"],
+    extensions: [],
+    filenames: ["Dockerfile", "Dockerfile.*"],
+    install: { method: "npm", package: "dockerfile-language-server-nodejs" }
+  },
+  // Docs
+  markdown: {
+    command: "marksman", args: ["server"],
+    extensions: [".md", ".markdown"],
+    install: { method: "brew", package: "marksman" }
+  },
+  latex: {
+    command: "texlab", args: [],
+    extensions: [".tex"],
+    install: { method: "cargo", package: "texlab" }
+  },
+  // Other
+  clojure: {
+    command: "clojure-lsp", args: ["--stdio"],
+    extensions: [".clj", ".cljs", ".cljc", ".edn"],
+    install: { method: "brew", package: "clojure-lsp/brew/clojure-lsp" }
+  },
+  fsharp: {
+    command: "fsautocomplete", args: ["--lsp"],
+    extensions: [".fs", ".fsx", ".fsi"],
+    install: { method: "dotnet", package: "fsautocomplete" }
+  },
+  gleam: {
+    command: "gleam", args: ["lsp"],
+    extensions: [".gleam"],
+    install: { method: "brew", package: "gleam" }
+  },
+  solidity: {
+    command: "solidity-lsp", args: ["--stdio"],
+    extensions: [".sol"],
+    install: { method: "npm", package: "@nomicfoundation/hardhat-language-server" }
+  },
+  prisma: {
+    command: "prisma-language-server", args: ["--stdio"],
+    extensions: [".prisma"],
+    install: { method: "npm", package: "@prisma/language-server" }
+  },
+  protobuf: {
+    command: "buf", args: ["lsp"],
+    extensions: [".proto"],
+    install: { method: "brew", package: "bufbuild/buf/buf" }
+  },
+};
+
+// Build extension → server key lookup map
+const EXTENSION_MAP = {};
+for (const [key, server] of Object.entries(KNOWN_SERVERS)) {
+  for (const ext of server.extensions || []) {
+    if (!EXTENSION_MAP[ext]) EXTENSION_MAP[ext] = key;
+  }
+}
+
+/**
+ * Resolve a file extension to its language server config.
+ * Returns the server config object with key, or null if no server known.
+ */
+export function resolveServer(extension, overrides = {}) {
+  // Check overrides first (user config)
+  for (const [key, server] of Object.entries(overrides)) {
+    if (server.extensions && server.extensions.includes(extension)) {
+      return { key, ...server };
+    }
+  }
+  // Then check built-in map
+  const key = EXTENSION_MAP[extension];
+  if (!key) return null;
+  return { key, ...KNOWN_SERVERS[key] };
+}
+
+/**
+ * Load user overrides from _meta/lsp.json.
+ * Returns merged server config (user overrides take precedence).
+ */
+export function loadUserConfig(brainPath) {
+  try {
+    const configPath = `${brainPath}/_meta/lsp.json`;
+    const config = JSON.parse(readFileSync(configPath, "utf-8"));
+    return config.servers || {};
+  } catch {
+    return {};
+  }
+}
+
+/** Get all known extensions (for FileWatcher filtering). */
+export function getKnownExtensions(overrides = {}) {
+  const extensions = new Set();
+  for (const server of Object.values(KNOWN_SERVERS)) {
+    for (const ext of server.extensions || []) extensions.add(ext);
+  }
+  for (const server of Object.values(overrides)) {
+    for (const ext of server.extensions || []) extensions.add(ext);
+  }
+  return extensions;
+}

package/server/lib/sqlite-search.mjs

@@ -11,6 +11,20 @@ function escapeFtsQuery(query) {
     .join(" ");
 }
 
+/** Weight factor for backlink count in search ranking (PageRank-lite). */
+const BACKLINK_WEIGHT = 0.5;
+
+/** Weight factor for access count in search ranking. */
+const SEARCH_ACCESS_WEIGHT = 0.1;
+
+/** Candidate scoring weights for promote mode. */
+const PROMOTE_ACCESS_WEIGHT = 0.3;
+const PROMOTE_SESSION_WEIGHT = 0.3;
+const PROMOTE_BACKLINK_WEIGHT = 0.2;
+const PROMOTE_RECENCY_WEIGHT = 0.2;
+const MAX_AGE_MS = 7776000000; // 90 days
+const ARCHIVE_AGE_MS = 2592000000; // 30 days
+
 export class SqliteSearch {
   #db;
   #brainId;
@@ -48,12 +62,74 @@ export class SqliteSearch {
         source_brain TEXT NOT NULL,
         target_path TEXT NOT NULL,
         target_brain TEXT,
+        rel TEXT,
         link_text TEXT
       );
 
       CREATE INDEX IF NOT EXISTS idx_links_source ON links(source_id);
       CREATE INDEX IF NOT EXISTS idx_links_target ON links(target_path);
+
+      CREATE TABLE IF NOT EXISTS access_log (
+        doc_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        accessed_at INTEGER NOT NULL
+      );
+      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);
     `);
+
+    this.#migrate();
+  }
+
+  /**
+   * Versioned schema migration system.
+   * Each migration upgrades from version N-1 to N.
+   * Migrations are idempotent — safe to re-run.
+   */
+  #migrate() {
+    // Ensure _schema_version table exists
+    this.#db.exec(`
+      CREATE TABLE IF NOT EXISTS _schema_version (
+        version INTEGER NOT NULL
+      )
+    `);
+
+    const row = this.#db.prepare(`SELECT version FROM _schema_version LIMIT 1`).get();
+    let currentVersion = row ? row.version : 0;
+
+    // Migration 1: add rel column to links table + access_log table
+    if (currentVersion < 1) {
+      try { this.#db.prepare(`SELECT rel FROM links LIMIT 0`).get(); } catch {
+        this.#db.exec(`ALTER TABLE links ADD COLUMN rel TEXT`);
+      }
+      // access_log is created by #initSchema's CREATE TABLE IF NOT EXISTS,
+      // but for databases that predate it, ensure it exists
+      this.#db.exec(`
+        CREATE TABLE IF NOT EXISTS access_log (
+          doc_id TEXT NOT NULL, session_id TEXT NOT NULL, accessed_at INTEGER NOT NULL
+        );
+        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);
+      `);
+      currentVersion = 1;
+    }
+
+    // Future migrations go here:
+    // if (currentVersion < 2) { ... currentVersion = 2; }
+
+    // Persist the current version
+    this.#db.exec(`DELETE FROM _schema_version`);
+    this.#db.prepare(`INSERT INTO _schema_version (version) VALUES (?)`).run(currentVersion);
+  }
+
+  /** Returns the current schema version number. */
+  schemaVersion() {
+    try {
+      const row = this.#db.prepare(`SELECT version FROM _schema_version LIMIT 1`).get();
+      return row ? row.version : 0;
+    } catch {
+      return 0;
+    }
   }
 
   index(doc) {
@@ -80,8 +156,8 @@ export class SqliteSearch {
 
     const deleteLinks = this.#db.prepare(`DELETE FROM links WHERE source_id = ?`);
     const insertLink = this.#db.prepare(`
-      INSERT INTO links (source_id, source_brain, target_path, target_brain, link_text)
-      VALUES (?, ?, ?, ?, ?)
+      INSERT INTO links (source_id, source_brain, target_path, target_brain, rel, link_text)
+      VALUES (?, ?, ?, ?, ?, ?)
     `);
 
     const run = this.#db.transaction(() => {
@@ -91,7 +167,7 @@ export class SqliteSearch {
       deleteLinks.run(id);
       const wikilinks = parseWikilinks(content);
       for (const link of wikilinks) {
-        insertLink.run(id, brainId, link.path, link.brain, link.raw);
+        insertLink.run(id, brainId, link.path, link.brain, link.rel || null, link.raw);
       }
     });
 
@@ -119,31 +195,66 @@ export class SqliteSearch {
     run();
   }
 
-  search({ query, limit = 10, offset = 0 }) {
+  search({ query, limit = 10, offset = 0, since = null, session_id = null }) {
     const escaped = escapeFtsQuery(query);
     if (!escaped) return { results: [], total_matches: 0, showing: 0 };
 
+    const sinceClause = since ? `AND d.indexed_at >= ?` : "";
+    const sinceParams = since ? [new Date(since).getTime()] : [];
+
     const rows = this.#db
       .prepare(`
         SELECT
           d.id,
           d.path,
           d.brain_id,
-          snippet(documents_fts, 2, '<b>', '</b>', '…', 32) AS snippet
+          snippet(documents_fts, 2, '<b>', '</b>', '…', 32) AS snippet,
+          COALESCE(link_count.cnt, 0) AS backlink_count,
+          COALESCE(ac.cnt, 0) AS access_count
         FROM documents_fts f
         JOIN documents d ON d.id = f.id
+        LEFT JOIN (
+          SELECT target_path, COUNT(*) AS cnt
+          FROM links
+          GROUP BY target_path
+        ) link_count ON d.path = link_count.target_path
+        LEFT JOIN (
+          SELECT doc_id, COUNT(*) AS cnt
+          FROM access_log
+          GROUP BY doc_id
+        ) ac ON d.id = ac.doc_id
         WHERE documents_fts MATCH ?
-        ORDER BY rank
+        ${sinceClause}
+        ORDER BY (f.rank - (COALESCE(link_count.cnt, 0) * ${BACKLINK_WEIGHT}) - (COALESCE(ac.cnt, 0) * ${SEARCH_ACCESS_WEIGHT}))
         LIMIT ? OFFSET ?
       `)
-      .all(escaped, limit, offset);
+      .all(escaped, ...sinceParams, limit, offset);
 
     const countRow = this.#db
-      .prepare(`SELECT COUNT(*) as cnt FROM documents_fts WHERE documents_fts MATCH ?`)
-      .get(escaped);
+      .prepare(
+        `SELECT COUNT(*) as cnt FROM documents_fts f
+         JOIN documents d ON d.id = f.id
+         WHERE documents_fts MATCH ?
+         ${sinceClause}`
+      )
+      .get(escaped, ...sinceParams);
 
     const total_matches = countRow ? countRow.cnt : 0;
 
+    // Log access for each returned document if session_id provided
+    if (session_id && rows.length > 0) {
+      const logAccess = this.#db.prepare(
+        `INSERT INTO access_log (doc_id, session_id, accessed_at) VALUES (?, ?, ?)`
+      );
+      const now = Date.now();
+      const logAll = this.#db.transaction(() => {
+        for (const row of rows) {
+          logAccess.run(row.id, session_id, now);
+        }
+      });
+      logAll();
+    }
+
     return {
       results: rows,
       total_matches,
@@ -230,6 +341,10 @@ export class SqliteSearch {
       .prepare(`SELECT COUNT(*) as cnt FROM documents WHERE path LIKE 'wiki/%'`)
       .get().cnt;
 
+    const memory = this.#db
+      .prepare(`SELECT COUNT(*) as cnt FROM documents WHERE path LIKE 'memory/%'`)
+      .get().cnt;
+
     const lastRow = this.#db
       .prepare(`SELECT MAX(indexed_at) as last FROM documents`)
       .get();
@@ -243,7 +358,7 @@ export class SqliteSearch {
       // in-memory or inaccessible
     }
 
-    return { total, chunks, wiki, last_indexed, db_size };
+    return { total, chunks, wiki, memory, last_indexed, db_size };
   }
 
   health() {
@@ -254,6 +369,97 @@ export class SqliteSearch {
     };
   }
 
+  candidates({ mode, limit = 20 }) {
+    const now = Date.now();
+
+    if (mode === "promote") {
+      return this.#db.prepare(`
+        SELECT d.id, d.path, d.indexed_at, d.frontmatter,
+               COALESCE(ac.access_count, 0) AS access_count,
+               COALESCE(ac.session_diversity, 0) AS session_diversity,
+               COALESCE(lc.cnt, 0) AS backlink_count
+        FROM documents d
+        LEFT JOIN (
+          SELECT doc_id,
+                 COUNT(*) AS access_count,
+                 COUNT(DISTINCT session_id) AS session_diversity
+          FROM access_log GROUP BY doc_id
+        ) ac ON d.id = ac.doc_id
+        LEFT JOIN (
+          SELECT target_path, COUNT(*) AS cnt
+          FROM links GROUP BY target_path
+        ) lc ON d.path = lc.target_path
+        WHERE d.path LIKE 'chunks/%' OR d.path LIKE 'memory/%'
+        ORDER BY (
+          COALESCE(ac.access_count, 0) * ${PROMOTE_ACCESS_WEIGHT}
+          + COALESCE(ac.session_diversity, 0) * ${PROMOTE_SESSION_WEIGHT}
+          + COALESCE(lc.cnt, 0) * ${PROMOTE_BACKLINK_WEIGHT}
+          + (1.0 - MIN(CAST((${now} - d.indexed_at) AS REAL) / ${MAX_AGE_MS}, 1.0)) * ${PROMOTE_RECENCY_WEIGHT}
+        ) DESC
+        LIMIT ?
+      `).all(limit);
+    }
+
+    if (mode === "archive") {
+      const cutoff = now - ARCHIVE_AGE_MS;
+      return this.#db.prepare(`
+        SELECT d.id, d.path, d.indexed_at, d.frontmatter,
+               COALESCE(ac.access_count, 0) AS access_count,
+               COALESCE(lc.cnt, 0) AS backlink_count
+        FROM documents d
+        LEFT JOIN (
+          SELECT doc_id, COUNT(*) AS access_count
+          FROM access_log GROUP BY doc_id
+        ) ac ON d.id = ac.doc_id
+        LEFT JOIN (
+          SELECT target_path, COUNT(*) AS cnt
+          FROM links GROUP BY target_path
+        ) lc ON d.path = lc.target_path
+        WHERE (d.path LIKE 'chunks/%' OR d.path LIKE 'memory/%')
+          AND COALESCE(ac.access_count, 0) = 0
+          AND COALESCE(lc.cnt, 0) = 0
+          AND d.indexed_at < ?
+        ORDER BY d.indexed_at ASC
+        LIMIT ?
+      `).all(cutoff, limit);
+    }
+
+    throw new Error(`Unknown candidates mode: ${mode}`);
+  }
+
+  accessLog(docId) {
+    const row = this.#db.prepare(`
+      SELECT
+        COUNT(*) as access_count,
+        COUNT(DISTINCT session_id) as session_diversity
+      FROM access_log
+      WHERE doc_id = ?
+    `).get(docId);
+    return row;
+  }
+
+  recentMemories({ days = 7, limit = 10 } = {}) {
+    const since = Date.now() - (days * 86400000);
+    return this.#db.prepare(`
+      SELECT id, path, frontmatter, indexed_at
+      FROM documents
+      WHERE path LIKE 'memory/%'
+        AND indexed_at >= ?
+      ORDER BY indexed_at DESC
+      LIMIT ?
+    `).all(since, limit);
+  }
+
+  contradictions() {
+    return this.#db
+      .prepare(`
+        SELECT source_id, source_brain, target_path, target_brain, link_text
+        FROM links
+        WHERE rel = 'contradicts'
+      `)
+      .all();
+  }
+
   close() {
     this.#db.close();
   }

package/server/lib/wikilinks.mjs

@@ -1,5 +1,14 @@
 const WIKILINK_RE = /\[\[([^\]]+)\]\]/g;
 
+const KNOWN_RELS = new Set([
+  "contradicts",
+  "supersedes",
+  "supports",
+  "caused-by",
+  "extends",
+  "depends-on",
+]);
+
 export function parseWikilinks(text) {
   const links = [];
   for (const match of text.matchAll(WIKILINK_RE)) {
@@ -8,11 +17,18 @@ export function parseWikilinks(text) {
     const raw = match[0];
     if (inner.includes("::")) {
       const idx = inner.indexOf("::");
-      const brain = inner.slice(0, idx).trim();
-      const path = inner.slice(idx + 2).trim();
-      if (brain && path) links.push({ brain, path, raw });
+      const left = inner.slice(0, idx).trim();
+      const right = inner.slice(idx + 2).trim();
+      if (!left || !right) continue;
+      if (KNOWN_RELS.has(left)) {
+        // Typed relationship link
+        links.push({ brain: null, path: right, rel: left, raw });
+      } else {
+        // Cross-brain link
+        links.push({ brain: left, path: right, rel: null, raw });
+      }
     } else {
-      links.push({ brain: null, path: inner, raw });
+      links.push({ brain: null, path: inner, rel: null, raw });
     }
   }
   return links;

package/server/package.json

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

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

@@ -0,0 +1,52 @@
+---
+name: wicked-brain-agent
+description: Factory skill for listing and dispatching wicked-brain agents. Agents enforce multi-step pipelines for consolidation, context assembly, session teardown, and project onboarding.
+---
+
+# wicked-brain:agent
+
+Factory skill for wicked-brain agents. Lists available agents and dispatches them.
+
+## Config
+
+Read `_meta/config.json` for brain path and server port.
+If it doesn't exist, trigger wicked-brain:init.
+
+## Parameters
+
+- **action** (required): `list` or `dispatch`
+- **agent** (dispatch mode): name of agent to dispatch (`consolidate`, `context`, `session-teardown`, `onboard`)
+- **depth** (list mode, optional): 0 (summary), 1 (pipeline steps), 2 (full instructions). Default: 0.
+- **params** (dispatch mode, optional): parameters to pass to the agent
+
+## List Mode
+
+Read agent definitions from the `agents/` subdirectory relative to this skill file. Return at requested depth.
+
+**Depth 0** — one-line summaries:
+- `consolidate`: Three-pass lifecycle — archive noise, promote patterns, merge duplicates
+- `context`: Tiered knowledge surfacing — hot path for simple prompts, fast path for complex
+- `session-teardown`: Capture session learnings — decisions, patterns, gotchas into memory
+- `onboard`: Full project understanding — scan, trace, ingest, compile, configure
+
+**Depth 1** — pipeline steps (read the agent's `## Depth 1` section)
+
+**Depth 2** — full subagent instructions (read the agent's `## Depth 2` section)
+
+## Dispatch Mode
+
+1. Read the requested agent's `.md` file from `agents/` at depth 2
+2. Dispatch as a subagent with those instructions using the host CLI's mechanism:
+   - Claude Code: use `Agent` tool
+   - Gemini CLI: `@agent_name` dispatch
+   - Copilot CLI: `/agent` command
+   - Other CLIs: inline execution (run the pipeline steps in current context)
+3. Pass brain_path, port, and any additional params to the subagent
+
+If the host CLI does not support subagent dispatch, fall back to inline execution — run the pipeline steps directly in the current context.
+
+## Cross-Platform Notes
+
+- Agent definitions are portable markdown — they work on all platforms
+- Dispatch mechanism varies by CLI but instructions are identical
+- Factory skill uses Read tool to load agent files (not shell commands)