@dikolab/kbdb 0.6.1 → 0.6.2

package/dist/cli.mjs

@@ -152,6 +152,10 @@ function parseArgs(argv) {
       case "-c":
         options.content = true;
         break;
+      case "--search":
+      case "-s":
+        options.search = true;
+        break;
       case "--relaxed":
         options.relaxed = true;
         break;
@@ -188,18 +192,19 @@ function parseArgs(argv) {
 }
 
 // src/shared/cli/functions/format-text-output.function.ts
-function formatTextOutput(paged) {
+function formatTextOutput(paged, content) {
   if (paged.items.length === 0) return "No results found.";
   const start = paged.offset + 1;
   const end = paged.offset + paged.items.length;
   const lines = paged.items.map((r, i) => {
     const num = paged.offset + i + 1;
-    const heading = r.heading ?? "(untitled)";
+    const heading = r.heading || "(untitled)";
     const terms = r.matched_terms.join(", ");
     const fields = r.matched_fields.join(", ");
     const confidencePct = (r.confidence * 100).toFixed(0);
+    const body = content ? r.preview || "(no content)" : r.snippet || r.preview || "(no snippet)";
     return `${String(num)}. [${r.kbid}] ${heading} (score: ${r.score.toFixed(4)}, confidence: ${confidencePct}%)
-   ${r.snippet || r.preview || "(no snippet)"}
+   ${body}
    type: ${r.type}  terms: ${terms}` + (fields ? `  fields: ${fields}` : "");
   }).join("\n\n");
   const footer = `
@@ -210,29 +215,21 @@ Use --offset ${String(end)} to see more` : "";
 }
 
 // src/shared/cli/functions/format-mcp-output.function.ts
-function formatMcpOutput(paged) {
-  const mcpItems = paged.items.map((r) => ({
-    kbid: r.kbid,
-    heading: r.heading,
-    type: r.type,
-    docids: r.docids,
-    snippet: r.snippet,
-    matched_terms: r.matched_terms,
-    matched_fields: r.matched_fields,
-    created_at: r.created_at
-  }));
+function formatMcpOutput(paged, content) {
+  const text = paged.items.length === 0 ? "No results found." : paged.items.map((r) => {
+    const body = content ? r.preview || "(no content)" : r.snippet || r.preview;
+    return `[${r.kbid}] ${r.heading || "(untitled)"} \u2014 ${body}`;
+  }).join("\n");
   return JSON.stringify(
     {
-      type: "text",
-      text: paged.items.map(
-        (r) => `[${r.kbid}] ${r.heading ?? "(untitled)"} \u2014 ${r.snippet || r.preview}`
-      ).join("\n"),
-      items: mcpItems,
-      total: paged.total,
-      offset: paged.offset,
-      limit: paged.limit,
-      has_more: paged.has_more,
-      relaxed: paged.relaxed
+      jsonrpc: "2.0",
+      result: {
+        content: [{ type: "text", text }],
+        total: paged.total,
+        offset: paged.offset,
+        limit: paged.limit,
+        has_more: paged.has_more
+      }
     },
     null,
     2
@@ -302,15 +299,24 @@ var SEARCH_FIELDS = [
   ["snippet", "snippet"],
   ["level", "level"]
 ];
-var LEARN_FIELDS = [
+var SEARCH_CONTENT_FIELDS = [
   ["kbid", "kbid"],
-  ["path", "path"],
-  ["size", "size"],
-  ["skipped", "skipped"],
-  ["superseded", "superseded"],
-  ["warnings", "warnings"],
+  ["heading", "heading"],
+  ["score", "score"],
+  ["confidence", "confidence"],
+  ["type", "type"],
+  ["terms", "matched_terms"],
+  ["fields", "matched_fields"],
+  ["content", "preview"],
   ["level", "level"]
 ];
+var LEARN_FIELDS = [
+  ["items", "items"],
+  ["total", "total"],
+  ["offset", "offset"],
+  ["superseded", "superseded"],
+  ["warnings", "warnings"]
+];
 var UNLEARN_FIELDS = [
   ["removed", "removed"],
   ["elapsed_ms", "elapsed_ms"]
@@ -338,7 +344,9 @@ var IMPORT_FIELDS = [
 ];
 var STATUS_FIELDS = [
   ["initialized", "initialized"],
-  ["path", "contextPath"],
+  ["path", "context_path"],
+  ["documents", "document_count"],
+  ["sections", "section_count"],
   ["content_cached", "cacheStats.contentCount"],
   ["index_cached", "cacheStats.indexCount"]
 ];
@@ -361,16 +369,19 @@ var REBUILD_FIELDS = [
 ];
 
 // src/shared/cli/functions/format-output.function.ts
-function formatOutput(paged, format) {
+function formatOutput(paged, format, content) {
   switch (format) {
     case "json":
       return JSON.stringify(paged, null, 2);
     case "text":
-      return formatTextOutput(paged);
+      return formatTextOutput(paged, content);
     case "rec":
-      return formatRecfileOutput(paged.items, SEARCH_FIELDS);
+      return formatRecfileOutput(
+        paged.items,
+        content ? SEARCH_CONTENT_FIELDS : SEARCH_FIELDS
+      );
     case "mcp":
-      return formatMcpOutput(paged);
+      return formatMcpOutput(paged, content);
   }
 }
 
@@ -387,6 +398,93 @@ var RECFILE_COMMAND_FIELD_MAP = {
   rebuild: REBUILD_FIELDS
 };
 
+// src/shared/cli/functions/format-command-text.function.ts
+function str(v) {
+  if (typeof v === "string") return v;
+  if (typeof v === "number") return String(v);
+  if (typeof v === "boolean") return String(v);
+  if (v == null) return "";
+  return JSON.stringify(v);
+}
+function formatCommandText(data, command) {
+  const obj = data;
+  switch (command) {
+    case "status":
+      return formatStatus(obj);
+    case "check":
+      return formatCheck(obj);
+    case "gc":
+      return formatGc(obj);
+    case "rebuild":
+      return formatRebuild(obj);
+    case "unlearn":
+      return formatUnlearn(obj);
+    case "learn":
+      return formatLearn(data);
+    default:
+      return JSON.stringify(data, null, 2);
+  }
+}
+function formatStatus(o) {
+  const cs = o["cacheStats"];
+  const path = o["context_path"] ?? o["contextPath"] ?? "(unknown)";
+  const lines = [
+    `Initialized: ${str(o["initialized"] ?? false)}`,
+    `Path: ${str(path)}`
+  ];
+  if (o["document_count"] != null)
+    lines.push(`Documents: ${str(o["document_count"])}`);
+  if (o["section_count"] != null)
+    lines.push(`Sections: ${str(o["section_count"])}`);
+  if (cs) {
+    lines.push(
+      `Content cached: ${str(cs["contentCount"] ?? 0)}`,
+      `Index cached: ${str(cs["indexCount"] ?? 0)}`
+    );
+  }
+  return lines.join("\n");
+}
+function formatCheck(o) {
+  const ok = o["ok"] ? "OK" : "FAILED";
+  return `Integrity check: ${ok} (${str(o["sections_checked"] ?? 0)} sections, ${str(o["documents_checked"] ?? 0)} documents, ${str(o["references_checked"] ?? 0)} refs, ${str(o["elapsed_ms"] ?? 0)}ms)`;
+}
+function formatGc(o) {
+  return `GC: removed ${str(o["removed_sections"] ?? 0)} sections, reclaimed ${str(o["removed_bytes"] ?? 0)} bytes (${str(o["elapsed_ms"] ?? 0)}ms)`;
+}
+function formatRebuild(o) {
+  return `Rebuild: ${str(o["sections_reindexed"] ?? 0)} sections reindexed, ${str(o["terms_indexed"] ?? 0)} terms (${str(o["elapsed_ms"] ?? 0)}ms)`;
+}
+function formatUnlearn(o) {
+  const removed = o["removed"];
+  if (Array.isArray(removed)) {
+    return `Removed: ${removed.length.toString()} section(s)`;
+  }
+  return `Removed: ${str(removed ?? false)} (${str(o["elapsed_ms"] ?? 0)}ms)`;
+}
+function formatLearn(data) {
+  const obj = data;
+  const items = obj["items"];
+  if (Array.isArray(items)) {
+    return items.map((id) => `Learned: ${str(id)}`).join("\n");
+  }
+  return JSON.stringify(data, null, 2);
+}
+
+// src/shared/cli/functions/wrap-mcp-envelope.function.ts
+function wrapMcpEnvelope(data, command) {
+  const text = formatCommandText(data, command);
+  return JSON.stringify(
+    {
+      jsonrpc: "2.0",
+      result: {
+        content: [{ type: "text", text }]
+      }
+    },
+    null,
+    2
+  );
+}
+
 // src/shared/cli/functions/format-command-output.function.ts
 function formatCommandOutput(data, format, command) {
   switch (format) {
@@ -395,9 +493,11 @@ function formatCommandOutput(data, format, command) {
       return fields ? formatRecfileOutput(data, fields) : JSON.stringify(data, null, 2);
     }
     case "json":
+      return JSON.stringify(data, null, 2);
     case "text":
+      return formatCommandText(data, command);
     case "mcp":
-      return JSON.stringify(data, null, 2);
+      return wrapMcpEnvelope(data, command);
   }
 }
 
@@ -430,7 +530,7 @@ async function runSearch(client, options) {
   return {
     items: results.items.map((r) => ({
       kbid: r.kbid,
-      heading: r.heading,
+      heading: r.heading || "(untitled)",
       type: r.type,
       docids: r.docids,
       score: r.score,
@@ -456,6 +556,11 @@ async function runSearch(client, options) {
 var SECTION_TYPES = ["text", "code", "image"];
 async function resolveKbidPrefix(prefix, client) {
   if (prefix.length >= 26) return prefix;
+  if (prefix.length < 2) {
+    const msg = `prefix "${prefix}" is too short (minimum 2 characters)`;
+    log(msg, 3 /* ERROR */);
+    throw new Error(msg);
+  }
   const seen = /* @__PURE__ */ new Set();
   for (const type of SECTION_TYPES) {
     const records = await client.listByType(type);
@@ -464,7 +569,7 @@ async function resolveKbidPrefix(prefix, client) {
     }
   }
   if (seen.size === 0) {
-    const msg = `no section matches prefix "${prefix}"`;
+    const msg = `no section matches prefix "${prefix}". Try "kbdb content --search <query>" to find by keyword`;
     log(msg, 3 /* ERROR */);
     throw new Error(msg);
   }
@@ -578,7 +683,9 @@ async function runLearn(client, options, io) {
         replace: options.replace,
         level: options.level
       });
-      results.push(mapAddSectionResult(result, "-", content.length));
+      results.push(
+        mapAddSectionResult(result, "-", content.length, "text")
+      );
       continue;
     }
     const files = collectFiles(target);
@@ -596,7 +703,7 @@ async function runLearn(client, options, io) {
         level: options.level ?? computeDirectoryLevel(file, target)
       });
       results.push(
-        mapAddSectionResult(result, file, content.length)
+        mapAddSectionResult(result, file, content.length, "text")
       );
     }
   }
@@ -606,9 +713,11 @@ async function runLearn(client, options, io) {
   );
   return results;
 }
-function mapAddSectionResult(result, path, size) {
+function mapAddSectionResult(result, path, size, sectionType) {
   return {
-    kbid: result.kbid,
+    kbid: result.items[0] ?? "",
+    indexed_terms_count: 0,
+    type: sectionType,
     path,
     size,
     skipped: false,
@@ -645,11 +754,26 @@ async function runUnlearn(client, options) {
 // src/shared/cli/functions/run-content.function.ts
 async function runContent(client, options) {
   log("running content", 0 /* DEBUG */);
+  if (options.search) {
+    return runContentSearch(client, options);
+  }
   const resolved = await Promise.all(
     options.args.map((a) => resolveKbidPrefix(a, client))
   );
   return client.content(resolved);
 }
+async function runContentSearch(client, options) {
+  const query = options.args.join(" ");
+  const result = await client.search({
+    query,
+    limit: options.limit
+  });
+  const kbids = result.items.map((hit) => hit.kbid);
+  if (kbids.length === 0) {
+    return { type: "text/markdown", data: "", total: 0 };
+  }
+  return client.content(kbids);
+}
 
 // src/shared/cli/functions/run-check.function.ts
 function parseDivergentContent(encoded) {
@@ -664,14 +788,21 @@ function parseDivergentContent(encoded) {
 async function runCheck(client, _options) {
   log("running check", 0 /* DEBUG */);
   const raw = await client.integrityCheck();
+  const divergent = parseDivergentContent(raw.divergent_content);
+  const divergentErrors = divergent.map((d) => ({
+    type: "divergent_content",
+    entity: d.sourceKey,
+    detail: `${d.kbids.length.toString()} divergent sections: ${d.kbids.join(", ")}`
+  }));
+  const errors = [...raw.errors, ...divergentErrors];
   return {
-    ok: raw.ok,
-    errors: raw.errors,
+    ok: raw.ok && errors.length === 0,
+    errors,
     sections_checked: raw.sections_checked,
     documents_checked: raw.documents_checked,
     references_checked: raw.references_checked,
     elapsed_ms: raw.elapsed_ms,
-    divergent_content: parseDivergentContent(raw.divergent_content)
+    divergent_content: divergent
   };
 }
 
@@ -969,7 +1100,15 @@ async function runSkillLearn(client, options) {
     description: options.description
   });
   return {
-    output: JSON.stringify(result, null, 2),
+    output: JSON.stringify(
+      {
+        kbid: result.items[0],
+        name,
+        arguments: args.length > 0 ? args : []
+      },
+      null,
+      2
+    ),
     exitCode: 0
   };
 }
@@ -1030,10 +1169,12 @@ async function runSkillGet(client, options) {
     };
   }
   let content;
-  if (/^[0-9a-f]{16,}$/i.test(identifier)) {
+  let kbid;
+  if (/^[a-z2-7]{26}$/.test(identifier)) {
     const sections = await client.readSections([identifier]);
     if (sections.length > 0) {
       content = sections[0]?.content;
+      kbid = identifier;
     }
   }
   if (content === void 0) {
@@ -1041,9 +1182,10 @@ async function runSkillGet(client, options) {
     const match = records.filter((r) => r.title === identifier).pop();
     if (match) {
       content = match.content;
+      kbid = match.kbid;
     }
   }
-  if (content === void 0) {
+  if (content === void 0 || kbid === void 0) {
     return {
       error: `skill not found: ${identifier}`,
       exitCode: 1
@@ -1051,7 +1193,7 @@ async function runSkillGet(client, options) {
   }
   const skill = parseSkillContent(content);
   return {
-    output: JSON.stringify(skill, null, 2),
+    output: JSON.stringify({ kbid, ...skill }, null, 2),
     exitCode: 0
   };
 }
@@ -1066,7 +1208,7 @@ async function runSkillDelete(client, options) {
   const result = await client.removeSection(kbid);
   return {
     output: JSON.stringify(
-      { kbid, removed: result.removed },
+      { removed: result.removed ? [kbid] : [] },
       null,
       2
     ),
@@ -1108,7 +1250,7 @@ async function runAgentCreate(client, options) {
     title: name,
     description: options.description
   });
-  const allKbids = [metaResult.kbid, ...skills];
+  const allKbids = [metaResult.items[0], ...skills];
   const docid = await client.groupSections(name, allKbids, "agent");
   return {
     output: JSON.stringify(
@@ -1208,11 +1350,33 @@ async function runAgentDelete(client, options) {
   }
   await client.removeGrouping(docid);
   return {
-    output: JSON.stringify({ docid, removed: true }, null, 2),
+    output: JSON.stringify({ removed: [docid] }, null, 2),
     exitCode: 0
   };
 }
 
+// src/shared/cli/functions/run-skill-search.function.ts
+async function runSkillSearch(client, options) {
+  const paged = await runSearch(client, options);
+  const filtered = paged.items.filter((item) => item.type === "skill");
+  return {
+    ...paged,
+    items: filtered,
+    total: filtered.length
+  };
+}
+
+// src/shared/cli/functions/run-agent-search.function.ts
+async function runAgentSearch(client, options) {
+  const paged = await runSearch(client, options);
+  const filtered = paged.items.filter((item) => item.type === "agent");
+  return {
+    ...paged,
+    items: filtered,
+    total: filtered.length
+  };
+}
+
 // src/shared/cli/functions/run-import.function.ts
 import { resolve as resolve4 } from "node:path";
 async function runImport(client, options) {
@@ -1303,6 +1467,10 @@ async function dispatchCommand(client, options, io) {
       const result = await runAgentDelete(client, options);
       return result;
     }
+    case "skill-search":
+      return handleTypedSearch(client, options, "skill");
+    case "agent-search":
+      return handleTypedSearch(client, options, "agent");
     default:
       log("unknown command: " + options.command, 2 /* WARNING */);
       return {
@@ -1314,8 +1482,33 @@ async function dispatchCommand(client, options, io) {
 async function handleLearn(client, options, io) {
   try {
     const results = await runLearn(client, options, io);
+    const items = results.map((r) => r.kbid);
+    const base = {
+      items,
+      total: results.length,
+      offset: 0
+    };
+    if (results.length === 0) {
+      const empty = {
+        ...base,
+        superseded: null,
+        warnings: [],
+        near_duplicates: []
+      };
+      return {
+        output: formatCommandOutput(empty, options.format, "learn"),
+        exitCode: 0
+      };
+    }
+    const last = results[results.length - 1];
+    const data = {
+      ...base,
+      superseded: last.superseded,
+      warnings: last.warnings,
+      near_duplicates: last.near_duplicates
+    };
     return {
-      output: formatCommandOutput(results, options.format, "learn"),
+      output: formatCommandOutput(data, options.format, "learn"),
       exitCode: 0
     };
   } catch (err) {
@@ -1328,9 +1521,10 @@ async function handleLearn(client, options, io) {
 async function handleUnlearn(client, options) {
   try {
     const results = await runUnlearn(client, options);
+    const removed = results.filter((r) => r.removed).map((r) => r.kbid);
     return {
       output: formatCommandOutput(
-        results,
+        { removed },
         options.format,
         "unlearn"
       ),
@@ -1350,7 +1544,7 @@ async function handleSearch(client, options) {
       await hydrateSearchPreviews(client, results);
     }
     return {
-      output: formatOutput(results, options.format),
+      output: formatOutput(results, options.format, options.content),
       exitCode: 0
     };
   } catch (err) {
@@ -1411,11 +1605,38 @@ async function handleImport(client, options) {
 async function handleContent(client, options) {
   try {
     const result = await runContent(client, options);
-    if (options.format === "rec") {
+    if (options.format === "text") {
       return { output: result.data, exitCode: 0 };
     }
+    if (options.format === "rec") {
+      const header = `type: ${result.type}
+total: ${String(result.total)}
+
+`;
+      return {
+        output: header + result.data,
+        exitCode: 0
+      };
+    }
+    if (options.format === "mcp") {
+      const text = result.data || "(empty)";
+      return {
+        output: JSON.stringify(
+          {
+            jsonrpc: "2.0",
+            result: {
+              content: [{ type: "text", text }]
+            }
+          },
+          null,
+          2
+        ),
+        exitCode: 0
+      };
+    }
+    const envelope = !options.search && options.args.length === 1 ? { kbid: options.args[0], ...result } : result;
     return {
-      output: JSON.stringify(result, null, 2),
+      output: JSON.stringify(envelope, null, 2),
       exitCode: 0
     };
   } catch (err) {
@@ -1502,6 +1723,21 @@ async function handleDbMigrate(client, options) {
     };
   }
 }
+async function handleTypedSearch(client, options, type) {
+  try {
+    const runner = type === "skill" ? runSkillSearch : runAgentSearch;
+    const results = await runner(client, options);
+    return {
+      output: formatOutput(results, options.format),
+      exitCode: 0
+    };
+  } catch (err) {
+    return {
+      error: `${type} search failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+}
 
 // src/shared/version/constants/version.constant.ts
 var VERSION = "0.6.1";
@@ -3048,8 +3284,15 @@ function handleInit(options, deps2) {
       exitCode: 0
     };
   }
+  const msg = result.errorMessage ?? "init failed";
+  if (/already exists/i.test(msg)) {
+    return {
+      output: `${result.targetPath} (already initialized)`,
+      exitCode: 0
+    };
+  }
   return {
-    error: `error: ${result.errorMessage ?? "init failed"}`,
+    error: `error: ${msg}`,
     exitCode: 1
   };
 }
@@ -3309,7 +3552,7 @@ function createToolDefinitions() {
         properties: {
           content: {
             type: "string",
-            description: "Text content to add"
+            description: "Raw text or Markdown content to index. Do not wrap in JSON."
           },
           type: {
             type: "string",
@@ -3539,7 +3782,7 @@ function createToolDefinitions() {
           },
           body: {
             type: "string",
-            description: "Skill body template. Use {{argName}} for placeholders."
+            description: "Skill body template as raw text. Use {{argName}} for placeholders. Do not wrap in JSON."
           }
         },
         required: ["name", "body"]
@@ -3628,7 +3871,7 @@ function createToolDefinitions() {
           },
           persona: {
             type: "string",
-            description: "Agent persona prompt"
+            description: "Agent persona as raw text. Do not wrap in JSON."
           },
           skills: {
             type: "array",
@@ -3703,6 +3946,56 @@ function createToolDefinitions() {
         openWorldHint: false
       }
     },
+    {
+      name: "skill-search",
+      description: "Search for skills by keyword. Returns ranked skill definitions matching the query.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Search query text"
+          },
+          limit: {
+            type: "number",
+            description: "Maximum results (default: 20)"
+          }
+        },
+        required: ["query"]
+      },
+      annotations: {
+        title: "Search Skills",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    {
+      name: "agent-search",
+      description: "Search for agents by keyword. Returns ranked agent profiles matching the query.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Search query text"
+          },
+          limit: {
+            type: "number",
+            description: "Maximum results (default: 20)"
+          }
+        },
+        required: ["query"]
+      },
+      annotations: {
+        title: "Search Agents",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
     {
       name: "auto-capture-review",
       description: "Review and approve pending auto-captured knowledge before storage.",
@@ -3745,6 +4038,33 @@ function createResourceTemplates() {
   ];
 }
 
+// src/shared/mcp/functions/format-search-results.function.ts
+function formatSearchResults(query, results) {
+  if (results.items.length === 0) {
+    return `No results found for "${query}"`;
+  }
+  const lines = results.items.map(
+    (item, index) => formatItem(item, results.offset + index + 1)
+  );
+  const start = results.offset + 1;
+  const end = results.offset + results.items.length;
+  const total = String(results.total);
+  return [
+    `Found ${total} results for "${query}"`,
+    "",
+    ...lines,
+    "",
+    `Showing ${String(start)}-${String(end)} of ${total} results`
+  ].join("\n");
+}
+function formatItem(item, position) {
+  const heading = item.heading ?? "(untitled)";
+  const terms = item.matched_terms.join(", ");
+  return `${String(position)}. [${item.kbid}] ${heading}
+   ${item.snippet}
+   type: ${item.type}  terms: ${terms}`;
+}
+
 // src/shared/mcp/functions/handle-agent-create.function.ts
 function asString(value, fallback) {
   return typeof value === "string" ? value : fallback;
@@ -3795,35 +4115,52 @@ async function handleAgentCreate(client, args) {
     title: name,
     description
   });
-  const allKbids = [metaResult.kbid, ...skills];
+  const allKbids = [metaResult.items[0], ...skills];
   const docid = await client.groupSections(name, allKbids, "agent");
   return {
     content: [
       {
         type: "text",
-        text: JSON.stringify({
-          docid,
-          name,
-          skillCount: skills.length
-        })
+        text: `Created agent "${name}" (docid: ${docid})
+Skills: ${String(skills.length)} attached`
       }
     ]
   };
 }
 
 // src/shared/mcp/functions/handle-agent-list.function.ts
+async function readAgentDescription(client, sections) {
+  const metaKbid = sections[0]?.kbid;
+  if (!metaKbid) return "";
+  const metaSections = await client.readSections([metaKbid]);
+  const first = metaSections.at(0);
+  if (!first) return "";
+  try {
+    const meta = JSON.parse(first.content);
+    return typeof meta["description"] === "string" ? meta["description"] : "";
+  } catch {
+    return "";
+  }
+}
 async function handleAgentList(client) {
   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 items = await Promise.all(
+    docs.map(async (d) => ({
+      name: d.title,
+      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"
+  );
   return {
     content: [
       {
         type: "text",
-        text: JSON.stringify(items, null, 2)
+        text
       }
     ]
   };
@@ -3872,6 +4209,19 @@ async function resolveSkillRefs(client, skillRefs) {
     }
   });
 }
+function formatAgent(agent) {
+  const skillLines = agent.skills.length > 0 ? agent.skills.map(
+    (s, index) => `${String(index + 1)}. ${s.name ?? `(missing: ${s.kbid})`}`
+  ).join("\n") : "none";
+  return [
+    `Agent: ${agent.name} (docid: ${agent.docid})`,
+    `Description: ${agent.description}`,
+    `Persona: ${agent.persona}`,
+    "",
+    "Skills:",
+    skillLines
+  ].join("\n");
+}
 async function handleAgentGet(client, args) {
   const docid = typeof args["docid"] === "string" ? args["docid"] : "";
   if (!docid) {
@@ -3896,7 +4246,7 @@ async function handleAgentGet(client, args) {
     content: [
       {
         type: "text",
-        text: JSON.stringify(agent, null, 2)
+        text: formatAgent(agent)
       }
     ]
   };
@@ -3916,17 +4266,74 @@ async function handleAgentDelete(client, args) {
     content: [
       {
         type: "text",
-        text: JSON.stringify({ docid, removed: true })
+        text: `Deleted agent (docid: ${docid})`
       }
     ]
   };
 }
 
 // src/shared/mcp/functions/handle-recall.function.ts
+function asRecord(value) {
+  return typeof value === "object" && value !== null ? value : void 0;
+}
+function strField(record, key, fallback) {
+  const value = record[key];
+  return typeof value === "string" ? value : fallback;
+}
+function formatList(label, items, line) {
+  if (items === void 0 || items === null) {
+    return "";
+  }
+  const list = Array.isArray(items) ? items : [];
+  const rows = list.map((raw) => asRecord(raw)).filter((r) => r !== void 0).map((r) => `  - ${line(r)}`);
+  if (rows.length > 0) {
+    return `
+
+${label}:
+${rows.join("\n")}`;
+  }
+  return `
+
+${label}: (none)`;
+}
+function formatRecallItem(raw) {
+  const item = asRecord(raw) ?? {};
+  const kbid = strField(item, "kbid", "?");
+  const heading = strField(item, "heading", "(untitled)");
+  const type = strField(item, "type", "unknown");
+  const content = strField(item, "content", "");
+  const refLine = (r) => `${strField(r, "heading", strField(r, "kbid", "?"))} (${strField(r, "kbid", "?")})`;
+  const text = `${heading} [${type}] (${kbid})
+
+${content}` + formatList(
+    "Documents",
+    item["documents"],
+    (d) => `${strField(d, "title", "?")} (${strField(d, "docid", "?")})`
+  ) + formatList("Back references", item["back_references"], refLine) + formatList("Siblings", item["siblings"], refLine) + formatList("References", item["references"], refLine);
+  return text;
+}
+function buildNotFoundResult(id, depth) {
+  const base = {
+    kbid: id,
+    heading: "(not found)",
+    type: "unknown",
+    content: "",
+    docids: []
+  };
+  if (depth >= 1) {
+    base["documents"] = [];
+    base["back_references"] = [];
+  }
+  if (depth >= 2) {
+    base["siblings"] = [];
+    base["references"] = [];
+  }
+  return base;
+}
 async function handleRecall2(client, args) {
   const kbid = typeof args["kbid"] === "string" ? args["kbid"] : void 0;
   const kbids = Array.isArray(args["kbids"]) && args["kbids"].every((item) => typeof item === "string") ? args["kbids"] : void 0;
-  if (!kbid && !kbids) {
+  if (!kbid && (!kbids || kbids.length === 0)) {
     return {
       content: [
         {
@@ -3938,17 +4345,63 @@ async function handleRecall2(client, args) {
     };
   }
   const depth = typeof args["depth"] === "number" ? args["depth"] : 0;
-  const result = await client.recall({ kbid, kbids, depth });
+  let result;
+  try {
+    result = await client.recall({ kbid, kbids, depth });
+  } catch {
+    const ids = kbid ? [kbid] : kbids ?? [];
+    const items = ids.map((id) => buildNotFoundResult(id, depth));
+    result = items.length === 1 ? items[0] : items;
+  }
+  const text = Array.isArray(result) ? result.map(formatRecallItem).join("\n\n---\n\n") : formatRecallItem(result);
   return {
     content: [
       {
         type: "text",
-        text: JSON.stringify(result, null, 2)
+        text
       }
     ]
   };
 }
 
+// src/shared/mcp/functions/handle-skill-search.function.ts
+async function handleSkillSearch(client, args) {
+  const query = typeof args["query"] === "string" ? args["query"] : "";
+  const results = await client.search({
+    query,
+    limit: args["limit"]
+  });
+  const filtered = {
+    ...results,
+    items: results.items.filter(
+      (item) => item.type === "skill"
+    ),
+    total: 0
+  };
+  filtered.total = filtered.items.length;
+  const text = formatSearchResults(query, filtered);
+  return { content: [{ type: "text", text }] };
+}
+
+// src/shared/mcp/functions/handle-agent-search.function.ts
+async function handleAgentSearch(client, args) {
+  const query = typeof args["query"] === "string" ? args["query"] : "";
+  const results = await client.search({
+    query,
+    limit: args["limit"]
+  });
+  const filtered = {
+    ...results,
+    items: results.items.filter(
+      (item) => item.type === "agent"
+    ),
+    total: 0
+  };
+  filtered.total = filtered.items.length;
+  const text = formatSearchResults(query, filtered);
+  return { content: [{ type: "text", text }] };
+}
+
 // src/shared/mcp/functions/handle-tool-call.function.ts
 function asString2(value, fallback) {
   return typeof value === "string" ? value : fallback;
@@ -3968,6 +4421,18 @@ function asStringArray2(value) {
   }
   return [];
 }
+function unwrapJsonContent(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith("{")) return raw;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed["content"] === "string")
+      return parsed["content"];
+    if (typeof parsed["text"] === "string") return parsed["text"];
+  } catch {
+  }
+  return raw;
+}
 async function handleToolCall(client, name, args) {
   log("tool call: " + name, 0 /* DEBUG */);
   try {
@@ -4010,6 +4475,10 @@ async function handleToolCall(client, name, args) {
         return await handleAgentGet(client, args);
       case "agent-delete":
         return await handleAgentDelete(client, args);
+      case "skill-search":
+        return await handleSkillSearch(client, args);
+      case "agent-search":
+        return await handleAgentSearch(client, args);
       case "auto-capture-review":
         return handleAutoCaptureReview();
       default:
@@ -4041,30 +4510,18 @@ async function handleToolCall(client, name, args) {
   }
 }
 async function handleSearch2(client, args) {
+  const query = asString2(args["query"], "");
   const results = await client.search({
-    query: asString2(args["query"], ""),
+    query,
     mode: args["mode"],
     limit: args["limit"],
     offset: args["offset"],
     algo: args["algo"],
     relaxed: args["relaxed"]
   });
-  const stripped = {
-    ...results,
-    items: results.items.map(
-      ({
-        score: _score,
-        confidence: _confidence,
-        ...rest
-      }) => rest
-    )
-  };
   return {
     content: [
-      {
-        type: "text",
-        text: JSON.stringify(stripped, null, 2)
-      }
+      { type: "text", text: formatSearchResults(query, results) }
     ]
   };
 }
@@ -4086,70 +4543,47 @@ async function handleLearn2(client, args) {
       isError: true
     };
   }
+  const rawContent = asString2(args["content"], "");
+  const content = unwrapJsonContent(rawContent);
   const result = await client.addSection({
     sectionType,
-    content: asString2(args["content"], ""),
+    content,
     title,
     description,
     docid,
     tags,
     replace
   });
-  const normalized = {
-    kbid: result.kbid,
-    indexed_terms_count: result.indexed_terms_count ?? 0,
-    elapsed_ms: result.elapsed_ms ?? 0,
+  const payload = {
+    items: result.items,
+    total: result.total,
+    offset: result.offset,
     superseded: result.superseded ?? null,
     warnings: result.warnings ?? [],
-    near_duplicates: (result.near_duplicates ?? []).map((d) => ({
-      kbid: d.kbid,
-      similarity: d.similarity,
-      ...d.method !== void 0 ? { method: d.method } : {}
-    }))
+    near_duplicates: result.near_duplicates ?? []
   };
   return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify(normalized)
-      }
-    ]
+    content: [{ type: "text", text: JSON.stringify(payload) }]
   };
 }
 async function handleUnlearn2(client, args) {
-  const result = await client.removeSection(
-    asString2(args["kbid"], "")
-  );
+  const kbid = asString2(args["kbid"], "");
+  await client.removeSection(kbid);
   return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify(result)
-      }
-    ]
+    content: [{ type: "text", text: `Removed section ${kbid}` }]
   };
 }
 async function handleRetrieve(client, args) {
   if (typeof args["kbid"] === "string") {
     const sections = await client.readSections([args["kbid"]]);
     return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(sections, null, 2)
-        }
-      ]
+      content: [{ type: "text", text: formatSections(sections) }]
     };
   }
   if (typeof args["docid"] === "string") {
     const doc = await client.retrieveDocument(args["docid"]);
     return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(doc, null, 2)
-        }
-      ]
+      content: [{ type: "text", text: formatDocument(doc) }]
     };
   }
   return {
@@ -4162,61 +4596,81 @@ async function handleRetrieve(client, args) {
     isError: true
   };
 }
+function formatSections(sections) {
+  if (sections.length === 0) {
+    return "No sections found";
+  }
+  return sections.map((s) => `${s.kbid} (${s.sectionType})
+${s.content}`).join("\n\n");
+}
+function formatDocument(doc) {
+  if (typeof doc !== "object" || doc === null) {
+    return String(doc);
+  }
+  return Object.entries(doc).map(([key, value]) => {
+    if (Array.isArray(value)) {
+      const items = value.map((item) => formatDocValue(item)).map((s) => `  - ${s}`);
+      return items.length > 0 ? `${key}:
+${items.join("\n")}` : `${key}: (none)`;
+    }
+    return `${key}: ${formatDocValue(value)}`;
+  }).join("\n");
+}
+function formatDocValue(value) {
+  if (typeof value !== "object" || value === null) {
+    return String(value);
+  }
+  const rec = value;
+  return Object.entries(rec).map(([k, v]) => `${k}=${String(v)}`).join(", ");
+}
 async function handleStatus2(client) {
   const status = await client.dbStatus();
-  return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify(status, null, 2)
-      }
-    ]
-  };
+  const cs = status.cacheStats;
+  const lines = [
+    `Database: ${status.contextPath}`,
+    `Initialized: ${status.initialized ? "yes" : "no"}`
+  ];
+  if (cs) {
+    lines.push(
+      `Cached content entries: ${String(cs.contentCount)}`,
+      `Cached index entries: ${String(cs.indexCount)}`
+    );
+  }
+  return { content: [{ type: "text", text: lines.join("\n") }] };
 }
 async function handleContent2(client, args) {
   const ids = asStringArray2(args["ids"]);
   const result = await client.content(ids);
+  const text = result.data || "(no content found)";
   return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify(result)
-      }
-    ]
+    content: [{ type: "text", text }]
   };
 }
 async function handleCheck2(client) {
   const report = await client.integrityCheck();
-  return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify(report, null, 2)
-      }
-    ]
-  };
+  const status = report.ok ? "OK" : "FAIL";
+  const lines = [
+    `Integrity check: ${status}. ${String(report.sections_checked)} sections checked.`
+  ];
+  for (const error of report.errors) {
+    lines.push(`- ${error.type}: ${error.entity} (${error.detail})`);
+  }
+  return { content: [{ type: "text", text: lines.join("\n") }] };
 }
 async function handleGc2(client) {
   const report = await client.gc();
-  return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify(report, null, 2)
-      }
-    ]
-  };
+  const lines = [
+    `GC complete: removed ${String(report.removed_sections)} sections, freed ${String(report.removed_bytes)} bytes.`
+  ];
+  if (report.stale_sources !== void 0) {
+    lines.push(`stale sources: ${String(report.stale_sources)}`);
+  }
+  return { content: [{ type: "text", text: lines.join("\n") }] };
 }
 async function handleRebuild2(client) {
   const report = await client.rebuildIndexes();
-  return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify(report, null, 2)
-      }
-    ]
-  };
+  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"], "");
@@ -4252,37 +4706,22 @@ async function handleSkillLearn(client, args) {
     content: [
       {
         type: "text",
-        text: JSON.stringify({ kbid: result.kbid, name })
+        text: `Created skill "${name}" (kbid: ${result.items[0]})`
       }
     ]
   };
 }
 async function handleSkillList(client) {
   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 lines = records.map((r, index) => {
+    const desc = r.description ? ` -- ${r.description}` : "";
+    const label = r.title ?? "(untitled)";
+    return `${String(index + 1)}. ${label} (${r.kbid})${desc}`;
   });
-  return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify(items, null, 2)
-      }
-    ]
-  };
+  const text = [`${String(records.length)} skills:`, ...lines].join(
+    "\n"
+  );
+  return { content: [{ type: "text", text }] };
 }
 async function handleSkillGet(client, args) {
   const kbid = typeof args["kbid"] === "string" ? args["kbid"] : void 0;
@@ -4326,14 +4765,29 @@ async function handleSkillGet(client, args) {
   }
   const skill = parseSkillContent(content);
   return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify(skill, null, 2)
-      }
-    ]
+    content: [{ type: "text", text: formatSkill(skill) }]
   };
 }
+function formatSkill(skill) {
+  const lines = [`name: ${skill.name}`];
+  if (skill.description) {
+    lines.push(`description: ${skill.description}`);
+  }
+  if (skill.arguments && skill.arguments.length > 0) {
+    lines.push("arguments:");
+    for (const arg of skill.arguments) {
+      const details = [
+        ...arg.type ? [arg.type] : [],
+        ...arg.required ? ["required"] : []
+      ];
+      lines.push(
+        details.length > 0 ? `- ${arg.name}: ${details.join(", ")}` : `- ${arg.name}`
+      );
+    }
+  }
+  lines.push("body:", skill.body);
+  return lines.join("\n");
+}
 async function handleSkillDelete(client, args) {
   const kbid = asString2(args["kbid"], "");
   if (!kbid) {
@@ -4342,14 +4796,9 @@ async function handleSkillDelete(client, args) {
       isError: true
     };
   }
-  const result = await client.removeSection(kbid);
+  await client.removeSection(kbid);
   return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify({ kbid, removed: result.removed })
-      }
-    ]
+    content: [{ type: "text", text: `Deleted skill ${kbid}` }]
   };
 }
 function handleAutoCaptureReview() {
@@ -4357,10 +4806,7 @@ function handleAutoCaptureReview() {
     content: [
       {
         type: "text",
-        text: JSON.stringify({
-          pending: [],
-          message: "No pending auto-captured knowledge entries."
-        })
+        text: "No pending auto-captured knowledge entries."
       }
     ]
   };
@@ -4370,14 +4816,13 @@ async function handleExport2(client, args) {
   const result = await client.export(
     path !== void 0 ? { path } : {}
   );
-  return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify(result)
-      }
-    ]
-  };
+  const lines = [
+    `Exported to ${result.path}`,
+    `sections: ${String(result.sections_exported)}`,
+    `documents: ${String(result.documents_exported)}`,
+    `elapsed: ${String(result.elapsed_ms)}ms`
+  ];
+  return { content: [{ type: "text", text: lines.join("\n") }] };
 }
 
 // src/shared/mcp/functions/handle-resource-read.function.ts