@dikolab/kbdb 0.6.3 → 0.6.4

package/dist/cli.cjs

@@ -3,7 +3,7 @@
 
 // src/cli.ts
 var import_node_fs10 = require("node:fs");
-var import_node_path14 = require("node:path");
+var import_node_path15 = require("node:path");
 
 // src/shared/runtime/functions/detect-runtime.ts
 function detectRuntime() {
@@ -745,6 +745,120 @@ function computeDirectoryLevel(filePath, basePath) {
   return Math.min(depth + 1, MAX_LEVEL);
 }
 
+// src/shared/cli/functions/learn-markdown-document.function.ts
+var import_node_path3 = require("node:path");
+
+// src/shared/cli/functions/split-markdown-sections.function.ts
+var HEADING_PATTERN = /^(#{1,6})\s+(.+)$/;
+function splitMarkdownSections(content) {
+  const sections = [];
+  let draft = { lines: [] };
+  let inCodeBlock = false;
+  for (const line of content.split("\n")) {
+    if (line.startsWith("```") || line.startsWith("~~~")) {
+      inCodeBlock = !inCodeBlock;
+      draft.lines.push(line);
+      continue;
+    }
+    const heading = inCodeBlock ? null : HEADING_PATTERN.exec(line);
+    if (heading) {
+      flushSection(draft, sections);
+      draft = {
+        title: heading[2].trim(),
+        level: heading[1].length,
+        lines: []
+      };
+      continue;
+    }
+    draft.lines.push(line);
+  }
+  flushSection(draft, sections);
+  return sections.length > 0 ? sections : [{ content: content.trimEnd() }];
+}
+function flushSection(draft, sections) {
+  const body = draft.lines.join("\n").trimEnd();
+  if (draft.title === void 0 && body.length === 0) return;
+  sections.push(
+    draft.title === void 0 ? { content: body } : { title: draft.title, level: draft.level, content: body }
+  );
+}
+
+// src/shared/cli/functions/map-add-section-result.function.ts
+function mapAddSectionResult(result, path, size, sectionType) {
+  return {
+    kbid: result.items[0] ?? "",
+    indexed_terms_count: 0,
+    type: sectionType,
+    path,
+    size,
+    skipped: false,
+    superseded: result.superseded ?? null,
+    warnings: result.warnings ?? [],
+    near_duplicates: result.near_duplicates ?? []
+  };
+}
+
+// src/shared/cli/functions/learn-markdown-document.function.ts
+async function learnMarkdownDocument(client, options, path, content, sourcePath) {
+  const sections = splitMarkdownSections(content);
+  const titled = sections.filter((s) => s.title !== void 0);
+  if (sections.length < 2 || titled.length === 0) return void 0;
+  const docTitle = titled[0]?.title ?? (0, import_node_path3.basename)(path);
+  const kbids = [];
+  const results = [];
+  for (const section of sections) {
+    const added = await client.addSection({
+      sectionType: "text",
+      content: section.content,
+      title: section.title,
+      description: options.description,
+      docid: path,
+      tags: options.tags,
+      replace: options.replace,
+      sourcePath,
+      level: section.level
+    });
+    kbids.push(added.items[0] ?? "");
+    results.push(
+      mapAddSectionResult(
+        added,
+        path,
+        section.content.length,
+        "text"
+      )
+    );
+  }
+  await client.groupSections(docTitle, kbids);
+  return results;
+}
+
+// src/shared/cli/functions/learn-target-content.function.ts
+async function learnTargetContent(client, options, path, content, sourcePath, level) {
+  const markdownEligible = (path === "-" || path.endsWith(".md")) && !options.title;
+  if (markdownEligible) {
+    const split = await learnMarkdownDocument(
+      client,
+      options,
+      path,
+      content,
+      sourcePath
+    );
+    if (split) return split;
+  }
+  const result = await client.addSection({
+    sectionType: "text",
+    content,
+    title: options.title,
+    description: options.description,
+    docid: options.docid,
+    tags: options.tags,
+    replace: options.replace,
+    sourcePath,
+    level
+  });
+  return [mapAddSectionResult(result, path, content.length, "text")];
+}
+
 // src/shared/cli/functions/run-learn.function.ts
 async function runLearn(client, options, io) {
   log(
@@ -759,37 +873,30 @@ async function runLearn(client, options, io) {
       if (stdinConsumed) continue;
       stdinConsumed = true;
       const content = await readStdin();
-      const result = await client.addSection({
-        sectionType: "text",
-        content,
-        title: options.title,
-        description: options.description,
-        docid: options.docid,
-        tags: options.tags,
-        replace: options.replace,
-        level: options.level
-      });
       results.push(
-        mapAddSectionResult(result, "-", content.length, "text")
+        ...await learnTargetContent(
+          client,
+          options,
+          "-",
+          content,
+          void 0,
+          options.level
+        )
       );
       continue;
     }
     const files = collectFiles(target);
     for (const file of files) {
       const content = (0, import_node_fs2.readFileSync)(file, "utf-8");
-      const result = await client.addSection({
-        sectionType: "text",
-        content,
-        title: options.title,
-        description: options.description,
-        docid: options.docid,
-        tags: options.tags,
-        replace: options.replace,
-        sourcePath: file,
-        level: options.level ?? computeDirectoryLevel(file, target)
-      });
       results.push(
-        mapAddSectionResult(result, file, content.length, "text")
+        ...await learnTargetContent(
+          client,
+          options,
+          file,
+          content,
+          file,
+          options.level ?? computeDirectoryLevel(file, target)
+        )
       );
     }
   }
@@ -799,19 +906,6 @@ async function runLearn(client, options, io) {
   );
   return results;
 }
-function mapAddSectionResult(result, path, size, sectionType) {
-  return {
-    kbid: result.items[0] ?? "",
-    indexed_terms_count: 0,
-    type: sectionType,
-    path,
-    size,
-    skipped: false,
-    superseded: result.superseded ?? null,
-    warnings: result.warnings ?? [],
-    near_duplicates: result.near_duplicates ?? []
-  };
-}
 function readProcessStdin() {
   return new Promise((resolve7) => {
     const chunks = [];
@@ -906,32 +1000,32 @@ async function runRebuild(client, _options) {
 
 // src/shared/cli/functions/find-db.function.ts
 var import_node_fs3 = require("node:fs");
-var import_node_path3 = require("node:path");
+var import_node_path4 = require("node:path");
 function findDb(dbPath) {
   if (dbPath) {
-    const target = (0, import_node_path3.join)((0, import_node_path3.resolve)(dbPath), ".kbdb");
+    const target = (0, import_node_path4.join)((0, import_node_path4.resolve)(dbPath), ".kbdb");
     return (0, import_node_fs3.existsSync)(target) ? target : null;
   }
   let current = process.cwd();
-  let parent = (0, import_node_path3.dirname)(current);
+  let parent = (0, import_node_path4.dirname)(current);
   while (parent !== current) {
-    const candidate2 = (0, import_node_path3.join)(current, ".kbdb");
+    const candidate2 = (0, import_node_path4.join)(current, ".kbdb");
     if ((0, import_node_fs3.existsSync)(candidate2)) return candidate2;
     current = parent;
-    parent = (0, import_node_path3.dirname)(current);
+    parent = (0, import_node_path4.dirname)(current);
   }
-  const candidate = (0, import_node_path3.join)(current, ".kbdb");
+  const candidate = (0, import_node_path4.join)(current, ".kbdb");
   return (0, import_node_fs3.existsSync)(candidate) ? candidate : null;
 }
 
 // src/shared/cli/functions/run-init.function.ts
 var import_node_fs5 = require("node:fs");
-var import_node_path5 = require("node:path");
+var import_node_path6 = require("node:path");
 
 // src/shared/cli/functions/install-default-skills.function.ts
 var import_node_crypto = require("node:crypto");
 var import_node_fs4 = require("node:fs");
-var import_node_path4 = require("node:path");
+var import_node_path5 = require("node:path");
 var BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
 function base32Encode(bytes) {
   let result = "";
@@ -992,8 +1086,8 @@ function installSkill(sectionsDir, skill) {
   });
   const kbid = computeSectionKbid("text/markdown", content);
   const prefix = kbid.slice(0, 2);
-  const shardDir = (0, import_node_path4.join)(sectionsDir, prefix);
-  const filePath = (0, import_node_path4.join)(shardDir, `${kbid}.section`);
+  const shardDir = (0, import_node_path5.join)(sectionsDir, prefix);
+  const filePath = (0, import_node_path5.join)(shardDir, `${kbid}.section`);
   if ((0, import_node_fs4.existsSync)(filePath)) {
     return;
   }
@@ -1021,7 +1115,7 @@ var DEFAULT_SKILLS = [
   }
 ];
 function installDefaultSkills(dbDir) {
-  const sectionsDir = (0, import_node_path4.join)(dbDir, "sections");
+  const sectionsDir = (0, import_node_path5.join)(dbDir, "sections");
   for (const skill of DEFAULT_SKILLS) {
     installSkill(sectionsDir, skill);
   }
@@ -1046,19 +1140,19 @@ var GITIGNORE = [
 ].join("\n");
 function createScaffold(dbDir) {
   (0, import_node_fs5.mkdirSync)(dbDir, { recursive: true });
-  (0, import_node_fs5.mkdirSync)((0, import_node_path5.join)(dbDir, "sections"));
-  (0, import_node_fs5.mkdirSync)((0, import_node_path5.join)(dbDir, "documents"));
-  (0, import_node_fs5.writeFileSync)((0, import_node_path5.join)(dbDir, "catalog.toml"), CATALOG_TOML);
-  (0, import_node_fs5.writeFileSync)((0, import_node_path5.join)(dbDir, "corpus.bin"), "");
-  (0, import_node_fs5.writeFileSync)((0, import_node_path5.join)(dbDir, "inverted.idx"), "");
-  (0, import_node_fs5.writeFileSync)((0, import_node_path5.join)(dbDir, "positional.idx"), "");
-  (0, import_node_fs5.writeFileSync)((0, import_node_path5.join)(dbDir, "worker.toml"), WORKER_TOML);
-  (0, import_node_fs5.writeFileSync)((0, import_node_path5.join)(dbDir, ".gitignore"), GITIGNORE);
+  (0, import_node_fs5.mkdirSync)((0, import_node_path6.join)(dbDir, "sections"));
+  (0, import_node_fs5.mkdirSync)((0, import_node_path6.join)(dbDir, "documents"));
+  (0, import_node_fs5.writeFileSync)((0, import_node_path6.join)(dbDir, "catalog.toml"), CATALOG_TOML);
+  (0, import_node_fs5.writeFileSync)((0, import_node_path6.join)(dbDir, "corpus.bin"), "");
+  (0, import_node_fs5.writeFileSync)((0, import_node_path6.join)(dbDir, "inverted.idx"), "");
+  (0, import_node_fs5.writeFileSync)((0, import_node_path6.join)(dbDir, "positional.idx"), "");
+  (0, import_node_fs5.writeFileSync)((0, import_node_path6.join)(dbDir, "worker.toml"), WORKER_TOML);
+  (0, import_node_fs5.writeFileSync)((0, import_node_path6.join)(dbDir, ".gitignore"), GITIGNORE);
 }
 function runInit(options) {
   log("running init", 0 /* DEBUG */);
-  const basePath = options.dbPath ? (0, import_node_path5.resolve)(options.dbPath) : process.cwd();
-  const dbDir = (0, import_node_path5.join)(basePath, ".kbdb");
+  const basePath = options.dbPath ? (0, import_node_path6.resolve)(options.dbPath) : process.cwd();
+  const dbDir = (0, import_node_path6.join)(basePath, ".kbdb");
   try {
     if ((0, import_node_fs5.existsSync)(dbDir)) {
       return {
@@ -1199,28 +1293,27 @@ async function runSkillLearn(client, options) {
   };
 }
 
+// src/shared/query-filter/functions/matches-query.function.ts
+function matchesQuery(query, ...fields) {
+  if (!query) return true;
+  const needle = query.toLowerCase();
+  return fields.some(
+    (field) => typeof field === "string" && field.toLowerCase().includes(needle)
+  );
+}
+
 // src/shared/cli/functions/run-skill-list.function.ts
-async function runSkillList(client, _options) {
+async function runSkillList(client, options) {
   log("running skill-list", 0 /* DEBUG */);
   const records = await client.listByType("skill");
-  const items = records.map((r) => {
-    let argumentCount = 0;
-    try {
-      const parsed = JSON.parse(r.content);
-      if (Array.isArray(parsed["arguments"])) {
-        argumentCount = parsed["arguments"].length;
-      }
-    } catch {
-    }
-    return {
-      kbid: r.kbid,
-      name: r.title,
-      description: r.description,
-      argumentCount
-    };
-  });
+  const query = options.args.join(" ").toLowerCase();
+  const filtered = records.filter(
+    (r) => matchesQuery(query, r.title, r.description)
+  );
+  const names = filtered.map((r) => r.title);
+  const data = { items: names, total: names.length, offset: 0 };
   return {
-    output: JSON.stringify(items, null, 2),
+    output: JSON.stringify(data, null, 2),
     exitCode: 0
   };
 }
@@ -1349,16 +1442,15 @@ async function runAgentCreate(client, options) {
 }
 
 // src/shared/cli/functions/run-agent-list.function.ts
-async function runAgentList(client, _options) {
+async function runAgentList(client, options) {
   log("running agent-list", 0 /* DEBUG */);
   const docs = await client.listDocumentsByType("agent");
-  const items = docs.map((d) => ({
-    docid: d.docid,
-    name: d.title,
-    skillCount: Math.max(0, d.sections.length - 1)
-  }));
+  const query = options.args.join(" ").toLowerCase();
+  const filtered = docs.filter((d) => matchesQuery(query, d.title));
+  const names = filtered.map((d) => d.title);
+  const data = { items: names, total: names.length, offset: 0 };
   return {
-    output: JSON.stringify(items, null, 2),
+    output: JSON.stringify(data, null, 2),
     exitCode: 0
   };
 }
@@ -1464,7 +1556,7 @@ async function runAgentSearch(client, options) {
 }
 
 // src/shared/cli/functions/run-import.function.ts
-var import_node_path6 = require("node:path");
+var import_node_path7 = require("node:path");
 async function runImport(client, options) {
   const from = options.from;
   if (!from) {
@@ -1473,7 +1565,7 @@ async function runImport(client, options) {
     throw new Error(msg);
   }
   return client.import({
-    from: (0, import_node_path6.resolve)(process.cwd(), from),
+    from: (0, import_node_path7.resolve)(process.cwd(), from),
     dryRun: options.dryRun === true
   });
 }
@@ -1826,7 +1918,7 @@ async function handleTypedSearch(client, options, type) {
 }
 
 // src/shared/version/constants/version.constant.ts
-var VERSION = "0.6.3";
+var VERSION = "0.6.4";
 
 // src/shared/cli/functions/generate-help.function.ts
 var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
@@ -1854,13 +1946,13 @@ var GROUP_SUBCOMMANDS = {
   ],
   skill: [
     ["learn", "Create a new skill definition"],
-    ["list", "List all skills"],
+    ["list", "List skills (filter by keyword)"],
     ["get", "Retrieve a skill by name or kbid"],
     ["delete", "Remove a skill"]
   ],
   agent: [
     ["create", "Create an agent with skill refs"],
-    ["list", "List all agents"],
+    ["list", "List agents (filter by keyword)"],
     ["get", "Retrieve an agent by docid"],
     ["delete", "Remove an agent"]
   ],
@@ -1905,9 +1997,9 @@ Usage: kbdb [options]
        kbdb <command> <subcommand> [options] ...[params]
 
 Knowledge Base:
-   learn               Import content from files/stdin
+   learn               Import content (splits .md on headings)
    unlearn             Remove sections by kbid
-   search              Query the knowledge base
+   search              Query the knowledge base (sibling boost)
    recall              Retrieve section context by kbid
    content             Compose rendered content from ids
 
@@ -1926,13 +2018,13 @@ Maintenance:
 
 Skills:
    skill learn         Create a new skill definition
-   skill list          List all skills
+   skill list          List skills (filter by keyword)
    skill get           Retrieve a skill by name or kbid
    skill delete        Remove a skill
 
 Agents:
    agent create        Create an agent with skill refs
-   agent list          List all agents
+   agent list          List agents (filter by keyword)
    agent get           Retrieve an agent by docid
    agent delete        Remove an agent
 
@@ -2004,9 +2096,17 @@ Options:
    --replace           Supersede existing section by source key
    --db <path>         Path to .kbdb directory
 
+Markdown splitting:
+   .md files are automatically split on ATX
+   headings (# through ######) into independent
+   sections. Each section uses its heading as
+   the title and shares a docid for document
+   grouping. Providing --title imports the file
+   as a single section (skips splitting).
+   Non-.md files are never split.
+
 Output:
-   JSON array of { kbid, path, size, skipped,
-                   superseded, warnings, near_duplicates }
+   { items, total, offset } envelope
 
 Examples:
    kbdb learn README.md
@@ -2045,8 +2145,14 @@ Options:
    --content, -c       Hydrate results with section content
    --db <path>         Path to .kbdb directory
 
+Scoring:
+   Results are ranked by BM25F. Sections from
+   the same document (shared docid) receive a
+   sibling score boost when multiple sections
+   match the query.
+
 Output:
-   JSON array of { kbid, score, preview, matches }
+   { items, total, offset } envelope
 
 Examples:
    kbdb search "machine learning"
@@ -2255,16 +2361,20 @@ Examples:
 `,
   "skill-list": `kbdb skill list - List all skills
 
-Usage: kbdb skill list [options]
+Usage: kbdb skill list [options] [keywords...]
+
+Arguments:
+   [keywords...]       Case-insensitive substring filter on name or description
 
 Options:
    --db <path>         Path to .kbdb directory
 
 Output:
-   JSON array of { kbid, name, description, argumentCount }
+   JSON { items, total, offset }
 
 Examples:
    kbdb skill list
+   kbdb skill list summarize
    kbdb skill list --db /path/to/project
 `,
   "skill-get": `kbdb skill get - Retrieve a skill by name or kbid
@@ -2320,16 +2430,20 @@ Examples:
 `,
   "agent-list": `kbdb agent list - List all agents
 
-Usage: kbdb agent list [options]
+Usage: kbdb agent list [options] [keywords...]
+
+Arguments:
+   [keywords...]       Case-insensitive substring filter on agent name
 
 Options:
    --db <path>         Path to .kbdb directory
 
 Output:
-   JSON array of { docid, name, description, skillCount }
+   JSON { items, total, offset }
 
 Examples:
    kbdb agent list
+   kbdb agent list reviewer
    kbdb agent list --db /path/to/project
 `,
   "agent-get": `kbdb agent get - Retrieve an agent by docid
@@ -2468,7 +2582,7 @@ var import_node_net = require("node:net");
 
 // src/shared/worker-client/functions/discover-daemon.function.ts
 var import_node_fs6 = require("node:fs");
-var import_node_path7 = require("node:path");
+var import_node_path8 = require("node:path");
 var import_node_os = require("node:os");
 
 // src/shared/platform/functions/is-process-alive.function.ts
@@ -2484,7 +2598,7 @@ function isProcessAlive(pid) {
 // src/shared/worker-client/functions/discover-daemon.function.ts
 function discoverDaemon(contextId) {
   log("discovering daemon for context: " + contextId, 0 /* DEBUG */);
-  const pidPath = (0, import_node_path7.join)((0, import_node_os.tmpdir)(), `kbdb-${contextId}.pid`);
+  const pidPath = (0, import_node_path8.join)((0, import_node_os.tmpdir)(), `kbdb-${contextId}.pid`);
   if (!(0, import_node_fs6.existsSync)(pidPath)) {
     log(
       "no daemon PID file found for context: " + contextId,
@@ -2506,8 +2620,8 @@ function discoverDaemon(contextId) {
     return null;
   }
   log("daemon found: pid=" + pid.toString(), 0 /* DEBUG */);
-  const socketPath = (0, import_node_path7.join)((0, import_node_os.tmpdir)(), `kbdb-${contextId}.sock`);
-  const crashPath = (0, import_node_path7.join)((0, import_node_os.tmpdir)(), `kbdb-${contextId}.crash`);
+  const socketPath = (0, import_node_path8.join)((0, import_node_os.tmpdir)(), `kbdb-${contextId}.sock`);
+  const crashPath = (0, import_node_path8.join)((0, import_node_os.tmpdir)(), `kbdb-${contextId}.crash`);
   try {
     (0, import_node_fs6.unlinkSync)(crashPath);
   } catch {
@@ -3028,10 +3142,10 @@ var WorkerClient = class {
 
 // src/shared/worker-client/functions/resolve-db-path.function.ts
 var import_node_fs7 = require("node:fs");
-var import_node_path8 = require("node:path");
+var import_node_path9 = require("node:path");
 function resolveDbPath(targetDir) {
-  const base = targetDir ? (0, import_node_path8.resolve)(targetDir) : process.cwd();
-  const dbPath = (0, import_node_path8.join)(base, ".kbdb");
+  const base = targetDir ? (0, import_node_path9.resolve)(targetDir) : process.cwd();
+  const dbPath = (0, import_node_path9.join)(base, ".kbdb");
   if (!(0, import_node_fs7.existsSync)(dbPath)) {
     const msg = `database not found: ${dbPath}`;
     log(msg, 3 /* ERROR */);
@@ -3098,13 +3212,13 @@ function spawnDaemon(contextPath, runtime, workerScript) {
 
 // src/shared/worker-client/functions/wait-for-daemon.function.ts
 var import_node_fs8 = require("node:fs");
-var import_node_path9 = require("node:path");
+var import_node_path10 = require("node:path");
 var import_node_os2 = require("node:os");
 var DEFAULT_TIMEOUT_MS = 1e4;
 var POLL_INTERVAL_MS = 100;
 async function waitForDaemon(contextId, timeoutMs = DEFAULT_TIMEOUT_MS) {
   log("waiting for daemon: contextId=" + contextId, 0 /* DEBUG */);
-  const pidPath = (0, import_node_path9.join)((0, import_node_os2.tmpdir)(), `kbdb-${contextId}.pid`);
+  const pidPath = (0, import_node_path10.join)((0, import_node_os2.tmpdir)(), `kbdb-${contextId}.pid`);
   const start = Date.now();
   let iteration = 0;
   while (Date.now() - start < timeoutMs) {
@@ -3132,10 +3246,10 @@ async function waitForDaemon(contextId, timeoutMs = DEFAULT_TIMEOUT_MS) {
 
 // src/shared/worker-client/functions/read-crash-reason.function.ts
 var import_node_fs9 = require("node:fs");
-var import_node_path10 = require("node:path");
+var import_node_path11 = require("node:path");
 var import_node_os3 = require("node:os");
 function readCrashReason(contextId) {
-  const crashPath = (0, import_node_path10.join)((0, import_node_os3.tmpdir)(), `kbdb-${contextId}.crash`);
+  const crashPath = (0, import_node_path11.join)((0, import_node_os3.tmpdir)(), `kbdb-${contextId}.crash`);
   if (!(0, import_node_fs9.existsSync)(crashPath)) {
     return "daemon failed to start (no details available)";
   }
@@ -3150,11 +3264,11 @@ function readCrashReason(contextId) {
 }
 
 // src/shared/worker-client/functions/resolve-spawn-script.function.ts
-var import_node_path12 = require("node:path");
+var import_node_path13 = require("node:path");
 var import_node_url = require("node:url");
 
 // src/shared/dir-resolver/functions/join-path.function.ts
-var import_node_path11 = require("node:path");
+var import_node_path12 = require("node:path");
 function isRemoteUrl(path) {
   return path.startsWith("http://") || path.startsWith("https://");
 }
@@ -3163,7 +3277,7 @@ function joinPath(base, ...segments) {
     const trailing = base.endsWith("/") ? "" : "/";
     return base + trailing + segments.join("/");
   }
-  return (0, import_node_path11.join)(base, ...segments);
+  return (0, import_node_path12.join)(base, ...segments);
 }
 
 // src/shared/dir-resolver/functions/resolve-worker-script.function.ts
@@ -3181,15 +3295,15 @@ function resolveSpawnScript(runtime) {
 }
 function resolveScriptDir2(runtime) {
   if (typeof __dirname !== "undefined") return __dirname;
-  const thisDir = (0, import_node_path12.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+  const thisDir = (0, import_node_path13.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
   if (runtime === "deno") {
-    return (0, import_node_path12.resolve)(thisDir, "..", "..", "..");
+    return (0, import_node_path13.resolve)(thisDir, "..", "..", "..");
   }
   return thisDir;
 }
 
 // src/shared/platform/functions/get-ipc-path.function.ts
-var import_node_path13 = require("node:path");
+var import_node_path14 = require("node:path");
 
 // src/shared/platform/functions/get-tmpdir.function.ts
 var import_node_os4 = require("node:os");
@@ -3202,7 +3316,7 @@ function getIpcPath(ctx) {
   if (process.platform === "win32") {
     return `\\\\.\\pipe\\kbdb-${ctx}`;
   }
-  return (0, import_node_path13.join)(getTmpdir(), `kbdb-${ctx}.sock`);
+  return (0, import_node_path14.join)(getTmpdir(), `kbdb-${ctx}.sock`);
 }
 
 // src/shared/worker-client/functions/create-worker-client.function.ts
@@ -3670,7 +3784,7 @@ function createToolDefinitions() {
   return [
     {
       name: "search",
-      description: "Query the knowledge base by keywords. Returns ranked results with heading, snippet, and matched terms. Use multiple short keyword queries for best coverage. Use recall to get full content.",
+      description: "Query the knowledge base by keywords. Returns ranked results with heading, snippet, and matched terms. Sections from the same document receive a sibling score boost when multiple sections match. Use multiple short keyword queries for best coverage. Use recall for full content.",
       inputSchema: {
         type: "object",
         properties: {
@@ -3713,7 +3827,7 @@ function createToolDefinitions() {
     },
     {
       name: "learn",
-      description: "Import content into the knowledge base. Use for durable facts, decisions, and corrections. Use replace when updating existing knowledge. Attach tags for scoping.",
+      description: "Import content into the knowledge base. Markdown content is automatically split on ATX headings into independent sections that share a docid. Providing title imports as a single section (skips splitting). Use replace when updating existing knowledge. Attach tags for scoping.",
       inputSchema: {
         type: "object",
         properties: {
@@ -3727,7 +3841,7 @@ function createToolDefinitions() {
           },
           title: {
             type: "string",
-            description: "Section title. Required for image/* types."
+            description: "Section title. Skips markdown splitting when set. Required for image/* types."
           },
           description: {
             type: "string",
@@ -3735,7 +3849,7 @@ function createToolDefinitions() {
           },
           docid: {
             type: "string",
-            description: "Document ID to group under"
+            description: "Document ID to group sections under. Set automatically when markdown splitting is active."
           },
           tags: {
             type: "array",
@@ -3964,10 +4078,15 @@ function createToolDefinitions() {
     },
     {
       name: "skill-list",
-      description: "List all skills in the knowledge base.",
+      description: "List skill definitions stored in the knowledge base, optionally filtered by a substring query.",
       inputSchema: {
         type: "object",
-        properties: {}
+        properties: {
+          query: {
+            type: "string",
+            description: "Case-insensitive substring filter on skill name or description."
+          }
+        }
       },
       annotations: {
         title: "List Skills",
@@ -4058,10 +4177,15 @@ function createToolDefinitions() {
     },
     {
       name: "agent-list",
-      description: "List all agents in the knowledge base.",
+      description: "List agent documents in the knowledge base, optionally filtered by a substring query.",
       inputSchema: {
         type: "object",
-        properties: {}
+        properties: {
+          query: {
+            type: "string",
+            description: "Case-insensitive substring filter on agent name or description."
+          }
+        }
       },
       annotations: {
         title: "List Agents",
@@ -4309,7 +4433,7 @@ async function readAgentDescription(client, sections) {
     return "";
   }
 }
-async function handleAgentList(client) {
+async function handleAgentList(client, args = {}) {
   const docs = await client.listDocumentsByType("agent");
   const items = await Promise.all(
     docs.map(async (d) => ({
@@ -4317,17 +4441,17 @@ async function handleAgentList(client) {
       description: await readAgentDescription(client, d.sections)
     }))
   );
-  const lines = items.map(
-    (item, index) => `${String(index + 1)}. ${item.name}` + (item.description ? ` -- ${item.description}` : "")
-  );
-  const text = [`${String(items.length)} agents:`, ...lines].join(
-    "\n"
+  const query = typeof args["query"] === "string" ? args["query"].toLowerCase() : "";
+  const filtered = items.filter(
+    (item) => matchesQuery(query, item.name, item.description)
   );
+  const names = filtered.map((item) => item.name);
+  const data = { items: names, total: names.length, offset: 0 };
   return {
     content: [
       {
         type: "text",
-        text
+        text: JSON.stringify(data, null, 2)
       }
     ]
   };
@@ -4629,7 +4753,7 @@ async function handleToolCall(client, name, args) {
       case "skill-learn":
         return await handleSkillLearn(client, args);
       case "skill-list":
-        return await handleSkillList(client);
+        return await handleSkillList(client, args);
       case "skill-get":
         return await handleSkillGet(client, args);
       case "skill-delete":
@@ -4637,7 +4761,7 @@ async function handleToolCall(client, name, args) {
       case "agent-create":
         return await handleAgentCreate(client, args);
       case "agent-list":
-        return await handleAgentList(client);
+        return await handleAgentList(client, args);
       case "agent-get":
         return await handleAgentGet(client, args);
       case "agent-delete":
@@ -4878,17 +5002,17 @@ async function handleSkillLearn(client, args) {
     ]
   };
 }
-async function handleSkillList(client) {
+async function handleSkillList(client, args) {
   const records = await client.listByType("skill");
-  const lines = records.map((r, index) => {
-    const desc = r.description ? ` -- ${r.description}` : "";
-    const label = r.title ?? "(untitled)";
-    return `${String(index + 1)}. ${label} (${r.kbid})${desc}`;
-  });
-  const text = [`${String(records.length)} skills:`, ...lines].join(
-    "\n"
+  const query = typeof args["query"] === "string" ? args["query"].toLowerCase() : "";
+  const filtered = records.filter(
+    (r) => matchesQuery(query, r.title, r.description)
   );
-  return { content: [{ type: "text", text }] };
+  const names = filtered.map((r) => r.title ?? "");
+  const data = { items: names, total: names.length, offset: 0 };
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
 }
 async function handleSkillGet(client, args) {
   const kbid = typeof args["kbid"] === "string" ? args["kbid"] : void 0;
@@ -5924,7 +6048,7 @@ var deps = {
     log("starting MCP server", 1 /* INFO */);
     const client = await createWorkerClient({ contextPath });
     try {
-      const tomlPath = (0, import_node_path14.join)(contextPath, "worker.toml");
+      const tomlPath = (0, import_node_path15.join)(contextPath, "worker.toml");
       let autoCaptureConfig;
       try {
         const tomlText = (0, import_node_fs10.readFileSync)(tomlPath, "utf-8");