@dikolab/kbdb 0.6.3 → 0.6.5

package/dist/cli.mjs

@@ -23,7 +23,10 @@ var SUPPORTED_EXTENSIONS = [
   ".md",
   ".txt",
   ".rst",
-  ".adoc"
+  ".adoc",
+  ".html",
+  ".htm",
+  ".toml"
 ];
 
 // src/shared/cli/functions/parse-args.function.ts
@@ -659,6 +662,319 @@ function computeDirectoryLevel(filePath, basePath) {
   return Math.min(depth + 1, MAX_LEVEL);
 }
 
+// src/shared/content-splitter/constants/content-type-maps.constant.ts
+var HINT_FORMAT_MAP = {
+  markdown: "markdown",
+  "text/markdown": "markdown",
+  md: "markdown",
+  html: "html",
+  "text/html": "html",
+  toml: "toml",
+  "application/toml": "toml",
+  "text/toml": "toml",
+  "text/x-toml": "toml"
+};
+var EXTENSION_FORMAT_MAP = {
+  md: "markdown",
+  markdown: "markdown",
+  html: "html",
+  htm: "html",
+  toml: "toml"
+};
+
+// src/shared/content-splitter/functions/detect-content-type.function.ts
+function detectContentType(content, typeHint, filePath) {
+  const hinted = typeHint && HINT_FORMAT_MAP[typeHint.toLowerCase()];
+  if (hinted) return hinted;
+  const extension = filePath?.split(".").pop()?.toLowerCase();
+  const extMatch = extension && EXTENSION_FORMAT_MAP[extension];
+  if (extMatch) return extMatch;
+  return sniffContentType(content);
+}
+function sniffContentType(content) {
+  const trimmed = content.trimStart();
+  if (/^<!DOCTYPE/i.test(trimmed) || /^<html/i.test(trimmed)) {
+    return "html";
+  }
+  if (trimmed.startsWith("[") && trimmed.includes("=")) {
+    return "toml";
+  }
+  return "plain-text";
+}
+
+// src/shared/content-splitter/classes/heading-parent-tracker.class.ts
+var HeadingParentTracker = class {
+  stack = [];
+  /**
+   * Resolves the parent index for a heading at `level`
+   * appearing at output position `index`, then records the
+   * heading so subsequent, deeper headings can nest under it.
+   *
+   * @param level - heading depth, shallower is smaller
+   * @param index - position of this heading in the output
+   *   sections array
+   * @returns the parent's output index, or `null` when the
+   *   heading is at the root
+   */
+  resolve(level, index) {
+    while (this.stack.length > 0 && this.stack[this.stack.length - 1].level >= level) {
+      this.stack.pop();
+    }
+    const parentIndex = this.stack.length > 0 ? this.stack[this.stack.length - 1].index : null;
+    this.stack.push({ level, index });
+    return parentIndex;
+  }
+};
+
+// src/shared/content-splitter/functions/push-content-section.function.ts
+function pushContentSection(sections, tracker, content, title, level) {
+  if (level === void 0) {
+    sections.push({ content, parentIndex: null });
+    return;
+  }
+  sections.push({
+    title,
+    level,
+    content,
+    parentIndex: tracker.resolve(level, sections.length)
+  });
+}
+
+// src/shared/content-splitter/functions/flush-markdown-draft.function.ts
+function flushMarkdownDraft(draft, sections, tracker) {
+  const body = draft.lines.join("\n").trimEnd();
+  if (draft.title === void 0 && body.length === 0) return;
+  pushContentSection(
+    sections,
+    tracker,
+    body,
+    draft.title,
+    draft.level
+  );
+}
+
+// src/shared/content-splitter/functions/split-markdown.function.ts
+var HEADING_PATTERN = /^(#{1,6})\s+(.+)$/;
+function splitMarkdown(content) {
+  const sections = [];
+  const tracker = new HeadingParentTracker();
+  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) {
+      flushMarkdownDraft(draft, sections, tracker);
+      draft = {
+        title: heading[2].trim(),
+        level: heading[1].length,
+        lines: []
+      };
+      continue;
+    }
+    draft.lines.push(line);
+  }
+  flushMarkdownDraft(draft, sections, tracker);
+  return sections.length > 0 ? sections : [{ content: content.trimEnd(), parentIndex: null }];
+}
+
+// src/shared/content-splitter/functions/split-html.function.ts
+var HEADING_PATTERN2 = /<h([1-6])[^>]*>(.*?)<\/h\1>/gi;
+function splitHtml(content) {
+  const matches = [...content.matchAll(HEADING_PATTERN2)];
+  if (matches.length === 0) {
+    return [{ content: content.trimEnd(), parentIndex: null }];
+  }
+  const sections = [];
+  const tracker = new HeadingParentTracker();
+  const firstIndex = matches[0].index;
+  const preamble = content.slice(0, firstIndex).trimEnd();
+  if (preamble.length > 0) {
+    pushContentSection(sections, tracker, preamble);
+  }
+  matches.forEach((match, i) => {
+    const start = match.index + match[0].length;
+    const end = matches[i + 1]?.index ?? content.length;
+    pushContentSection(
+      sections,
+      tracker,
+      content.slice(start, end).trimEnd(),
+      match[2].trim(),
+      Number(match[1])
+    );
+  });
+  return sections;
+}
+
+// src/shared/content-splitter/functions/flush-toml-draft.function.ts
+function flushTomlDraft(draft, sections, pathIndex) {
+  const body = draft.lines.join("\n").trimEnd();
+  if (draft.title === void 0 && body.length === 0) return;
+  if (draft.title === void 0) {
+    sections.push({ content: body, parentIndex: null });
+    return;
+  }
+  const path = draft.path ?? draft.title;
+  sections.push({
+    title: draft.title,
+    content: body,
+    parentIndex: resolveParentIndex(path, pathIndex)
+  });
+  pathIndex.set(path, sections.length - 1);
+}
+function resolveParentIndex(path, pathIndex) {
+  if (/^["']/.test(path)) return null;
+  const segments = path.split(".");
+  segments.pop();
+  if (segments.length === 0) return null;
+  return pathIndex.get(segments.join(".")) ?? null;
+}
+
+// src/shared/content-splitter/functions/split-toml.function.ts
+var HEADER_PATTERN = /^\[([^\]]+)\]\s*$/;
+var QUOTED_PATTERN = /^(["'])(.*)\1$/;
+function splitToml(content) {
+  const sections = [];
+  const pathIndex = /* @__PURE__ */ new Map();
+  let draft = { lines: [] };
+  for (const line of content.split("\n")) {
+    const header = HEADER_PATTERN.exec(line);
+    if (header) {
+      flushTomlDraft(draft, sections, pathIndex);
+      draft = { ...parseHeader(header[1]), lines: [] };
+      continue;
+    }
+    draft.lines.push(line);
+  }
+  flushTomlDraft(draft, sections, pathIndex);
+  return sections.length > 0 ? sections : [{ content: content.trimEnd(), parentIndex: null }];
+}
+function parseHeader(inner) {
+  const trimmed = inner.trim();
+  const quoted = QUOTED_PATTERN.exec(trimmed);
+  return quoted ? { title: quoted[2], path: trimmed } : { title: trimmed, path: trimmed };
+}
+
+// src/shared/content-splitter/functions/split-plain-text.function.ts
+function splitPlainText(content) {
+  return [{ content, parentIndex: null }];
+}
+
+// src/shared/content-splitter/constants/split-strategy-map.constant.ts
+var SPLIT_STRATEGY_MAP = {
+  markdown: splitMarkdown,
+  html: splitHtml,
+  toml: splitToml,
+  "plain-text": splitPlainText
+};
+
+// src/shared/content-splitter/functions/split-content.function.ts
+function splitContent(content, typeHint, filePath) {
+  const format = detectContentType(content, typeHint, filePath);
+  return {
+    format,
+    sections: SPLIT_STRATEGY_MAP[format](content)
+  };
+}
+
+// src/shared/content-splitter/functions/resolve-parent-ids.function.ts
+function resolveParentIds(sections, kbids) {
+  return sections.map(
+    (section) => section.parentIndex === null ? null : kbids[section.parentIndex]
+  );
+}
+
+// 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-structured-document.function.ts
+import { basename as basename2 } from "node:path";
+async function learnStructuredDocument(client, options, path, splitResult, sourcePath) {
+  const { sections } = splitResult;
+  const firstTitled = sections.find((s) => s.title !== void 0);
+  const docTitle = firstTitled?.title ?? basename2(path);
+  const kbids = [];
+  const results = [];
+  for (const section of sections) {
+    const [parent] = resolveParentIds([section], kbids);
+    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,
+      parent: parent ?? void 0
+    });
+    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) {
+  if (!options.title) {
+    const isStdin = path === "-";
+    const split = splitContent(
+      content,
+      isStdin ? "markdown" : void 0,
+      isStdin ? void 0 : path
+    );
+    const hasTitled = split.sections.some(
+      (s) => s.title !== void 0
+    );
+    if (split.sections.length >= 2 && hasTitled) {
+      return learnStructuredDocument(
+        client,
+        options,
+        path,
+        split,
+        sourcePath
+      );
+    }
+  }
+  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(
@@ -673,37 +989,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 = 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)
+        )
       );
     }
   }
