@bodhi-ventures/aiocs 0.5.3 → 0.6.0

package/dist/cli.js

@@ -4,6 +4,7 @@ import {
   AiocsError,
   backfillEmbeddings,
   clearEmbeddings,
+  describeSource,
   diffSnapshotsForSource,
   exportCatalogBackup,
   fetchSources,
@@ -12,26 +13,33 @@ import {
   getDoctorReport,
   getEmbeddingStatus,
   getManagedSourceSpecDirectories,
+  getSourceContextForSource,
   importCatalogBackup,
   initManagedSources,
   linkProjectSources,
+  listRoutingLearningsForQuery,
   listSnapshotsForSource,
+  listSourcePages,
   listSources,
   openCatalog,
   packageName,
   packageVersion,
   parseDaemonConfig,
   refreshDueSources,
+  retrieveContext,
   runEmbeddingWorker,
   runSourceCanaries,
+  saveRoutingLearning,
   searchCatalog,
   showChunk,
+  showPage,
   startDaemon,
   toAiocsError,
   unlinkProjectSources,
+  upsertSourceContextFromFile,
   upsertSourceFromSpecFile,
   verifyCoverage
-} from "./chunk-M767TPUX.js";
+} from "./chunk-2UWV3O7E.js";
 
 // src/cli.ts
 import { Command, CommanderError as CommanderError2 } from "commander";
@@ -99,7 +107,7 @@ function inferRequestedCommand(argv) {
   if (!first) {
     return "cli";
   }
-  if (["source", "snapshot", "project", "refresh", "verify", "backup"].includes(first) && second && !second.startsWith("-")) {
+  if (["source", "snapshot", "page", "project", "refresh", "verify", "backup", "learning"].includes(first) && second && !second.startsWith("-")) {
     return `${first}.${second}`;
   }
   return first;
@@ -124,6 +132,20 @@ function renderSearchResult(result) {
     ""
   ].join("\n");
 }
+function renderPageResult(result) {
+  return [
+    `Source: ${result.sourceId}`,
+    `Snapshot: ${result.snapshotId}`,
+    ...result.pageKind ? [`Kind: ${result.pageKind}`] : [],
+    ...result.filePath ? [`Path: ${result.filePath}`] : [],
+    ...result.language ? [`Language: ${result.language}`] : [],
+    `Page: ${result.title}`,
+    `URL: ${result.url}`,
+    "",
+    result.markdown,
+    ""
+  ].join("\n");
+}
 function parsePositiveIntegerOption(value, field) {
   if (typeof value === "undefined") {
     return void 0;
@@ -351,6 +373,58 @@ source.command("list").action(async (_options, command) => {
     };
   });
 });
