@dikolab/kbdb 0.6.4 → 0.6.5

package/dist/cli.cjs

@@ -31,7 +31,10 @@ var SUPPORTED_EXTENSIONS = [
   ".md",
   ".txt",
   ".rst",
-  ".adoc"
+  ".adoc",
+  ".html",
+  ".htm",
+  ".toml"
 ];
 
 // src/shared/log/typings/log-level.type.ts
@@ -745,13 +748,102 @@ 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/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/cli/functions/split-markdown-sections.function.ts
+// 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 splitMarkdownSections(content) {
+function splitMarkdown(content) {
   const sections = [];
+  const tracker = new HeadingParentTracker();
   let draft = { lines: [] };
   let inCodeBlock = false;
   for (const line of content.split("\n")) {
@@ -762,7 +854,7 @@ function splitMarkdownSections(content) {
     }
     const heading = inCodeBlock ? null : HEADING_PATTERN.exec(line);
     if (heading) {
-      flushSection(draft, sections);
+      flushMarkdownDraft(draft, sections, tracker);
       draft = {
         title: heading[2].trim(),
         level: heading[1].length,
@@ -772,14 +864,113 @@ function splitMarkdownSections(content) {
     }
     draft.lines.push(line);
   }
-  flushSection(draft, sections);
-  return sections.length > 0 ? sections : [{ content: content.trimEnd() }];
+  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;
 }
-function flushSection(draft, 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;
-  sections.push(
-    draft.title === void 0 ? { content: body } : { title: draft.title, level: draft.level, content: body }
+  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]
   );
 }
 
@@ -798,15 +989,16 @@ function mapAddSectionResult(result, path, size, sectionType) {
   };
 }
 
-// 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);
+// src/shared/cli/functions/learn-structured-document.function.ts
+var import_node_path3 = require("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 ?? (0, import_node_path3.basename)(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,
@@ -816,7 +1008,8 @@ async function learnMarkdownDocument(client, options, path, content, sourcePath)
       tags: options.tags,
       replace: options.replace,
       sourcePath,
-      level: section.level
+      level: section.level,
+      parent: parent ?? void 0
     });
     kbids.push(added.items[0] ?? "");
     results.push(
@@ -834,16 +1027,25 @@ async function learnMarkdownDocument(client, options, path, content, sourcePath)
 
 // 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,
+  if (!options.title) {
+    const isStdin = path === "-";
+    const split = splitContent(
       content,
-      sourcePath
+      isStdin ? "markdown" : void 0,
+      isStdin ? void 0 : path
+    );
+    const hasTitled = split.sections.some(
+      (s) => s.title !== void 0
     );
-    if (split) return split;
+    if (split.sections.length >= 2 && hasTitled) {
+      return learnStructuredDocument(
+        client,
+        options,
+        path,
+        split,
+        sourcePath
+      );
+    }
   }
   const result = await client.addSection({
     sectionType: "text",
@@ -1918,7 +2120,7 @@ async function handleTypedSearch(client, options, type) {
 }
 
 // src/shared/version/constants/version.constant.ts
-var VERSION = "0.6.4";
+var VERSION = "0.6.5";
 
 // src/shared/cli/functions/generate-help.function.ts
 var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
@@ -1997,7 +2199,7 @@ Usage: kbdb [options]
        kbdb <command> <subcommand> [options] ...[params]
 
 Knowledge Base:
-   learn               Import content (splits .md on headings)
+   learn               Import content (auto-splits structured formats)
    unlearn             Remove sections by kbid
    search              Query the knowledge base (sibling boost)
    recall              Retrieve section context by kbid
@@ -2021,25 +2223,31 @@ 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 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.
 `;
@@ -2096,14 +2304,19 @@ 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.
+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:
    { items, total, offset } envelope
@@ -2141,7 +2354,7 @@ 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
 
@@ -2151,6 +2364,11 @@ Scoring:
    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:
    { items, total, offset } envelope
 
@@ -2172,7 +2390,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
@@ -2181,11 +2400,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:
@@ -2194,6 +2416,7 @@ Output:
 Examples:
    kbdb content abcdef1234567890abcdef1234
    kbdb content id1 id2
+   kbdb content --search machine learning
 `,
   check: `kbdb check - Verify knowledge base integrity
 
@@ -3784,7 +4007,7 @@ function createToolDefinitions() {
   return [
     {
       name: "search",
-      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.",
+      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: {
@@ -3827,7 +4050,7 @@ function createToolDefinitions() {
     },
     {
       name: "learn",
-      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.",
+      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: {
@@ -3837,11 +4060,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. Skips markdown splitting when set. Required for image/* types."
+            description: "Section title. Skips content splitting when set. Required for image/* types."
           },
           description: {
             type: "string",
@@ -3849,7 +4072,7 @@ function createToolDefinitions() {
           },
           docid: {
             type: "string",
-            description: "Document ID to group sections under. Set automatically when markdown splitting is active."
+            description: "Document ID to group sections under. Set automatically when content splitting is active."
           },
           tags: {
             type: "array",
@@ -3918,7 +4141,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: {
@@ -4049,7 +4272,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: {
@@ -4143,7 +4366,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: {
@@ -4304,7 +4527,7 @@ function createToolDefinitions() {
         title: "Auto-Capture Review",
         readOnlyHint: false,
         destructiveHint: false,
-        idempotentHint: true,
+        idempotentHint: false,
         openWorldHint: false
       }
     }
@@ -4693,25 +4916,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;
@@ -4724,6 +4960,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 {
@@ -4731,7 +5119,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":
@@ -4751,7 +5139,7 @@ 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, args);
       case "skill-get":
@@ -4816,47 +5204,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);
@@ -4963,45 +5310,6 @@ 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, args) {
   const records = await client.listByType("skill");
   const query = typeof args["query"] === "string" ? args["query"].toLowerCase() : "";