@@ -713,19 +1022,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 = [];
@@ -1113,28 +1409,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
   };
 }
@@ -1263,16 +1558,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
   };
 }
@@ -1740,7 +2034,7 @@ async function handleTypedSearch(client, options, type) {
 }
 
 // src/shared/version/constants/version.constant.ts
-var VERSION = "0.6.3";
+var VERSION = "0.6.5";
 
 // src/shared/cli/functions/generate-help.function.ts
 var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
@@ -1768,13 +2062,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"]
   ],
@@ -1819,9 +2113,9 @@ Usage: kbdb [options]
        kbdb <command> <subcommand> [options] ...[params]
 
 Knowledge Base:
-   learn               Import content from files/stdin
+   learn               Import content (auto-splits structured formats)
    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
 
@@ -1840,28 +2134,34 @@ 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
+   skill search        Search skills by keyword
 
 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
-
-Worker:
-   worker stop         Stop the worker daemon
-   worker restart      Restart the worker daemon
+   agent search        Search agents by keyword
 
 Server:
    mcp                 Start MCP server mode (stdio)
 
 Global Options:
    -h, --help          Show this help message
-   -v, --version       Show version information
+   --version           Show version information
+   -v, --verbose       Log warnings (-vv info, -vvv debug)
    --db <path>         Path to .kbdb directory