+source.command("describe").argument("<source-id>").action(async (sourceId, _options, command) => {
+  await executeCommand(command, "source.describe", async () => {
+    const result = await describeSource(sourceId);
+    return {
+      data: result,
+      human: [
+        `${result.source.id} | ${result.source.kind} | ${result.source.label}`,
+        `Spec ${result.source.specPath ?? "(inline/unknown)"}`,
+        result.latestSnapshot ? `Latest ${result.latestSnapshot.snapshotId} | pages=${result.latestSnapshot.pageCount} | created=${result.latestSnapshot.createdAt}` : "No successful snapshots",
+        ...result.context.context ? [
+          ...result.context.context.purpose ? [`Purpose: ${result.context.context.purpose}`] : [],
+          ...result.context.context.summary ? [`Summary: ${result.context.context.summary}`] : [],
+          ...result.context.context.topicHints.length > 0 ? [`Topics: ${result.context.context.topicHints.join(", ")}`] : [],
+          ...result.context.context.commonLocations.length > 0 ? [
+            "Common locations:",
+            ...result.context.context.commonLocations.map((location) => `- ${location.label} | ${location.filePath ?? location.url ?? "(unknown)"}${location.note ? ` | ${location.note}` : ""}`)
+          ] : []
+        ] : ["No curated source context"],
+        ...result.recentLearnings.length > 0 ? [
+          "Recent learnings:",
+          ...result.recentLearnings.map((learning2) => `- ${learning2.learningType} | ${learning2.intent} | ${learning2.filePath ?? learning2.pageUrl ?? "(no target)"}`)
+        ] : ["No routing learnings"]
+      ]
+    };
+  });
+});
+var sourceContext = source.command("context");
+sourceContext.command("show").argument("<source-id>").action(async (sourceId, _options, command) => {
+  await executeCommand(command, "source.context.show", async () => {
+    const result = await getSourceContextForSource(sourceId);
+    return {
+      data: result,
+      human: result.context ? [
+        `Context for ${sourceId}`,
+        ...result.context.purpose ? [`Purpose: ${result.context.purpose}`] : [],
+        ...result.context.summary ? [`Summary: ${result.context.summary}`] : [],
+        ...result.context.topicHints.length > 0 ? [`Topics: ${result.context.topicHints.join(", ")}`] : [],
+        ...result.context.authNotes.length > 0 ? ["Auth notes:", ...result.context.authNotes.map((item) => `- ${item}`)] : [],
+        ...result.context.gotchas.length > 0 ? ["Gotchas:", ...result.context.gotchas.map((item) => `- ${item}`)] : []
+      ] : `No curated source context for ${sourceId}`
+    };
+  });
+});
+sourceContext.command("upsert").argument("<source-id>").argument("<context-file>").action(async (sourceId, contextFile, _options, command) => {
+  await executeCommand(command, "source.context.upsert", async () => {
+    const result = await upsertSourceContextFromFile(sourceId, contextFile);
+    return {
+      data: result,
+      human: `Updated source context for ${result.sourceId}`
+    };
+  });
+});
 program.command("fetch").argument("<source-id-or-all>").action(async (sourceIdOrAll, _options, command) => {
   await executeCommand(command, "fetch", async () => {
     const result = await fetchSources(sourceIdOrAll);
@@ -403,6 +477,48 @@ snapshot.command("list").argument("<source-id>").action(async (sourceId, _option
     };
   });
 });
+var page = program.command("page");
+page.command("list").argument("<source-id>").option("--snapshot <snapshot-id>", "list pages from a specific snapshot").option("--query <text>", "filter pages by title, url, or file path").option("--path <glob>", "restrict pages to file paths matching a glob", (value, current) => {
+  current.push(value);
+  return current;
+}, []).option("--limit <count>", "maximum number of pages to return").option("--offset <count>", "number of pages to skip before returning results").action(async (sourceId, options, command) => {
+  await executeCommand(command, "page.list", async () => {
+    const limit = parsePositiveIntegerOption(options.limit, "limit");
+    const offset = parsePositiveIntegerOption(options.offset, "offset");
+    const result = await listSourcePages(sourceId, {
+      ...options.snapshot ? { snapshot: options.snapshot } : {},
+      ...options.query ? { query: options.query } : {},
+      ...options.path && options.path.length > 0 ? { path: options.path } : {},
+      ...typeof limit === "number" ? { limit } : {},
+      ...typeof offset === "number" ? { offset } : {}
+    });
+    return {
+      data: result,
+      human: result.pages.length === 0 ? `No pages for ${sourceId}` : [
+        `Showing ${result.offset + 1}-${result.offset + result.pages.length} of ${result.total} page(s) for ${sourceId}`,
+        ...result.pages.map((entry) => `${entry.title} | ${entry.filePath ?? entry.url} | kind=${entry.pageKind} | chars=${entry.markdownLength}`)
+      ]
+    };
+  });
+});
+page.command("show").argument("<source-id>").option("--snapshot <snapshot-id>", "read from a specific snapshot").option("--url <page-url>", "read a page by URL").option("--path <file-path>", "read a file-backed page by file path").action(async (sourceId, options, command) => {
+  await executeCommand(command, "page.show", async () => {
+    const result = await showPage({
+      sourceId,
+      ...options.snapshot ? { snapshotId: options.snapshot } : {},
+      ...options.url ? { url: options.url } : {},
+      ...options.path ? { filePath: options.path } : {}
+    });
+    return {
+      data: result,
+      human: renderPageResult({
+        sourceId: result.sourceId,
+        snapshotId: result.snapshotId,
+        ...result.page
+      })
+    };
+  });
+});
 program.command("diff").alias("changes").argument("<source-id>").option("--from <snapshot-id>", "base snapshot id").option("--to <snapshot-id>", "target snapshot id").description("Compare two snapshots for a source.").action(
   async (sourceId, options, command) => {
     await executeCommand(command, "diff", async () => {
@@ -521,6 +637,94 @@ embeddings.command("run").description("Process queued embedding jobs immediately
     };
   });
 });
+var learning = program.command("learning");
+learning.command("save").requiredOption("--source <source-id>", "source to attach the learning to").requiredOption("--kind <discovery|negative>", "learning type").requiredOption("--intent <text>", "intent or question pattern this learning applies to").option("--snapshot <snapshot-id>", "snapshot associated with the learning").option("--page-url <page-url>", "page URL associated with the learning").option("--file-path <file-path>", "file-backed page path associated with the learning").option("--title <title>", "page title or short label").option("--note <text>", "additional note").option("--search-term <term>", "search term that worked (or failed)", (value, current) => {
+  current.push(value);
+  return current;
+}, []).action(async (options, command) => {
+  await executeCommand(command, "learning.save", async () => {
+    if (options.kind !== "discovery" && options.kind !== "negative") {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.invalidArgument,
+        "kind must be discovery or negative"
+      );
+    }
+    const result = await saveRoutingLearning({
+      sourceId: options.source,
+      learningType: options.kind,
+      intent: options.intent,
+      ...options.snapshot ? { snapshotId: options.snapshot } : {},
+      ...options.pageUrl ? { pageUrl: options.pageUrl } : {},
+      ...options.filePath ? { filePath: options.filePath } : {},
+      ...options.title ? { title: options.title } : {},
+      ...options.note ? { note: options.note } : {},
+      ...options.searchTerm && options.searchTerm.length > 0 ? { searchTerms: options.searchTerm } : {}
+    });
+    return {
+      data: result,
+      human: `Saved ${result.learning.learningType} learning for ${result.learning.sourceId}`
+    };
+  });
+});
+learning.command("list").option("--source <source-id>", "filter by source id").option("--kind <discovery|negative>", "filter by learning type").option("--intent <text>", "filter by intent substring").option("--limit <count>", "maximum number of learnings to return").action(async (options, command) => {
+  await executeCommand(command, "learning.list", async () => {
+    const limit = parsePositiveIntegerOption(options.limit, "limit");
+    if (options.kind && options.kind !== "discovery" && options.kind !== "negative") {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.invalidArgument,
+        "kind must be discovery or negative"
+      );
+    }
+    const result = await listRoutingLearningsForQuery({
+      ...options.source ? { sourceId: options.source } : {},
+      ...options.kind ? { learningType: options.kind } : {},
+      ...options.intent ? { intentQuery: options.intent } : {},
+      ...typeof limit === "number" ? { limit } : {}
+    });
+    return {
+      data: result,
+      human: result.learnings.length === 0 ? "No learnings recorded." : result.learnings.map((entry) => `${entry.learningType} | ${entry.sourceId} | ${entry.intent} | ${entry.filePath ?? entry.pageUrl ?? "(no target)"}`)
+    };
+  });
+});
+program.command("retrieve").argument("<query>").option("--source <source-id>", "restrict retrieval to a source", (value, current) => {
+  current.push(value);
+  return current;
+}, []).option("--snapshot <snapshot-id>", "retrieve from a specific snapshot").option("--all", "retrieve across all latest snapshots").option("--project <path>", "resolve retrieval scope as if running from this path").option("--path <glob>", "restrict retrieval to file paths matching a glob", (value, current) => {
+  current.push(value);
+  return current;
+}, []).option("--language <name>", "restrict retrieval to a language", (value, current) => {
+  current.push(value);
+  return current;
+}, []).option("--mode <mode>", "search mode: auto, lexical, hybrid, semantic").option("--limit <count>", "maximum number of search results to shortlist").option("--offset <count>", "number of search results to skip before shortlisting").option("--page-limit <count>", "maximum number of full pages to read into context").action(async (query, options, command) => {
+  await executeCommand(command, "retrieve", async () => {
+    const limit = parsePositiveIntegerOption(options.limit, "limit");
+    const offset = parsePositiveIntegerOption(options.offset, "offset");
+    const pageLimit = parsePositiveIntegerOption(options.pageLimit, "limit");
+    const mode = parseSearchModeOption(options.mode);
+    const result = await retrieveContext(query, {
+      source: options.source,
+      ...options.snapshot ? { snapshot: options.snapshot } : {},
+      ...typeof options.all !== "undefined" ? { all: options.all } : {},
+      ...options.project ? { project: options.project } : {},
+      ...options.path && options.path.length > 0 ? { path: options.path } : {},
+      ...options.language && options.language.length > 0 ? { language: options.language } : {},
+      ...mode ? { mode } : {},
+      ...typeof limit === "number" ? { limit } : {},
+      ...typeof offset === "number" ? { offset } : {},
+      ...typeof pageLimit === "number" ? { pageLimit } : {}
+    });
+    return {
+      data: result,
+      human: [
+        `Retrieval for "${query}" | mode=${result.modeUsed} | sources=${result.sourceScope.join(", ") || "(none)"}`,
+        ...result.sourceHints.length > 0 ? ["Source hints:", ...result.sourceHints.map((hint) => `- ${hint.sourceId} | score=${hint.score} | ${hint.context.summary ?? hint.context.purpose ?? "context"}`)] : [],
+        ...result.matchedLearnings.length > 0 ? ["Matched learnings:", ...result.matchedLearnings.map((learning2) => `- ${learning2.sourceId} | ${learning2.intent} | score=${learning2.score}`)] : [],
+        ...result.pages.length > 0 ? ["Full pages read:", ...result.pages.map((page2) => `${page2.sourceId} | ${page2.filePath ?? page2.url} | ${page2.title}`)] : ["No full pages selected"]
+      ]
+    };
+  });
+});
 program.command("search").argument("<query>").option("--source <source-id>", "restrict search to a source", (value, current) => {
   current.push(value);
   return current;

package/dist/mcp-server.js

@@ -4,29 +4,37 @@ import {
   AiocsError,
   backfillEmbeddings,
   clearEmbeddings,
+  describeSource,
   diffSnapshotsForSource,
   exportCatalogBackup,
   fetchSources,
   getDoctorReport,
   getEmbeddingStatus,
+  getSourceContextForSource,
   importCatalogBackup,
   initManagedSources,
   linkProjectSources,
+  listRoutingLearningsForQuery,
   listSnapshotsForSource,
+  listSourcePages,
   listSources,
   packageDescription,
   packageName,
   packageVersion,
   refreshDueSources,
+  retrieveContext,
   runEmbeddingWorker,
   runSourceCanaries,
+  saveRoutingLearning,
   searchCatalog,
   showChunk,
+  showPage,
   toAiocsError,
   unlinkProjectSources,
+  upsertSourceContextFromFile,
   upsertSourceFromSpecFile,
   verifyCoverage
-} from "./chunk-M767TPUX.js";
+} from "./chunk-2UWV3O7E.js";
 
 // src/mcp-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -64,6 +72,52 @@ var sourceSchema = z.object({
   lastSuccessfulCanaryAt: z.string().nullable(),
   lastCanaryStatus: z.enum(["pass", "fail"]).nullable()
 });
