@bodhi-ventures/aiocs 0.5.3 → 0.6.0

package/dist/{chunk-M767TPUX.js → chunk-2UWV3O7E.js}

@@ -7,8 +7,10 @@ var AIOCS_ERROR_CODES = {
   noPagesFetched: "NO_PAGES_FETCHED",
   noProjectScope: "NO_PROJECT_SCOPE",
   chunkNotFound: "CHUNK_NOT_FOUND",
+  pageNotFound: "PAGE_NOT_FOUND",
   referenceFileNotFound: "REFERENCE_FILE_NOT_FOUND",
   invalidReferenceFile: "INVALID_REFERENCE_FILE",
+  sourceContextInvalid: "SOURCE_CONTEXT_INVALID",
   authEnvMissing: "AUTH_ENV_MISSING",
   canaryFailed: "CANARY_FAILED",
   backupConflict: "BACKUP_CONFLICT",
@@ -818,6 +820,35 @@ function initSchema(db) {
       PRIMARY KEY(project_path, source_id)
     );
 
+    CREATE TABLE IF NOT EXISTS source_context (
+      source_id TEXT PRIMARY KEY REFERENCES sources(id) ON DELETE CASCADE,
+      context_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS routing_learnings (
+      id TEXT PRIMARY KEY,
+      route_key TEXT NOT NULL UNIQUE,
+      source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
+      snapshot_id TEXT REFERENCES snapshots(id) ON DELETE SET NULL,
+      learning_type TEXT NOT NULL CHECK(learning_type IN ('discovery', 'negative')),
+      intent TEXT NOT NULL,
+      page_url TEXT,
+      file_path TEXT,
+      title TEXT,
+      note TEXT,
+      search_terms_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_routing_learnings_source_type
+      ON routing_learnings(source_id, learning_type, updated_at);
+
+    CREATE INDEX IF NOT EXISTS idx_routing_learnings_intent
+      ON routing_learnings(intent, updated_at);
+
     CREATE TABLE IF NOT EXISTS daemon_state (
       singleton_id INTEGER PRIMARY KEY CHECK(singleton_id = 1),
       last_started_at TEXT,
@@ -926,6 +957,15 @@ function normalizeQuery(query) {
   const words = query.replace(/[^\p{L}\p{N}]+/gu, " ").split(/\s+/).map((part) => part.trim()).filter(Boolean);
   return words.join(" ");
 }
+function buildRouteKey(input) {
+  return sha256(stableStringify({
+    sourceId: input.sourceId,
+    learningType: input.learningType,
+    intent: normalizeQuery(input.intent).toLowerCase(),
+    pageUrl: input.pageUrl ?? null,
+    filePath: input.filePath ?? null
+  }));
+}
 function normalizePatternFilters(patterns) {
   if (!patterns || patterns.length === 0) {
     return null;
@@ -1297,6 +1337,62 @@ function openCatalog(options) {
       }
       return JSON.parse(row.spec_json);
     },
+    getSourceById(sourceId) {
+      return this.listSources().find((source) => source.id === sourceId) ?? null;
+    },
+    upsertSourceContext(sourceId, context) {
+      const source = this.getSourceById(sourceId);
+      if (!source) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.sourceNotFound,
+          `Unknown source '${sourceId}'`
+        );
+      }
+      const timestamp = nowIso();
+      const existing = db.prepare(`
+        SELECT created_at
+        FROM source_context
+        WHERE source_id = ?
+      `).get(sourceId);
+      db.prepare(`
+        INSERT INTO source_context (source_id, context_json, created_at, updated_at)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT(source_id) DO UPDATE SET
+          context_json = excluded.context_json,
+          updated_at = excluded.updated_at
+      `).run(
+        sourceId,
+        JSON.stringify(context),
+        existing?.created_at ?? timestamp,
+        timestamp
+      );
+      return {
+        sourceId,
+        context,
+        createdAt: existing?.created_at ?? timestamp,
+        updatedAt: timestamp
+      };
+    },
+    getSourceContext(sourceId) {
+      const source = this.getSourceById(sourceId);
+      if (!source) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.sourceNotFound,
+          `Unknown source '${sourceId}'`
+        );
+      }
+      const row = db.prepare(`
+        SELECT context_json, created_at, updated_at
+        FROM source_context
+        WHERE source_id = ?
+      `).get(sourceId);
+      return {
+        sourceId,
+        context: row ? JSON.parse(row.context_json) : null,
+        createdAt: row?.created_at ?? null,
+        updatedAt: row?.updated_at ?? null
+      };
+    },
     listSources() {
       const rows = db.prepare(`
         SELECT
@@ -1335,6 +1431,280 @@ function openCatalog(options) {
         };
       });
     },
+    listPages(input) {
+      const source = this.getSourceById(input.sourceId);
+      if (!source) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.sourceNotFound,
+          `Unknown source '${input.sourceId}'`
+        );
+      }
+      const snapshotId = input.snapshotId ?? source.lastSuccessfulSnapshotId;
+      if (!snapshotId) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.snapshotNotFound,
+          `No successful snapshot found for source '${input.sourceId}'`
+        );
+      }
+      const snapshotRow = db.prepare(`
+        SELECT id
+        FROM snapshots
+        WHERE id = ?
+          AND source_id = ?
+      `).get(snapshotId, input.sourceId);
+      if (!snapshotRow) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.snapshotNotFound,
+          `Snapshot '${snapshotId}' not found for source '${input.sourceId}'`
+        );
+      }
+      const normalizedQuery = input.query ? normalizeQuery(input.query).toLowerCase() : "";
+      const pathPatterns = normalizePatternFilters(input.pathPatterns);
+      const limit = assertPaginationValue(input.limit, "limit", 50);
+      const offset = assertPaginationValue(input.offset, "offset", 0);
+      const whereSql = [
+        "snapshot_id = ?"
+      ];
+      const args = [snapshotId];
+      if (normalizedQuery) {
+        whereSql.push("(LOWER(title) LIKE ? OR LOWER(url) LIKE ? OR LOWER(COALESCE(file_path, '')) LIKE ?)");
+        const queryLike = `%${normalizedQuery}%`;
+        args.push(queryLike, queryLike, queryLike);
+      }
+      if (pathPatterns && pathPatterns.length > 0) {
+        whereSql.push(`file_path IS NOT NULL AND (${pathPatterns.map(() => "file_path GLOB ?").join(" OR ")})`);
+        args.push(...pathPatterns.map((pattern) => toSqliteGlob(pattern)));
+      }
+      const whereClause = whereSql.join(" AND ");
+      const totalRow = db.prepare(`
+        SELECT COUNT(*) AS total
+        FROM pages
+        WHERE ${whereClause}
+      `).get(...args);
+      const rows = db.prepare(`
+        SELECT url, title, markdown, page_kind, file_path, language
+        FROM pages
+        WHERE ${whereClause}
+        ORDER BY title, url
+        LIMIT ?
+        OFFSET ?
+      `).all(...args, limit, offset);
+      return {
+        sourceId: input.sourceId,
+        snapshotId,
+        total: totalRow.total,
+        limit,
+        offset,
+        hasMore: offset + rows.length < totalRow.total,
+        pages: rows.map((row) => ({
+          url: row.url,
+          title: row.title,
+          pageKind: row.page_kind,
+          filePath: row.file_path,
+          language: row.language,
+          markdownLength: row.markdown.length
+        }))
+      };
+    },
+    getPage(input) {
+      const source = this.getSourceById(input.sourceId);
+      if (!source) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.sourceNotFound,
+          `Unknown source '${input.sourceId}'`
+        );
+      }
+      if (!input.url && !input.filePath || input.url && input.filePath) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.invalidArgument,
+          "Provide exactly one of url or filePath"
+        );
+      }
+      const snapshotId = input.snapshotId ?? source.lastSuccessfulSnapshotId;
+      if (!snapshotId) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.snapshotNotFound,
+          `No successful snapshot found for source '${input.sourceId}'`
+        );
+      }
+      const row = db.prepare(`
+        SELECT p.snapshot_id, p.url, p.title, p.markdown, p.page_kind, p.file_path, p.language
+        FROM pages p
+        INNER JOIN snapshots s
+          ON s.id = p.snapshot_id
+        WHERE p.snapshot_id = ?
+          AND s.source_id = ?
+          AND ${input.url ? "p.url = ?" : "p.file_path = ?"}
+        LIMIT 1
+      `).get(snapshotId, input.sourceId, input.url ?? input.filePath);
+      if (!row) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.pageNotFound,
+          input.url ? `Page '${input.url}' not found for source '${input.sourceId}'` : `Page path '${input.filePath}' not found for source '${input.sourceId}'`
+        );
+      }
+      return {
+        sourceId: input.sourceId,
+        snapshotId,
+        page: {
+          url: row.url,
+          title: row.title,
+          markdown: row.markdown,
+          pageKind: row.page_kind,
+          filePath: row.file_path,
+          language: row.language
+        }
+      };
+    },
+    upsertRoutingLearning(input) {
+      const source = this.getSourceById(input.sourceId);
+      if (!source) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.sourceNotFound,
+          `Unknown source '${input.sourceId}'`
+        );
+      }
+      const timestamp = nowIso();
+      const routeKey = buildRouteKey(input);
+      const searchTerms = [...new Set((input.searchTerms ?? []).map((term) => term.trim()).filter(Boolean))];
+      const validationSnapshotId = input.snapshotId ?? source.lastSuccessfulSnapshotId ?? null;
+      const storedSnapshotId = input.snapshotId ?? null;
+      const hasTargetPage = Boolean(input.pageUrl || input.filePath);
+      if (input.snapshotId) {
+        const snapshotRow = db.prepare(`
+          SELECT id
+          FROM snapshots
+          WHERE id = ?
+            AND source_id = ?
+        `).get(input.snapshotId, input.sourceId);
+        if (!snapshotRow) {
+          throw new AiocsError(
+            AIOCS_ERROR_CODES.snapshotNotFound,
+            `Snapshot '${input.snapshotId}' not found for source '${input.sourceId}'`
+          );
+        }
+      }
+      if (hasTargetPage) {
+        if (!validationSnapshotId) {
+          throw new AiocsError(
+            AIOCS_ERROR_CODES.snapshotNotFound,
+            `No successful snapshot found for source '${input.sourceId}'`
+          );
+        }
+        this.getPage({
+          sourceId: input.sourceId,
+          snapshotId: validationSnapshotId,
+          ...input.pageUrl ? { url: input.pageUrl } : input.filePath ? { filePath: input.filePath } : {}
+        });
+      }
+      const existing = db.prepare(`
+        SELECT id, created_at
+        FROM routing_learnings
+        WHERE route_key = ?
+      `).get(routeKey);
+      const learningId = existing?.id ?? randomUUID();
+      db.prepare(`
+        INSERT INTO routing_learnings (
+          id,
+          route_key,
+          source_id,
+          snapshot_id,
+          learning_type,
+          intent,
+          page_url,
+          file_path,
+          title,
+          note,
+          search_terms_json,
+          created_at,
+          updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(route_key) DO UPDATE SET
+          snapshot_id = excluded.snapshot_id,
+          title = excluded.title,
+          note = excluded.note,
+          search_terms_json = excluded.search_terms_json,
+          updated_at = excluded.updated_at
+      `).run(
+        learningId,
+        routeKey,
+        input.sourceId,
+        storedSnapshotId,
+        input.learningType,
+        input.intent.trim(),
+        input.pageUrl ?? null,
+        input.filePath ?? null,
+        input.title ?? null,
+        input.note ?? null,
+        JSON.stringify(searchTerms),
+        existing?.created_at ?? timestamp,
+        timestamp
+      );
+      return {
+        learningId,
+        sourceId: input.sourceId,
+        snapshotId: storedSnapshotId,
+        learningType: input.learningType,
+        intent: input.intent.trim(),
+        pageUrl: input.pageUrl ?? null,
+        filePath: input.filePath ?? null,
+        title: input.title ?? null,
+        note: input.note ?? null,
+        searchTerms,
+        createdAt: existing?.created_at ?? timestamp,
+        updatedAt: timestamp
+      };
+    },
+    listRoutingLearnings(input) {
+      const whereSql = [];
+      const args = [];
+      if (input?.sourceId) {
+        whereSql.push("source_id = ?");
+        args.push(input.sourceId);
+      }
+      if (input?.learningType) {
+        whereSql.push("learning_type = ?");
+        args.push(input.learningType);
+      }
+      if (input?.intentQuery) {
+        whereSql.push("LOWER(intent) LIKE ?");
+        args.push(`%${normalizeQuery(input.intentQuery).toLowerCase()}%`);
+      }
+      const limit = assertPaginationValue(input?.limit, "limit", 50);
+      const rows = db.prepare(`
+        SELECT
+          id,
+          source_id,
+          snapshot_id,
+          learning_type,
+          intent,
+          page_url,
+          file_path,
+          title,
+          note,
+          search_terms_json,
+          created_at,
+          updated_at
+        FROM routing_learnings
+        ${whereSql.length > 0 ? `WHERE ${whereSql.join(" AND ")}` : ""}
+        ORDER BY updated_at DESC, source_id, intent
+        LIMIT ?
+      `).all(...args, limit);
+      return rows.map((row) => ({
+        learningId: row.id,
+        sourceId: row.source_id,
+        snapshotId: row.snapshot_id,
+        learningType: row.learning_type,
+        intent: row.intent,
+        pageUrl: row.page_url,
+        filePath: row.file_path,
+        title: row.title,
+        note: row.note,
+        searchTerms: JSON.parse(row.search_terms_json),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at
+      }));
+    },
     listDueSourceIds(referenceTime = nowIso()) {
       const rows = db.prepare(`
         SELECT id
@@ -3997,7 +4367,7 @@ async function startDaemon(input) {
 // package.json
 var package_default = {
   name: "@bodhi-ventures/aiocs",
-  version: "0.5.3",
+  version: "0.6.0",
   license: "MIT",
   type: "module",
   description: "Local-only documentation store, fetcher, and search CLI for AI agents.",
@@ -5052,7 +5422,121 @@ async function searchHybridCatalog(input) {
   };
 }
 
+// src/retrieval.ts
+function tokenize(value) {
+  return value.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").split(/\s+/).map((part) => part.trim()).filter(Boolean);
+}
+function overlapScore(queryTokens, candidate) {
+  const candidateTokens = new Set(tokenize(candidate));
+  if (candidateTokens.size === 0) {
+    return 0;
+  }
+  let matches = 0;
+  for (const token of queryTokens) {
+    if (candidateTokens.has(token)) {
+      matches += 1;
+    }
+  }
+  return matches;
+}
+function scoreLearning(query, learning) {
+  const queryTokens = tokenize(query);
+  const candidates = [learning.intent, ...learning.searchTerms];
+  const bestOverlap = Math.max(0, ...candidates.map((candidate) => overlapScore(queryTokens, candidate)));
+  const exactIntentBoost = learning.intent.trim().toLowerCase() === query.trim().toLowerCase() ? 10 : 0;
+  const recencyBoost = learning.learningType === "discovery" ? 1 : 0;
+  return bestOverlap + exactIntentBoost + recencyBoost;
+}
+function scoreSourceContext(query, context) {
+  if (!context) {
+    return 0;
+  }
+  const queryTokens = tokenize(query);
+  const candidates = [
+    context.purpose ?? "",
+    context.summary ?? "",
+    ...context.topicHints,
+    ...context.gotchas,
+    ...context.authNotes,
+    ...context.commonLocations.flatMap((location) => [location.label, location.note ?? "", location.url ?? "", location.filePath ?? ""])
+  ];
+  return Math.max(0, ...candidates.map((candidate) => overlapScore(queryTokens, candidate)));
+}
+
+// src/source-context.ts
+import { readFile as readFile4 } from "fs/promises";
+import { extname as extname3 } from "path";
+import YAML2 from "yaml";
+import { z as z2 } from "zod";
+var commonLocationSchema = z2.object({
+  label: z2.string().min(1),
+  url: z2.string().url().optional(),
+  filePath: z2.string().min(1).optional(),
+  note: z2.string().min(1).optional()
+}).superRefine((value, context) => {
+  if (!value.url && !value.filePath) {
+    context.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: "common location entries must include url or filePath",
+      path: ["url"]
+    });
+  }
+});
+var sourceContextSchema = z2.object({
+  purpose: z2.string().min(1).optional(),
+  summary: z2.string().min(1).optional(),
+  topicHints: z2.array(z2.string().min(1)).default([]),
+  commonLocations: z2.array(commonLocationSchema).default([]),
+  gotchas: z2.array(z2.string().min(1)).default([]),
+  authNotes: z2.array(z2.string().min(1)).default([])
+});
+function parseSourceContext(raw, extension) {
+  if (extension === ".json") {
+    return JSON.parse(raw);
+  }
+  return YAML2.parse(raw);
+}
+async function loadSourceContextFile(path) {
+  try {
+    const raw = await readFile4(path, "utf8");
+    return sourceContextSchema.parse(parseSourceContext(raw, extname3(path).toLowerCase()));
+  } catch (error) {
+    if (error instanceof z2.ZodError) {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.sourceContextInvalid,
+        `Invalid source context file '${path}'`,
+        {
+          issues: error.issues.map((issue) => ({
+            path: issue.path.join("."),
+            message: issue.message
+          }))
+        }
+      );
+    }
+    if (error instanceof Error) {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.sourceContextInvalid,
+        `Failed to load source context file '${path}': ${error.message}`
+      );
+    }
+    throw error;
+  }
+}
+
 // src/services.ts
+function dedupePagesByIdentity(rows) {
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const row of rows) {
+    const key = `${row.sourceId}::${row.snapshotId}::${row.filePath ?? row.pageUrl}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduped.push(row);
+  }
+  return deduped;
+}
 function createCatalog() {
   const dataDir = getAiocsDataDir();
   getAiocsConfigDir();
@@ -5079,6 +5563,70 @@ async function listSources() {
   const sources = await withCatalog(({ catalog }) => catalog.listSources());
   return { sources };
 }
+async function describeSource(sourceId) {
+  return withCatalog(({ catalog }) => {
+    const source = catalog.getSourceById(sourceId);
+    if (!source) {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.sourceNotFound,
+        `Unknown source '${sourceId}'`
+      );
+    }
+    const latestSnapshot = catalog.listSnapshots(sourceId)[0] ?? null;
+    return {
+      source,
+      context: catalog.getSourceContext(sourceId),
+      latestSnapshot,
+      recentLearnings: catalog.listRoutingLearnings({
+        sourceId,
+        limit: 10
+      })
+    };
+  });
+}
+async function upsertSourceContextFromFile(sourceId, contextFile) {
+  const resolvedContextFile = resolve8(contextFile);
+  const context = await loadSourceContextFile(resolvedContextFile);
+  const result = await withCatalog(({ catalog }) => catalog.upsertSourceContext(sourceId, context));
+  return {
+    ...result,
+    contextFile: resolvedContextFile
+  };
+}
+async function getSourceContextForSource(sourceId) {
+  return withCatalog(({ catalog }) => catalog.getSourceContext(sourceId));
+}
+async function listSourcePages(sourceId, options) {
+  return withCatalog(({ catalog }) => catalog.listPages({
+    sourceId,
+    ...options.snapshot ? { snapshotId: options.snapshot } : {},
+    ...options.query ? { query: options.query } : {},
+    ...options.path && options.path.length > 0 ? { pathPatterns: options.path } : {},
+    ...typeof options.limit === "number" ? { limit: options.limit } : {},
+    ...typeof options.offset === "number" ? { offset: options.offset } : {}
+  }));
+}
+async function showPage(input) {
+  return withCatalog(({ catalog }) => catalog.getPage(input));
+}
+async function saveRoutingLearning(input) {
+  const learning = await withCatalog(({ catalog }) => catalog.upsertRoutingLearning({
+    sourceId: input.sourceId,
+    ...input.snapshotId ? { snapshotId: input.snapshotId } : {},
+    learningType: input.learningType,
+    intent: input.intent,
+    ...input.pageUrl ? { pageUrl: input.pageUrl } : {},
+    ...input.filePath ? { filePath: input.filePath } : {},
+    ...input.title ? { title: input.title } : {},
+    ...input.note ? { note: input.note } : {},
+    ...input.searchTerms ? { searchTerms: input.searchTerms } : {}
+  }));
+  return { learning };
+}
+async function listRoutingLearningsForQuery(input) {
+  const learnings = await withCatalog(({ catalog }) => catalog.listRoutingLearnings(input));
+  return { learnings };
+}
 async function fetchSources(sourceIdOrAll) {
   const results = await withCatalog(async ({ catalog, dataDir }) => {
     const sourceIds = sourceIdOrAll === "all" ? catalog.listSources().map((item) => item.id) : [sourceIdOrAll];
@@ -5222,6 +5770,125 @@ async function searchCatalog(query, options) {
     results: results.results
   };
 }
+async function retrieveContext(query, options) {
+  const cwd = options.project ? resolve8(options.project) : process.cwd();
+  const explicitSources = options.source.length > 0;
+  const pageLimit = typeof options.pageLimit === "number" ? options.pageLimit : 3;
+  return withCatalog(async ({ catalog }) => {
+    const hybridConfig = getHybridRuntimeConfig();
+    const scope = resolveProjectScope(cwd, catalog.listProjectLinks());
+    if (!explicitSources && !options.all && !scope) {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.noProjectScope,
+        "No linked project scope found. Use --source or --all."
+      );
+    }
+    const sourceScope = explicitSources ? options.source : options.all ? catalog.listSources().map((source) => source.id) : scope?.sourceIds ?? [];
+    const learnings = catalog.listRoutingLearnings({
+      limit: 100
+    }).filter((learning) => sourceScope.length === 0 || sourceScope.includes(learning.sourceId));
+    const scoredLearnings = learnings.map((learning) => ({
+      ...learning,
+      score: scoreLearning(query, learning)
+    })).filter((learning) => learning.score > 0).sort((left, right) => right.score - left.score || right.updatedAt.localeCompare(left.updatedAt));
+    const matchedLearnings = scoredLearnings.filter((learning) => learning.learningType === "discovery");
+    const avoidedLearnings = scoredLearnings.filter((learning) => learning.learningType === "negative");
+    const avoidedPageKeys = new Set(
+      avoidedLearnings.map((learning) => `${learning.sourceId}::${learning.filePath ?? learning.pageUrl ?? ""}`)
+    );
+    const sourceHints = sourceScope.map((sourceId) => {
+      const contextRecord = catalog.getSourceContext(sourceId);
+      const score = scoreSourceContext(query, contextRecord.context);
+      if (!contextRecord.context || score <= 0) {
+        return null;
+      }
+      const matchedCommonLocations = contextRecord.context.commonLocations.filter(
+        (location) => scoreSourceContext(query, {
+          purpose: "",
+          summary: "",
+          topicHints: [],
+          commonLocations: [location],
+          gotchas: [],
+          authNotes: []
+        }) > 0
+      );
+      return {
+        sourceId,
+        score,
+        context: contextRecord.context,
+        matchedCommonLocations
+      };
+    }).filter((entry) => Boolean(entry)).sort((left, right) => right.score - left.score || left.sourceId.localeCompare(right.sourceId));
+    const search = await searchHybridCatalog({
+      catalog,
+      config: hybridConfig,
+      query,
+      mode: options.mode ?? hybridConfig.defaultSearchMode,
+      searchInput: {
+        cwd,
+        ...explicitSources ? { sourceIds: options.source } : {},
+        ...options.snapshot ? { snapshotId: options.snapshot } : {},
+        ...options.all ? { all: true } : {},
+        ...options.path && options.path.length > 0 ? { pathPatterns: options.path } : {},
+        ...options.language && options.language.length > 0 ? { languages: options.language } : {},
+        ...typeof options.limit === "number" ? { limit: options.limit } : {},
+        ...typeof options.offset === "number" ? { offset: options.offset } : {}
+      }
+    });
+    const learnedPages = matchedLearnings.filter((learning) => learning.pageUrl || learning.filePath).map((learning) => ({
+      sourceId: learning.sourceId,
+      snapshotId: learning.snapshotId ?? catalog.getSourceById(learning.sourceId)?.lastSuccessfulSnapshotId ?? "",
+      pageUrl: learning.pageUrl ?? "",
+      filePath: learning.filePath ?? null
+    })).filter((entry) => entry.snapshotId);
+    const searchedPages = search.results.filter((result) => !avoidedPageKeys.has(`${result.sourceId}::${result.filePath ?? result.pageUrl}`)).map((result) => ({
+      sourceId: result.sourceId,
+      snapshotId: result.snapshotId,
+      pageUrl: result.pageUrl,
+      filePath: result.filePath
+    }));
+    const selectedPages = dedupePagesByIdentity([
+      ...learnedPages,
+      ...searchedPages
+    ]).slice(0, Math.max(1, pageLimit));
+    const pages = selectedPages.flatMap((entry) => {
+      try {
+        const page = catalog.getPage({
+          sourceId: entry.sourceId,
+          snapshotId: entry.snapshotId,
+          ...entry.filePath ? { filePath: entry.filePath } : { url: entry.pageUrl }
+        });
+        return [{
+          sourceId: page.sourceId,
+          snapshotId: page.snapshotId,
+          ...page.page
+        }];
+      } catch (error) {
+        if (error instanceof AiocsError && (error.code === AIOCS_ERROR_CODES.pageNotFound || error.code === AIOCS_ERROR_CODES.snapshotNotFound)) {
+          return [];
+        }
+        throw error;
+      }
+    });
+    return {
+      query,
+      modeRequested: search.modeRequested,
+      modeUsed: search.modeUsed,
+      sourceScope,
+      sourceHints,
+      matchedLearnings,
+      avoidedLearnings,
+      search: {
+        total: search.total,
+        limit: search.limit,
+        offset: search.offset,
+        hasMore: search.hasMore,
+        results: search.results
+      },
+      pages
+    };
+  });
+}
 async function showChunk(chunkId) {
   const chunk = await withCatalog(({ catalog }) => catalog.getChunkById(chunkId));
   if (!chunk) {
@@ -5361,6 +6028,13 @@ export {
   packageDescription,
   upsertSourceFromSpecFile,
   listSources,
+  describeSource,
+  upsertSourceContextFromFile,
+  getSourceContextForSource,
+  listSourcePages,
+  showPage,
+  saveRoutingLearning,
+  listRoutingLearningsForQuery,
   fetchSources,
   refreshDueSources,
   runSourceCanaries,
@@ -5369,6 +6043,7 @@ export {
   linkProjectSources,
   unlinkProjectSources,
   searchCatalog,
+  retrieveContext,
   showChunk,
   verifyCoverage,
   initManagedSources,