-   --format <fmt>      Output format (json|text|mcp)
+   --format <fmt>      Output format (rec|json|text|mcp)
+   --timeout-ms <ms>   Request timeout (default 30000)
+   --retry <n>         Retries on timeout (default 1)
+   --non-interactive   Suppress prompts
+
+Worker:
+   worker stop         Stop background daemon
+   worker restart      Restart background daemon
 
 Run "kbdb <command> --help" for detailed information.
 `;
@@ -1918,9 +2218,22 @@ Options:
    --replace           Supersede existing section by source key
    --db <path>         Path to .kbdb directory
 
+Content splitting:
+   Structured formats are automatically split
+   into independent sections that share a docid.
+   Each section carries a level (heading depth)
+   and parent (kbid of enclosing section).
+   Providing --title imports as a single section
+   (skips splitting).
+
+   Supported formats:
+     Markdown  .md, text/markdown     ATX headings
+     HTML      .html, text/html       <h1>-<h6> tags
+     TOML      .toml, application/toml  [section]
+     Plain     .txt, text/plain       no splitting
+
 Output:
-   JSON array of { kbid, path, size, skipped,
-                   superseded, warnings, near_duplicates }
+   { items, total, offset } envelope
 
 Examples:
    kbdb learn README.md
@@ -1955,12 +2268,23 @@ Arguments:
 Options:
    --mode <mode>       Result granularity (sections|documents|stats)
    --limit <n>         Max results (default: 20)
-   --format <fmt>      Output format (json|text|mcp)
+   --format <fmt>      Output format (rec|json|text|mcp)
    --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.
+
+Fields:
+   Each result includes level (heading depth,
+   1-6 or null) and parent (kbid of enclosing
+   section or null).
+
 Output:
-   JSON array of { kbid, score, preview, matches }
+   { items, total, offset } envelope
 
 Examples:
    kbdb search "machine learning"
@@ -1980,7 +2304,8 @@ Options:
    --db <path>         Path to .kbdb directory
 
 Output:
-   JSON RecallResult or RecallResult[]
+   JSON RecallResult or RecallResult[] with
+   level, parent, siblings, and references
 
 Examples:
    kbdb recall abcdef1234567890abcdef1234
@@ -1989,11 +2314,14 @@ Examples:
   content: `kbdb content - Compose rendered content from ids
 
 Usage: kbdb content [options] <id>...