+var sourceContextSchema = z.object({
+  purpose: z.string().optional(),
+  summary: z.string().optional(),
+  topicHints: z.array(z.string()),
+  commonLocations: z.array(z.object({
+    label: z.string(),
+    url: z.string().optional(),
+    filePath: z.string().optional(),
+    note: z.string().optional()
+  })),
+  gotchas: z.array(z.string()),
+  authNotes: z.array(z.string())
+});
+var routingLearningSchema = z.object({
+  learningId: z.string(),
+  sourceId: z.string(),
+  snapshotId: z.string().nullable(),
+  learningType: z.enum(["discovery", "negative"]),
+  intent: z.string(),
+  pageUrl: z.string().nullable(),
+  filePath: z.string().nullable(),
+  title: z.string().nullable(),
+  note: z.string().nullable(),
+  searchTerms: z.array(z.string()),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+var pageSchema = z.object({
+  url: z.string(),
+  title: z.string(),
+  markdown: z.string(),
+  pageKind: z.enum(["document", "file"]),
+  filePath: z.string().nullable(),
+  language: z.string().nullable()
+});
+var pageListingSchema = z.object({
+  sourceId: z.string(),
+  snapshotId: z.string(),
+  total: z.number().int().nonnegative(),
+  limit: z.number().int().nonnegative(),
+  offset: z.number().int().nonnegative(),
+  hasMore: z.boolean(),
+  pages: z.array(pageSchema.omit({ markdown: true }).extend({
+    markdownLength: z.number().int().nonnegative()
+  }))
+});
 var fetchResultSchema = z.object({
   sourceId: z.string(),
   snapshotId: z.string(),
@@ -254,10 +308,26 @@ var toolHandlers = {
   }),
   source_upsert: async (args = {}) => upsertSourceFromSpecFile(args.specFile),
   source_list: async () => listSources(),
+  source_describe: async (args = {}) => describeSource(args.sourceId),
+  source_context_show: async (args = {}) => getSourceContextForSource(args.sourceId),
+  source_context_upsert: async (args = {}) => upsertSourceContextFromFile(args.sourceId, args.contextFile),
   fetch: async (args = {}) => fetchSources(args.sourceIdOrAll),
   canary: async (args = {}) => runSourceCanaries(args.sourceIdOrAll),
   refresh_due: async (args = {}) => refreshDueSources(args.sourceIdOrAll ?? "all"),
   snapshot_list: async (args = {}) => listSnapshotsForSource(args.sourceId),
+  page_list: async (args = {}) => listSourcePages(args.sourceId, {
+    ...typeof args.snapshotId === "string" ? { snapshot: args.snapshotId } : {},
+    ...typeof args.query === "string" ? { query: args.query } : {},
+    ...Array.isArray(args.pathPatterns) ? { path: args.pathPatterns } : {},
+    ...typeof args.limit === "number" ? { limit: args.limit } : {},
+    ...typeof args.offset === "number" ? { offset: args.offset } : {}
+  }),
+  page_show: async (args = {}) => showPage({
+    sourceId: args.sourceId,
+    ...typeof args.snapshotId === "string" ? { snapshotId: args.snapshotId } : {},
+    ...typeof args.url === "string" ? { url: args.url } : {},
+    ...typeof args.filePath === "string" ? { filePath: args.filePath } : {}
+  }),
   diff_snapshots: async (args = {}) => diffSnapshotsForSource({
     sourceId: args.sourceId,
     ...typeof args.fromSnapshotId === "string" ? { fromSnapshotId: args.fromSnapshotId } : {},
@@ -276,6 +346,35 @@ var toolHandlers = {
     ...typeof args.limit === "number" ? { limit: args.limit } : {},
     ...typeof args.offset === "number" ? { offset: args.offset } : {}
   }),
+  retrieve_context: async (args = {}) => retrieveContext(args.query, {
+    source: args.sourceIds ?? [],
+    ...typeof args.snapshotId === "string" ? { snapshot: args.snapshotId } : {},
+    ...typeof args.all === "boolean" ? { all: args.all } : {},
+    ...typeof args.project === "string" ? { project: args.project } : {},
+    ...Array.isArray(args.pathPatterns) ? { path: args.pathPatterns } : {},
+    ...Array.isArray(args.languages) ? { language: args.languages } : {},
+    ...typeof args.mode === "string" ? { mode: args.mode } : {},
+    ...typeof args.limit === "number" ? { limit: args.limit } : {},
+    ...typeof args.offset === "number" ? { offset: args.offset } : {},
+    ...typeof args.pageLimit === "number" ? { pageLimit: args.pageLimit } : {}
+  }),
+  learning_save: async (args = {}) => saveRoutingLearning({
+    sourceId: args.sourceId,
+    learningType: args.learningType,
+    intent: args.intent,
+    ...typeof args.snapshotId === "string" ? { snapshotId: args.snapshotId } : {},
+    ...typeof args.pageUrl === "string" ? { pageUrl: args.pageUrl } : {},
+    ...typeof args.filePath === "string" ? { filePath: args.filePath } : {},
+    ...typeof args.title === "string" ? { title: args.title } : {},
+    ...typeof args.note === "string" ? { note: args.note } : {},
+    ...Array.isArray(args.searchTerms) ? { searchTerms: args.searchTerms } : {}
+  }),
+  learning_list: async (args = {}) => listRoutingLearningsForQuery({
+    ...typeof args.sourceId === "string" ? { sourceId: args.sourceId } : {},
+    ...typeof args.learningType === "string" ? { learningType: args.learningType } : {},
+    ...typeof args.intentQuery === "string" ? { intentQuery: args.intentQuery } : {},
+    ...typeof args.limit === "number" ? { limit: args.limit } : {}
+  }),
   show: async (args = {}) => showChunk(args.chunkId),
   embeddings_status: async () => getEmbeddingStatus(),
   embeddings_backfill: async (args = {}) => backfillEmbeddings(args.sourceIdOrAll),
@@ -410,6 +509,66 @@ registerAiocsTool(
     })
   }
 );
+registerAiocsTool(
+  "source_describe",
+  {
+    title: "Source describe",
+    description: "Describe one source with latest snapshot info, curated source context, and recent routing learnings.",
+    inputSchema: z.object({
+      sourceId: z.string()
+    }),
+    outputSchema: z.object({
+      source: sourceSchema,
+      context: z.object({
+        sourceId: z.string(),
+        context: sourceContextSchema.nullable(),
+        createdAt: z.string().nullable(),
+        updatedAt: z.string().nullable()
+      }),
+      latestSnapshot: z.object({
+        snapshotId: z.string(),
+        detectedVersion: z.string().nullable(),
+        createdAt: z.string(),
+        pageCount: z.number().int().nonnegative()
+      }).nullable(),
+      recentLearnings: z.array(routingLearningSchema)
+    })
+  }
+);
+registerAiocsTool(
+  "source_context_show",
+  {
+    title: "Source context show",
+    description: "Show curated local source context for a source.",
+    inputSchema: z.object({
+      sourceId: z.string()
+    }),
+    outputSchema: z.object({
+      sourceId: z.string(),
+      context: sourceContextSchema.nullable(),
+      createdAt: z.string().nullable(),
+      updatedAt: z.string().nullable()
+    })
+  }
+);
+registerAiocsTool(
+  "source_context_upsert",
+  {
+    title: "Source context upsert",
+    description: "Load or update curated local source context from a JSON or YAML file.",
+    inputSchema: z.object({
+      sourceId: z.string(),
+      contextFile: z.string()
+    }),
+    outputSchema: z.object({
+      sourceId: z.string(),
+      context: sourceContextSchema,
+      contextFile: z.string(),
+      createdAt: z.string(),
+      updatedAt: z.string()
+    })
+  }
+);
 registerAiocsTool(
   "fetch",
   {
@@ -469,6 +628,40 @@ registerAiocsTool(
     })
   }
 );
