@bodhi-ventures/aiocs 0.1.0

package/dist/chunk-ID3PUSMY.js

@@ -0,0 +1,4535 @@
+// src/errors.ts
+var AIOCS_ERROR_CODES = {
+  invalidArgument: "INVALID_ARGUMENT",
+  sourceNotFound: "SOURCE_NOT_FOUND",
+  snapshotNotFound: "SNAPSHOT_NOT_FOUND",
+  snapshotDiffBaseNotFound: "SNAPSHOT_DIFF_BASE_NOT_FOUND",
+  noPagesFetched: "NO_PAGES_FETCHED",
+  noProjectScope: "NO_PROJECT_SCOPE",
+  chunkNotFound: "CHUNK_NOT_FOUND",
+  referenceFileNotFound: "REFERENCE_FILE_NOT_FOUND",
+  invalidReferenceFile: "INVALID_REFERENCE_FILE",
+  authEnvMissing: "AUTH_ENV_MISSING",
+  canaryFailed: "CANARY_FAILED",
+  backupConflict: "BACKUP_CONFLICT",
+  backupInvalid: "BACKUP_INVALID",
+  backupSourceMissing: "BACKUP_SOURCE_MISSING",
+  embeddingConfigInvalid: "EMBEDDING_CONFIG_INVALID",
+  embeddingProviderUnavailable: "EMBEDDING_PROVIDER_UNAVAILABLE",
+  vectorStoreUnavailable: "VECTOR_STORE_UNAVAILABLE",
+  embeddingJobNotFound: "EMBEDDING_JOB_NOT_FOUND",
+  internalError: "INTERNAL_ERROR"
+};
+var AiocsError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.name = "AiocsError";
+    this.code = code;
+    this.details = details;
+  }
+};
+function isAiocsError(error) {
+  return error instanceof AiocsError;
+}
+function toAiocsError(error) {
+  if (isAiocsError(error)) {
+    return error;
+  }
+  if (error instanceof Error) {
+    return new AiocsError(AIOCS_ERROR_CODES.internalError, error.message);
+  }
+  return new AiocsError(AIOCS_ERROR_CODES.internalError, String(error));
+}
+
+// src/catalog/catalog.ts
+import { mkdirSync } from "fs";
+import { join, resolve as resolve2 } from "path";
+import { randomUUID } from "crypto";
+import Database from "better-sqlite3";
+
+// src/catalog/chunking.ts
+var MAX_CHUNK_BYTES = 16384;
+var HEADING_PATTERN = /^(#{1,6})\s+(.*)$/;
+function byteLength(value) {
+  return Buffer.byteLength(value, "utf8");
+}
+function splitLargeSection(sectionTitle, markdown, startOrder) {
+  const lines = markdown.split("\n");
+  const chunks = [];
+  let current = "";
+  let order = startOrder;
+  const flush = () => {
+    const trimmed = current.trim();
+    if (!trimmed) {
+      current = "";
+      return;
+    }
+    chunks.push({
+      sectionTitle,
+      markdown: trimmed,
+      chunkOrder: order
+    });
+    order += 1;
+    current = "";
+  };
+  for (const line of lines) {
+    const next = current ? `${current}
+${line}` : line;
+    if (current && byteLength(next) > MAX_CHUNK_BYTES) {
+      flush();
+    }
+    current = current ? `${current}
+${line}` : line;
+  }
+  flush();
+  return chunks;
+}
+function chunkMarkdown(pageTitle, markdown) {
+  const trimmed = markdown.trim();
+  if (!trimmed) {
+    return [];
+  }
+  if (byteLength(trimmed) <= MAX_CHUNK_BYTES) {
+    return [{ sectionTitle: pageTitle, markdown: trimmed, chunkOrder: 0 }];
+  }
+  const lines = trimmed.split("\n");
+  const sections = [];
+  let currentTitle = pageTitle;
+  let currentLines = [];
+  const flushSection = () => {
+    const content = currentLines.join("\n").trim();
+    if (!content) {
+      currentLines = [];
+      return;
+    }
+    sections.push({ title: currentTitle, markdown: content });
+    currentLines = [];
+  };
+  for (const line of lines) {
+    const match = line.trim().match(HEADING_PATTERN);
+    if (match && match[1].length >= 2) {
+      flushSection();
+      currentTitle = match[2].trim() || pageTitle;
+    }
+    currentLines.push(line);
+  }
+  flushSection();
+  const chunks = [];
+  let order = 0;
+  for (const section of sections) {
+    if (byteLength(section.markdown) <= MAX_CHUNK_BYTES) {
+      chunks.push({
+        sectionTitle: section.title,
+        markdown: section.markdown,
+        chunkOrder: order
+      });
+      order += 1;
+      continue;
+    }
+    const split = splitLargeSection(section.title, section.markdown, order);
+    chunks.push(...split);
+    order = chunks.length;
+  }
+  return chunks;
+}
+
+// src/catalog/fingerprint.ts
+import { createHash } from "crypto";
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function buildSnapshotFingerprint(input) {
+  const normalizedPages = [...input.pages].sort((left, right) => left.url.localeCompare(right.url));
+  const payload = JSON.stringify({
+    sourceId: input.sourceId,
+    configHash: input.configHash,
+    pages: normalizedPages
+  });
+  return sha256(payload);
+}
+
+// src/catalog/project-scope.ts
+import { realpathSync } from "fs";
+import { resolve } from "path";
+function isWithin(candidate, root) {
+  return candidate === root || candidate.startsWith(`${root}/`);
+}
+function canonicalizeProjectPath(path) {
+  const resolved = resolve(path);
+  try {
+    return realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
+}
+function resolveProjectScope(cwd, scopes) {
+  const normalizedCwd = canonicalizeProjectPath(cwd);
+  const normalizedScopes = scopes.map((scope) => ({
+    projectPath: canonicalizeProjectPath(scope.projectPath),
+    sourceIds: [...scope.sourceIds]
+  })).filter((scope) => isWithin(normalizedCwd, scope.projectPath)).sort((left, right) => right.projectPath.length - left.projectPath.length);
+  return normalizedScopes[0] ?? null;
+}
+
+// src/spec/source-spec.ts
+import { readFile } from "fs/promises";
+import { extname } from "path";
+import YAML from "yaml";
+import { z } from "zod";
+var patternSchema = z.string().min(1);
+var interactionSchema = z.discriminatedUnion("action", [
+  z.object({
+    action: z.literal("hover"),
+    selector: z.string().min(1),
+    timeoutMs: z.number().int().positive().optional()
+  }),
+  z.object({
+    action: z.literal("click"),
+    selector: z.string().min(1),
+    timeoutMs: z.number().int().positive().optional()
+  }),
+  z.object({
+    action: z.literal("press"),
+    key: z.string().min(1)
+  }),
+  z.object({
+    action: z.literal("wait"),
+    timeoutMs: z.number().int().positive()
+  })
+]);
+var clipboardExtractSchema = z.object({
+  strategy: z.literal("clipboardButton"),
+  interactions: z.array(interactionSchema).min(1),
+  clipboardTimeoutMs: z.number().int().positive().default(1e4)
+});
+var selectorExtractSchema = z.object({
+  strategy: z.literal("selector"),
+  selector: z.string().min(1)
+});
+var readabilityExtractSchema = z.object({
+  strategy: z.literal("readability")
+});
+var authHeaderSchema = z.object({
+  name: z.string().min(1),
+  valueFromEnv: z.string().min(1),
+  hosts: z.array(z.string().min(1)).min(1).optional(),
+  include: z.array(patternSchema).min(1).optional()
+});
+var authCookieSchema = z.object({
+  name: z.string().min(1),
+  valueFromEnv: z.string().min(1),
+  domain: z.string().min(1),
+  path: z.string().min(1).default("/"),
+  secure: z.boolean().optional(),
+  httpOnly: z.boolean().optional(),
+  sameSite: z.enum(["Strict", "Lax", "None"]).optional()
+});
+var canaryCheckSchema = z.object({
+  url: z.string().url(),
+  expectedTitle: z.string().min(1).optional(),
+  expectedText: z.string().min(1).optional(),
+  minMarkdownLength: z.number().int().positive().default(40)
+});
+var sourceSpecSchema = z.object({
+  id: z.string().min(1).regex(/^[a-z0-9-]+$/),
+  label: z.string().min(1),
+  startUrls: z.array(z.string().url()).min(1),
+  allowedHosts: z.array(z.string().min(1)).min(1),
+  discovery: z.object({
+    include: z.array(patternSchema).min(1),
+    exclude: z.array(patternSchema),
+    maxPages: z.number().int().positive()
+  }),
+  extract: z.discriminatedUnion("strategy", [
+    clipboardExtractSchema,
+    selectorExtractSchema,
+    readabilityExtractSchema
+  ]),
+  normalize: z.object({
+    prependSourceComment: z.boolean().default(true)
+  }),
+  schedule: z.object({
+    everyHours: z.number().int().positive()
+  }),
+  auth: z.object({
+    headers: z.array(authHeaderSchema).default([]),
+    cookies: z.array(authCookieSchema).default([])
+  }).optional(),
+  canary: z.object({
+    everyHours: z.number().int().positive().optional(),
+    checks: z.array(canaryCheckSchema).min(1)
+  }).optional()
+}).superRefine((spec, context) => {
+  for (const [index, header] of (spec.auth?.headers ?? []).entries()) {
+    if (!header.hosts) {
+      continue;
+    }
+    for (const host of header.hosts) {
+      if (!spec.allowedHosts.includes(host)) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["auth", "headers", index, "hosts"],
+          message: `Authenticated header host '${host}' must be included in allowedHosts`
+        });
+      }
+    }
+  }
+});
+function parseSourceSpec(raw, ext) {
+  if (ext === ".json") {
+    return JSON.parse(raw);
+  }
+  return YAML.parse(raw);
+}
+async function loadSourceSpec(path) {
+  const raw = await readFile(path, "utf8");
+  const parsed = parseSourceSpec(raw, extname(path).toLowerCase());
+  return sourceSpecSchema.parse(parsed);
+}
+function resolveSourceCanary(spec) {
+  return {
+    everyHours: spec.canary?.everyHours ?? Math.max(1, Math.min(spec.schedule.everyHours, 6)),
+    checks: spec.canary?.checks ?? [
+      {
+        url: spec.startUrls[0],
+        minMarkdownLength: 40
+      }
+    ]
+  };
+}
+
+// src/catalog/catalog.ts
+function initSchema(db) {
+  db.exec(`
+    PRAGMA foreign_keys = ON;
+
+    CREATE TABLE IF NOT EXISTS sources (
+      id TEXT PRIMARY KEY,
+      label TEXT NOT NULL,
+      spec_json TEXT NOT NULL,
+      spec_path TEXT,
+      config_hash TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      last_checked_at TEXT,
+      last_successful_snapshot_at TEXT,
+      last_successful_snapshot_id TEXT,
+      last_canary_checked_at TEXT,
+      last_successful_canary_at TEXT,
+      last_canary_status TEXT,
+      next_canary_due_at TEXT,
+      next_due_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS snapshots (
+      id TEXT PRIMARY KEY,
+      source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
+      fingerprint TEXT NOT NULL,
+      config_hash TEXT NOT NULL,
+      detected_version TEXT,
+      page_count INTEGER NOT NULL,
+      created_at TEXT NOT NULL,
+      UNIQUE(source_id, fingerprint)
+    );
+
+    CREATE TABLE IF NOT EXISTS pages (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      snapshot_id TEXT NOT NULL REFERENCES snapshots(id) ON DELETE CASCADE,
+      url TEXT NOT NULL,
+      title TEXT NOT NULL,
+      markdown TEXT NOT NULL,
+      content_hash TEXT NOT NULL,
+      UNIQUE(snapshot_id, url)
+    );
+
+    CREATE TABLE IF NOT EXISTS chunks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
+      snapshot_id TEXT NOT NULL REFERENCES snapshots(id) ON DELETE CASCADE,
+      page_id INTEGER NOT NULL REFERENCES pages(id) ON DELETE CASCADE,
+      page_url TEXT NOT NULL,
+      page_title TEXT NOT NULL,
+      section_title TEXT NOT NULL,
+      chunk_order INTEGER NOT NULL,
+      markdown TEXT NOT NULL
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
+      page_title,
+      section_title,
+      markdown,
+      content=chunks,
+      content_rowid=id,
+      tokenize='porter unicode61'
+    );
+
+    CREATE TRIGGER IF NOT EXISTS chunks_ai AFTER INSERT ON chunks BEGIN
+      INSERT INTO chunks_fts(rowid, page_title, section_title, markdown)
+      VALUES (new.id, new.page_title, new.section_title, new.markdown);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS chunks_ad AFTER DELETE ON chunks BEGIN
+      INSERT INTO chunks_fts(chunks_fts, rowid, page_title, section_title, markdown)
+      VALUES ('delete', old.id, old.page_title, old.section_title, old.markdown);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS chunks_au AFTER UPDATE ON chunks BEGIN
+      INSERT INTO chunks_fts(chunks_fts, rowid, page_title, section_title, markdown)
+      VALUES ('delete', old.id, old.page_title, old.section_title, old.markdown);
+      INSERT INTO chunks_fts(rowid, page_title, section_title, markdown)
+      VALUES (new.id, new.page_title, new.section_title, new.markdown);
+    END;
+
+    CREATE TABLE IF NOT EXISTS fetch_runs (
+      id TEXT PRIMARY KEY,
+      source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
+      status TEXT NOT NULL CHECK(status IN ('success', 'failed')),
+      error_message TEXT,
+      snapshot_id TEXT REFERENCES snapshots(id) ON DELETE SET NULL,
+      started_at TEXT NOT NULL,
+      finished_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS canary_runs (
+      id TEXT PRIMARY KEY,
+      source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
+      status TEXT NOT NULL CHECK(status IN ('pass', 'fail')),
+      checked_at TEXT NOT NULL,
+      details_json TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS project_links (
+      project_path TEXT NOT NULL,
+      source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
+      created_at TEXT NOT NULL,
+      PRIMARY KEY(project_path, source_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS daemon_state (
+      singleton_id INTEGER PRIMARY KEY CHECK(singleton_id = 1),
+      last_started_at TEXT,
+      last_cycle_started_at TEXT,
+      last_cycle_completed_at TEXT,
+      last_cycle_status TEXT,
+      interval_minutes INTEGER,
+      fetch_on_start INTEGER
+    );
+
+    CREATE TABLE IF NOT EXISTS embedding_state (
+      chunk_id INTEGER PRIMARY KEY REFERENCES chunks(id) ON DELETE CASCADE,
+      source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
+      snapshot_id TEXT NOT NULL REFERENCES snapshots(id) ON DELETE CASCADE,
+      content_hash TEXT NOT NULL,
+      model_key TEXT,
+      status TEXT NOT NULL CHECK(status IN ('pending', 'indexed', 'failed', 'stale')),
+      vector_point_id TEXT,
+      last_attempted_at TEXT,
+      indexed_at TEXT,
+      error_message TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS embedding_jobs (
+      source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
+      snapshot_id TEXT NOT NULL REFERENCES snapshots(id) ON DELETE CASCADE,
+      status TEXT NOT NULL CHECK(status IN ('pending', 'running', 'succeeded', 'failed')),
+      attempt_count INTEGER NOT NULL DEFAULT 0,
+      chunk_count INTEGER NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      claimed_at TEXT,
+      completed_at TEXT,
+      error_message TEXT,
+      PRIMARY KEY(source_id, snapshot_id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_embedding_jobs_status_updated
+      ON embedding_jobs(status, updated_at, source_id, snapshot_id);
+
+    CREATE INDEX IF NOT EXISTS idx_embedding_state_source_snapshot
+      ON embedding_state(source_id, snapshot_id, status);
+  `);
+  const sourceColumns = db.prepare("PRAGMA table_info(sources)").all();
+  if (!sourceColumns.some((column) => column.name === "spec_path")) {
+    db.exec("ALTER TABLE sources ADD COLUMN spec_path TEXT");
+  }
+  if (!sourceColumns.some((column) => column.name === "last_successful_snapshot_at")) {
+    db.exec("ALTER TABLE sources ADD COLUMN last_successful_snapshot_at TEXT");
+  }
+  if (!sourceColumns.some((column) => column.name === "last_canary_checked_at")) {
+    db.exec("ALTER TABLE sources ADD COLUMN last_canary_checked_at TEXT");
+  }
+  if (!sourceColumns.some((column) => column.name === "last_successful_canary_at")) {
+    db.exec("ALTER TABLE sources ADD COLUMN last_successful_canary_at TEXT");
+  }
+  if (!sourceColumns.some((column) => column.name === "last_canary_status")) {
+    db.exec("ALTER TABLE sources ADD COLUMN last_canary_status TEXT");
+  }
+  if (!sourceColumns.some((column) => column.name === "next_canary_due_at")) {
+    db.exec("ALTER TABLE sources ADD COLUMN next_canary_due_at TEXT");
+  }
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function addHoursIso(hours) {
+  return new Date(Date.now() + hours * 60 * 60 * 1e3).toISOString();
+}
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value).sort(
+      ([left], [right]) => left.localeCompare(right)
+    );
+    return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function normalizeQuery(query) {
+  const words = query.replace(/[^\p{L}\p{N}]+/gu, " ").split(/\s+/).map((part) => part.trim()).filter(Boolean);
+  return words.join(" ");
+}
+function assertPaginationValue(value, field, fallback) {
+  if (typeof value === "undefined") {
+    return fallback;
+  }
+  if (!Number.isInteger(value) || value < 0) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.invalidArgument,
+      `${field} must be a non-negative integer`
+    );
+  }
+  if (field === "limit" && value === 0) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.invalidArgument,
+      "limit must be greater than zero"
+    );
+  }
+  return value;
+}
+function openCatalog(options) {
+  const dataDir = resolve2(options.dataDir);
+  mkdirSync(dataDir, { recursive: true });
+  const db = new Database(join(dataDir, "catalog.sqlite"));
+  initSchema(db);
+  const listProjectLinks = () => {
+    const rows = db.prepare("SELECT project_path, source_id FROM project_links ORDER BY project_path, source_id").all();
+    const grouped = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      const current = grouped.get(row.project_path) ?? [];
+      current.push(row.source_id);
+      grouped.set(row.project_path, current);
+    }
+    return [...grouped.entries()].map(([projectPath, sourceIds]) => ({ projectPath, sourceIds }));
+  };
+  const resolveSearchScope = (input) => {
+    const limit = assertPaginationValue(input.limit, "limit", 20);
+    const offset = assertPaginationValue(input.offset, "offset", 0);
+    let sourceIds = input.sourceIds ? [...input.sourceIds] : void 0;
+    if (!sourceIds || sourceIds.length === 0) {
+      if (input.cwd) {
+        const scope = resolveProjectScope(
+          input.cwd,
+          listProjectLinks().map((link) => ({
+            projectPath: link.projectPath,
+            sourceIds: link.sourceIds
+          }))
+        );
+        if (scope) {
+          sourceIds = scope.sourceIds;
+        }
+      }
+    }
+    if ((!sourceIds || sourceIds.length === 0) && !input.all) {
+      return {
+        limit,
+        offset,
+        sourceIds: null,
+        snapshotIds: []
+      };
+    }
+    const filterSourceIds = sourceIds && sourceIds.length > 0 ? [...new Set(sourceIds)] : null;
+    const latestSnapshotIds = input.snapshotId ? [input.snapshotId] : db.prepare(`
+          SELECT last_successful_snapshot_id AS snapshot_id
+          FROM sources
+          WHERE last_successful_snapshot_id IS NOT NULL
+          ${filterSourceIds ? `AND id IN (${filterSourceIds.map(() => "?").join(",")})` : ""}
+        `).all(...filterSourceIds ?? []).map((row) => row.snapshot_id);
+    return {
+      limit,
+      offset,
+      sourceIds: filterSourceIds,
+      snapshotIds: latestSnapshotIds
+    };
+  };
+  const searchLexicalByScope = (input) => {
+    const normalized = normalizeQuery(input.query);
+    const limit = assertPaginationValue(input.limit, "limit", input.scope.limit);
+    const offset = assertPaginationValue(input.offset, "offset", input.scope.offset);
+    if (!normalized || input.scope.snapshotIds.length === 0) {
+      return {
+        total: 0,
+        limit,
+        offset,
+        hasMore: false,
+        results: []
+      };
+    }
+    const whereSnapshotPlaceholders = input.scope.snapshotIds.map(() => "?").join(",");
+    const sourceSql = input.scope.sourceIds ? `AND c.source_id IN (${input.scope.sourceIds.map(() => "?").join(",")})` : "";
+    const queryArgs = [
+      normalized,
+      ...input.scope.snapshotIds,
+      ...input.scope.sourceIds ?? []
+    ];
+    const totalRow = db.prepare(`
+      SELECT COUNT(*) AS total
+      FROM chunks_fts
+      JOIN chunks c ON c.id = chunks_fts.rowid
+      WHERE chunks_fts MATCH ?
+        AND c.snapshot_id IN (${whereSnapshotPlaceholders})
+        ${sourceSql}
+    `).get(...queryArgs);
+    const rows = db.prepare(`
+      SELECT
+        c.id AS chunk_id,
+        c.source_id,
+        c.snapshot_id,
+        c.page_url,
+        c.page_title,
+        c.section_title,
+        c.markdown
+      FROM chunks_fts
+      JOIN chunks c ON c.id = chunks_fts.rowid
+      WHERE chunks_fts MATCH ?
+        AND c.snapshot_id IN (${whereSnapshotPlaceholders})
+        ${sourceSql}
+      ORDER BY bm25(chunks_fts), c.id
+      LIMIT ?
+      OFFSET ?
+    `).all(...queryArgs, limit, offset);
+    const results = rows.map((row) => ({
+      chunkId: row.chunk_id,
+      sourceId: row.source_id,
+      snapshotId: row.snapshot_id,
+      pageUrl: row.page_url,
+      pageTitle: row.page_title,
+      sectionTitle: row.section_title,
+      markdown: row.markdown
+    }));
+    return {
+      total: totalRow.total,
+      limit,
+      offset,
+      hasMore: offset + results.length < totalRow.total,
+      results
+    };
+  };
+  const listLatestSnapshots = (sourceIds) => {
+    const filterSourceIds = sourceIds && sourceIds.length > 0 ? [...new Set(sourceIds)] : null;
+    const rows = db.prepare(`
+      SELECT id AS source_id, last_successful_snapshot_id AS snapshot_id
+      FROM sources
+      WHERE last_successful_snapshot_id IS NOT NULL
+      ${filterSourceIds ? `AND id IN (${filterSourceIds.map(() => "?").join(",")})` : ""}
+      ORDER BY id
+    `).all(...filterSourceIds ?? []);
+    return rows.map((row) => ({
+      sourceId: row.source_id,
+      snapshotId: row.snapshot_id
+    }));
+  };
+  const queueEmbeddingJobForSnapshot = (sourceId, snapshotId, previousLatestSnapshotId) => {
+    const timestamp = nowIso();
+    if (previousLatestSnapshotId && previousLatestSnapshotId !== snapshotId) {
+      db.prepare(`
+        UPDATE embedding_state
+        SET
+          status = 'stale',
+          vector_point_id = NULL,
+          indexed_at = NULL,
+          error_message = NULL
+        WHERE source_id = ?
+          AND snapshot_id = ?
+      `).run(sourceId, previousLatestSnapshotId);
+      db.prepare(`
+        DELETE FROM embedding_jobs
+        WHERE source_id = ?
+          AND snapshot_id = ?
+      `).run(sourceId, previousLatestSnapshotId);
+    }
+    const chunkRows = db.prepare(`
+      SELECT id, markdown
+      FROM chunks
+      WHERE source_id = ?
+        AND snapshot_id = ?
+      ORDER BY id
+    `).all(sourceId, snapshotId);
+    const upsertState = db.prepare(`
+      INSERT INTO embedding_state (
+        chunk_id,
+        source_id,
+        snapshot_id,
+        content_hash,
+        model_key,
+        status,
+        vector_point_id,
+        last_attempted_at,
+        indexed_at,
+        error_message
+      ) VALUES (?, ?, ?, ?, NULL, 'pending', NULL, NULL, NULL, NULL)
+      ON CONFLICT(chunk_id) DO UPDATE SET
+        source_id = excluded.source_id,
+        snapshot_id = excluded.snapshot_id,
+        content_hash = excluded.content_hash,
+        model_key = CASE
+          WHEN embedding_state.status = 'indexed' AND embedding_state.content_hash = excluded.content_hash
+            THEN embedding_state.model_key
+          ELSE NULL
+        END,
+        status = CASE
+          WHEN embedding_state.status = 'indexed' AND embedding_state.content_hash = excluded.content_hash
+            THEN 'indexed'
+          ELSE 'pending'
+        END,
+        vector_point_id = CASE
+          WHEN embedding_state.status = 'indexed' AND embedding_state.content_hash = excluded.content_hash
+            THEN embedding_state.vector_point_id
+          ELSE NULL
+        END,
+        last_attempted_at = CASE
+          WHEN embedding_state.status = 'indexed' AND embedding_state.content_hash = excluded.content_hash
+            THEN embedding_state.last_attempted_at
+          ELSE NULL
+        END,
+        indexed_at = CASE
+          WHEN embedding_state.status = 'indexed' AND embedding_state.content_hash = excluded.content_hash
+            THEN embedding_state.indexed_at
+          ELSE NULL
+        END,
+        error_message = CASE
+          WHEN embedding_state.status = 'indexed' AND embedding_state.content_hash = excluded.content_hash
+            THEN embedding_state.error_message
+          ELSE NULL
+        END
+    `);
+    const transaction = db.transaction(() => {
+      for (const chunk of chunkRows) {
+        upsertState.run(
+          chunk.id,
+          sourceId,
+          snapshotId,
+          sha256(chunk.markdown)
+        );
+      }
+    });
+    transaction();
+    const pendingRow = db.prepare(`
+      SELECT COUNT(*) AS pending_count
+      FROM embedding_state
+      WHERE source_id = ?
+        AND snapshot_id = ?
+        AND status != 'indexed'
+    `).get(sourceId, snapshotId);
+    if (pendingRow.pending_count === 0) {
+      db.prepare(`
+        INSERT INTO embedding_jobs (
+          source_id,
+          snapshot_id,
+          status,
+          attempt_count,
+          chunk_count,
+          created_at,
+          updated_at,
+          claimed_at,
+          completed_at,
+          error_message
+        ) VALUES (?, ?, 'succeeded', 0, ?, ?, ?, NULL, ?, NULL)
+        ON CONFLICT(source_id, snapshot_id) DO UPDATE SET
+          status = 'succeeded',
+          chunk_count = excluded.chunk_count,
+          updated_at = excluded.updated_at,
+          claimed_at = NULL,
+          completed_at = excluded.completed_at,
+          error_message = NULL
+      `).run(sourceId, snapshotId, chunkRows.length, timestamp, timestamp, timestamp);
+      return;
+    }
+    db.prepare(`
+      INSERT INTO embedding_jobs (
+        source_id,
+        snapshot_id,
+        status,
+        attempt_count,
+        chunk_count,
+        created_at,
+        updated_at,
+        claimed_at,
+        completed_at,
+        error_message
+      ) VALUES (?, ?, 'pending', 0, ?, ?, ?, NULL, NULL, NULL)
+      ON CONFLICT(source_id, snapshot_id) DO UPDATE SET
+        status = 'pending',
+        chunk_count = excluded.chunk_count,
+        updated_at = excluded.updated_at,
+        claimed_at = NULL,
+        completed_at = NULL,
+        error_message = NULL
+    `).run(sourceId, snapshotId, chunkRows.length, timestamp, timestamp);
+  };
+  return {
+    close() {
+      db.close();
+    },
+    upsertSource(spec, options2) {
+      const timestamp = nowIso();
+      const configHash = sha256(stableStringify(spec));
+      const existing = db.prepare("SELECT id, created_at, next_due_at, next_canary_due_at, config_hash FROM sources WHERE id = ?").get(spec.id);
+      const resolvedSpecPath = options2?.specPath ? resolve2(options2.specPath) : null;
+      const nextDueAt = !existing ? timestamp : existing.config_hash === configHash ? existing.next_due_at : timestamp;
+      const canaryConfig = resolveSourceCanary(spec);
+      const nextCanaryDueAt = !existing ? timestamp : existing.config_hash === configHash ? existing.next_canary_due_at ?? addHoursIso(canaryConfig.everyHours) : timestamp;
+      const configChanged = Boolean(existing && existing.config_hash !== configHash);
+      db.prepare(`
+        INSERT INTO sources (
+          id, label, spec_json, spec_path, config_hash, created_at, updated_at, next_due_at, next_canary_due_at
+        ) VALUES (
+          @id, @label, @specJson, @specPath, @configHash, @createdAt, @updatedAt, @nextDueAt, @nextCanaryDueAt
+        )
+        ON CONFLICT(id) DO UPDATE SET
+          label = excluded.label,
+          spec_json = excluded.spec_json,
+          spec_path = excluded.spec_path,
+          config_hash = excluded.config_hash,
+          updated_at = excluded.updated_at,
+          next_due_at = excluded.next_due_at,
+          next_canary_due_at = excluded.next_canary_due_at
+      `).run({
+        id: spec.id,
+        label: spec.label,
+        specJson: JSON.stringify(spec),
+        specPath: resolvedSpecPath,
+        configHash,
+        createdAt: existing?.created_at ?? timestamp,
+        updatedAt: timestamp,
+        nextDueAt,
+        nextCanaryDueAt
+      });
+      return {
+        sourceId: spec.id,
+        configHash,
+        configChanged
+      };
+    },
+    getSourceSpec(sourceId) {
+      const row = db.prepare("SELECT spec_json FROM sources WHERE id = ?").get(sourceId);
+      if (!row) {
+        return null;
+      }
+      return JSON.parse(row.spec_json);
+    },
+    listSources() {
+      const rows = db.prepare(`
+        SELECT
+          id,
+          label,
+          spec_path,
+          next_due_at,
+          next_canary_due_at,
+          last_checked_at,
+          last_successful_snapshot_at,
+          last_successful_snapshot_id,
+          last_canary_checked_at,
+          last_successful_canary_at,
+          last_canary_status
+        FROM sources
+        ORDER BY id
+      `).all();
+      return rows.map((row) => ({
+        id: row.id,
+        label: row.label,
+        specPath: row.spec_path,
+        nextDueAt: row.next_due_at,
+        isDue: Date.parse(row.next_due_at) <= Date.now(),
+        nextCanaryDueAt: row.next_canary_due_at,
+        isCanaryDue: row.next_canary_due_at ? Date.parse(row.next_canary_due_at) <= Date.now() : false,
+        lastCheckedAt: row.last_checked_at,
+        lastSuccessfulSnapshotAt: row.last_successful_snapshot_at,
+        lastSuccessfulSnapshotId: row.last_successful_snapshot_id,
+        lastCanaryCheckedAt: row.last_canary_checked_at,
+        lastSuccessfulCanaryAt: row.last_successful_canary_at,
+        lastCanaryStatus: row.last_canary_status
+      }));
+    },
+    listDueSourceIds(referenceTime = nowIso()) {
+      const rows = db.prepare(`
+        SELECT id
+        FROM sources
+        WHERE next_due_at <= ?
+        ORDER BY next_due_at, id
+      `).all(referenceTime);
+      return rows.map((row) => row.id);
+    },
+    listCanaryDueSourceIds(referenceTime = nowIso()) {
+      const rows = db.prepare(`
+        SELECT id
+        FROM sources
+        WHERE next_canary_due_at IS NOT NULL
+          AND next_canary_due_at <= ?
+        ORDER BY next_canary_due_at, id
+      `).all(referenceTime);
+      return rows.map((row) => row.id);
+    },
+    linkProject(projectPath, sourceIds) {
+      const normalizedPath = canonicalizeProjectPath(projectPath);
+      const timestamp = nowIso();
+      const insert = db.prepare(`
+        INSERT INTO project_links (project_path, source_id, created_at)
+        VALUES (?, ?, ?)
+        ON CONFLICT(project_path, source_id) DO NOTHING
+      `);
+      const transaction = db.transaction((ids) => {
+        for (const sourceId of ids) {
+          insert.run(normalizedPath, sourceId, timestamp);
+        }
+      });
+      transaction(sourceIds);
+    },
+    unlinkProject(projectPath, sourceIds) {
+      const normalizedPath = canonicalizeProjectPath(projectPath);
+      if (!sourceIds || sourceIds.length === 0) {
+        db.prepare("DELETE FROM project_links WHERE project_path = ?").run(normalizedPath);
+        return;
+      }
+      const statement = db.prepare("DELETE FROM project_links WHERE project_path = ? AND source_id = ?");
+      const transaction = db.transaction((ids) => {
+        for (const sourceId of ids) {
+          statement.run(normalizedPath, sourceId);
+        }
+      });
+      transaction(sourceIds);
+    },
+    recordSuccessfulSnapshot(input) {
+      const sourceRow = db.prepare("SELECT config_hash, spec_json, last_successful_snapshot_id FROM sources WHERE id = ?").get(input.sourceId);
+      if (!sourceRow) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.sourceNotFound,
+          `Unknown source '${input.sourceId}'`
+        );
+      }
+      const pagesWithHashes = input.pages.map((page) => ({
+        ...page,
+        markdown: page.markdown.trim(),
+        contentHash: sha256(page.markdown.trim())
+      }));
+      const fingerprint = buildSnapshotFingerprint({
+        sourceId: input.sourceId,
+        configHash: sourceRow.config_hash,
+        pages: pagesWithHashes.map((page) => ({
+          url: page.url,
+          contentHash: page.contentHash
+        }))
+      });
+      const existing = db.prepare("SELECT id FROM snapshots WHERE source_id = ? AND fingerprint = ?").get(input.sourceId, fingerprint);
+      const spec = JSON.parse(sourceRow.spec_json);
+      const checkedAt = nowIso();
+      const nextDueAt = addHoursIso(spec.schedule.everyHours);
+      if (existing) {
+        db.prepare(`
+          UPDATE sources
+          SET last_checked_at = ?, last_successful_snapshot_at = ?, last_successful_snapshot_id = ?, next_due_at = ?, updated_at = ?
+          WHERE id = ?
+        `).run(checkedAt, checkedAt, existing.id, nextDueAt, checkedAt, input.sourceId);
+        queueEmbeddingJobForSnapshot(
+          input.sourceId,
+          existing.id,
+          sourceRow.last_successful_snapshot_id
+        );
+        db.prepare(`
+          INSERT INTO fetch_runs (id, source_id, status, snapshot_id, started_at, finished_at)
+          VALUES (?, ?, 'success', ?, ?, ?)
+        `).run(randomUUID(), input.sourceId, existing.id, checkedAt, checkedAt);
+        return {
+          snapshotId: existing.id,
+          reused: true
+        };
+      }
+      const snapshotId = `snp_${checkedAt.replace(/[-:.TZ]/g, "")}_${fingerprint.slice(0, 12)}`;
+      const insertSnapshot = db.prepare(`
+        INSERT INTO snapshots (
+          id, source_id, fingerprint, config_hash, detected_version, page_count, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      `);
+      const insertPage = db.prepare(`
+        INSERT INTO pages (snapshot_id, url, title, markdown, content_hash)
+        VALUES (?, ?, ?, ?, ?)
+      `);
+      const insertChunk = db.prepare(`
+        INSERT INTO chunks (
+          source_id, snapshot_id, page_id, page_url, page_title, section_title, chunk_order, markdown
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+      const insertRun = db.prepare(`
+        INSERT INTO fetch_runs (id, source_id, status, snapshot_id, started_at, finished_at)
+        VALUES (?, ?, 'success', ?, ?, ?)
+      `);
+      const transaction = db.transaction(() => {
+        insertSnapshot.run(
+          snapshotId,
+          input.sourceId,
+          fingerprint,
+          sourceRow.config_hash,
+          input.detectedVersion ?? null,
+          pagesWithHashes.length,
+          checkedAt
+        );
+        for (const page of pagesWithHashes) {
+          const pageInsert = insertPage.run(snapshotId, page.url, page.title, page.markdown, page.contentHash);
+          const pageId = Number(pageInsert.lastInsertRowid);
+          const chunks = chunkMarkdown(page.title, page.markdown);
+          for (const chunk of chunks) {
+            insertChunk.run(
+              input.sourceId,
+              snapshotId,
+              pageId,
+              page.url,
+              page.title,
+              chunk.sectionTitle,
+              chunk.chunkOrder,
+              chunk.markdown
+            );
+          }
+        }
+        db.prepare(`
+          UPDATE sources
+          SET last_checked_at = ?, last_successful_snapshot_at = ?, last_successful_snapshot_id = ?, next_due_at = ?, updated_at = ?
+          WHERE id = ?
+        `).run(checkedAt, checkedAt, snapshotId, nextDueAt, checkedAt, input.sourceId);
+        queueEmbeddingJobForSnapshot(
+          input.sourceId,
+          snapshotId,
+          sourceRow.last_successful_snapshot_id
+        );
+        insertRun.run(randomUUID(), input.sourceId, snapshotId, checkedAt, checkedAt);
+      });
+      transaction();
+      return {
+        snapshotId,
+        reused: false
+      };
+    },
+    recordFailedFetchRun(input) {
+      const sourceRow = db.prepare("SELECT spec_json FROM sources WHERE id = ?").get(input.sourceId);
+      if (!sourceRow) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.sourceNotFound,
+          `Unknown source '${input.sourceId}'`
+        );
+      }
+      const spec = JSON.parse(sourceRow.spec_json);
+      const timestamp = nowIso();
+      db.prepare(`
+        INSERT INTO fetch_runs (id, source_id, status, error_message, started_at, finished_at)
+        VALUES (?, ?, 'failed', ?, ?, ?)
+      `).run(randomUUID(), input.sourceId, input.errorMessage, timestamp, timestamp);
+      db.prepare(`
+        UPDATE sources
+        SET last_checked_at = ?, next_due_at = ?, updated_at = ?
+        WHERE id = ?
+      `).run(timestamp, addHoursIso(spec.schedule.everyHours), timestamp, input.sourceId);
+    },
+    recordCanaryRun(input) {
+      const sourceRow = db.prepare("SELECT spec_json FROM sources WHERE id = ?").get(input.sourceId);
+      if (!sourceRow) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.sourceNotFound,
+          `Unknown source '${input.sourceId}'`
+        );
+      }
+      const spec = JSON.parse(sourceRow.spec_json);
+      const canary = resolveSourceCanary(spec);
+      db.prepare(`
+        INSERT INTO canary_runs (id, source_id, status, checked_at, details_json)
+        VALUES (?, ?, ?, ?, ?)
+      `).run(
+        randomUUID(),
+        input.sourceId,
+        input.status,
+        input.checkedAt,
+        JSON.stringify(input.details)
+      );
+      db.prepare(`
+        UPDATE sources
+        SET
+          last_canary_checked_at = ?,
+          last_successful_canary_at = CASE WHEN ? = 'pass' THEN ? ELSE last_successful_canary_at END,
+          last_canary_status = ?,
+          next_canary_due_at = ?,
+          updated_at = ?
+        WHERE id = ?
+      `).run(
+        input.checkedAt,
+        input.status,
+        input.checkedAt,
+        input.status,
+        addHoursIso(canary.everyHours),
+        input.checkedAt,
+        input.sourceId
+      );
+    },
+    listProjectLinks,
+    removeManagedSources(input) {
+      if (input.managedRoots.length === 0) {
+        return [];
+      }
+      const activeSourceKeys = new Set(
+        input.activeSources.map((source) => `${source.sourceId}::${resolve2(source.specPath)}`)
+      );
+      const rows = db.prepare(`
+        SELECT id, spec_path
+        FROM sources
+        WHERE spec_path IS NOT NULL
+        ORDER BY id
+      `).all();
+      const toDelete = rows.filter((row) => {
+        if (!row.spec_path) {
+          return false;
+        }
+        const normalizedSpecPath = resolve2(row.spec_path);
+        return input.managedRoots.some(
+          (managedRoot) => normalizedSpecPath === managedRoot || normalizedSpecPath.startsWith(`${managedRoot}/`)
+        ) && !activeSourceKeys.has(`${row.id}::${normalizedSpecPath}`);
+      }).map((row) => row.id);
+      if (toDelete.length === 0) {
+        return [];
+      }
+      const deleteStatement = db.prepare("DELETE FROM sources WHERE id = ?");
+      const transaction = db.transaction((sourceIds) => {
+        for (const sourceId of sourceIds) {
+          deleteStatement.run(sourceId);
+        }
+      });
+      transaction(toDelete);
+      return toDelete;
+    },
+    listSnapshots(sourceId) {
+      const rows = db.prepare(`
+        SELECT id, source_id, detected_version, created_at, page_count
+        FROM snapshots
+        WHERE source_id = ?
+        ORDER BY rowid DESC
+      `).all(sourceId);
+      return rows.map((row) => ({
+        snapshotId: row.id,
+        sourceId: row.source_id,
+        detectedVersion: row.detected_version,
+        createdAt: row.created_at,
+        pageCount: row.page_count
+      }));
+    },
+    diffSnapshots(input) {
+      const snapshots = this.listSnapshots(input.sourceId);
+      if (snapshots.length === 0) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.snapshotNotFound,
+          `No successful snapshot found for source '${input.sourceId}'`
+        );
+      }
+      const toSnapshot = input.toSnapshotId ? snapshots.find((snapshot) => snapshot.snapshotId === input.toSnapshotId) : snapshots[0];
+      if (!toSnapshot) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.snapshotNotFound,
+          `Snapshot '${input.toSnapshotId}' not found for source '${input.sourceId}'`
+        );
+      }
+      const toSnapshotIndex = snapshots.findIndex((snapshot) => snapshot.snapshotId === toSnapshot.snapshotId);
+      const fromSnapshot = input.fromSnapshotId ? snapshots.find((snapshot) => snapshot.snapshotId === input.fromSnapshotId) : snapshots[toSnapshotIndex + 1];
+      if (!fromSnapshot) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.snapshotDiffBaseNotFound,
+          `No base snapshot available to diff source '${input.sourceId}'`
+        );
+      }
+      const loadSnapshotPages = (snapshotId) => db.prepare(`
+          SELECT url, title, markdown, content_hash
+          FROM pages
+          WHERE snapshot_id = ?
+          ORDER BY url
+        `).all(snapshotId);
+      const beforePages = loadSnapshotPages(fromSnapshot.snapshotId);
+      const afterPages = loadSnapshotPages(toSnapshot.snapshotId);
+      const beforeMap = new Map(beforePages.map((page) => [page.url, page]));
+      const afterMap = new Map(afterPages.map((page) => [page.url, page]));
+      const addedPages = afterPages.filter((page) => !beforeMap.has(page.url)).map((page) => ({
+        url: page.url,
+        title: page.title
+      }));
+      const removedPages = beforePages.filter((page) => !afterMap.has(page.url)).map((page) => ({
+        url: page.url,
+        title: page.title
+      }));
+      const summarizeLineDiff = (beforeMarkdown, afterMarkdown) => {
+        const beforeLines = beforeMarkdown.split("\n");
+        const afterLines = afterMarkdown.split("\n");
+        let prefix = 0;
+        while (prefix < beforeLines.length && prefix < afterLines.length && beforeLines[prefix] === afterLines[prefix]) {
+          prefix += 1;
+        }
+        let suffix = 0;
+        while (suffix < beforeLines.length - prefix && suffix < afterLines.length - prefix && beforeLines[beforeLines.length - 1 - suffix] === afterLines[afterLines.length - 1 - suffix]) {
+          suffix += 1;
+        }
+        return {
+          addedLineCount: Math.max(0, afterLines.length - prefix - suffix),
+          removedLineCount: Math.max(0, beforeLines.length - prefix - suffix)
+        };
+      };
+      const changedPages = beforePages.filter((page) => afterMap.has(page.url)).map((page) => ({
+        before: page,
+        after: afterMap.get(page.url)
+      })).filter(({ before, after }) => before.content_hash !== after.content_hash || before.title !== after.title).map(({ before, after }) => ({
+        url: before.url,
+        beforeTitle: before.title,
+        afterTitle: after.title,
+        lineSummary: summarizeLineDiff(before.markdown, after.markdown)
+      }));
+      const unchangedPageCount = beforePages.filter((page) => {
+        const next = afterMap.get(page.url);
+        return next && next.content_hash === page.content_hash && next.title === page.title;
+      }).length;
+      return {
+        sourceId: input.sourceId,
+        fromSnapshotId: fromSnapshot.snapshotId,
+        toSnapshotId: toSnapshot.snapshotId,
+        summary: {
+          addedPageCount: addedPages.length,
+          removedPageCount: removedPages.length,
+          changedPageCount: changedPages.length,
+          unchangedPageCount
+        },
+        addedPages,
+        removedPages,
+        changedPages
+      };
+    },
+    resolveSearchScope(input) {
+      return resolveSearchScope(input);
+    },
+    searchLexical(input) {
+      return searchLexicalByScope(input);
+    },
+    search(input) {
+      return searchLexicalByScope({
+        query: input.query,
+        scope: resolveSearchScope(input)
+      });
+    },
+    listLatestSnapshots(sourceIds) {
+      return listLatestSnapshots(sourceIds);
+    },
+    listSnapshotChunks(input) {
+      const rows = db.prepare(`
+        SELECT
+          c.id AS chunk_id,
+          c.source_id,
+          c.snapshot_id,
+          c.page_url,
+          c.page_title,
+          c.section_title,
+          c.markdown
+        FROM chunks c
+        WHERE c.source_id = ?
+          AND c.snapshot_id = ?
+        ORDER BY c.id
+      `).all(input.sourceId, input.snapshotId);
+      return rows.map((row) => ({
+        chunkId: row.chunk_id,
+        sourceId: row.source_id,
+        snapshotId: row.snapshot_id,
+        pageUrl: row.page_url,
+        pageTitle: row.page_title,
+        sectionTitle: row.section_title,
+        markdown: row.markdown,
+        contentHash: sha256(row.markdown)
+      }));
+    },
+    getSnapshotEmbeddingState(input) {
+      const rows = db.prepare(`
+        SELECT chunk_id, status, model_key, content_hash
+        FROM embedding_state
+        WHERE source_id = ?
+          AND snapshot_id = ?
+        ORDER BY chunk_id
+      `).all(input.sourceId, input.snapshotId);
+      return rows.map((row) => ({
+        chunkId: row.chunk_id,
+        status: row.status,
+        modelKey: row.model_key,
+        contentHash: row.content_hash
+      }));
+    },
+    listStaleEmbeddingChunkIds(sourceId) {
+      const rows = db.prepare(`
+        SELECT chunk_id
+        FROM embedding_state
+        WHERE source_id = ?
+          AND status = 'stale'
+        ORDER BY chunk_id
+      `).all(sourceId);
+      return rows.map((row) => row.chunk_id);
+    },
+    listEmbeddingChunkIds(sourceIds) {
+      const filterSourceIds = sourceIds && sourceIds.length > 0 ? [...new Set(sourceIds)] : null;
+      const rows = db.prepare(`
+        SELECT chunk_id
+        FROM embedding_state
+        ${filterSourceIds ? `WHERE source_id IN (${filterSourceIds.map(() => "?").join(",")})` : ""}
+        ORDER BY chunk_id
+      `).all(...filterSourceIds ?? []);
+      return rows.map((row) => row.chunk_id);
+    },
+    getChunksByIds(chunkIds) {
+      if (chunkIds.length === 0) {
+        return [];
+      }
+      const rows = db.prepare(`
+        SELECT
+          c.id AS chunk_id,
+          c.source_id,
+          c.snapshot_id,
+          c.page_url,
+          c.page_title,
+          c.section_title,
+          c.markdown
+        FROM chunks c
+        WHERE c.id IN (${chunkIds.map(() => "?").join(",")})
+      `).all(...chunkIds);
+      return rows.map((row) => ({
+        chunkId: row.chunk_id,
+        sourceId: row.source_id,
+        snapshotId: row.snapshot_id,
+        pageUrl: row.page_url,
+        pageTitle: row.page_title,
+        sectionTitle: row.section_title,
+        markdown: row.markdown
+      }));
+    },
+    queueLatestEmbeddingJobs(sourceIds) {
+      const latestSnapshots = listLatestSnapshots(sourceIds);
+      const transaction = db.transaction((snapshots) => {
+        for (const snapshot of snapshots) {
+          queueEmbeddingJobForSnapshot(snapshot.sourceId, snapshot.snapshotId);
+        }
+      });
+      transaction(latestSnapshots);
+      return {
+        queuedJobs: latestSnapshots.length
+      };
+    },
+    requeueLatestEmbeddingJobs(sourceIds) {
+      const latestSnapshots = listLatestSnapshots(sourceIds);
+      const transaction = db.transaction((snapshots) => {
+        for (const snapshot of snapshots) {
+          db.prepare(`
+            UPDATE embedding_state
+            SET
+              status = 'pending',
+              model_key = NULL,
+              vector_point_id = NULL,
+              last_attempted_at = NULL,
+              indexed_at = NULL,
+              error_message = NULL
+            WHERE source_id = ?
+              AND snapshot_id = ?
+          `).run(snapshot.sourceId, snapshot.snapshotId);
+          queueEmbeddingJobForSnapshot(snapshot.sourceId, snapshot.snapshotId);
+        }
+      });
+      transaction(latestSnapshots);
+      return {
+        queuedJobs: latestSnapshots.length
+      };
+    },
+    resetEmbeddingsAfterImport() {
+      const transaction = db.transaction(() => {
+        db.prepare("DELETE FROM embedding_jobs").run();
+        db.prepare("DELETE FROM embedding_state").run();
+      });
+      transaction();
+      const latestSnapshots = listLatestSnapshots();
+      const queueTransaction = db.transaction((snapshots) => {
+        for (const snapshot of snapshots) {
+          queueEmbeddingJobForSnapshot(snapshot.sourceId, snapshot.snapshotId);
+        }
+      });
+      queueTransaction(latestSnapshots);
+      return {
+        queuedJobs: latestSnapshots.length
+      };
+    },
+    resetRunningEmbeddingJobs() {
+      const result = db.prepare(`
+        UPDATE embedding_jobs
+        SET
+          status = 'pending',
+          updated_at = ?,
+          claimed_at = NULL,
+          error_message = NULL
+        WHERE status = 'running'
+      `).run(nowIso());
+      return result.changes;
+    },
+    claimEmbeddingJobs(limit) {
+      const normalizedLimit = assertPaginationValue(limit, "limit", limit);
+      if (normalizedLimit === 0) {
+        return [];
+      }
+      const claimedAt = nowIso();
+      const transaction = db.transaction(() => {
+        const pending = db.prepare(`
+          SELECT
+            source_id,
+            snapshot_id,
+            status,
+            attempt_count,
+            chunk_count,
+            created_at,
+            updated_at,
+            claimed_at,
+            completed_at,
+            error_message
+          FROM embedding_jobs
+          WHERE status = 'pending'
+          ORDER BY updated_at, source_id, snapshot_id
+          LIMIT ?
+        `).all(normalizedLimit);
+        const claim = db.prepare(`
+          UPDATE embedding_jobs
+          SET
+            status = 'running',
+            attempt_count = attempt_count + 1,
+            updated_at = ?,
+            claimed_at = ?,
+            error_message = NULL
+          WHERE source_id = ?
+            AND snapshot_id = ?
+        `);
+        for (const job of pending) {
+          claim.run(claimedAt, claimedAt, job.source_id, job.snapshot_id);
+        }
+        return pending.map((job) => ({
+          sourceId: job.source_id,
+          snapshotId: job.snapshot_id,
+          status: "running",
+          attemptCount: job.attempt_count + 1,
+          chunkCount: job.chunk_count,
+          createdAt: job.created_at,
+          updatedAt: claimedAt,
+          claimedAt,
+          completedAt: job.completed_at,
+          errorMessage: null
+        }));
+      });
+      return transaction();
+    },
+    markEmbeddingJobSucceeded(input) {
+      const timestamp = nowIso();
+      const staleChunkIds = [...new Set(input.staleChunkIds ?? [])];
+      const indexedChunkIds = [...new Set(input.indexedChunkIds)];
+      const indexedPlaceholders = indexedChunkIds.length > 0 ? indexedChunkIds.map(() => "?").join(",") : null;
+      const stalePlaceholders = staleChunkIds.length > 0 ? staleChunkIds.map(() => "?").join(",") : null;
+      const transaction = db.transaction(() => {
+        if (indexedPlaceholders) {
+          db.prepare(`
+            UPDATE embedding_state
+            SET
+              status = 'indexed',
+              model_key = ?,
+              vector_point_id = CAST(chunk_id AS TEXT),
+              last_attempted_at = ?,
+              indexed_at = ?,
+              error_message = NULL
+            WHERE chunk_id IN (${indexedPlaceholders})
+          `).run(input.modelKey, timestamp, timestamp, ...indexedChunkIds);
+        }
+        db.prepare(`
+          UPDATE embedding_state
+          SET
+            status = 'failed',
+            model_key = NULL,
+            vector_point_id = NULL,
+            last_attempted_at = ?,
+            indexed_at = NULL,
+            error_message = 'Chunk was not indexed during the latest embedding run'
+          WHERE source_id = ?
+            AND snapshot_id = ?
+            AND status != 'indexed'
+        `).run(timestamp, input.sourceId, input.snapshotId);
+        if (stalePlaceholders) {
+          db.prepare(`
+            DELETE FROM embedding_state
+            WHERE chunk_id IN (${stalePlaceholders})
+          `).run(...staleChunkIds);
+        }
+        db.prepare(`
+          UPDATE embedding_jobs
+          SET
+            status = 'succeeded',
+            updated_at = ?,
+            completed_at = ?,
+            claimed_at = NULL,
+            error_message = NULL
+          WHERE source_id = ?
+            AND snapshot_id = ?
+        `).run(timestamp, timestamp, input.sourceId, input.snapshotId);
+      });
+      transaction();
+    },
+    markEmbeddingJobFailed(input) {
+      const timestamp = nowIso();
+      const transaction = db.transaction(() => {
+        db.prepare(`
+          UPDATE embedding_state
+          SET
+            status = 'failed',
+            model_key = NULL,
+            vector_point_id = NULL,
+            last_attempted_at = ?,
+            indexed_at = NULL,
+            error_message = ?
+          WHERE source_id = ?
+            AND snapshot_id = ?
+            AND status != 'indexed'
+        `).run(timestamp, input.errorMessage, input.sourceId, input.snapshotId);
+        db.prepare(`
+          UPDATE embedding_jobs
+          SET
+            status = 'failed',
+            updated_at = ?,
+            completed_at = ?,
+            claimed_at = NULL,
+            error_message = ?
+          WHERE source_id = ?
+            AND snapshot_id = ?
+        `).run(timestamp, timestamp, input.errorMessage, input.sourceId, input.snapshotId);
+      });
+      transaction();
+    },
+    clearEmbeddings(sourceIds) {
+      const latestSnapshots = listLatestSnapshots(sourceIds);
+      const clearedSources = latestSnapshots.map((snapshot) => snapshot.sourceId);
+      const filterSourceIds = sourceIds && sourceIds.length > 0 ? [...new Set(sourceIds)] : null;
+      const transaction = db.transaction(() => {
+        if (filterSourceIds && filterSourceIds.length > 0) {
+          db.prepare(`
+            DELETE FROM embedding_jobs
+            WHERE source_id IN (${filterSourceIds.map(() => "?").join(",")})
+          `).run(...filterSourceIds);
+          db.prepare(`
+            DELETE FROM embedding_state
+            WHERE source_id IN (${filterSourceIds.map(() => "?").join(",")})
+          `).run(...filterSourceIds);
+        } else {
+          db.prepare("DELETE FROM embedding_jobs").run();
+          db.prepare("DELETE FROM embedding_state").run();
+        }
+      });
+      transaction();
+      return {
+        clearedSources
+      };
+    },
+    getEmbeddingOverview() {
+      const queueCounts = db.prepare(`
+        SELECT
+          SUM(CASE WHEN status = 'pending' THEN 1 ELSE 0 END) AS pending_jobs,
+          SUM(CASE WHEN status = 'running' THEN 1 ELSE 0 END) AS running_jobs,
+          SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS failed_jobs
+        FROM embedding_jobs
+      `).get();
+      const rows = db.prepare(`
+        SELECT
+          s.id AS source_id,
+          s.last_successful_snapshot_id AS snapshot_id,
+          COUNT(c.id) AS total_chunks,
+          SUM(CASE WHEN es.status = 'indexed' THEN 1 ELSE 0 END) AS indexed_chunks,
+          SUM(CASE WHEN es.status = 'pending' THEN 1 ELSE 0 END) AS pending_chunks,
+          SUM(CASE WHEN es.status = 'failed' THEN 1 ELSE 0 END) AS failed_chunks,
+          SUM(CASE WHEN es.status = 'stale' THEN 1 ELSE 0 END) AS stale_chunks
+        FROM sources s
+        LEFT JOIN chunks c
+          ON c.snapshot_id = s.last_successful_snapshot_id
+        LEFT JOIN embedding_state es
+          ON es.chunk_id = c.id
+        GROUP BY s.id, s.last_successful_snapshot_id
+        ORDER BY s.id
+      `).all();
+      return {
+        queue: {
+          pendingJobs: queueCounts.pending_jobs ?? 0,
+          runningJobs: queueCounts.running_jobs ?? 0,
+          failedJobs: queueCounts.failed_jobs ?? 0
+        },
+        sources: rows.map((row) => ({
+          sourceId: row.source_id,
+          snapshotId: row.snapshot_id,
+          totalChunks: row.total_chunks,
+          indexedChunks: row.indexed_chunks,
+          pendingChunks: row.pending_chunks,
+          failedChunks: row.failed_chunks,
+          staleChunks: row.stale_chunks,
+          coverageRatio: row.total_chunks === 0 ? 0 : row.indexed_chunks / row.total_chunks
+        }))
+      };
+    },
+    markDaemonStarted(input) {
+      db.prepare(`
+        INSERT INTO daemon_state (
+          singleton_id,
+          last_started_at,
+          interval_minutes,
+          fetch_on_start
+        ) VALUES (1, ?, ?, ?)
+        ON CONFLICT(singleton_id) DO UPDATE SET
+          last_started_at = excluded.last_started_at,
+          interval_minutes = excluded.interval_minutes,
+          fetch_on_start = excluded.fetch_on_start
+      `).run(
+        input.startedAt,
+        input.intervalMinutes,
+        input.fetchOnStart ? 1 : 0
+      );
+    },
+    markDaemonCycleStarted(startedAt) {
+      db.prepare(`
+        INSERT INTO daemon_state (singleton_id, last_cycle_started_at)
+        VALUES (1, ?)
+        ON CONFLICT(singleton_id) DO UPDATE SET
+          last_cycle_started_at = excluded.last_cycle_started_at
+      `).run(startedAt);
+    },
+    markDaemonCycleCompleted(input) {
+      db.prepare(`
+        INSERT INTO daemon_state (
+          singleton_id,
+          last_cycle_completed_at,
+          last_cycle_status
+        ) VALUES (1, ?, ?)
+        ON CONFLICT(singleton_id) DO UPDATE SET
+          last_cycle_completed_at = excluded.last_cycle_completed_at,
+          last_cycle_status = excluded.last_cycle_status
+      `).run(
+        input.completedAt,
+        input.status
+      );
+    },
+    getDaemonState() {
+      const row = db.prepare(`
+        SELECT
+          last_started_at,
+          last_cycle_started_at,
+          last_cycle_completed_at,
+          last_cycle_status,
+          interval_minutes,
+          fetch_on_start
+        FROM daemon_state
+        WHERE singleton_id = 1
+      `).get();
+      if (!row) {
+        return null;
+      }
+      return {
+        lastStartedAt: row.last_started_at,
+        lastCycleStartedAt: row.last_cycle_started_at,
+        lastCycleCompletedAt: row.last_cycle_completed_at,
+        lastCycleStatus: row.last_cycle_status,
+        intervalMinutes: row.interval_minutes,
+        fetchOnStart: row.fetch_on_start === null ? null : row.fetch_on_start === 1
+      };
+    },
+    getCoverageCorpus(input) {
+      const sourceRow = db.prepare("SELECT last_successful_snapshot_id FROM sources WHERE id = ?").get(input.sourceId);
+      if (!sourceRow) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.sourceNotFound,
+          `Unknown source '${input.sourceId}'`
+        );
+      }
+      const snapshotId = input.snapshotId ?? sourceRow.last_successful_snapshot_id;
+      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 rows = db.prepare(`
+        SELECT page_title, section_title, markdown
+        FROM chunks
+        WHERE source_id = ?
+          AND snapshot_id = ?
+        ORDER BY page_id, chunk_order
+      `).all(input.sourceId, snapshotId);
+      return {
+        sourceId: input.sourceId,
+        snapshotId,
+        entries: rows.map((row) => ({
+          pageTitle: row.page_title,
+          sectionTitle: row.section_title,
+          markdown: row.markdown
+        }))
+      };
+    },
+    getChunkById(chunkId) {
+      const row = db.prepare(`
+        SELECT
+          c.id AS chunk_id,
+          c.source_id,
+          c.snapshot_id,
+          c.page_url,
+          c.page_title,
+          c.section_title,
+          c.markdown
+        FROM chunks c
+        WHERE c.id = ?
+      `).get(chunkId);
+      if (!row) {
+        return null;
+      }
+      return {
+        chunkId: row.chunk_id,
+        sourceId: row.source_id,
+        snapshotId: row.snapshot_id,
+        pageUrl: row.page_url,
+        pageTitle: row.page_title,
+        sectionTitle: row.section_title,
+        markdown: row.markdown
+      };
+    }
+  };
+}
+
+// src/runtime/paths.ts
+import { homedir } from "os";
+import { join as join2 } from "path";
+import { mkdirSync as mkdirSync2 } from "fs";
+function expandTilde(path) {
+  if (path === "~") {
+    return homedir();
+  }
+  if (path.startsWith("~/")) {
+    return join2(homedir(), path.slice(2));
+  }
+  return path;
+}
+function getAiocsDataDir(env = process.env) {
+  const override = env.AIOCS_DATA_DIR;
+  if (override) {
+    mkdirSync2(expandTilde(override), { recursive: true });
+    return expandTilde(override);
+  }
+  const target = join2(homedir(), ".aiocs", "data");
+  mkdirSync2(target, { recursive: true });
+  return target;
+}
+function getAiocsConfigDir(env = process.env) {
+  const override = env.AIOCS_CONFIG_DIR;
+  if (override) {
+    mkdirSync2(expandTilde(override), { recursive: true });
+    return expandTilde(override);
+  }
+  const target = join2(homedir(), ".aiocs", "config");
+  mkdirSync2(target, { recursive: true });
+  return target;
+}
+function getAiocsSourcesDir(env = process.env) {
+  const override = env.AIOCS_SOURCES_DIR;
+  if (override) {
+    mkdirSync2(expandTilde(override), { recursive: true });
+    return expandTilde(override);
+  }
+  const target = join2(homedir(), ".aiocs", "sources");
+  mkdirSync2(target, { recursive: true });
+  return target;
+}
+
+// src/daemon.ts
+import { resolve as resolve4 } from "path";
+import { setTimeout as sleep2 } from "timers/promises";
+
+// src/fetch/fetch-source.ts
+import { mkdirSync as mkdirSync3, writeFileSync } from "fs";
+import { join as join3 } from "path";
+import { setTimeout as sleep } from "timers/promises";
+import { chromium } from "playwright";
+
+// src/fetch/extract.ts
+import { JSDOM } from "jsdom";
+import { Readability } from "@mozilla/readability";
+
+// src/fetch/normalize.ts
+import TurndownService from "turndown";
+import { gfm } from "turndown-plugin-gfm";
+var turndown = new TurndownService({
+  headingStyle: "atx",
+  codeBlockStyle: "fenced"
+});
+turndown.use(gfm);
+function htmlToMarkdown(html) {
+  return turndown.turndown(html).trim();
+}
+function ensureTitle(markdown, title) {
+  const trimmed = markdown.trim();
+  if (!trimmed) {
+    return `# ${title}`;
+  }
+  if (trimmed.startsWith("# ")) {
+    return trimmed;
+  }
+  return `# ${title}
+
+${trimmed}`;
+}
+function normalizeMarkdown(spec, page) {
+  const titled = ensureTitle(page.markdown, page.title);
+  if (!spec.normalize.prependSourceComment) {
+    return titled;
+  }
+  return `<!-- source: ${page.url} -->
+
+${titled}`;
+}
+
+// src/fetch/extract.ts
+var CLIPBOARD_INTERACTION_DEFAULT_TIMEOUT_MS = 1e3;
+async function readClipboard(page) {
+  return page.evaluate(() => navigator.clipboard.readText());
+}
+async function writeClipboard(page, value) {
+  return page.evaluate(async (nextValue) => {
+    try {
+      await navigator.clipboard.writeText(nextValue);
+      return true;
+    } catch {
+      return false;
+    }
+  }, value);
+}
+async function waitForClipboardChange(page, previousText, timeoutMs) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    const current = (await readClipboard(page)).trim();
+    if (current && current !== previousText.trim()) {
+      return current;
+    }
+    await page.waitForTimeout(100);
+  }
+  throw new Error("Timed out waiting for clipboard content to change");
+}
+async function performClipboardInteractions(page, strategy, deadlineAt) {
+  for (const interaction of strategy.interactions) {
+    const remainingMs = deadlineAt - Date.now();
+    if (remainingMs <= 0) {
+      throw new Error("Timed out before clipboard copy controls became ready");
+    }
+    if (interaction.action === "hover") {
+      const locator = page.locator(interaction.selector).first();
+      const interactionTimeout = Math.min(
+        interaction.timeoutMs ?? CLIPBOARD_INTERACTION_DEFAULT_TIMEOUT_MS,
+        remainingMs
+      );
+      await locator.waitFor({
+        state: "visible",
+        timeout: interactionTimeout
+      });
+      await locator.hover({
+        timeout: interactionTimeout
+      });
+      continue;
+    }
+    if (interaction.action === "click") {
+      const locator = page.locator(interaction.selector).first();
+      const interactionTimeout = Math.min(
+        interaction.timeoutMs ?? CLIPBOARD_INTERACTION_DEFAULT_TIMEOUT_MS,
+        remainingMs
+      );
+      await locator.waitFor({
+        state: "visible",
+        timeout: interactionTimeout
+      });
+      await locator.click({
+        timeout: interactionTimeout
+      });
+      continue;
+    }
+    if (interaction.action === "press") {
+      await page.keyboard.press(interaction.key);
+      continue;
+    }
+    await page.waitForTimeout(Math.min(interaction.timeoutMs, remainingMs));
+  }
+}
+async function runClipboardStrategy(page, strategy) {
+  const sentinel = `__aiocs_clipboard_marker__${Date.now()}__${Math.random().toString(36).slice(2)}__`;
+  const before = await writeClipboard(page, sentinel).catch(() => false) ? sentinel : await readClipboard(page).catch(() => "");
+  const deadlineAt = Date.now() + strategy.clipboardTimeoutMs;
+  let lastError = null;
+  let markdown = null;
+  while (Date.now() < deadlineAt && !markdown) {
+    try {
+      await performClipboardInteractions(page, strategy, deadlineAt);
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+    }
+    const remainingMs = deadlineAt - Date.now();
+    if (remainingMs <= 0) {
+      break;
+    }
+    try {
+      markdown = await waitForClipboardChange(page, before, Math.min(400, remainingMs));
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+    }
+  }
+  if (!markdown) {
+    throw lastError ?? new Error("Timed out waiting for clipboard content to change");
+  }
+  const title = extractTitleFromMarkdown(markdown) ?? await page.title();
+  return {
+    title,
+    markdown: markdown.trim()
+  };
+}
+async function runSelectorStrategy(page, selector) {
+  const locator = page.locator(selector).first();
+  await locator.waitFor({ state: "visible", timeout: 1e4 });
+  const html = await locator.innerHTML();
+  const heading = await locator.locator("h1").first().textContent().catch(() => null);
+  const title = (heading ?? await page.title()).trim();
+  return {
+    title,
+    markdown: htmlToMarkdown(html)
+  };
+}
+async function runReadabilityStrategy(page) {
+  const html = await page.content();
+  const dom = new JSDOM(html, { url: page.url() });
+  const reader = new Readability(dom.window.document);
+  const article = reader.parse();
+  if (!article?.content) {
+    throw new Error(`Readability could not extract content for ${page.url()}`);
+  }
+  return {
+    title: article.title?.trim() || await page.title(),
+    markdown: htmlToMarkdown(article.content)
+  };
+}
+function extractTitleFromMarkdown(markdown) {
+  for (const line of markdown.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("# ")) {
+      return trimmed.slice(2).trim();
+    }
+  }
+  return null;
+}
+async function extractPage(page, strategy) {
+  if (strategy.strategy === "clipboardButton") {
+    return runClipboardStrategy(page, strategy);
+  }
+  if (strategy.strategy === "selector") {
+    return runSelectorStrategy(page, strategy.selector);
+  }
+  return runReadabilityStrategy(page);
+}
+
+// src/fetch/url-patterns.ts
+function escapeRegex(value) {
+  return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}
+function patternToRegex(pattern) {
+  let regex = "^";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const current = pattern[index];
+    const next = pattern[index + 1];
+    if (current === "*" && next === "*") {
+      regex += ".*";
+      index += 1;
+      continue;
+    }
+    if (current === "*") {
+      regex += "[^?#]*";
+      continue;
+    }
+    regex += escapeRegex(current ?? "");
+  }
+  return new RegExp(`${regex}$`);
+}
+function matchesPatterns(url, patterns) {
+  return patterns.some((pattern) => patternToRegex(pattern).test(url));
+}
+
+// src/fetch/fetch-source.ts
+var MAX_FETCH_ATTEMPTS = 3;
+var RETRY_DELAY_MS = 250;
+function nowIso2() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function canonicalizeUrl(raw) {
+  const url = new URL(raw);
+  url.hash = "";
+  if (url.pathname !== "/" && url.pathname.endsWith("/")) {
+    url.pathname = url.pathname.slice(0, -1);
+  }
+  return url.toString();
+}
+function getCrawlKey(raw) {
+  const url = new URL(canonicalizeUrl(raw));
+  if (/\.(md|markdown)$/i.test(url.pathname)) {
+    url.pathname = url.pathname.replace(/\.(md|markdown)$/i, "");
+  }
+  return url.toString();
+}
+function isAllowed(url, allowedHosts, include, exclude) {
+  const parsed = new URL(url);
+  if (!allowedHosts.includes(parsed.hostname)) {
+    return false;
+  }
+  if (parsed.pathname.startsWith("/~gitbook/")) {
+    return false;
+  }
+  if (!matchesPatterns(url, include)) {
+    return false;
+  }
+  if (exclude.length > 0 && matchesPatterns(url, exclude)) {
+    return false;
+  }
+  return true;
+}
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "page";
+}
+function extractTitleFromMarkdown2(markdown) {
+  for (const line of markdown.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("# ")) {
+      return trimmed.slice(2).trim();
+    }
+  }
+  return null;
+}
+function deriveTitleFromUrl(url) {
+  const pathname = new URL(url).pathname;
+  const lastSegment = pathname.split("/").filter(Boolean).pop() ?? "page";
+  return lastSegment.replace(/\.(md|markdown)$/i, "").replace(/[-_]+/g, " ").trim() || "page";
+}
+function isRawMarkdownResponse(url, response) {
+  if (!response) {
+    return false;
+  }
+  const contentType = response.headers()["content-type"]?.toLowerCase() ?? "";
+  if (contentType.includes("text/markdown") || contentType.includes("text/x-markdown")) {
+    return true;
+  }
+  return contentType.includes("text/plain") && /\.(md|markdown)$/i.test(new URL(url).pathname);
+}
+async function extractRawMarkdownPage(url, response) {
+  const markdown = (await response.text()).trim();
+  return {
+    url,
+    title: extractTitleFromMarkdown2(markdown) ?? deriveTitleFromUrl(url),
+    markdown
+  };
+}
+function persistSnapshotPages(input, snapshotId, pages) {
+  const snapshotDir = join3(input.dataDir, "sources", input.sourceId, "snapshots", snapshotId, "pages");
+  mkdirSync3(snapshotDir, { recursive: true });
+  pages.forEach((page, index) => {
+    const filename = `${String(index + 1).padStart(3, "0")}-${slugify(page.title)}.md`;
+    writeFileSync(join3(snapshotDir, filename), page.markdown, "utf8");
+  });
+}
+function resolveEnvValue(name, env) {
+  const value = env[name];
+  if (!value) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.authEnvMissing,
+      `Missing required environment variable '${name}' for authenticated source access`,
+      {
+        envVar: name
+      }
+    );
+  }
+  return value;
+}
+function resolveSourceAuth(spec, env) {
+  const scopedHeaders = (spec.auth?.headers ?? []).map((header) => ({
+    name: header.name,
+    value: resolveEnvValue(header.valueFromEnv, env),
+    hosts: header.hosts ?? spec.allowedHosts,
+    ...header.include ? { include: header.include } : {}
+  }));
+  const cookies = (spec.auth?.cookies ?? []).map((cookie) => ({
+    name: cookie.name,
+    value: resolveEnvValue(cookie.valueFromEnv, env),
+    domain: cookie.domain,
+    path: cookie.path,
+    ...typeof cookie.secure === "boolean" ? { secure: cookie.secure } : {},
+    ...typeof cookie.httpOnly === "boolean" ? { httpOnly: cookie.httpOnly } : {},
+    ...cookie.sameSite ? { sameSite: cookie.sameSite } : {}
+  }));
+  return {
+    scopedHeaders,
+    cookies
+  };
+}
+function applyScopedAuthHeaders(requestUrl, headers, scopedHeaders) {
+  if (scopedHeaders.length === 0) {
+    return headers;
+  }
+  const hostname = new URL(requestUrl).hostname;
+  const nextHeaders = { ...headers };
+  for (const header of scopedHeaders) {
+    if (!header.hosts.includes(hostname)) {
+      continue;
+    }
+    if (header.include && !matchesPatterns(requestUrl, header.include)) {
+      continue;
+    }
+    nextHeaders[header.name] = header.value;
+  }
+  return nextHeaders;
+}
+async function createSourceContext(spec, env) {
+  const { scopedHeaders, cookies } = resolveSourceAuth(spec, env);
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({
+    viewport: {
+      width: 1440,
+      height: 1200
+    }
+  });
+  if (scopedHeaders.length > 0) {
+    await context.route("**/*", async (route) => {
+      await route.continue({
+        headers: applyScopedAuthHeaders(route.request().url(), route.request().headers(), scopedHeaders)
+      });
+    });
+  }
+  if (cookies.length > 0) {
+    await context.addCookies(cookies);
+  }
+  const uniqueOrigins = [...new Set(spec.startUrls.map((url) => new URL(url).origin))];
+  for (const origin of uniqueOrigins) {
+    await context.grantPermissions(["clipboard-read", "clipboard-write"], { origin });
+  }
+  const page = await context.newPage();
+  page.setDefaultTimeout(15e3);
+  return {
+    page,
+    async close() {
+      await context.close();
+      await browser.close();
+    }
+  };
+}
+async function discoverLinks(page) {
+  return page.locator("a[href]").evaluateAll(
+    (anchors) => anchors.map((anchor) => anchor.href).filter((href) => typeof href === "string" && href.length > 0)
+  );
+}
+async function extractFetchedPage(spec, page, url, response) {
+  if (response && isRawMarkdownResponse(url, response)) {
+    const extracted2 = await extractRawMarkdownPage(url, response);
+    const markdown2 = normalizeMarkdown(spec, extracted2);
+    return {
+      ...extracted2,
+      markdown: markdown2,
+      markdownLength: markdown2.trim().length
+    };
+  }
+  await page.waitForTimeout(150);
+  const extracted = await extractPage(page, spec.extract);
+  const markdown = normalizeMarkdown(spec, {
+    title: extracted.title,
+    url,
+    markdown: extracted.markdown
+  });
+  return {
+    url,
+    title: extracted.title,
+    markdown,
+    markdownLength: markdown.trim().length
+  };
+}
+async function fetchSourceOnce(input) {
+  const spec = input.catalog.getSourceSpec(input.sourceId);
+  if (!spec) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.sourceNotFound,
+      `Unknown source '${input.sourceId}'`
+    );
+  }
+  const session = await createSourceContext(spec, input.env ?? process.env);
+  const { page } = session;
+  const queue = spec.startUrls.map((url) => canonicalizeUrl(url));
+  const seen = /* @__PURE__ */ new Set();
+  const pageOrder = [];
+  const pagesByCrawlKey = /* @__PURE__ */ new Map();
+  const pendingRawFallbacks = /* @__PURE__ */ new Map();
+  try {
+    while (queue.length > 0 && pagesByCrawlKey.size < spec.discovery.maxPages) {
+      const next = queue.shift();
+      if (!next) {
+        break;
+      }
+      const url = canonicalizeUrl(next);
+      const crawlKey = getCrawlKey(url);
+      const isRawMarkdownUrl = crawlKey !== url;
+      const existing = pagesByCrawlKey.get(crawlKey);
+      if (isRawMarkdownUrl) {
+        if (existing && !existing.isRawMarkdown) {
+          continue;
+        }
+        if (!seen.has(crawlKey) && !existing) {
+          pendingRawFallbacks.set(crawlKey, url);
+          const canonicalQueued = queue.some((queuedUrl) => canonicalizeUrl(queuedUrl) === crawlKey);
+          if (!canonicalQueued) {
+            queue.unshift(crawlKey);
+          }
+          continue;
+        }
+      }
+      if (seen.has(url)) {
+        continue;
+      }
+      seen.add(url);
+      if (!isAllowed(url, spec.allowedHosts, spec.discovery.include, spec.discovery.exclude)) {
+        continue;
+      }
+      const response = await page.goto(url, { waitUntil: "domcontentloaded" });
+      if (response && response.status() >= 400) {
+        const pendingRawFallback = pendingRawFallbacks.get(crawlKey);
+        if (!isRawMarkdownUrl && pendingRawFallback && !seen.has(pendingRawFallback)) {
+          queue.unshift(pendingRawFallback);
+        }
+        continue;
+      }
+      let fetchedPage;
+      try {
+        fetchedPage = await extractFetchedPage(spec, page, url, response);
+      } catch (error) {
+        const pendingRawFallback = pendingRawFallbacks.get(crawlKey);
+        if (!isRawMarkdownUrl && pendingRawFallback && !seen.has(pendingRawFallback)) {
+          queue.unshift(pendingRawFallback);
+          continue;
+        }
+        throw error;
+      }
+      const isRawMarkdown = response !== null && isRawMarkdownResponse(url, response);
+      if (!existing) {
+        pageOrder.push(crawlKey);
+        pagesByCrawlKey.set(crawlKey, { page: fetchedPage, isRawMarkdown });
+      } else if (existing.isRawMarkdown && !isRawMarkdown) {
+        pagesByCrawlKey.set(crawlKey, { page: fetchedPage, isRawMarkdown });
+      }
+      if (!isRawMarkdown) {
+        pendingRawFallbacks.delete(crawlKey);
+      }
+      if (!isRawMarkdown) {
+        const links = await discoverLinks(page);
+        for (const link of links) {
+          const canonical = canonicalizeUrl(link);
+          if (!seen.has(canonical) && isAllowed(canonical, spec.allowedHosts, spec.discovery.include, spec.discovery.exclude)) {
+            queue.push(canonical);
+          }
+        }
+      }
+    }
+    const pages = pageOrder.map((crawlKey) => pagesByCrawlKey.get(crawlKey)?.page).filter((pageEntry) => pageEntry !== void 0);
+    if (pages.length === 0) {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.noPagesFetched,
+        `No pages fetched for source '${input.sourceId}'`
+      );
+    }
+    const result = input.catalog.recordSuccessfulSnapshot({
+      sourceId: input.sourceId,
+      pages
+    });
+    if (!result.reused) {
+      persistSnapshotPages(input, result.snapshotId, pages);
+    }
+    return {
+      snapshotId: result.snapshotId,
+      pageCount: pages.length,
+      reused: result.reused
+    };
+  } finally {
+    await session.close();
+  }
+}
+async function fetchSource(input) {
+  let lastError;
+  for (let attempt = 1; attempt <= MAX_FETCH_ATTEMPTS; attempt += 1) {
+    try {
+      return await fetchSourceOnce(input);
+    } catch (error) {
+      lastError = error;
+      if (attempt >= MAX_FETCH_ATTEMPTS) {
+        input.catalog.recordFailedFetchRun({
+          sourceId: input.sourceId,
+          errorMessage: error instanceof Error ? error.message : String(error)
+        });
+        throw error;
+      }
+      await sleep(RETRY_DELAY_MS * attempt);
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+async function runSourceCanaryOnce(input) {
+  const spec = input.catalog.getSourceSpec(input.sourceId);
+  if (!spec) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.sourceNotFound,
+      `Unknown source '${input.sourceId}'`
+    );
+  }
+  const canary = resolveSourceCanary(spec);
+  const session = await createSourceContext(spec, input.env ?? process.env);
+  const { page } = session;
+  const checks = [];
+  try {
+    for (const check of canary.checks) {
+      const url = canonicalizeUrl(check.url);
+      try {
+        if (!isAllowed(url, spec.allowedHosts, spec.discovery.include, spec.discovery.exclude)) {
+          throw new AiocsError(
+            AIOCS_ERROR_CODES.invalidArgument,
+            `Canary URL '${url}' is outside the allowed source scope`
+          );
+        }
+        const response = await page.goto(url, { waitUntil: "domcontentloaded" });
+        if (response && response.status() >= 400) {
+          throw new Error(`Canary request failed with HTTP ${response.status()}`);
+        }
+        const extracted = await extractFetchedPage(spec, page, url, response);
+        if (check.expectedTitle && !extracted.title.includes(check.expectedTitle)) {
+          throw new Error(`Expected title to include '${check.expectedTitle}'`);
+        }
+        if (check.expectedText && !extracted.markdown.includes(check.expectedText)) {
+          throw new Error(`Expected markdown to include '${check.expectedText}'`);
+        }
+        if (extracted.markdownLength < check.minMarkdownLength) {
+          throw new Error(
+            `Expected markdown length to be at least ${check.minMarkdownLength}, received ${extracted.markdownLength}`
+          );
+        }
+        checks.push({
+          url,
+          status: "pass",
+          title: extracted.title,
+          markdownLength: extracted.markdownLength
+        });
+      } catch (error) {
+        checks.push({
+          url,
+          status: "fail",
+          errorMessage: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+  } finally {
+    await session.close();
+  }
+  const result = {
+    sourceId: input.sourceId,
+    status: checks.every((check) => check.status === "pass") ? "pass" : "fail",
+    checkedAt: nowIso2(),
+    summary: {
+      checkCount: checks.length,
+      passCount: checks.filter((check) => check.status === "pass").length,
+      failCount: checks.filter((check) => check.status === "fail").length
+    },
+    checks
+  };
+  input.catalog.recordCanaryRun({
+    sourceId: input.sourceId,
+    status: result.status,
+    checkedAt: result.checkedAt,
+    details: result
+  });
+  if (result.status === "fail") {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.canaryFailed,
+      `Canary failed for source '${input.sourceId}'`,
+      result
+    );
+  }
+  return result;
+}
+async function runSourceCanary(input) {
+  let lastError;
+  for (let attempt = 1; attempt <= MAX_FETCH_ATTEMPTS; attempt += 1) {
+    try {
+      return await runSourceCanaryOnce(input);
+    } catch (error) {
+      lastError = error;
+      if (attempt >= MAX_FETCH_ATTEMPTS) {
+        if (error instanceof AiocsError && error.code === AIOCS_ERROR_CODES.canaryFailed) {
+          return error.details;
+        }
+        throw error;
+      }
+      await sleep(RETRY_DELAY_MS * attempt);
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+
+// src/hybrid/ollama.ts
+function getEmbeddingModelKey(config) {
+  return `${config.embeddingProvider}:${config.ollamaEmbeddingModel}`;
+}
+function normalizeBaseUrl(baseUrl) {
+  return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+}
+async function parseJsonResponse(response) {
+  const text = await response.text();
+  if (!text) {
+    return {};
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.embeddingProviderUnavailable,
+      `Ollama returned a non-JSON response with status ${response.status}`
+    );
+  }
+}
+async function embedTexts(config, texts) {
+  if (texts.length === 0) {
+    return [];
+  }
+  const response = await fetch(`${normalizeBaseUrl(config.ollamaBaseUrl)}/api/embed`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json"
+    },
+    signal: AbortSignal.timeout(config.ollamaTimeoutMs),
+    body: JSON.stringify({
+      model: config.ollamaEmbeddingModel,
+      input: texts
+    })
+  }).catch((error) => {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.embeddingProviderUnavailable,
+      `Unable to reach Ollama at ${config.ollamaBaseUrl}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.embeddingProviderUnavailable,
+      `Ollama embed request failed with status ${response.status}`,
+      body ? { body } : void 0
+    );
+  }
+  const payload = await parseJsonResponse(response);
+  if (!Array.isArray(payload.embeddings)) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.embeddingProviderUnavailable,
+      "Ollama embed response did not include an embeddings array"
+    );
+  }
+  const embeddings = payload.embeddings.map((entry) => {
+    if (!Array.isArray(entry) || !entry.every((value) => typeof value === "number")) {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.embeddingProviderUnavailable,
+        "Ollama embed response contained an invalid embedding vector"
+      );
+    }
+    return entry;
+  });
+  if (embeddings.length !== texts.length) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.embeddingProviderUnavailable,
+      `Ollama returned ${embeddings.length} embeddings for ${texts.length} inputs`
+    );
+  }
+  return embeddings;
+}
+async function getEmbeddingProviderStatus(config) {
+  const response = await fetch(`${normalizeBaseUrl(config.ollamaBaseUrl)}/api/tags`, {
+    signal: AbortSignal.timeout(config.ollamaTimeoutMs)
+  }).catch((error) => {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.embeddingProviderUnavailable,
+      `Unable to reach Ollama at ${config.ollamaBaseUrl}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  });
+  if (!response.ok) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.embeddingProviderUnavailable,
+      `Ollama tags request failed with status ${response.status}`
+    );
+  }
+  const payload = await parseJsonResponse(response);
+  const availableModels = (payload.models ?? []).map((entry) => entry.name ?? entry.model).filter((entry) => typeof entry === "string" && entry.length > 0);
+  const modelPresent = availableModels.some(
+    (name) => name === config.ollamaEmbeddingModel || name.startsWith(`${config.ollamaEmbeddingModel}:`)
+  );
+  return {
+    ok: modelPresent,
+    modelPresent,
+    baseUrl: config.ollamaBaseUrl,
+    model: config.ollamaEmbeddingModel,
+    availableModels
+  };
+}
+
+// src/hybrid/qdrant.ts
+import { QdrantClient } from "@qdrant/js-client-rest";
+var AiocsVectorStore = class {
+  client;
+  collectionName;
+  constructor(config) {
+    this.client = new QdrantClient({
+      url: config.qdrantUrl,
+      timeout: config.qdrantTimeoutMs,
+      checkCompatibility: false
+    });
+    this.collectionName = config.qdrantCollection;
+  }
+  pointIdForChunk(chunkId) {
+    return chunkId;
+  }
+  async ensureCollection(dimension) {
+    const existsResponse = await this.client.collectionExists(this.collectionName).catch((error) => {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.vectorStoreUnavailable,
+        `Unable to reach Qdrant collection '${this.collectionName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+    });
+    const exists = typeof existsResponse === "boolean" ? existsResponse : Boolean(existsResponse.exists);
+    if (!exists) {
+      await this.client.createCollection(this.collectionName, {
+        vectors: {
+          size: dimension,
+          distance: "Cosine"
+        }
+      }).catch((error) => {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.vectorStoreUnavailable,
+          `Unable to create Qdrant collection '${this.collectionName}': ${error instanceof Error ? error.message : String(error)}`
+        );
+      });
+      return;
+    }
+    const collection = await this.client.getCollection(this.collectionName).catch((error) => {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.vectorStoreUnavailable,
+        `Unable to inspect Qdrant collection '${this.collectionName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+    });
+    const params = collection.config?.params?.vectors;
+    const currentSize = typeof params === "object" && params && "size" in params ? Number(params.size) : null;
+    if (!currentSize || currentSize !== dimension) {
+      await this.client.recreateCollection(this.collectionName, {
+        vectors: {
+          size: dimension,
+          distance: "Cosine"
+        }
+      }).catch((error) => {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.vectorStoreUnavailable,
+          `Unable to recreate Qdrant collection '${this.collectionName}' for dimension ${dimension}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      });
+    }
+  }
+  async upsertChunks(input) {
+    if (input.points.length === 0) {
+      return;
+    }
+    const points = input.points.map((point) => ({
+      id: this.pointIdForChunk(point.chunkId),
+      vector: point.vector,
+      payload: {
+        chunkId: point.chunkId,
+        sourceId: point.sourceId,
+        snapshotId: point.snapshotId,
+        pageUrl: point.pageUrl,
+        pageTitle: point.pageTitle,
+        sectionTitle: point.sectionTitle,
+        modelKey: input.modelKey
+      }
+    }));
+    await this.client.upsert(this.collectionName, {
+      wait: true,
+      points
+    }).catch((error) => {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.vectorStoreUnavailable,
+        `Unable to upsert vectors into Qdrant collection '${this.collectionName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+    });
+  }
+  async deleteChunkIds(chunkIds) {
+    if (chunkIds.length === 0) {
+      return;
+    }
+    await this.client.delete(this.collectionName, {
+      wait: true,
+      points: chunkIds.map((chunkId) => this.pointIdForChunk(chunkId))
+    }).catch((error) => {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.vectorStoreUnavailable,
+        `Unable to delete vectors from Qdrant collection '${this.collectionName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+    });
+  }
+  async clearCollection() {
+    const existsResponse = await this.client.collectionExists(this.collectionName).catch((error) => {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.vectorStoreUnavailable,
+        `Unable to reach Qdrant collection '${this.collectionName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+    });
+    const exists = typeof existsResponse === "boolean" ? existsResponse : Boolean(existsResponse.exists);
+    if (!exists) {
+      return;
+    }
+    await this.client.deleteCollection(this.collectionName).catch((error) => {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.vectorStoreUnavailable,
+        `Unable to delete Qdrant collection '${this.collectionName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+    });
+  }
+  async search(input) {
+    if (input.snapshotIds.length === 0) {
+      return [];
+    }
+    const results = await this.client.search(this.collectionName, {
+      vector: input.vector,
+      limit: input.limit,
+      ...typeof input.offset === "number" ? { offset: input.offset } : {},
+      with_payload: ["chunkId", "snapshotId", "sourceId", "modelKey"],
+      filter: {
+        must: [
+          {
+            key: "snapshotId",
+            match: {
+              any: input.snapshotIds
+            }
+          },
+          {
+            key: "modelKey",
+            match: {
+              value: input.modelKey
+            }
+          },
+          ...input.sourceIds && input.sourceIds.length > 0 ? [{
+            key: "sourceId",
+            match: {
+              any: input.sourceIds
+            }
+          }] : []
+        ]
+      }
+    }).catch((error) => {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.vectorStoreUnavailable,
+        `Unable to search Qdrant collection '${this.collectionName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+    });
+    return results.map((result) => {
+      const payload = result.payload ?? {};
+      const chunkId = typeof payload.chunkId === "number" ? payload.chunkId : typeof result.id === "number" ? result.id : Number(result.id);
+      if (!Number.isInteger(chunkId)) {
+        return null;
+      }
+      return {
+        chunkId,
+        score: result.score
+      };
+    }).filter((result) => result !== null);
+  }
+  async getHealth() {
+    try {
+      const response = await this.client.getCollections();
+      return {
+        ok: true,
+        collections: response.collections?.map((entry) => entry.name) ?? []
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        errorMessage: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+};
+
+// src/hybrid/worker.ts
+function chunkArray(values, size) {
+  const chunks = [];
+  for (let index = 0; index < values.length; index += size) {
+    chunks.push(values.slice(index, index + size));
+  }
+  return chunks;
+}
+async function processEmbeddingJobs(input) {
+  const claimedJobs = input.catalog.claimEmbeddingJobs(input.config.embeddingJobsPerCycle);
+  if (claimedJobs.length === 0) {
+    return {
+      processedJobs: 0,
+      succeededJobs: [],
+      failedJobs: []
+    };
+  }
+  const vectorStore = new AiocsVectorStore(input.config);
+  const modelKey = getEmbeddingModelKey(input.config);
+  const succeededJobs = [];
+  const failedJobs = [];
+  for (const job of claimedJobs) {
+    try {
+      const chunks = input.catalog.listSnapshotChunks({
+        sourceId: job.sourceId,
+        snapshotId: job.snapshotId
+      });
+      if (chunks.length === 0) {
+        input.catalog.markEmbeddingJobFailed({
+          sourceId: job.sourceId,
+          snapshotId: job.snapshotId,
+          errorMessage: "No chunks found for embedding job snapshot"
+        });
+        failedJobs.push({
+          sourceId: job.sourceId,
+          snapshotId: job.snapshotId,
+          errorMessage: "No chunks found for embedding job snapshot"
+        });
+        continue;
+      }
+      const existingState = input.catalog.getSnapshotEmbeddingState({
+        sourceId: job.sourceId,
+        snapshotId: job.snapshotId
+      });
+      const staleChunkIds = [
+        .../* @__PURE__ */ new Set([
+          ...input.catalog.listStaleEmbeddingChunkIds(job.sourceId),
+          ...existingState.filter((entry) => entry.modelKey && entry.modelKey !== modelKey).map((entry) => entry.chunkId)
+        ])
+      ];
+      const needsReindex = existingState.some((entry) => entry.status !== "indexed" || entry.modelKey !== modelKey);
+      if (!needsReindex) {
+        input.catalog.markEmbeddingJobSucceeded({
+          sourceId: job.sourceId,
+          snapshotId: job.snapshotId,
+          modelKey,
+          indexedChunkIds: chunks.map((chunk) => chunk.chunkId),
+          staleChunkIds
+        });
+        succeededJobs.push({
+          sourceId: job.sourceId,
+          snapshotId: job.snapshotId,
+          chunkCount: chunks.length
+        });
+        continue;
+      }
+      const dimensionProbe = await embedTexts(input.config, [chunks[0].markdown]);
+      const vectorDimension = dimensionProbe[0]?.length;
+      if (!vectorDimension) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.embeddingProviderUnavailable,
+          "Embedding provider returned an empty vector for the first chunk"
+        );
+      }
+      await vectorStore.ensureCollection(vectorDimension);
+      if (staleChunkIds.length > 0) {
+        await vectorStore.deleteChunkIds(staleChunkIds);
+      }
+      const indexedChunkIds = [];
+      const batchedChunks = chunkArray(chunks, input.config.embeddingBatchSize);
+      let dimensionProbeConsumed = false;
+      for (const batch of batchedChunks) {
+        const embeddings = dimensionProbeConsumed ? await embedTexts(input.config, batch.map((chunk) => chunk.markdown)) : [
+          dimensionProbe[0],
+          ...batch.length > 1 ? await embedTexts(input.config, batch.slice(1).map((chunk) => chunk.markdown)) : []
+        ];
+        dimensionProbeConsumed = true;
+        if (embeddings.length !== batch.length) {
+          throw new AiocsError(
+            AIOCS_ERROR_CODES.embeddingProviderUnavailable,
+            `Embedding provider returned ${embeddings.length} embeddings for a batch of ${batch.length}`
+          );
+        }
+        await vectorStore.upsertChunks({
+          modelKey,
+          points: batch.map((chunk, index) => ({
+            chunkId: chunk.chunkId,
+            vector: embeddings[index],
+            sourceId: chunk.sourceId,
+            snapshotId: chunk.snapshotId,
+            pageUrl: chunk.pageUrl,
+            pageTitle: chunk.pageTitle,
+            sectionTitle: chunk.sectionTitle
+          }))
+        });
+        indexedChunkIds.push(...batch.map((chunk) => chunk.chunkId));
+      }
+      input.catalog.markEmbeddingJobSucceeded({
+        sourceId: job.sourceId,
+        snapshotId: job.snapshotId,
+        modelKey,
+        indexedChunkIds,
+        staleChunkIds
+      });
+      succeededJobs.push({
+        sourceId: job.sourceId,
+        snapshotId: job.snapshotId,
+        chunkCount: indexedChunkIds.length
+      });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      input.catalog.markEmbeddingJobFailed({
+        sourceId: job.sourceId,
+        snapshotId: job.snapshotId,
+        errorMessage
+      });
+      failedJobs.push({
+        sourceId: job.sourceId,
+        snapshotId: job.snapshotId,
+        errorMessage
+      });
+    }
+  }
+  return {
+    processedJobs: claimedJobs.length,
+    succeededJobs,
+    failedJobs
+  };
+}
+
+// src/runtime/bundled-sources.ts
+import { existsSync } from "fs";
+import { dirname, join as join4 } from "path";
+import { fileURLToPath } from "url";
+function findPackageRoot(startDir) {
+  let currentDir = startDir;
+  while (true) {
+    if (existsSync(join4(currentDir, "package.json")) && existsSync(join4(currentDir, "sources"))) {
+      return currentDir;
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      throw new Error(`Could not locate aiocs package root from ${startDir}`);
+    }
+    currentDir = parentDir;
+  }
+}
+function getBundledSourcesDir() {
+  const currentFilePath = fileURLToPath(import.meta.url);
+  const packageRoot = findPackageRoot(dirname(currentFilePath));
+  return join4(packageRoot, "sources");
+}
+
+// src/runtime/hybrid-config.ts
+function parsePositiveInteger(value, field, fallback) {
+  if (typeof value === "undefined" || value.trim() === "") {
+    return fallback;
+  }
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.embeddingConfigInvalid,
+      `${field} must be a positive integer`
+    );
+  }
+  return parsed;
+}
+function parseSearchMode(value) {
+  if (!value) {
+    return "auto";
+  }
+  if (value === "auto" || value === "lexical" || value === "hybrid" || value === "semantic") {
+    return value;
+  }
+  throw new AiocsError(
+    AIOCS_ERROR_CODES.embeddingConfigInvalid,
+    "AIOCS_SEARCH_MODE_DEFAULT must be one of: auto, lexical, hybrid, semantic"
+  );
+}
+function getHybridRuntimeConfig(env = process.env) {
+  const embeddingProvider = env.AIOCS_EMBEDDING_PROVIDER ?? "ollama";
+  if (embeddingProvider !== "ollama") {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.embeddingConfigInvalid,
+      "AIOCS_EMBEDDING_PROVIDER currently supports only ollama"
+    );
+  }
+  return {
+    defaultSearchMode: parseSearchMode(env.AIOCS_SEARCH_MODE_DEFAULT),
+    qdrantUrl: env.AIOCS_QDRANT_URL ?? "http://127.0.0.1:6333",
+    qdrantCollection: env.AIOCS_QDRANT_COLLECTION ?? "aiocs_docs_chunks",
+    qdrantTimeoutMs: parsePositiveInteger(env.AIOCS_QDRANT_TIMEOUT_MS, "AIOCS_QDRANT_TIMEOUT_MS", 1e3),
+    embeddingProvider: "ollama",
+    ollamaBaseUrl: env.AIOCS_OLLAMA_BASE_URL ?? "http://127.0.0.1:11434",
+    ollamaEmbeddingModel: env.AIOCS_OLLAMA_EMBEDDING_MODEL ?? "nomic-embed-text",
+    ollamaTimeoutMs: parsePositiveInteger(env.AIOCS_OLLAMA_TIMEOUT_MS, "AIOCS_OLLAMA_TIMEOUT_MS", 1e3),
+    embeddingBatchSize: parsePositiveInteger(env.AIOCS_EMBEDDING_BATCH_SIZE, "AIOCS_EMBEDDING_BATCH_SIZE", 32),
+    embeddingJobsPerCycle: parsePositiveInteger(env.AIOCS_EMBEDDING_JOB_LIMIT_PER_CYCLE, "AIOCS_EMBEDDING_JOB_LIMIT_PER_CYCLE", 2),
+    lexicalCandidateWindow: parsePositiveInteger(env.AIOCS_LEXICAL_CANDIDATE_WINDOW, "AIOCS_LEXICAL_CANDIDATE_WINDOW", 40),
+    vectorCandidateWindow: parsePositiveInteger(env.AIOCS_VECTOR_CANDIDATE_WINDOW, "AIOCS_VECTOR_CANDIDATE_WINDOW", 40),
+    rrfK: parsePositiveInteger(env.AIOCS_RRF_K, "AIOCS_RRF_K", 60)
+  };
+}
+
+// src/spec/source-spec-files.ts
+import { access, readdir } from "fs/promises";
+import { constants as fsConstants } from "fs";
+import { extname as extname2, join as join5, resolve as resolve3 } from "path";
+var SOURCE_SPEC_EXTENSIONS = /* @__PURE__ */ new Set([".yaml", ".yml", ".json"]);
+function uniqueResolvedPaths(paths) {
+  const seen = /* @__PURE__ */ new Set();
+  const unique = [];
+  for (const rawPath of paths) {
+    const normalized = resolve3(rawPath);
+    if (seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    unique.push(normalized);
+  }
+  return unique;
+}
+async function pathExists(targetPath) {
+  try {
+    await access(targetPath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function walkSourceSpecFiles(rootDir) {
+  const entries = await readdir(rootDir, { withFileTypes: true });
+  const discovered = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    const entryPath = join5(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      discovered.push(...await walkSourceSpecFiles(entryPath));
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    if (SOURCE_SPEC_EXTENSIONS.has(extname2(entry.name).toLowerCase())) {
+      discovered.push(entryPath);
+    }
+  }
+  return discovered;
+}
+
+// src/daemon.ts
+var DEFAULT_INTERVAL_MINUTES = 60;
+var DEFAULT_CONTAINER_SOURCE_DIR = "/app/sources";
+var BOOLEAN_TRUE_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+var BOOLEAN_FALSE_VALUES = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
+function nowIso3() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function parsePositiveInteger2(raw, variableName) {
+  if (!/^\d+$/.test(raw)) {
+    throw new Error(`${variableName} must be a positive integer`);
+  }
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${variableName} must be a positive integer`);
+  }
+  return parsed;
+}
+function parseBoolean(raw, variableName) {
+  const normalized = raw.trim().toLowerCase();
+  if (BOOLEAN_TRUE_VALUES.has(normalized)) {
+    return true;
+  }
+  if (BOOLEAN_FALSE_VALUES.has(normalized)) {
+    return false;
+  }
+  throw new Error(`${variableName} must be one of: true, false, 1, 0, yes, no, on, off`);
+}
+function parseDaemonConfig(env, options = {}) {
+  const intervalMinutes = env.AIOCS_DAEMON_INTERVAL_MINUTES ? parsePositiveInteger2(env.AIOCS_DAEMON_INTERVAL_MINUTES, "AIOCS_DAEMON_INTERVAL_MINUTES") : DEFAULT_INTERVAL_MINUTES;
+  const fetchOnStart = env.AIOCS_DAEMON_FETCH_ON_START ? parseBoolean(env.AIOCS_DAEMON_FETCH_ON_START, "AIOCS_DAEMON_FETCH_ON_START") : true;
+  const defaultSourceDirs = uniqueResolvedPaths([
+    options.bundledSourceDir ?? getBundledSourcesDir(),
+    options.userSourceDir ?? getAiocsSourcesDir(env),
+    options.containerSourceDir ?? DEFAULT_CONTAINER_SOURCE_DIR
+  ]);
+  const sourceSpecDirs = env.AIOCS_SOURCE_SPEC_DIRS ? uniqueResolvedPaths(
+    env.AIOCS_SOURCE_SPEC_DIRS.split(",").map((entry) => entry.trim()).filter(Boolean)
+  ) : defaultSourceDirs;
+  if (env.AIOCS_SOURCE_SPEC_DIRS && sourceSpecDirs.length === 0) {
+    throw new Error("AIOCS_SOURCE_SPEC_DIRS must include at least one directory");
+  }
+  return {
+    intervalMinutes,
+    fetchOnStart,
+    strictSourceSpecDirs: Boolean(env.AIOCS_SOURCE_SPEC_DIRS),
+    sourceSpecDirs
+  };
+}
+async function bootstrapSourceSpecs(input) {
+  const normalizedSourceSpecDirs = uniqueResolvedPaths(input.sourceSpecDirs);
+  const missingDirs = [];
+  const existingDirs = [];
+  const sources = [];
+  for (const sourceSpecDir of normalizedSourceSpecDirs) {
+    if (!await pathExists(sourceSpecDir)) {
+      missingDirs.push(sourceSpecDir);
+      continue;
+    }
+    existingDirs.push(sourceSpecDir);
+  }
+  if (input.strictSourceSpecDirs && missingDirs.length > 0) {
+    throw new Error(`Missing source spec directories: ${missingDirs.join(", ")}`);
+  }
+  for (const sourceSpecDir of existingDirs) {
+    const specPaths = await walkSourceSpecFiles(sourceSpecDir);
+    for (const specPath of specPaths) {
+      const spec = await loadSourceSpec(specPath);
+      const upserted = input.catalog.upsertSource(spec, { specPath });
+      sources.push({
+        sourceId: upserted.sourceId,
+        configHash: upserted.configHash,
+        configChanged: upserted.configChanged,
+        specPath
+      });
+    }
+  }
+  if (input.strictSourceSpecDirs && sources.length === 0) {
+    throw new Error(`No source spec files found in configured directories: ${normalizedSourceSpecDirs.join(", ")}`);
+  }
+  const removedSourceIds = input.catalog.removeManagedSources({
+    managedRoots: existingDirs.map((sourceSpecDir) => resolve4(sourceSpecDir)),
+    activeSources: sources.map((source) => ({
+      sourceId: source.sourceId,
+      specPath: source.specPath
+    }))
+  });
+  return {
+    processedSpecCount: sources.length,
+    removedSourceIds,
+    sources
+  };
+}
+async function runDaemonCycle(input) {
+  const startedAt = nowIso3();
+  const bootstrapped = await bootstrapSourceSpecs({
+    catalog: input.catalog,
+    sourceSpecDirs: input.sourceSpecDirs,
+    ...input.strictSourceSpecDirs !== void 0 ? { strictSourceSpecDirs: input.strictSourceSpecDirs } : {}
+  });
+  const dueSourceIds = [
+    .../* @__PURE__ */ new Set([
+      ...input.catalog.listDueSourceIds(input.referenceTime ?? startedAt),
+      ...bootstrapped.sources.filter((source) => source.configChanged).map((source) => source.sourceId)
+    ])
+  ];
+  const canaryDueSourceIds = [
+    .../* @__PURE__ */ new Set([
+      ...input.catalog.listCanaryDueSourceIds(input.referenceTime ?? startedAt),
+      ...bootstrapped.sources.filter((source) => source.configChanged).map((source) => source.sourceId),
+      ...input.catalog.listSources().filter((source) => source.lastCanaryCheckedAt === null).map((source) => source.id)
+    ])
+  ];
+  const canaried = [];
+  const canaryFailed = [];
+  const refreshed = [];
+  const failed = [];
+  const embedded = [];
+  const embeddingFailed = [];
+  for (const sourceId of canaryDueSourceIds) {
+    try {
+      const result = await runSourceCanary({
+        catalog: input.catalog,
+        sourceId,
+        env: process.env
+      });
+      canaried.push({
+        sourceId,
+        status: result.status,
+        checkedAt: result.checkedAt,
+        summary: result.summary
+      });
+      if (result.status === "fail") {
+        canaryFailed.push({
+          sourceId,
+          errorMessage: `One or more canary checks failed for ${sourceId}`
+        });
+      }
+    } catch (error) {
+      canaryFailed.push({
+        sourceId,
+        errorMessage: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  for (const sourceId of dueSourceIds) {
+    try {
+      const result = await fetchSource({
+        catalog: input.catalog,
+        dataDir: input.dataDir,
+        sourceId
+      });
+      refreshed.push({
+        sourceId,
+        snapshotId: result.snapshotId,
+        pageCount: result.pageCount,
+        reused: result.reused
+      });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      failed.push({
+        sourceId,
+        errorMessage
+      });
+    }
+  }
+  try {
+    const embeddingResult = await processEmbeddingJobs({
+      catalog: input.catalog,
+      config: getHybridRuntimeConfig(process.env)
+    });
+    embedded.push(...embeddingResult.succeededJobs);
+    embeddingFailed.push(...embeddingResult.failedJobs);
+  } catch (error) {
+    embeddingFailed.push({
+      sourceId: "system",
+      snapshotId: "system",
+      errorMessage: error instanceof Error ? error.message : String(error)
+    });
+  }
+  return {
+    startedAt,
+    finishedAt: nowIso3(),
+    dueSourceIds,
+    canaryDueSourceIds,
+    bootstrapped,
+    canaried,
+    canaryFailed,
+    refreshed,
+    failed,
+    embedded,
+    embeddingFailed
+  };
+}
+async function startDaemon(input) {
+  const intervalMs = input.config.intervalMinutes * 6e4;
+  input.catalog.resetRunningEmbeddingJobs();
+  input.catalog.markDaemonStarted({
+    startedAt: nowIso3(),
+    intervalMinutes: input.config.intervalMinutes,
+    fetchOnStart: input.config.fetchOnStart
+  });
+  input.logger.emit({
+    type: "daemon.started",
+    intervalMinutes: input.config.intervalMinutes,
+    fetchOnStart: input.config.fetchOnStart,
+    sourceSpecDirs: input.config.sourceSpecDirs
+  });
+  const runCycle = async (reason) => {
+    const startedAt = nowIso3();
+    input.catalog.markDaemonCycleStarted(startedAt);
+    input.logger.emit({
+      type: "daemon.cycle.started",
+      reason,
+      startedAt
+    });
+    try {
+      const result = await runDaemonCycle({
+        catalog: input.catalog,
+        dataDir: input.dataDir,
+        sourceSpecDirs: input.config.sourceSpecDirs,
+        strictSourceSpecDirs: input.config.strictSourceSpecDirs,
+        referenceTime: startedAt
+      });
+      input.catalog.markDaemonCycleCompleted({
+        completedAt: result.finishedAt,
+        status: result.failed.length > 0 || result.canaryFailed.length > 0 || result.embeddingFailed.length > 0 ? "degraded" : "success"
+      });
+      input.logger.emit({
+        type: "daemon.cycle.completed",
+        reason,
+        result
+      });
+    } catch (error) {
+      input.catalog.markDaemonCycleCompleted({
+        completedAt: nowIso3(),
+        status: "failed"
+      });
+      throw error;
+    }
+  };
+  if (input.config.fetchOnStart && !input.signal?.aborted) {
+    await runCycle("startup");
+  }
+  while (!input.signal?.aborted) {
+    try {
+      await sleep2(intervalMs, void 0, { signal: input.signal });
+    } catch (error) {
+      if (input.signal?.aborted) {
+        break;
+      }
+      throw error;
+    }
+    if (input.signal?.aborted) {
+      break;
+    }
+    await runCycle("interval");
+  }
+  input.logger.emit({
+    type: "daemon.stopped"
+  });
+}
+
+// package.json
+var package_default = {
+  name: "@bodhi-ventures/aiocs",
+  version: "0.1.0",
+  license: "MIT",
+  type: "module",
+  description: "Local-only documentation store, fetcher, and search CLI for AI agents.",
+  keywords: [
+    "ai",
+    "docs",
+    "search",
+    "mcp",
+    "cli"
+  ],
+  homepage: "https://github.com/Bodhi-Ventures/aiocs",
+  bugs: {
+    url: "https://github.com/Bodhi-Ventures/aiocs/issues"
+  },
+  repository: {
+    type: "git",
+    url: "https://github.com/Bodhi-Ventures/aiocs.git"
+  },
+  publishConfig: {
+    access: "public",
+    provenance: true
+  },
+  packageManager: "pnpm@9.15.9",
+  files: [
+    "dist",
+    "sources",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "skills"
+  ],
+  bin: {
+    docs: "./dist/cli.js",
+    "aiocs-mcp": "./dist/mcp-server.js"
+  },
+  engines: {
+    node: ">=22"
+  },
+  scripts: {
+    build: "tsup --config tsup.config.ts",
+    dev: "tsx src/cli.ts",
+    "dev:mcp": "tsx src/mcp-server.ts",
+    lint: "tsc --noEmit",
+    test: "vitest run",
+    "test:watch": "vitest"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "@mozilla/readability": "^0.6.0",
+    "@qdrant/js-client-rest": "1.17.0",
+    "better-sqlite3": "^12.4.1",
+    commander: "^14.0.1",
+    jsdom: "^27.0.1",
+    playwright: "^1.57.0",
+    turndown: "^7.2.1",
+    "turndown-plugin-gfm": "^1.0.2",
+    yaml: "^2.8.1",
+    zod: "^4.1.12"
+  },
+  devDependencies: {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^24.7.2",
+    "@types/turndown": "^5.0.5",
+    execa: "^9.6.0",
+    tsup: "^8.5.0",
+    tsx: "^4.20.6",
+    typescript: "^5.9.3",
+    vitest: "^3.2.4"
+  }
+};
+
+// src/runtime/package-metadata.ts
+var packageName = package_default.name;
+var packageVersion = package_default.version;
+var packageDescription = package_default.description;
+
+// src/services.ts
+import { resolve as resolve7 } from "path";
+
+// src/backup.ts
+import { cp, mkdir, readdir as readdir2, readFile as readFile2, rename, rm, stat, writeFile } from "fs/promises";
+import { basename, dirname as dirname2, join as join6, resolve as resolve5 } from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+import Database2 from "better-sqlite3";
+var CATALOG_DB_FILENAME = "catalog.sqlite";
+var SQLITE_SIDE_CAR_SUFFIXES = ["-wal", "-shm"];
+async function pathExists2(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function assertSourceDirExists(path) {
+  if (!await pathExists2(path)) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.backupSourceMissing,
+      `Backup source path does not exist: ${path}`
+    );
+  }
+}
+async function isDirectoryEmpty(path) {
+  if (!await pathExists2(path)) {
+    return true;
+  }
+  return (await readdir2(path)).length === 0;
+}
+async function listEntries(root, relativePath = "") {
+  const absolutePath = relativePath ? join6(root, relativePath) : root;
+  const stats = await stat(absolutePath);
+  if (!stats.isDirectory()) {
+    return [{
+      relativePath,
+      type: "file",
+      size: stats.size
+    }];
+  }
+  const childNames = await readdir2(absolutePath);
+  const entries = relativePath ? [{
+    relativePath,
+    type: "directory",
+    size: 0
+  }] : [];
+  for (const childName of childNames.sort()) {
+    entries.push(...await listEntries(root, relativePath ? join6(relativePath, childName) : childName));
+  }
+  return entries;
+}
+async function copyIfPresent(from, to, entries, relativePrefix) {
+  if (!await pathExists2(from)) {
+    return;
+  }
+  await mkdir(to, { recursive: true });
+  await cp(from, to, { recursive: true, force: true });
+  const copiedEntries = await listEntries(to);
+  entries.push(
+    ...copiedEntries.map((entry) => ({
+      ...entry,
+      relativePath: join6(relativePrefix, entry.relativePath)
+    }))
+  );
+}
+async function copyDataDirForBackup(from, to) {
+  const sourceCatalogPath = join6(from, CATALOG_DB_FILENAME);
+  if (!await pathExists2(sourceCatalogPath)) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.backupSourceMissing,
+      `Backup source is missing the catalog database: ${sourceCatalogPath}`
+    );
+  }
+  await mkdir(to, { recursive: true });
+  await cp(from, to, {
+    recursive: true,
+    force: true,
+    filter: (source) => {
+      const name = basename(source);
+      if (name === CATALOG_DB_FILENAME) {
+        return false;
+      }
+      return !SQLITE_SIDE_CAR_SUFFIXES.some((suffix) => name === `${CATALOG_DB_FILENAME}${suffix}`);
+    }
+  });
+  const targetCatalogPath = join6(to, CATALOG_DB_FILENAME);
+  const sourceCatalog = new Database2(sourceCatalogPath, { readonly: true });
+  try {
+    await sourceCatalog.backup(targetCatalogPath);
+  } finally {
+    sourceCatalog.close();
+  }
+}
+async function loadValidatedBackupPayload(inputDir) {
+  const manifestPath = join6(inputDir, "manifest.json");
+  await assertSourceDirExists(inputDir);
+  if (!await pathExists2(manifestPath)) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.backupInvalid,
+      `Backup manifest not found: ${manifestPath}`
+    );
+  }
+  const manifest = JSON.parse(await readFile2(manifestPath, "utf8"));
+  if (manifest.formatVersion !== 1 || !Array.isArray(manifest.entries)) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.backupInvalid,
+      `Invalid backup manifest: ${manifestPath}`
+    );
+  }
+  const backupDataDir = join6(inputDir, "data");
+  if (!await pathExists2(backupDataDir)) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.backupInvalid,
+      `Backup payload is missing the data directory: ${backupDataDir}`
+    );
+  }
+  const backupCatalogPath = join6(backupDataDir, CATALOG_DB_FILENAME);
+  if (!await pathExists2(backupCatalogPath)) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.backupInvalid,
+      `Backup payload is missing the catalog database: ${backupCatalogPath}`
+    );
+  }
+  const backupConfigDir = join6(inputDir, "config");
+  return {
+    manifest,
+    backupDataDir,
+    ...await pathExists2(backupConfigDir) ? { backupConfigDir } : {}
+  };
+}
+async function prepareReplacementTarget(backupDir, targetDir) {
+  const parentDir = dirname2(targetDir);
+  const stagingDir = join6(parentDir, `.${basename(targetDir)}.import-${randomUUID2()}`);
+  await rm(stagingDir, { recursive: true, force: true });
+  await mkdir(parentDir, { recursive: true });
+  await cp(backupDir, stagingDir, { recursive: true, force: true });
+  return stagingDir;
+}
+async function exportBackup(input) {
+  const dataDir = resolve5(input.dataDir);
+  const outputDir = resolve5(input.outputDir);
+  const configDir = input.configDir ? resolve5(input.configDir) : void 0;
+  await assertSourceDirExists(dataDir);
+  if (!await isDirectoryEmpty(outputDir)) {
+    if (!input.replaceExisting) {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.backupConflict,
+        `Backup output directory is not empty: ${outputDir}`
+      );
+    }
+    await rm(outputDir, { recursive: true, force: true });
+  }
+  await mkdir(outputDir, { recursive: true });
+  const entries = [];
+  await copyDataDirForBackup(dataDir, join6(outputDir, "data"));
+  entries.push(...(await listEntries(join6(outputDir, "data"))).map((entry) => ({
+    ...entry,
+    relativePath: join6("data", entry.relativePath)
+  })));
+  if (configDir) {
+    await copyIfPresent(configDir, join6(outputDir, "config"), entries, "config");
+  }
+  const manifest = {
+    formatVersion: 1,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    packageVersion,
+    entries
+  };
+  const manifestPath = join6(outputDir, "manifest.json");
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
+  return {
+    outputDir,
+    manifestPath,
+    manifest
+  };
+}
+async function importBackup(input) {
+  const inputDir = resolve5(input.inputDir);
+  const dataDir = resolve5(input.dataDir);
+  const configDir = input.configDir ? resolve5(input.configDir) : void 0;
+  const { manifest, backupDataDir, backupConfigDir } = await loadValidatedBackupPayload(inputDir);
+  if (!await isDirectoryEmpty(dataDir)) {
+    if (!input.replaceExisting) {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.backupConflict,
+        `Backup target data directory is not empty: ${dataDir}`
+      );
+    }
+  }
+  if (configDir && backupConfigDir && !await isDirectoryEmpty(configDir)) {
+    if (!input.replaceExisting) {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.backupConflict,
+        `Backup target config directory is not empty: ${configDir}`
+      );
+    }
+  }
+  const stagedDataDir = await prepareReplacementTarget(backupDataDir, dataDir);
+  const stagedConfigDir = configDir && backupConfigDir ? await prepareReplacementTarget(backupConfigDir, configDir) : void 0;
+  try {
+    await rm(dataDir, { recursive: true, force: true });
+    await rename(stagedDataDir, dataDir);
+    if (configDir && stagedConfigDir) {
+      await rm(configDir, { recursive: true, force: true });
+      await rename(stagedConfigDir, configDir);
+    }
+  } catch (error) {
+    await rm(stagedDataDir, { recursive: true, force: true });
+    if (stagedConfigDir) {
+      await rm(stagedConfigDir, { recursive: true, force: true });
+    }
+    throw error;
+  }
+  return {
+    inputDir,
+    dataDir,
+    ...configDir ? { configDir } : {},
+    manifest
+  };
+}
+
+// src/coverage.ts
+import { readFile as readFile3 } from "fs/promises";
+import { resolve as resolve6 } from "path";
+function normalizeText(value) {
+  return value.replace(/[`*_~]+/g, "").replace(/\s+/g, " ").trim().toLowerCase();
+}
+function extractHeadings(markdown) {
+  const matches = [...markdown.matchAll(/^#{1,6}\s+(.+)$/gm)];
+  return matches.map((match) => match[1]?.trim() ?? "").filter(Boolean);
+}
+function extractComparableLines(markdown) {
+  return markdown.split("\n").map((line) => line.replace(/^\s*(#{1,6}|\d+\.\s+|[-*+]\s+)/, "").trim()).map((line) => normalizeText(line)).filter(Boolean);
+}
+function classifyHeading(heading, pageTitles, sectionTitles, comparableMarkdownLines) {
+  const normalizedHeading = normalizeText(heading);
+  if (!normalizedHeading) {
+    return null;
+  }
+  if (pageTitles.has(normalizedHeading)) {
+    return "page_title";
+  }
+  if (sectionTitles.has(normalizedHeading)) {
+    return "section_title";
+  }
+  if (comparableMarkdownLines.has(normalizedHeading)) {
+    return "body";
+  }
+  return null;
+}
+async function verifyCoverageAgainstReferences(corpus, referenceFiles) {
+  if (referenceFiles.length === 0) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.invalidArgument,
+      "At least one reference file is required for coverage verification."
+    );
+  }
+  const pageTitles = new Set(corpus.entries.map((entry) => normalizeText(entry.pageTitle)).filter(Boolean));
+  const sectionTitles = new Set(corpus.entries.map((entry) => normalizeText(entry.sectionTitle)).filter(Boolean));
+  const comparableMarkdownLines = new Set(
+    corpus.entries.flatMap((entry) => extractComparableLines(entry.markdown))
+  );
+  const files = [];
+  let headingCount = 0;
+  let matchedHeadingCount = 0;
+  let missingHeadingCount = 0;
+  const matchCounts = {
+    pageTitle: 0,
+    sectionTitle: 0,
+    body: 0
+  };
+  for (const referenceFile of referenceFiles) {
+    const resolvedReferenceFile = resolve6(referenceFile);
+    let raw;
+    try {
+      raw = await readFile3(resolvedReferenceFile, "utf8");
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.referenceFileNotFound,
+          `Reference file not found: ${resolvedReferenceFile}`
+        );
+      }
+      throw error;
+    }
+    const headings = extractHeadings(raw);
+    if (headings.length === 0) {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.invalidReferenceFile,
+        `Reference file does not contain any markdown headings: ${resolvedReferenceFile}`
+      );
+    }
+    const fileMatchCounts = {
+      pageTitle: 0,
+      sectionTitle: 0,
+      body: 0
+    };
+    const missingHeadings = [];
+    for (const heading of headings) {
+      const matchType = classifyHeading(heading, pageTitles, sectionTitles, comparableMarkdownLines);
+      if (matchType === "page_title") {
+        fileMatchCounts.pageTitle += 1;
+        matchCounts.pageTitle += 1;
+        matchedHeadingCount += 1;
+      } else if (matchType === "section_title") {
+        fileMatchCounts.sectionTitle += 1;
+        matchCounts.sectionTitle += 1;
+        matchedHeadingCount += 1;
+      } else if (matchType === "body") {
+        fileMatchCounts.body += 1;
+        matchCounts.body += 1;
+        matchedHeadingCount += 1;
+      } else {
+        missingHeadings.push(heading);
+        missingHeadingCount += 1;
+      }
+    }
+    headingCount += headings.length;
+    files.push({
+      referenceFile: resolvedReferenceFile,
+      headingCount: headings.length,
+      matchedHeadingCount: headings.length - missingHeadings.length,
+      missingHeadingCount: missingHeadings.length,
+      missingHeadings,
+      matchCounts: fileMatchCounts
+    });
+  }
+  return {
+    sourceId: corpus.sourceId,
+    snapshotId: corpus.snapshotId,
+    complete: missingHeadingCount === 0,
+    summary: {
+      fileCount: files.length,
+      headingCount,
+      matchedHeadingCount,
+      missingHeadingCount,
+      matchCounts
+    },
+    files
+  };
+}
+
+// src/doctor.ts
+import { access as access2 } from "fs/promises";
+import { execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+function summarize(checks) {
+  const passCount = checks.filter((check) => check.status === "pass").length;
+  const warnCount = checks.filter((check) => check.status === "warn").length;
+  const failCount = checks.filter((check) => check.status === "fail").length;
+  return {
+    status: failCount > 0 ? "unhealthy" : warnCount > 0 ? "degraded" : "healthy",
+    checkCount: checks.length,
+    passCount,
+    warnCount,
+    failCount
+  };
+}
+function toErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function parseTimestamp(value) {
+  if (!value) {
+    return null;
+  }
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+async function checkCatalog(env) {
+  const dataDir = getAiocsDataDir(env);
+  const configDir = getAiocsConfigDir(env);
+  let catalog = null;
+  try {
+    catalog = openCatalog({ dataDir });
+    const sourceCount = catalog.listSources().length;
+    const projectLinkCount = catalog.listProjectLinks().length;
+    return {
+      id: "catalog",
+      status: "pass",
+      summary: `Catalog opened successfully at ${dataDir}`,
+      details: {
+        dataDir,
+        configDir,
+        sourceCount,
+        projectLinkCount
+      }
+    };
+  } catch (error) {
+    return {
+      id: "catalog",
+      status: "fail",
+      summary: `Catalog unavailable: ${toErrorMessage(error)}`,
+      details: {
+        dataDir,
+        configDir
+      }
+    };
+  } finally {
+    catalog?.close();
+  }
+}
+async function checkPlaywright() {
+  try {
+    const { chromium: chromium2 } = await import("playwright");
+    const executablePath = chromium2.executablePath();
+    if (!executablePath) {
+      return {
+        id: "playwright",
+        status: "fail",
+        summary: "Playwright is installed but Chromium has no resolved executable path."
+      };
+    }
+    await access2(executablePath);
+    return {
+      id: "playwright",
+      status: "pass",
+      summary: "Playwright Chromium executable is available.",
+      details: {
+        executablePath
+      }
+    };
+  } catch (error) {
+    return {
+      id: "playwright",
+      status: "fail",
+      summary: `Playwright is not ready: ${toErrorMessage(error)}`
+    };
+  }
+}
+async function checkDaemonConfig(env) {
+  try {
+    const daemonConfig = parseDaemonConfig(env, {
+      bundledSourceDir: getBundledSourcesDir()
+    });
+    return {
+      daemonConfig,
+      daemonConfigCheck: {
+        id: "daemon-config",
+        status: "pass",
+        summary: "Daemon configuration parsed successfully.",
+        details: daemonConfig
+      }
+    };
+  } catch (error) {
+    return {
+      daemonConfig: null,
+      daemonConfigCheck: {
+        id: "daemon-config",
+        status: "fail",
+        summary: `Daemon configuration is invalid: ${toErrorMessage(error)}`
+      }
+    };
+  }
+}
+async function checkSourceSpecDirs(daemonConfig) {
+  if (!daemonConfig) {
+    return {
+      id: "source-spec-dirs",
+      status: "fail",
+      summary: "Source spec directories cannot be validated until daemon configuration is valid."
+    };
+  }
+  const directories = await Promise.all(daemonConfig.sourceSpecDirs.map(async (directory) => {
+    const exists = await pathExists(directory);
+    const specFiles = exists ? await walkSourceSpecFiles(directory) : [];
+    return {
+      directory,
+      exists,
+      specCount: specFiles.length
+    };
+  }));
+  const existingCount = directories.filter((directory) => directory.exists).length;
+  const totalSpecCount = directories.reduce((sum, directory) => sum + directory.specCount, 0);
+  let status = "pass";
+  let summary = `Validated ${directories.length} source spec director${directories.length === 1 ? "y" : "ies"}.`;
+  if (directories.length === 0) {
+    status = "fail";
+    summary = "No source spec directories are configured.";
+  } else if (daemonConfig.strictSourceSpecDirs && directories.some((directory) => !directory.exists)) {
+    status = "fail";
+    summary = "One or more explicitly configured source spec directories are missing.";
+  } else if (existingCount === 0) {
+    status = "warn";
+    summary = "No configured source spec directories currently exist.";
+  } else if (totalSpecCount === 0) {
+    status = "warn";
+    summary = "Configured source spec directories exist but contain no source specs.";
+  } else if (directories.some((directory) => !directory.exists)) {
+    status = "warn";
+    summary = "Some optional source spec directories are missing.";
+  }
+  return {
+    id: "source-spec-dirs",
+    status,
+    summary,
+    details: {
+      strict: daemonConfig.strictSourceSpecDirs,
+      directories
+    }
+  };
+}
+async function checkFreshness(env) {
+  const dataDir = getAiocsDataDir(env);
+  let catalog = null;
+  try {
+    catalog = openCatalog({ dataDir });
+    const sources = catalog.listSources();
+    const referenceTime = Date.now();
+    if (sources.length === 0) {
+      return {
+        id: "freshness",
+        status: "pass",
+        summary: "No sources are registered, so no source freshness checks are pending.",
+        details: {
+          sourceCount: 0
+        }
+      };
+    }
+    const staleSources = sources.filter((source) => !source.lastSuccessfulSnapshotId || Date.parse(source.nextDueAt) <= referenceTime).map((source) => ({
+      sourceId: source.id,
+      nextDueAt: source.nextDueAt,
+      lastSuccessfulSnapshotAt: source.lastSuccessfulSnapshotAt,
+      lastSuccessfulSnapshotAgeMinutes: source.lastSuccessfulSnapshotAt ? Math.floor((referenceTime - Date.parse(source.lastSuccessfulSnapshotAt)) / 6e4) : null
+    }));
+    const staleCanaries = sources.filter(
+      (source) => source.nextCanaryDueAt && Date.parse(source.nextCanaryDueAt) <= referenceTime || source.lastCanaryStatus === "fail"
+    ).map((source) => ({
+      sourceId: source.id,
+      nextCanaryDueAt: source.nextCanaryDueAt,
+      lastCanaryCheckedAt: source.lastCanaryCheckedAt,
+      lastCanaryStatus: source.lastCanaryStatus
+    }));
+    const status = staleSources.length > 0 || staleCanaries.length > 0 ? "warn" : "pass";
+    const summary = status === "pass" ? "Source snapshots and canaries are fresh." : `Source freshness issues detected: ${staleSources.length} stale snapshot scope(s), ${staleCanaries.length} stale/failed canary scope(s).`;
+    return {
+      id: "freshness",
+      status,
+      summary,
+      details: {
+        sourceCount: sources.length,
+        staleSources,
+        staleCanaries,
+        checkedAt: new Date(referenceTime).toISOString()
+      }
+    };
+  } catch (error) {
+    return {
+      id: "freshness",
+      status: "fail",
+      summary: `Freshness checks failed: ${toErrorMessage(error)}`
+    };
+  } finally {
+    catalog?.close();
+  }
+}
+async function checkDaemonHeartbeat(env) {
+  const dataDir = getAiocsDataDir(env);
+  let catalog = null;
+  try {
+    catalog = openCatalog({ dataDir });
+    const daemonState = catalog.getDaemonState();
+    if (!daemonState) {
+      return {
+        id: "daemon-heartbeat",
+        status: "warn",
+        summary: "No daemon heartbeat has been recorded yet."
+      };
+    }
+    const intervalMinutes = daemonState.intervalMinutes ?? 60;
+    const completedAt = parseTimestamp(daemonState.lastCycleCompletedAt);
+    if (!completedAt) {
+      return {
+        id: "daemon-heartbeat",
+        status: "warn",
+        summary: "Daemon heartbeat exists but no completed cycle has been recorded yet.",
+        details: daemonState
+      };
+    }
+    const ageMinutes = Math.floor((Date.now() - completedAt) / 6e4);
+    const stale = ageMinutes > intervalMinutes * 2;
+    const unhealthyStatus = daemonState.lastCycleStatus === "failed" || daemonState.lastCycleStatus === "degraded";
+    return {
+      id: "daemon-heartbeat",
+      status: stale || unhealthyStatus ? "warn" : "pass",
+      summary: stale || unhealthyStatus ? `Daemon heartbeat is stale or unhealthy (age=${ageMinutes}m, status=${daemonState.lastCycleStatus ?? "unknown"}).` : `Daemon heartbeat is recent (age=${ageMinutes}m).`,
+      details: {
+        ...daemonState,
+        ageMinutes
+      }
+    };
+  } catch (error) {
+    return {
+      id: "daemon-heartbeat",
+      status: "fail",
+      summary: `Daemon heartbeat check failed: ${toErrorMessage(error)}`
+    };
+  } finally {
+    catalog?.close();
+  }
+}
+async function checkEmbeddingProvider(env) {
+  try {
+    const config = getHybridRuntimeConfig(env);
+    const status = await getEmbeddingProviderStatus(config);
+    return {
+      id: "embedding-provider",
+      status: status.ok ? "pass" : "warn",
+      summary: status.ok ? `Embedding provider is ready with model ${status.model}.` : `Embedding provider is reachable but model ${status.model} is not available locally.`,
+      details: status
+    };
+  } catch (error) {
+    return {
+      id: "embedding-provider",
+      status: "fail",
+      summary: `Embedding provider check failed: ${toErrorMessage(error)}`
+    };
+  }
+}
+async function checkVectorStore(env) {
+  try {
+    const config = getHybridRuntimeConfig(env);
+    const status = await new AiocsVectorStore(config).getHealth();
+    return {
+      id: "vector-store",
+      status: status.ok ? "pass" : "warn",
+      summary: status.ok ? `Qdrant is reachable at ${config.qdrantUrl}.` : `Qdrant is not ready at ${config.qdrantUrl}: ${status.errorMessage ?? "unknown error"}`,
+      details: {
+        qdrantUrl: config.qdrantUrl,
+        collection: config.qdrantCollection,
+        ...status.collections ? { collections: status.collections } : {}
+      }
+    };
+  } catch (error) {
+    return {
+      id: "vector-store",
+      status: "fail",
+      summary: `Vector store check failed: ${toErrorMessage(error)}`
+    };
+  }
+}
+async function checkEmbeddings(env) {
+  const dataDir = getAiocsDataDir(env);
+  let catalog = null;
+  try {
+    catalog = openCatalog({ dataDir });
+    const overview = catalog.getEmbeddingOverview();
+    const underIndexedSources = overview.sources.filter((source) => source.totalChunks > 0 && source.indexedChunks < source.totalChunks).map((source) => ({
+      sourceId: source.sourceId,
+      snapshotId: source.snapshotId,
+      coverageRatio: source.coverageRatio,
+      totalChunks: source.totalChunks,
+      indexedChunks: source.indexedChunks,
+      pendingChunks: source.pendingChunks,
+      failedChunks: source.failedChunks,
+      staleChunks: source.staleChunks
+    }));
+    const status = overview.queue.failedJobs > 0 ? "warn" : underIndexedSources.length > 0 || overview.queue.pendingJobs > 0 || overview.queue.runningJobs > 0 ? "warn" : "pass";
+    return {
+      id: "embeddings",
+      status,
+      summary: status === "pass" ? "Embedding coverage is complete for latest snapshots." : `Embedding backlog detected: ${overview.queue.pendingJobs} pending, ${overview.queue.runningJobs} running, ${overview.queue.failedJobs} failed job(s).`,
+      details: {
+        queue: overview.queue,
+        underIndexedSources
+      }
+    };
+  } catch (error) {
+    return {
+      id: "embeddings",
+      status: "fail",
+      summary: `Embedding status check failed: ${toErrorMessage(error)}`
+    };
+  } finally {
+    catalog?.close();
+  }
+}
+async function checkDocker() {
+  try {
+    const { stdout } = await execFileAsync("docker", ["info", "--format", "{{json .ServerVersion}}"]);
+    const version = JSON.parse(stdout.trim());
+    return {
+      id: "docker",
+      status: "pass",
+      summary: `Docker is available (server ${version}).`,
+      details: {
+        serverVersion: version
+      }
+    };
+  } catch (error) {
+    const message = toErrorMessage(error);
+    if (message.includes("ENOENT")) {
+      return {
+        id: "docker",
+        status: "warn",
+        summary: "Docker CLI is not installed; Docker-based daemon deployment is unavailable on this machine."
+      };
+    }
+    return {
+      id: "docker",
+      status: "warn",
+      summary: `Docker is not ready: ${message}`
+    };
+  }
+}
+async function runDoctor(env = process.env) {
+  const catalogCheck = await checkCatalog(env);
+  const playwrightCheck = await checkPlaywright();
+  const { daemonConfigCheck, daemonConfig } = await checkDaemonConfig(env);
+  const sourceSpecDirsCheck = await checkSourceSpecDirs(daemonConfig);
+  const freshnessCheck = await checkFreshness(env);
+  const daemonHeartbeatCheck = await checkDaemonHeartbeat(env);
+  const embeddingProviderCheck = await checkEmbeddingProvider(env);
+  const vectorStoreCheck = await checkVectorStore(env);
+  const embeddingsCheck = await checkEmbeddings(env);
+  const dockerCheck = await checkDocker();
+  const checks = [
+    catalogCheck,
+    playwrightCheck,
+    daemonConfigCheck,
+    sourceSpecDirsCheck,
+    freshnessCheck,
+    daemonHeartbeatCheck,
+    embeddingProviderCheck,
+    vectorStoreCheck,
+    embeddingsCheck,
+    dockerCheck
+  ];
+  return {
+    summary: summarize(checks),
+    checks
+  };
+}
+
+// src/hybrid/rank.ts
+function reciprocalRankFusion(candidateLists, rrfK) {
+  const byChunkId = /* @__PURE__ */ new Map();
+  for (const candidates of candidateLists) {
+    for (const candidate of candidates) {
+      const current = byChunkId.get(candidate.chunkId) ?? {
+        fusedScore: 0,
+        signals: /* @__PURE__ */ new Set()
+      };
+      current.fusedScore += 1 / (rrfK + candidate.rank);
+      current.signals.add(candidate.signal);
+      byChunkId.set(candidate.chunkId, current);
+    }
+  }
+  return [...byChunkId.entries()].map(([chunkId, value]) => ({
+    chunkId,
+    fusedScore: value.fusedScore,
+    signals: [...value.signals]
+  })).sort((left, right) => right.fusedScore - left.fusedScore || left.chunkId - right.chunkId);
+}
+
+// src/hybrid/search.ts
+function windowSize(limit, offset, minimum) {
+  return Math.max(limit + offset, minimum);
+}
+function withScores(rows, scoreLookup) {
+  return rows.map((row) => {
+    const score = scoreLookup.get(row.chunkId) ?? {
+      score: 0,
+      signals: ["lexical"]
+    };
+    return {
+      ...row,
+      score: score.score,
+      signals: score.signals
+    };
+  });
+}
+async function searchHybridCatalog(input) {
+  const scope = input.catalog.resolveSearchScope({
+    query: input.query,
+    ...input.searchInput.cwd ? { cwd: input.searchInput.cwd } : {},
+    ...input.searchInput.sourceIds ? { sourceIds: input.searchInput.sourceIds } : {},
+    ...input.searchInput.snapshotId ? { snapshotId: input.searchInput.snapshotId } : {},
+    ...input.searchInput.all ? { all: true } : {},
+    ...typeof input.searchInput.limit === "number" ? { limit: input.searchInput.limit } : {},
+    ...typeof input.searchInput.offset === "number" ? { offset: input.searchInput.offset } : {}
+  });
+  const lexicalOnly = () => {
+    const lexical = input.catalog.searchLexical({
+      query: input.query,
+      scope
+    });
+    return {
+      query: input.query,
+      total: lexical.total,
+      limit: lexical.limit,
+      offset: lexical.offset,
+      hasMore: lexical.hasMore,
+      modeRequested: input.mode,
+      modeUsed: "lexical",
+      results: lexical.results.map((result, index) => ({
+        ...result,
+        score: 1 / (index + 1),
+        signals: ["lexical"]
+      }))
+    };
+  };
+  if (scope.snapshotIds.length === 0) {
+    return {
+      query: input.query,
+      total: 0,
+      limit: scope.limit,
+      offset: scope.offset,
+      hasMore: false,
+      modeRequested: input.mode,
+      modeUsed: input.mode === "semantic" ? "semantic" : "lexical",
+      results: []
+    };
+  }
+  if (input.mode === "lexical") {
+    return lexicalOnly();
+  }
+  const overview = input.catalog.getEmbeddingOverview();
+  const snapshotIdSet = new Set(scope.snapshotIds);
+  const scopedSources = overview.sources.filter(
+    (source) => source.snapshotId ? snapshotIdSet.has(source.snapshotId) : false
+  );
+  const allSnapshotsIndexed = scopedSources.every(
+    (source) => !source.snapshotId || source.totalChunks > 0 && source.indexedChunks === source.totalChunks
+  );
+  if (input.mode === "auto" && !allSnapshotsIndexed) {
+    return lexicalOnly();
+  }
+  let queryVector;
+  let vectorCandidates = [];
+  const modelKey = getEmbeddingModelKey(input.config);
+  try {
+    const embedding = await embedTexts(input.config, [input.query]);
+    queryVector = embedding[0];
+    if (!queryVector) {
+      throw new AiocsError(
+        AIOCS_ERROR_CODES.embeddingProviderUnavailable,
+        "Embedding provider returned no vector for the search query"
+      );
+    }
+    const vectorStore = new AiocsVectorStore(input.config);
+    vectorCandidates = await vectorStore.search({
+      vector: queryVector,
+      snapshotIds: scope.snapshotIds,
+      sourceIds: scope.sourceIds,
+      modelKey,
+      limit: windowSize(scope.limit, scope.offset, input.config.vectorCandidateWindow)
+    });
+  } catch (error) {
+    if (input.mode === "auto") {
+      return lexicalOnly();
+    }
+    throw error;
+  }
+  if (input.mode === "auto" && vectorCandidates.length === 0) {
+    return lexicalOnly();
+  }
+  if (input.mode === "semantic") {
+    const orderedChunkIds2 = vectorCandidates.map((candidate) => candidate.chunkId);
+    const chunkRows2 = input.catalog.getChunksByIds(orderedChunkIds2);
+    const chunkMap2 = new Map(chunkRows2.map((row) => [row.chunkId, row]));
+    const orderedRows2 = orderedChunkIds2.map((chunkId) => chunkMap2.get(chunkId)).filter((row) => Boolean(row));
+    const pagedRows2 = orderedRows2.slice(scope.offset, scope.offset + scope.limit);
+    const scoreLookup2 = new Map(vectorCandidates.map((candidate) => [
+      candidate.chunkId,
+      { score: candidate.score, signals: ["vector"] }
+    ]));
+    return {
+      query: input.query,
+      total: orderedRows2.length,
+      limit: scope.limit,
+      offset: scope.offset,
+      hasMore: scope.offset + pagedRows2.length < orderedRows2.length,
+      modeRequested: input.mode,
+      modeUsed: "semantic",
+      results: withScores(pagedRows2, scoreLookup2)
+    };
+  }
+  const lexicalCandidates = input.catalog.searchLexical({
+    query: input.query,
+    scope,
+    limit: windowSize(scope.limit, scope.offset, input.config.lexicalCandidateWindow),
+    offset: 0
+  });
+  const fused = reciprocalRankFusion([
+    lexicalCandidates.results.map((result, index) => ({
+      chunkId: result.chunkId,
+      rank: index + 1,
+      signal: "lexical"
+    })),
+    vectorCandidates.map((result, index) => ({
+      chunkId: result.chunkId,
+      rank: index + 1,
+      signal: "vector",
+      score: result.score
+    }))
+  ], input.config.rrfK);
+  const orderedChunkIds = fused.map((result) => result.chunkId);
+  const chunkRows = input.catalog.getChunksByIds(orderedChunkIds);
+  const chunkMap = new Map(chunkRows.map((row) => [row.chunkId, row]));
+  const orderedRows = orderedChunkIds.map((chunkId) => chunkMap.get(chunkId)).filter((row) => Boolean(row));
+  const pagedRows = orderedRows.slice(scope.offset, scope.offset + scope.limit);
+  const scoreLookup = new Map(fused.map((candidate) => [
+    candidate.chunkId,
+    {
+      score: candidate.fusedScore,
+      signals: candidate.signals
+    }
+  ]));
+  return {
+    query: input.query,
+    total: orderedRows.length,
+    limit: scope.limit,
+    offset: scope.offset,
+    hasMore: scope.offset + pagedRows.length < orderedRows.length,
+    modeRequested: input.mode,
+    modeUsed: "hybrid",
+    results: withScores(pagedRows, scoreLookup)
+  };
+}
+
+// src/services.ts
+function createCatalog() {
+  const dataDir = getAiocsDataDir();
+  getAiocsConfigDir();
+  return {
+    dataDir,
+    catalog: openCatalog({ dataDir })
+  };
+}
+function withCatalog(run) {
+  const ctx = createCatalog();
+  return Promise.resolve(run(ctx)).finally(() => ctx.catalog.close());
+}
+async function upsertSourceFromSpecFile(specFile) {
+  const specPath = resolve7(specFile);
+  const spec = await loadSourceSpec(specPath);
+  const result = await withCatalog(({ catalog }) => catalog.upsertSource(spec, { specPath }));
+  return {
+    sourceId: result.sourceId,
+    configHash: result.configHash,
+    specPath
+  };
+}
+async function listSources() {
+  const sources = await withCatalog(({ catalog }) => catalog.listSources());
+  return { sources };
+}
+async function fetchSources(sourceIdOrAll) {
+  const results = await withCatalog(async ({ catalog, dataDir }) => {
+    const sourceIds = sourceIdOrAll === "all" ? catalog.listSources().map((item) => item.id) : [sourceIdOrAll];
+    if (sourceIds.length === 0) {
+      return [];
+    }
+    const fetched = [];
+    for (const sourceId of sourceIds) {
+      const result = await fetchSource({ catalog, sourceId, dataDir });
+      fetched.push({
+        sourceId,
+        snapshotId: result.snapshotId,
+        pageCount: result.pageCount,
+        reused: result.reused
+      });
+    }
+    await processEmbeddingJobs({
+      catalog,
+      config: getHybridRuntimeConfig()
+    });
+    return fetched;
+  });
+  return { results };
+}
+async function refreshDueSources(sourceIdOrAll = "all") {
+  const results = await withCatalog(async ({ catalog, dataDir }) => {
+    const dueIds = sourceIdOrAll === "all" ? catalog.listDueSourceIds() : (() => {
+      const spec = catalog.getSourceSpec(sourceIdOrAll);
+      if (!spec) {
+        throw new AiocsError(
+          AIOCS_ERROR_CODES.sourceNotFound,
+          `Unknown source '${sourceIdOrAll}'`
+        );
+      }
+      return catalog.listDueSourceIds().includes(sourceIdOrAll) ? [sourceIdOrAll] : [];
+    })();
+    const fetched = [];
+    for (const sourceId of dueIds) {
+      const result = await fetchSource({ catalog, sourceId, dataDir });
+      fetched.push({
+        sourceId,
+        snapshotId: result.snapshotId,
+        pageCount: result.pageCount,
+        reused: result.reused
+      });
+    }
+    await processEmbeddingJobs({
+      catalog,
+      config: getHybridRuntimeConfig()
+    });
+    return fetched;
+  });
+  return { results };
+}
+async function runSourceCanaries(sourceIdOrAll) {
+  const results = await withCatalog(async ({ catalog }) => {
+    const sourceIds = sourceIdOrAll === "all" ? catalog.listSources().map((item) => item.id) : [sourceIdOrAll];
+    if (sourceIds.length === 0) {
+      return [];
+    }
+    const canaried = [];
+    for (const sourceId of sourceIds) {
+      canaried.push(await runSourceCanary({
+        catalog,
+        sourceId,
+        env: process.env
+      }));
+    }
+    return canaried;
+  });
+  return { results };
+}
+async function listSnapshotsForSource(sourceId) {
+  const snapshots = await withCatalog(({ catalog }) => catalog.listSnapshots(sourceId));
+  return {
+    sourceId,
+    snapshots
+  };
+}
+async function diffSnapshotsForSource(input) {
+  return withCatalog(({ catalog }) => catalog.diffSnapshots(input));
+}
+async function linkProjectSources(projectPath, sourceIds) {
+  const resolvedProjectPath = resolve7(projectPath);
+  await withCatalog(({ catalog }) => {
+    catalog.linkProject(resolvedProjectPath, sourceIds);
+  });
+  return {
+    projectPath: resolvedProjectPath,
+    sourceIds
+  };
+}
+async function unlinkProjectSources(projectPath, sourceIds) {
+  const resolvedProjectPath = resolve7(projectPath);
+  await withCatalog(({ catalog }) => {
+    catalog.unlinkProject(resolvedProjectPath, sourceIds);
+  });
+  return {
+    projectPath: resolvedProjectPath,
+    sourceIds
+  };
+}
+async function searchCatalog(query, options) {
+  const cwd = options.project ? resolve7(options.project) : process.cwd();
+  const explicitSources = options.source.length > 0;
+  const results = await withCatalog(({ 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."
+      );
+    }
+    return 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 } : {},
+        ...typeof options.limit === "number" ? { limit: options.limit } : {},
+        ...typeof options.offset === "number" ? { offset: options.offset } : {}
+      }
+    });
+  });
+  return {
+    query,
+    total: results.total,
+    limit: results.limit,
+    offset: results.offset,
+    hasMore: results.hasMore,
+    modeRequested: results.modeRequested,
+    modeUsed: results.modeUsed,
+    results: results.results
+  };
+}
+async function showChunk(chunkId) {
+  const chunk = await withCatalog(({ catalog }) => catalog.getChunkById(chunkId));
+  if (!chunk) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.chunkNotFound,
+      `Chunk ${chunkId} not found`
+    );
+  }
+  return { chunk };
+}
+async function verifyCoverage(input) {
+  return withCatalog(async ({ catalog }) => {
+    const corpus = catalog.getCoverageCorpus({
+      sourceId: input.sourceId,
+      ...input.snapshotId ? { snapshotId: input.snapshotId } : {}
+    });
+    return verifyCoverageAgainstReferences(corpus, input.referenceFiles);
+  });
+}
+async function initBuiltInSources(options) {
+  const sourceSpecDir = options?.sourceSpecDir ?? getBundledSourcesDir();
+  const fetched = options?.fetch ?? false;
+  const userSourceDir = getAiocsSourcesDir();
+  return withCatalog(async ({ catalog, dataDir }) => {
+    const bootstrapped = await bootstrapSourceSpecs({
+      catalog,
+      sourceSpecDirs: [sourceSpecDir],
+      strictSourceSpecDirs: true
+    });
+    const fetchResults = [];
+    if (fetched) {
+      for (const source of bootstrapped.sources) {
+        const result = await fetchSource({
+          catalog,
+          dataDir,
+          sourceId: source.sourceId
+        });
+        fetchResults.push({
+          sourceId: source.sourceId,
+          snapshotId: result.snapshotId,
+          pageCount: result.pageCount,
+          reused: result.reused
+        });
+      }
+      await processEmbeddingJobs({
+        catalog,
+        config: getHybridRuntimeConfig()
+      });
+    }
+    return {
+      sourceSpecDir,
+      userSourceDir,
+      fetched,
+      initializedSources: bootstrapped.sources,
+      removedSourceIds: bootstrapped.removedSourceIds,
+      fetchResults
+    };
+  });
+}
+function getManagedSourceSpecDirectories() {
+  return {
+    bundledSourceDir: getBundledSourcesDir(),
+    userSourceDir: getAiocsSourcesDir()
+  };
+}
+function getDoctorReport(env = process.env) {
+  return runDoctor(env);
+}
+async function exportCatalogBackup(input) {
+  return exportBackup({
+    dataDir: getAiocsDataDir(),
+    configDir: getAiocsConfigDir(),
+    outputDir: input.outputDir,
+    ...typeof input.replaceExisting === "boolean" ? { replaceExisting: input.replaceExisting } : {}
+  });
+}
+async function importCatalogBackup(input) {
+  const result = await importBackup({
+    inputDir: input.inputDir,
+    dataDir: getAiocsDataDir(),
+    configDir: getAiocsConfigDir(),
+    ...typeof input.replaceExisting === "boolean" ? { replaceExisting: input.replaceExisting } : {}
+  });
+  try {
+    await new AiocsVectorStore(getHybridRuntimeConfig()).clearCollection();
+  } catch {
+  }
+  await withCatalog(({ catalog }) => {
+    catalog.resetEmbeddingsAfterImport();
+  });
+  return result;
+}
+async function getEmbeddingStatus() {
+  return withCatalog(({ catalog }) => catalog.getEmbeddingOverview());
+}
+async function backfillEmbeddings(sourceIdOrAll) {
+  return withCatalog(({ catalog }) => sourceIdOrAll === "all" ? catalog.requeueLatestEmbeddingJobs() : catalog.requeueLatestEmbeddingJobs([sourceIdOrAll]));
+}
+async function clearEmbeddings(sourceIdOrAll) {
+  return withCatalog(async ({ catalog }) => {
+    const hybridConfig = getHybridRuntimeConfig();
+    const vectorStore = new AiocsVectorStore(hybridConfig);
+    if (sourceIdOrAll === "all") {
+      await vectorStore.clearCollection();
+      return catalog.clearEmbeddings();
+    }
+    const chunkIds = catalog.listEmbeddingChunkIds([sourceIdOrAll]);
+    if (chunkIds.length > 0) {
+      await vectorStore.deleteChunkIds(chunkIds);
+    }
+    return catalog.clearEmbeddings([sourceIdOrAll]);
+  });
+}
+async function runEmbeddingWorker() {
+  return withCatalog(({ catalog }) => processEmbeddingJobs({
+    catalog,
+    config: getHybridRuntimeConfig()
+  }));
+}
+
+export {
+  AIOCS_ERROR_CODES,
+  AiocsError,
+  toAiocsError,
+  openCatalog,
+  getAiocsDataDir,
+  getAiocsConfigDir,
+  parseDaemonConfig,
+  startDaemon,
+  packageName,
+  packageVersion,
+  packageDescription,
+  upsertSourceFromSpecFile,
+  listSources,
+  fetchSources,
+  refreshDueSources,
+  runSourceCanaries,
+  listSnapshotsForSource,
+  diffSnapshotsForSource,
+  linkProjectSources,
+  unlinkProjectSources,
+  searchCatalog,
+  showChunk,
+  verifyCoverage,
+  initBuiltInSources,
+  getManagedSourceSpecDirectories,
+  getDoctorReport,
+  exportCatalogBackup,
+  importCatalogBackup,
+  getEmbeddingStatus,
+  backfillEmbeddings,
+  clearEmbeddings,
+  runEmbeddingWorker
+};