+       kbdb content --search <query>...
 
 Arguments:
    <id>                kbid or docid identifier
+   <query>             Search terms (with --search)
 
 Options:
+   --search, -s        Search for ids by keyword
    --db <path>         Path to .kbdb directory
 
 Output:
@@ -2002,6 +2330,7 @@ Output:
 Examples:
    kbdb content abcdef1234567890abcdef1234
    kbdb content id1 id2
+   kbdb content --search machine learning
 `,
   check: `kbdb check - Verify knowledge base integrity
 
@@ -2169,16 +2498,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
@@ -2234,16 +2567,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
@@ -3503,7 +3840,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, matched terms, level, and parent. 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: {
@@ -3546,7 +3883,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. Structured content (Markdown, HTML, TOML) is automatically split into sections that share a docid. Each section carries a level (heading depth) and parent reference. Providing title imports as a single section (skips splitting). Use replace when updating existing knowledge. Attach tags for scoping.",
       inputSchema: {
         type: "object",
         properties: {
@@ -3556,11 +3893,11 @@ function createToolDefinitions() {
           },
           type: {
             type: "string",
-            description: "MIME type (default: text/markdown). Use image/* for images."
+            description: "MIME type or format hint. Supported: text/markdown, text/html, application/toml (also text/toml, text/x-toml), text/plain, image/*. Default: text/markdown."
           },
           title: {
             type: "string",
-            description: "Section title. Required for image/* types."
+            description: "Section title. Skips content splitting when set. Required for image/* types."
           },
           description: {
             type: "string",
@@ -3568,7 +3905,7 @@ function createToolDefinitions() {
           },
           docid: {
             type: "string",
-            description: "Document ID to group under"
+            description: "Document ID to group sections under. Set automatically when content splitting is active."
           },
           tags: {
             type: "array",
@@ -3637,7 +3974,7 @@ function createToolDefinitions() {
     },
     {
       name: "recall",
-      description: "Retrieve full content and context for sections by identifier. Use after search to read relevant results. Returns section text, metadata, references, and back-references.",
+      description: "Retrieve full content and context for sections by identifier. Use after search to read relevant results. Returns section text, level, parent, metadata, references, and back-references.",
       inputSchema: {
         type: "object",
         properties: {
@@ -3768,7 +4105,7 @@ function createToolDefinitions() {
     },
     {
       name: "skill-learn",
-      description: "Create or update a skill definition. Skills are reusable AI agent capabilities with template placeholders.",
+      description: "Create or update a skill definition. Skills are reusable AI agent capabilities with template placeholders. Stored as atomic JSON (not split into sections).",
       inputSchema: {
         type: "object",
         properties: {
@@ -3797,10 +4134,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",
@@ -3857,7 +4199,7 @@ function createToolDefinitions() {
     },
     {
       name: "agent-create",
-      description: "Create an AI agent with a persona and optional skill references.",
+      description: "Create an AI agent with a persona and optional skill references. Stored as atomic JSON (not split into sections).",
       inputSchema: {
         type: "object",
         properties: {
@@ -3891,10 +4233,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",
@@ -4013,7 +4360,7 @@ function createToolDefinitions() {
         title: "Auto-Capture Review",
         readOnlyHint: false,
         destructiveHint: false,
-        idempotentHint: true,
+        idempotentHint: false,
         openWorldHint: false
       }
     }
@@ -4142,7 +4489,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) => ({
@@ -4150,17 +4497,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)
       }
     ]
   };
@@ -4402,25 +4749,38 @@ async function handleAgentSearch(client, args) {
   return { content: [{ type: "text", text }] };
 }
 
-// src/shared/mcp/functions/handle-tool-call.function.ts
+// src/shared/mcp/functions/as-string.function.ts
 function asString2(value, fallback) {
   return typeof value === "string" ? value : fallback;
 }
-function asBooleanOrUndefined(value) {
-  return typeof value === "boolean" ? value : void 0;
-}
+
+// src/shared/mcp/functions/as-string-array-or-undefined.function.ts
 function asStringArrayOrUndefined(value) {
   if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
     return value;
   }
   return void 0;
 }
-function asStringArray2(value) {
-  if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
-    return value;
-  }
-  return [];
+
+// src/shared/mcp/functions/as-boolean-or-undefined.function.ts
+function asBooleanOrUndefined(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+
+// src/shared/mcp/functions/parse-learn-args.function.ts
+function parseLearnArgs(args) {
+  return {
+    sectionType: asString2(args["type"], "text/markdown"),
+    title: typeof args["title"] === "string" ? args["title"] : void 0,
+    description: typeof args["description"] === "string" ? args["description"] : void 0,
+    docid: typeof args["docid"] === "string" ? args["docid"] : void 0,
+    tags: asStringArrayOrUndefined(args["tags"]),
+    replace: asBooleanOrUndefined(args["replace"]),
+    level: typeof args["level"] === "number" ? args["level"] : void 0
+  };
 }
+
+// src/shared/mcp/functions/unwrap-json-content.function.ts
 function unwrapJsonContent(raw) {
   const trimmed = raw.trim();
   if (!trimmed.startsWith("{")) return raw;
@@ -4433,6 +4793,158 @@ function unwrapJsonContent(raw) {
   }
   return raw;
 }
+
+// src/shared/mcp/functions/determine-learn-split.function.ts
+function determineLearnSplit(content, sectionType, title) {
+  const splittable = sectionType.startsWith("text/") || sectionType === "markdown" || sectionType === "application/toml";
+  if (title !== void 0 || !splittable) return void 0;
+  const result = splitContent(content, sectionType);
+  const hasTitledSection = result.sections.some(
+    (section) => section.title !== void 0
+  );
+  return result.sections.length >= 2 && hasTitledSection ? result : void 0;
+}
+
+// src/shared/mcp/functions/learn-with-splitting.function.ts
+async function learnWithSplitting(client, splitResult, params) {
+  const { sections } = splitResult;
+  const firstTitled = sections.find((s) => s.title !== void 0);
+  const docTitle = firstTitled?.title ?? params.docid ?? "Untitled";
+  const docid = params.docid ?? firstTitled?.title;
+  const kbids = [];
+  for (const section of sections) {
+    const [parent] = resolveParentIds([section], kbids);
+    const result = await client.addSection({
+      sectionType: params.sectionType,
+      content: section.content,
+      title: section.title,
+      description: params.description,
+      docid,
+      tags: params.tags,
+      replace: params.replace,
+      level: section.level,
+      parent: parent ?? void 0
+    });
+    kbids.push(result.items[0] ?? "");
+  }
+  return { kbids, docTitle };
+}
+
+// src/shared/mcp/functions/store-split-learn-sections.function.ts
+async function storeSplitLearnSections(client, splitResult, params) {
+  const { kbids, docTitle } = await learnWithSplitting(
+    client,
+    splitResult,
+    params
+  );
+  await client.groupSections(docTitle, kbids);
+  return {
+    items: kbids,
+    total: kbids.length,
+    offset: 0,
+    superseded: null,
+    warnings: [],
+    near_duplicates: []
+  };
+}
+
+// src/shared/mcp/functions/build-learn-payload.function.ts
+function buildLearnPayload(result) {
+  return {
+    items: result.items,
+    total: result.total,
+    offset: result.offset,
+    superseded: result.superseded ?? null,
+    warnings: result.warnings ?? [],
+    near_duplicates: result.near_duplicates ?? []
+  };
+}
+
+// src/shared/mcp/functions/handle-tool-learn.function.ts
+async function handleToolLearn(client, args) {
+  const learnArgs = parseLearnArgs(args);
+  const { sectionType, title, level, ...shared } = learnArgs;
+  if (sectionType.startsWith("image/") && !title) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "title is required for image/* types"
+        }
+      ],
+      isError: true
+    };
+  }
+  const content = unwrapJsonContent(asString2(args["content"], ""));
+  const splitResult = determineLearnSplit(content, sectionType, title);
+  const result = splitResult ? await storeSplitLearnSections(client, splitResult, {
+    sectionType,
+    ...shared
+  }) : await client.addSection({
+    sectionType,
+    content,
+    title,
+    level,
+    ...shared
+  });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(buildLearnPayload(result))
+      }
+    ]
+  };
+}
+
+// src/shared/mcp/functions/handle-tool-skill-learn.function.ts
+async function handleToolSkillLearn(client, args) {
+  const name = asString2(args["name"], "");
+  if (!name) {
+    return {
+      content: [{ type: "text", text: "name is required" }],
+      isError: true
+    };
+  }
+  const body = asString2(args["body"], "");
+  if (!body) {
+    return {
+      content: [{ type: "text", text: "body is required" }],
+      isError: true
+    };
+  }
+  const description = typeof args["description"] === "string" ? args["description"] : void 0;
+  const skillArgs = extractSkillArguments(body);
+  const skill = {
+    name,
+    description,
+    arguments: skillArgs.length > 0 ? skillArgs : void 0,
+    body
+  };
+  const json = serializeSkillContent(skill);
+  const result = await client.addSection({
+    sectionType: "skill",
+    content: json,
+    title: name,
+    description
+  });
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Created skill "${name}" (kbid: ${result.items[0]})`
+      }
+    ]
+  };
+}
+
+// src/shared/mcp/functions/handle-tool-call.function.ts
+function asStringArray2(value) {
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+    return value;
+  }
+  return [];
+}
 async function handleToolCall(client, name, args) {
   log("tool call: " + name, 0 /* DEBUG */);
   try {
@@ -4440,7 +4952,7 @@ async function handleToolCall(client, name, args) {
       case "search":
         return await handleSearch2(client, args);
       case "learn":
-        return await handleLearn2(client, args);
+        return await handleToolLearn(client, args);
       case "unlearn":
         return await handleUnlearn2(client, args);
       case "retrieve":
@@ -4460,9 +4972,9 @@ async function handleToolCall(client, name, args) {
       case "export":
         return await handleExport2(client, args);
       case "skill-learn":
-        return await handleSkillLearn(client, args);
+        return await handleToolSkillLearn(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":
@@ -4470,7 +4982,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":
@@ -4525,47 +5037,6 @@ async function handleSearch2(client, args) {
     ]
   };
 }
-async function handleLearn2(client, args) {
-  const sectionType = asString2(args["type"], "text/markdown");
-  const title = typeof args["title"] === "string" ? args["title"] : void 0;
-  const description = typeof args["description"] === "string" ? args["description"] : void 0;
-  const docid = typeof args["docid"] === "string" ? args["docid"] : void 0;
-  const tags = asStringArrayOrUndefined(args["tags"]);
-  const replace = asBooleanOrUndefined(args["replace"]);
-  if (sectionType.startsWith("image/") && !title) {
-    return {
-      content: [
-        {
-          type: "text",
-          text: "title is required for image/* types"
-        }
-      ],
-      isError: true
-    };
-  }
-  const rawContent = asString2(args["content"], "");
-  const content = unwrapJsonContent(rawContent);
-  const result = await client.addSection({
-    sectionType,
-    content,
-    title,
-    description,
-    docid,
-    tags,
-    replace
-  });
-  const payload = {
-    items: result.items,
-    total: result.total,
-    offset: result.offset,
-    superseded: result.superseded ?? null,
-    warnings: result.warnings ?? [],
-    near_duplicates: result.near_duplicates ?? []
-  };
-  return {
-    content: [{ type: "text", text: JSON.stringify(payload) }]
-  };
-}
 async function handleUnlearn2(client, args) {
   const kbid = asString2(args["kbid"], "");
   await client.removeSection(kbid);
@@ -4672,56 +5143,17 @@ async function handleRebuild2(client) {
   const text = `Rebuild complete: ${String(report.sections_reindexed)} sections reindexed, ${String(report.terms_indexed)} terms indexed.`;
   return { content: [{ type: "text", text }] };
 }
-async function handleSkillLearn(client, args) {
-  const name = asString2(args["name"], "");
-  if (!name) {
-    return {
-      content: [{ type: "text", text: "name is required" }],
-      isError: true
-    };
-  }
-  const body = asString2(args["body"], "");
-  if (!body) {
-    return {
-      content: [{ type: "text", text: "body is required" }],
-      isError: true
-    };
-  }
-  const description = typeof args["description"] === "string" ? args["description"] : void 0;
-  const skillArgs = extractSkillArguments(body);
-  const skill = {
-    name,
-    description,
-    arguments: skillArgs.length > 0 ? skillArgs : void 0,
-    body
-  };
-  const json = serializeSkillContent(skill);
-  const result = await client.addSection({
-    sectionType: "skill",
-    content: json,
-    title: name,
-    description
-  });
-  return {
-    content: [
-      {
-        type: "text",
-        text: `Created skill "${name}" (kbid: ${result.items[0]})`
-      }
-    ]
-  };
-}
-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;