+registerAiocsTool(
+  "page_list",
+  {
+    title: "Page list",
+    description: "List stored pages for a source snapshot with optional query and path filtering.",
+    inputSchema: z.object({
+      sourceId: z.string(),
+      snapshotId: z.string().optional(),
+      query: z.string().optional(),
+      pathPatterns: z.array(z.string()).optional(),
+      limit: z.number().int().positive().optional(),
+      offset: z.number().int().nonnegative().optional()
+    }),
+    outputSchema: pageListingSchema
+  }
+);
+registerAiocsTool(
+  "page_show",
+  {
+    title: "Page show",
+    description: "Read a full stored page by URL or file path.",
+    inputSchema: z.object({
+      sourceId: z.string(),
+      snapshotId: z.string().optional(),
+      url: z.string().optional(),
+      filePath: z.string().optional()
+    }),
+    outputSchema: z.object({
+      sourceId: z.string(),
+      snapshotId: z.string(),
+      page: pageSchema
+    })
+  }
+);
 registerAiocsTool(
   "diff_snapshots",
   {
@@ -541,6 +734,56 @@ registerAiocsTool(
     })
   }
 );
+registerAiocsTool(
+  "retrieve_context",
+  {
+    title: "Retrieve context",
+    description: "Run aiocs awareness, learned routing hints, search, and full-page reads to assemble grounded answer context.",
+    inputSchema: z.object({
+      query: z.string(),
+      sourceIds: z.array(z.string()).optional(),
+      snapshotId: z.string().optional(),
+      all: z.boolean().optional(),
+      project: z.string().optional(),
+      pathPatterns: z.array(z.string()).optional(),
+      languages: z.array(z.string()).optional(),
+      mode: z.enum(["auto", "lexical", "hybrid", "semantic"]).optional(),
+      limit: z.number().int().positive().optional(),
+      offset: z.number().int().nonnegative().optional(),
+      pageLimit: z.number().int().positive().optional()
+    }),
+    outputSchema: z.object({
+      query: z.string(),
+      modeRequested: z.enum(["auto", "lexical", "hybrid", "semantic"]),
+      modeUsed: z.enum(["lexical", "hybrid", "semantic"]),
+      sourceScope: z.array(z.string()),
+      sourceHints: z.array(z.object({
+        sourceId: z.string(),
+        score: z.number(),
+        context: sourceContextSchema,
+        matchedCommonLocations: z.array(z.object({
+          label: z.string(),
+          url: z.string().optional(),
+          filePath: z.string().optional(),
+          note: z.string().optional()
+        }))
+      })),
+      matchedLearnings: z.array(routingLearningSchema.extend({ score: z.number() })),
+      avoidedLearnings: z.array(routingLearningSchema.extend({ score: z.number() })),
+      search: z.object({
+        total: z.number().int().nonnegative(),
+        limit: z.number().int().positive(),
+        offset: z.number().int().nonnegative(),
+        hasMore: z.boolean(),
+        results: z.array(searchResultSchema)
+      }),
+      pages: z.array(pageSchema.extend({
+        sourceId: z.string(),
+        snapshotId: z.string()
+      }))
+    })
+  }
+);
 registerAiocsTool(
   "show",
   {
@@ -554,6 +797,43 @@ registerAiocsTool(
     })
   }
 );
+registerAiocsTool(
+  "learning_save",
+  {
+    title: "Learning save",
+    description: "Save a discovery or negative routing learning for future retrieval hints.",
+    inputSchema: z.object({
+      sourceId: z.string(),
+      learningType: z.enum(["discovery", "negative"]),
+      intent: z.string(),
+      snapshotId: z.string().optional(),
+      pageUrl: z.string().optional(),
+      filePath: z.string().optional(),
+      title: z.string().optional(),
+      note: z.string().optional(),
+      searchTerms: z.array(z.string()).optional()
+    }),
+    outputSchema: z.object({
+      learning: routingLearningSchema
+    })
+  }
+);
+registerAiocsTool(
+  "learning_list",
+  {
+    title: "Learning list",
+    description: "List saved routing learnings, optionally filtered by source, type, or intent substring.",
+    inputSchema: z.object({
+      sourceId: z.string().optional(),
+      learningType: z.enum(["discovery", "negative"]).optional(),
+      intentQuery: z.string().optional(),
+      limit: z.number().int().positive().optional()
+    }),
+    outputSchema: z.object({
+      learnings: z.array(routingLearningSchema)
+    })
+  }
+);
 registerAiocsTool(
   "embeddings_status",
   {