@bodhi-ventures/aiocs 0.1.2 → 0.2.0

package/dist/{chunk-CZ6C4YUX.js → chunk-M7YEYMJL.js}

@@ -150,42 +150,91 @@ import Database from "better-sqlite3";
 
 // src/catalog/chunking.ts
 var MAX_CHUNK_BYTES = 16384;
+var CHUNK_OVERLAP_LINES = 6;
 var HEADING_PATTERN = /^(#{1,6})\s+(.*)$/;
 function byteLength(value) {
   return Buffer.byteLength(value, "utf8");
 }
+function normalizeLanguage(filePath, language) {
+  if (language) {
+    return language.toLowerCase();
+  }
+  if (!filePath) {
+    return null;
+  }
+  const lower = filePath.toLowerCase();
+  if (lower.endsWith(".md") || lower.endsWith(".mdx")) {
+    return "markdown";
+  }
+  if (lower.endsWith(".ts")) {
+    return "typescript";
+  }
+  if (lower.endsWith(".tsx")) {
+    return "tsx";
+  }
+  if (lower.endsWith(".js")) {
+    return "javascript";
+  }
+  if (lower.endsWith(".jsx")) {
+    return "jsx";
+  }
+  if (lower.endsWith(".json")) {
+    return "json";
+  }
+  if (lower.endsWith(".yaml") || lower.endsWith(".yml")) {
+    return "yaml";
+  }
+  if (lower.endsWith(".toml")) {
+    return "toml";
+  }
+  if (lower.endsWith(".py")) {
+    return "python";
+  }
+  if (lower.endsWith(".rs")) {
+    return "rust";
+  }
+  if (lower.endsWith(".go")) {
+    return "go";
+  }
+  if (lower.endsWith(".sql")) {
+    return "sql";
+  }
+  if (lower.endsWith(".sh")) {
+    return "shell";
+  }
+  return null;
+}
+function flushChunk(chunks, sectionTitle, current, chunkOrder) {
+  const trimmed = current.trim();
+  if (!trimmed) {
+    return chunkOrder;
+  }
+  chunks.push({
+    sectionTitle,
+    markdown: trimmed,
+    chunkOrder
+  });
+  return chunkOrder + 1;
+}
 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();
+      order = flushChunk(chunks, sectionTitle, current, order);
+      current = "";
     }
     current = current ? `${current}
 ${line}` : line;
   }
-  flush();
+  flushChunk(chunks, sectionTitle, current, order);
   return chunks;
 }
-function chunkMarkdown(pageTitle, markdown) {
+function chunkMarkdownSectioned(pageTitle, markdown) {
   const trimmed = markdown.trim();
   if (!trimmed) {
     return [];
@@ -233,6 +282,154 @@ function chunkMarkdown(pageTitle, markdown) {
   }
   return chunks;
 }
+function symbolBoundary(line, language) {
+  const trimmed = line.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const patterns = [];
+  switch (language) {
+    case "typescript":
+    case "tsx":
+    case "javascript":
+    case "jsx":
+      patterns.push(
+        /^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+([A-Za-z0-9_$]+)/,
+        /^(?:export\s+)?(?:default\s+)?class\s+([A-Za-z0-9_$]+)/,
+        /^(?:export\s+)?(?:interface|type|enum)\s+([A-Za-z0-9_$]+)/,
+        /^(?:export\s+)?const\s+([A-Za-z0-9_$]+)\s*=/
+      );
+      break;
+    case "python":
+      patterns.push(/^(?:async\s+def|def|class)\s+([A-Za-z0-9_]+)/);
+      break;
+    case "rust":
+      patterns.push(/^(?:pub\s+)?(?:async\s+)?fn\s+([A-Za-z0-9_]+)/, /^(?:pub\s+)?(?:struct|enum|trait)\s+([A-Za-z0-9_]+)/);
+      break;
+    case "go":
+      patterns.push(/^func\s+([A-Za-z0-9_]+)/, /^type\s+([A-Za-z0-9_]+)/);
+      break;
+    case "json":
+    case "yaml":
+    case "toml":
+      patterns.push(/^["']?([A-Za-z0-9_.-]+)["']?\s*[:=]/);
+      break;
+    default:
+      patterns.push(/^(?:export\s+)?(?:async\s+)?function\s+([A-Za-z0-9_$]+)/, /^(?:class|interface|type|enum)\s+([A-Za-z0-9_$]+)/);
+      break;
+  }
+  for (const pattern of patterns) {
+    const match = trimmed.match(pattern);
+    if (match?.[1]) {
+      return match[1];
+    }
+  }
+  return null;
+}
+function discoverBoundaries(lines, title, language) {
+  const boundaries = [];
+  lines.forEach((line, index) => {
+    const symbol = symbolBoundary(line, language);
+    if (symbol) {
+      boundaries.push({
+        index,
+        title: symbol
+      });
+    }
+  });
+  if (boundaries.length === 0 || boundaries[0].index !== 0) {
+    boundaries.unshift({
+      index: 0,
+      title
+    });
+  }
+  return boundaries;
+}
+function buildWindowTitle(title, startLine, endLine) {
+  return `${title} (${startLine}-${endLine})`;
+}
+function chunkLineWindows(title, content, startOrder) {
+  const lines = content.split("\n");
+  const chunks = [];
+  let start = 0;
+  let order = startOrder;
+  while (start < lines.length) {
+    let end = start;
+    let current = "";
+    while (end < lines.length) {
+      const candidate = current ? `${current}
+${lines[end]}` : lines[end];
+      if (current && byteLength(candidate) > MAX_CHUNK_BYTES) {
+        break;
+      }
+      current = candidate;
+      end += 1;
+    }
+    const trimmed = current.trim();
+    if (!trimmed) {
+      break;
+    }
+    chunks.push({
+      sectionTitle: buildWindowTitle(title, start + 1, end),
+      markdown: trimmed,
+      chunkOrder: order
+    });
+    order += 1;
+    if (end >= lines.length) {
+      break;
+    }
+    start = Math.max(start + 1, end - CHUNK_OVERLAP_LINES);
+  }
+  return chunks;
+}
+function chunkByBoundaries(input, language) {
+  const trimmed = input.content.trim();
+  if (!trimmed) {
+    return [];
+  }
+  if (byteLength(trimmed) <= MAX_CHUNK_BYTES) {
+    return [{ sectionTitle: input.title, markdown: trimmed, chunkOrder: 0 }];
+  }
+  const lines = trimmed.split("\n");
+  const boundaries = discoverBoundaries(lines, input.title, language);
+  const chunks = [];
+  let order = 0;
+  for (let index = 0; index < boundaries.length; index += 1) {
+    const boundary = boundaries[index];
+    const nextIndex = boundaries[index + 1]?.index ?? lines.length;
+    const sectionLines = lines.slice(boundary.index, nextIndex);
+    const sectionContent = sectionLines.join("\n").trim();
+    if (!sectionContent) {
+      continue;
+    }
+    if (byteLength(sectionContent) <= MAX_CHUNK_BYTES) {
+      chunks.push({
+        sectionTitle: boundary.title,
+        markdown: sectionContent,
+        chunkOrder: order
+      });
+      order += 1;
+      continue;
+    }
+    const splitChunks = chunkLineWindows(boundary.title, sectionContent, order);
+    chunks.push(...splitChunks);
+    order = chunks.length;
+  }
+  return chunks.length > 0 ? chunks : chunkLineWindows(input.title, trimmed, 0);
+}
+function chunkContent(input) {
+  const language = normalizeLanguage(input.filePath, input.language);
+  if (language === "markdown") {
+    return chunkMarkdownSectioned(input.title, input.content);
+  }
+  if (!language) {
+    return chunkLineWindows(input.title, input.content.trim(), 0);
+  }
+  return chunkByBoundaries(input, language);
+}
+function detectLanguage(filePath, language) {
+  return normalizeLanguage(filePath, language);
+}
 
 // src/catalog/fingerprint.ts
 import { createHash } from "crypto";
@@ -244,6 +441,7 @@ function buildSnapshotFingerprint(input) {
   const payload = JSON.stringify({
     sourceId: input.sourceId,
     configHash: input.configHash,
+    revisionKey: input.revisionKey ?? null,
     pages: normalizedPages
   });
   return sha256(payload);
@@ -272,22 +470,55 @@ function resolveProjectScope(cwd, scopes) {
   return normalizedScopes[0] ?? null;
 }
 
+// src/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(value, patterns) {
+  return patterns.some((pattern) => patternToRegex(pattern).test(value));
+}
+function toSqliteGlob(pattern) {
+  return pattern.replace(/\*\*/g, "*");
+}
+
 // 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 positiveIntSchema = z.number().int().positive();
+var scheduleSchema = z.object({
+  everyHours: positiveIntSchema
+});
 var interactionSchema = z.discriminatedUnion("action", [
   z.object({
     action: z.literal("hover"),
     selector: z.string().min(1),
-    timeoutMs: z.number().int().positive().optional()
+    timeoutMs: positiveIntSchema.optional()
   }),
   z.object({
     action: z.literal("click"),
     selector: z.string().min(1),
-    timeoutMs: z.number().int().positive().optional()
+    timeoutMs: positiveIntSchema.optional()
   }),
   z.object({
     action: z.literal("press"),
@@ -295,13 +526,13 @@ var interactionSchema = z.discriminatedUnion("action", [
   }),
   z.object({
     action: z.literal("wait"),
-    timeoutMs: z.number().int().positive()
+    timeoutMs: positiveIntSchema
   })
 ]);
 var clipboardExtractSchema = z.object({
   strategy: z.literal("clipboardButton"),
   interactions: z.array(interactionSchema).min(1),
-  clipboardTimeoutMs: z.number().int().positive().default(1e4)
+  clipboardTimeoutMs: positiveIntSchema.default(1e4)
 });
 var selectorExtractSchema = z.object({
   strategy: z.literal("selector"),
@@ -310,13 +541,13 @@ var selectorExtractSchema = z.object({
 var readabilityExtractSchema = z.object({
   strategy: z.literal("readability")
 });
-var authHeaderSchema = z.object({
+var webAuthHeaderSchema = 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({
+var webAuthCookieSchema = z.object({
   name: z.string().min(1),
   valueFromEnv: z.string().min(1),
   domain: z.string().min(1),
@@ -325,21 +556,36 @@ var authCookieSchema = z.object({
   httpOnly: z.boolean().optional(),
   sameSite: z.enum(["Strict", "Lax", "None"]).optional()
 });
-var canaryCheckSchema = z.object({
+var webCanaryCheckSchema = 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)
+  minMarkdownLength: positiveIntSchema.default(40)
+});
+var gitAuthSchema = z.object({
+  tokenFromEnv: z.string().min(1),
+  username: z.string().min(1).default("x-access-token"),
+  scheme: z.enum(["basic", "bearer"]).default("basic")
+});
+var gitCanaryCheckSchema = z.object({
+  path: z.string().min(1),
+  expectedTitle: z.string().min(1).optional(),
+  expectedText: z.string().min(1).optional(),
+  minContentLength: positiveIntSchema.default(40)
 });
-var sourceSpecSchema = z.object({
+var baseSourceSpecSchema = z.object({
   id: z.string().min(1).regex(/^[a-z0-9-]+$/),
   label: z.string().min(1),
+  schedule: scheduleSchema
+});
+var webSourceSpecSchema = baseSourceSpecSchema.extend({
+  kind: z.literal("web").default("web"),
   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()
+    exclude: z.array(patternSchema).default([]),
+    maxPages: positiveIntSchema
   }),
   extract: z.discriminatedUnion("strategy", [
     clipboardExtractSchema,
@@ -349,16 +595,13 @@ var sourceSpecSchema = z.object({
   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([])
+    headers: z.array(webAuthHeaderSchema).default([]),
+    cookies: z.array(webAuthCookieSchema).default([])
   }).optional(),
   canary: z.object({
-    everyHours: z.number().int().positive().optional(),
-    checks: z.array(canaryCheckSchema).min(1)
+    everyHours: positiveIntSchema.optional(),
+    checks: z.array(webCanaryCheckSchema).min(1)
   }).optional()
 }).superRefine((spec, context) => {
   for (const [index, header] of (spec.auth?.headers ?? []).entries()) {
@@ -376,6 +619,47 @@ var sourceSpecSchema = z.object({
     }
   }
 });
+var gitSourceSpecSchema = baseSourceSpecSchema.extend({
+  kind: z.literal("git"),
+  repo: z.object({
+    url: z.string().url(),
+    ref: z.string().min(1).default("HEAD"),
+    include: z.array(patternSchema).min(1),
+    exclude: z.array(patternSchema).default([]),
+    maxFiles: positiveIntSchema.default(2e3),
+    textFileMaxBytes: positiveIntSchema.default(262144),
+    auth: gitAuthSchema.optional()
+  }),
+  canary: z.object({
+    everyHours: positiveIntSchema.optional(),
+    checks: z.array(gitCanaryCheckSchema).min(1)
+  }).optional()
+}).superRefine((spec, context) => {
+  const protocol = new URL(spec.repo.url).protocol;
+  if (!["https:", "http:", "file:"].includes(protocol)) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["repo", "url"],
+      message: `Unsupported git source protocol '${protocol}'. Use https:// or file://.`
+    });
+  }
+});
+var sourceSpecSchema = z.preprocess((value) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return value;
+  }
+  const candidate = value;
+  if (!("kind" in candidate)) {
+    return {
+      ...candidate,
+      kind: "web"
+    };
+  }
+  return candidate;
+}, z.discriminatedUnion("kind", [
+  webSourceSpecSchema,
+  gitSourceSpecSchema
+]));
 function parseSourceSpec(raw, ext) {
   if (ext === ".json") {
     return JSON.parse(raw);
@@ -387,8 +671,27 @@ async function loadSourceSpec(path) {
   const parsed = parseSourceSpec(raw, extname(path).toLowerCase());
   return sourceSpecSchema.parse(parsed);
 }
+function parseSourceSpecObject(value) {
+  return sourceSpecSchema.parse(value);
+}
+function isGitSourceSpec(spec) {
+  return spec.kind === "git";
+}
 function resolveSourceCanary(spec) {
+  if (spec.kind === "git") {
+    return {
+      kind: "git",
+      everyHours: spec.canary?.everyHours ?? Math.max(1, Math.min(spec.schedule.everyHours, 6)),
+      checks: spec.canary?.checks ?? [
+        {
+          path: "README.md",
+          minContentLength: 40
+        }
+      ]
+    };
+  }
   return {
+    kind: "web",
     everyHours: spec.canary?.everyHours ?? Math.max(1, Math.min(spec.schedule.everyHours, 6)),
     checks: spec.canary?.checks ?? [
       {
@@ -440,6 +743,9 @@ function initSchema(db) {
       title TEXT NOT NULL,
       markdown TEXT NOT NULL,
       content_hash TEXT NOT NULL,
+      page_kind TEXT NOT NULL DEFAULT 'document' CHECK(page_kind IN ('document', 'file')),
+      file_path TEXT,
+      language TEXT,
       UNIQUE(snapshot_id, url)
     );
 
@@ -452,7 +758,10 @@ function initSchema(db) {
       page_title TEXT NOT NULL,
       section_title TEXT NOT NULL,
       chunk_order INTEGER NOT NULL,
-      markdown TEXT NOT NULL
+      markdown TEXT NOT NULL,
+      page_kind TEXT NOT NULL DEFAULT 'document' CHECK(page_kind IN ('document', 'file')),
+      file_path TEXT,
+      language TEXT
     );
 
     CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
@@ -568,6 +877,26 @@ function initSchema(db) {
   if (!sourceColumns.some((column) => column.name === "next_canary_due_at")) {
     db.exec("ALTER TABLE sources ADD COLUMN next_canary_due_at TEXT");
   }
+  const pageColumns = db.prepare("PRAGMA table_info(pages)").all();
+  if (!pageColumns.some((column) => column.name === "page_kind")) {
+    db.exec(`ALTER TABLE pages ADD COLUMN page_kind TEXT NOT NULL DEFAULT 'document'`);
+  }
+  if (!pageColumns.some((column) => column.name === "file_path")) {
+    db.exec("ALTER TABLE pages ADD COLUMN file_path TEXT");
+  }
+  if (!pageColumns.some((column) => column.name === "language")) {
+    db.exec("ALTER TABLE pages ADD COLUMN language TEXT");
+  }
+  const chunkColumns = db.prepare("PRAGMA table_info(chunks)").all();
+  if (!chunkColumns.some((column) => column.name === "page_kind")) {
+    db.exec(`ALTER TABLE chunks ADD COLUMN page_kind TEXT NOT NULL DEFAULT 'document'`);
+  }
+  if (!chunkColumns.some((column) => column.name === "file_path")) {
+    db.exec("ALTER TABLE chunks ADD COLUMN file_path TEXT");
+  }
+  if (!chunkColumns.some((column) => column.name === "language")) {
+    db.exec("ALTER TABLE chunks ADD COLUMN language TEXT");
+  }
 }
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
@@ -575,6 +904,9 @@ function nowIso() {
 function addHoursIso(hours) {
   return new Date(Date.now() + hours * 60 * 60 * 1e3).toISOString();
 }
+function resolveCanaryEveryHours(spec) {
+  return spec.canary?.everyHours ?? Math.max(1, Math.min(spec.schedule.everyHours, 6));
+}
 function stableStringify(value) {
   if (Array.isArray(value)) {
     return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
@@ -591,6 +923,20 @@ function normalizeQuery(query) {
   const words = query.replace(/[^\p{L}\p{N}]+/gu, " ").split(/\s+/).map((part) => part.trim()).filter(Boolean);
   return words.join(" ");
 }
+function normalizePatternFilters(patterns) {
+  if (!patterns || patterns.length === 0) {
+    return null;
+  }
+  const normalized = [...new Set(patterns.map((pattern) => pattern.trim()).filter(Boolean))];
+  return normalized.length > 0 ? normalized : null;
+}
+function normalizeLanguageFilters(languages) {
+  if (!languages || languages.length === 0) {
+    return null;
+  }
+  const normalized = [...new Set(languages.map((language) => language.trim().toLowerCase()).filter(Boolean))];
+  return normalized.length > 0 ? normalized : null;
+}
 function assertPaginationValue(value, field, fallback) {
   if (typeof value === "undefined") {
     return fallback;
@@ -647,7 +993,9 @@ function openCatalog(options) {
         limit,
         offset,
         sourceIds: null,
-        snapshotIds: []
+        snapshotIds: [],
+        pathPatterns: normalizePatternFilters(input.pathPatterns),
+        languages: normalizeLanguageFilters(input.languages)
       };
     }
     const filterSourceIds = sourceIds && sourceIds.length > 0 ? [...new Set(sourceIds)] : null;
@@ -661,7 +1009,9 @@ function openCatalog(options) {
       limit,
       offset,
       sourceIds: filterSourceIds,
-      snapshotIds: latestSnapshotIds
+      snapshotIds: latestSnapshotIds,
+      pathPatterns: normalizePatternFilters(input.pathPatterns),
+      languages: normalizeLanguageFilters(input.languages)
     };
   };
   const searchLexicalByScope = (input) => {
@@ -679,10 +1029,14 @@ function openCatalog(options) {
     }
     const whereSnapshotPlaceholders = input.scope.snapshotIds.map(() => "?").join(",");
     const sourceSql = input.scope.sourceIds ? `AND c.source_id IN (${input.scope.sourceIds.map(() => "?").join(",")})` : "";
+    const pathSql = input.scope.pathPatterns ? `AND c.file_path IS NOT NULL AND (${input.scope.pathPatterns.map(() => "c.file_path GLOB ?").join(" OR ")})` : "";
+    const languageSql = input.scope.languages ? `AND c.language IN (${input.scope.languages.map(() => "?").join(",")})` : "";
     const queryArgs = [
       normalized,
       ...input.scope.snapshotIds,
-      ...input.scope.sourceIds ?? []
+      ...input.scope.sourceIds ?? [],
+      ...(input.scope.pathPatterns ?? []).map((pattern) => toSqliteGlob(pattern)),
+      ...input.scope.languages ?? []
     ];
     const totalRow = db.prepare(`
       SELECT COUNT(*) AS total
@@ -691,6 +1045,8 @@ function openCatalog(options) {
       WHERE chunks_fts MATCH ?
         AND c.snapshot_id IN (${whereSnapshotPlaceholders})
         ${sourceSql}
+        ${pathSql}
+        ${languageSql}
     `).get(...queryArgs);
     const rows = db.prepare(`
       SELECT
@@ -700,12 +1056,17 @@ function openCatalog(options) {
         c.page_url,
         c.page_title,
         c.section_title,
-        c.markdown
+        c.markdown,
+        c.page_kind,
+        c.file_path,
+        c.language
       FROM chunks_fts
       JOIN chunks c ON c.id = chunks_fts.rowid
       WHERE chunks_fts MATCH ?
         AND c.snapshot_id IN (${whereSnapshotPlaceholders})
         ${sourceSql}
+        ${pathSql}
+        ${languageSql}
       ORDER BY bm25(chunks_fts), c.id
       LIMIT ?
       OFFSET ?
@@ -717,7 +1078,10 @@ function openCatalog(options) {
       pageUrl: row.page_url,
       pageTitle: row.page_title,
       sectionTitle: row.section_title,
-      markdown: row.markdown
+      markdown: row.markdown,
+      pageKind: row.page_kind,
+      filePath: row.file_path,
+      language: row.language
     }));
     return {
       total: totalRow.total,
@@ -889,8 +1253,8 @@ function openCatalog(options) {
       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 ? canonicalizeManagedSpecPath(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 canaryEveryHours = resolveCanaryEveryHours(spec);
+      const nextCanaryDueAt = !existing ? timestamp : existing.config_hash === configHash ? existing.next_canary_due_at ?? addHoursIso(canaryEveryHours) : timestamp;
       const configChanged = Boolean(existing && existing.config_hash !== configHash);
       db.prepare(`
         INSERT INTO sources (
@@ -935,6 +1299,7 @@ function openCatalog(options) {
         SELECT
           id,
           label,
+          spec_json,
           spec_path,
           next_due_at,
           next_canary_due_at,
@@ -947,21 +1312,25 @@ function openCatalog(options) {
         FROM sources
         ORDER BY id
       `).all();
-      return rows.map((row) => ({
-        id: row.id,
-        label: row.label,
-        specPath: row.spec_path ? canonicalizeManagedSpecPath(row.spec_path) : null,
-        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
-      }));
+      return rows.map((row) => {
+        const storedSpec = parseSourceSpecObject(JSON.parse(row.spec_json));
+        return {
+          id: row.id,
+          kind: storedSpec.kind,
+          label: row.label,
+          specPath: row.spec_path ? canonicalizeManagedSpecPath(row.spec_path) : null,
+          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(`
@@ -1022,11 +1391,15 @@ function openCatalog(options) {
       const pagesWithHashes = input.pages.map((page) => ({
         ...page,
         markdown: page.markdown.trim(),
-        contentHash: sha256(page.markdown.trim())
+        contentHash: sha256(page.markdown.trim()),
+        pageKind: page.pageKind ?? "document",
+        filePath: page.filePath ?? null,
+        language: detectLanguage(page.filePath, page.language)
       }));
       const fingerprint = buildSnapshotFingerprint({
         sourceId: input.sourceId,
         configHash: sourceRow.config_hash,
+        ...input.revisionKey ? { revisionKey: input.revisionKey } : {},
         pages: pagesWithHashes.map((page) => ({
           url: page.url,
           contentHash: page.contentHash
@@ -1063,13 +1436,13 @@ function openCatalog(options) {
         ) VALUES (?, ?, ?, ?, ?, ?, ?)
       `);
       const insertPage = db.prepare(`
-        INSERT INTO pages (snapshot_id, url, title, markdown, content_hash)
-        VALUES (?, ?, ?, ?, ?)
+        INSERT INTO pages (snapshot_id, url, title, markdown, content_hash, page_kind, file_path, language)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
       `);
       const insertChunk = db.prepare(`
         INSERT INTO chunks (
-          source_id, snapshot_id, page_id, page_url, page_title, section_title, chunk_order, markdown
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+          source_id, snapshot_id, page_id, page_url, page_title, section_title, chunk_order, markdown, page_kind, file_path, language
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `);
       const insertRun = db.prepare(`
         INSERT INTO fetch_runs (id, source_id, status, snapshot_id, started_at, finished_at)
@@ -1086,9 +1459,23 @@ function openCatalog(options) {
           checkedAt
         );
         for (const page of pagesWithHashes) {
-          const pageInsert = insertPage.run(snapshotId, page.url, page.title, page.markdown, page.contentHash);
+          const pageInsert = insertPage.run(
+            snapshotId,
+            page.url,
+            page.title,
+            page.markdown,
+            page.contentHash,
+            page.pageKind,
+            page.filePath,
+            page.language
+          );
           const pageId = Number(pageInsert.lastInsertRowid);
-          const chunks = chunkMarkdown(page.title, page.markdown);
+          const chunks = chunkContent({
+            title: page.title,
+            content: page.markdown,
+            filePath: page.filePath,
+            language: page.language
+          });
           for (const chunk of chunks) {
             insertChunk.run(
               input.sourceId,
@@ -1098,7 +1485,10 @@ function openCatalog(options) {
               page.title,
               chunk.sectionTitle,
               chunk.chunkOrder,
-              chunk.markdown
+              chunk.markdown,
+              page.pageKind,
+              page.filePath,
+              page.language
             );
           }
         }
@@ -1149,7 +1539,6 @@ function openCatalog(options) {
         );
       }
       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 (?, ?, ?, ?, ?)
@@ -1174,7 +1563,7 @@ function openCatalog(options) {
         input.status,
         input.checkedAt,
         input.status,
-        addHoursIso(canary.everyHours),
+        addHoursIso(resolveCanaryEveryHours(spec)),
         input.checkedAt,
         input.sourceId
       );
@@ -1254,7 +1643,7 @@ function openCatalog(options) {
         );
       }
       const loadSnapshotPages = (snapshotId) => db.prepare(`
-          SELECT url, title, markdown, content_hash
+          SELECT url, title, markdown, content_hash, page_kind, file_path, language
           FROM pages
           WHERE snapshot_id = ?
           ORDER BY url
@@ -1265,11 +1654,17 @@ function openCatalog(options) {
       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
+        title: page.title,
+        pageKind: page.page_kind,
+        filePath: page.file_path,
+        language: page.language
       }));
       const removedPages = beforePages.filter((page) => !afterMap.has(page.url)).map((page) => ({
         url: page.url,
-        title: page.title
+        title: page.title,
+        pageKind: page.page_kind,
+        filePath: page.file_path,
+        language: page.language
       }));
       const summarizeLineDiff = (beforeMarkdown, afterMarkdown) => {
         const beforeLines = beforeMarkdown.split("\n");
@@ -1294,6 +1689,9 @@ function openCatalog(options) {
         url: before.url,
         beforeTitle: before.title,
         afterTitle: after.title,
+        pageKind: after.page_kind,
+        filePath: after.file_path,
+        language: after.language,
         lineSummary: summarizeLineDiff(before.markdown, after.markdown)
       }));
       const unchangedPageCount = beforePages.filter((page) => {
@@ -1339,11 +1737,14 @@ function openCatalog(options) {
           c.page_url,
           c.page_title,
           c.section_title,
-          c.markdown
+          c.markdown,
+          c.page_kind,
+          c.file_path,
+          c.language
         FROM chunks c
         WHERE c.source_id = ?
           AND c.snapshot_id = ?
-        ORDER BY c.id
+      ORDER BY c.id
       `).all(input.sourceId, input.snapshotId);
       return rows.map((row) => ({
         chunkId: row.chunk_id,
@@ -1353,6 +1754,9 @@ function openCatalog(options) {
         pageTitle: row.page_title,
         sectionTitle: row.section_title,
         markdown: row.markdown,
+        pageKind: row.page_kind,
+        filePath: row.file_path,
+        language: row.language,
         contentHash: sha256(row.markdown)
       }));
     },
@@ -1403,7 +1807,10 @@ function openCatalog(options) {
           c.page_url,
           c.page_title,
           c.section_title,
-          c.markdown
+          c.markdown,
+          c.page_kind,
+          c.file_path,
+          c.language
         FROM chunks c
         WHERE c.id IN (${chunkIds.map(() => "?").join(",")})
       `).all(...chunkIds);
@@ -1414,7 +1821,10 @@ function openCatalog(options) {
         pageUrl: row.page_url,
         pageTitle: row.page_title,
         sectionTitle: row.section_title,
-        markdown: row.markdown
+        markdown: row.markdown,
+        pageKind: row.page_kind,
+        filePath: row.file_path,
+        language: row.language
       }));
     },
     queueLatestEmbeddingJobs(sourceIds) {
@@ -1798,7 +2208,10 @@ function openCatalog(options) {
           c.page_url,
           c.page_title,
           c.section_title,
-          c.markdown
+          c.markdown,
+          c.page_kind,
+          c.file_path,
+          c.language
         FROM chunks c
         WHERE c.id = ?
       `).get(chunkId);
@@ -1812,23 +2225,336 @@ function openCatalog(options) {
         pageUrl: row.page_url,
         pageTitle: row.page_title,
         sectionTitle: row.section_title,
-        markdown: row.markdown
+        markdown: row.markdown,
+        pageKind: row.page_kind,
+        filePath: row.file_path,
+        language: row.language
       };
     }
   };
 }
 
 // src/daemon.ts
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { resolve as resolve5 } from "path";
 import { setTimeout as sleep2 } from "timers/promises";
 
 // src/fetch/fetch-source.ts
-import { mkdirSync as mkdirSync3, writeFileSync } from "fs";
-import { join as join4 } from "path";
+import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync2 } from "fs";
+import { join as join5 } from "path";
 import { setTimeout as sleep } from "timers/promises";
 import { chromium } from "playwright";
 
+// src/git/git-source.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync3, writeFileSync } from "fs";
+import { dirname as dirname2, join as join4 } from "path";
+import { execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+function nowIso2() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function getGitMirrorDir(dataDir, sourceId) {
+  return join4(dataDir, "git-mirrors", `${sourceId}.git`);
+}
+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 buildGitAuthHeader(spec, env) {
+  if (!spec.repo.auth) {
+    return null;
+  }
+  const token = resolveEnvValue(spec.repo.auth.tokenFromEnv, env);
+  if (spec.repo.auth.scheme === "bearer") {
+    return `AUTHORIZATION: Bearer ${token}`;
+  }
+  const credentials = Buffer.from(`${spec.repo.auth.username}:${token}`, "utf8").toString("base64");
+  return `AUTHORIZATION: Basic ${credentials}`;
+}
+async function runGit(args, options = {}) {
+  const commandArgs = options.authHeader ? ["-c", `http.extraHeader=${options.authHeader}`, ...args] : args;
+  const result = await execFileAsync("git", commandArgs, {
+    cwd: options.cwd,
+    env: {
+      ...process.env,
+      ...options.env,
+      GIT_TERMINAL_PROMPT: "0"
+    },
+    encoding: options.encoding ?? "utf8",
+    maxBuffer: 32 * 1024 * 1024
+  }).catch((error) => {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.internalError,
+      `Git command failed: ${error instanceof Error ? error.message : String(error)}`,
+      {
+        args
+      }
+    );
+  });
+  return result.stdout;
+}
+async function ensureGitMirror(spec, dataDir, env) {
+  const mirrorDir = getGitMirrorDir(dataDir, spec.id);
+  mkdirSync3(dirname2(mirrorDir), { recursive: true });
+  const authHeader = buildGitAuthHeader(spec, env);
+  if (!existsSync2(mirrorDir)) {
+    await runGit(["clone", "--mirror", spec.repo.url, mirrorDir], {
+      env,
+      authHeader
+    });
+    return mirrorDir;
+  }
+  await runGit(["--git-dir", mirrorDir, "remote", "set-url", "origin", spec.repo.url], {
+    env,
+    authHeader
+  });
+  await runGit(["--git-dir", mirrorDir, "fetch", "--prune", "--prune-tags", "--tags", "origin"], {
+    env,
+    authHeader
+  });
+  return mirrorDir;
+}
+async function resolveGitCommit(mirrorDir, ref, env) {
+  const stdout = await runGit(["--git-dir", mirrorDir, "rev-parse", `${ref}^{commit}`], {
+    env
+  });
+  return String(stdout).trim();
+}
+async function listRepoFiles(mirrorDir, commitSha, env) {
+  const stdout = await runGit(["--git-dir", mirrorDir, "ls-tree", "-r", "-z", "--name-only", commitSha], {
+    env,
+    encoding: "buffer"
+  });
+  const entries = stdout instanceof Buffer ? stdout.toString("utf8") : String(stdout);
+  return entries.split("\0").map((entry) => entry.trim()).filter(Boolean);
+}
+function isIncluded(spec, filePath) {
+  if (!matchesPatterns(filePath, spec.repo.include)) {
+    return false;
+  }
+  if (spec.repo.exclude.length > 0 && matchesPatterns(filePath, spec.repo.exclude)) {
+    return false;
+  }
+  return true;
+}
+async function getObjectSize(mirrorDir, commitSha, filePath, env) {
+  const stdout = await runGit(["--git-dir", mirrorDir, "cat-file", "-s", `${commitSha}:${filePath}`], {
+    env
+  });
+  return Number(String(stdout).trim());
+}
+function isProbablyBinary(buffer) {
+  return buffer.includes(0);
+}
+async function readRepoFile(mirrorDir, commitSha, filePath, env) {
+  const stdout = await runGit(["--git-dir", mirrorDir, "show", `${commitSha}:${filePath}`], {
+    env,
+    encoding: "buffer"
+  });
+  return stdout instanceof Buffer ? stdout : Buffer.from(String(stdout), "utf8");
+}
+function normalizeRepoUrl(repoUrl) {
+  return new URL(repoUrl);
+}
+function normalizeRepoWebBase(repoUrl) {
+  const url = normalizeRepoUrl(repoUrl);
+  const pathname = url.pathname.replace(/\.git$/i, "");
+  return `${url.origin}${pathname}`;
+}
+function buildRepoFileUrl(spec, filePath) {
+  const url = normalizeRepoUrl(spec.repo.url);
+  const encodedPath = filePath.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  const encodedRef = spec.repo.ref.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  if (url.protocol === "file:") {
+    return `${spec.repo.url}#ref=${encodeURIComponent(spec.repo.ref)}&path=${encodeURIComponent(filePath)}`;
+  }
+  const base = normalizeRepoWebBase(spec.repo.url);
+  if (url.hostname === "github.com") {
+    return `${base}/blob/${encodedRef}/${encodedPath}`;
+  }
+  if (url.hostname === "gitlab.com") {
+    return `${base}/-/blob/${encodedRef}/${encodedPath}`;
+  }
+  return `${base}#ref=${encodeURIComponent(spec.repo.ref)}&path=${encodeURIComponent(filePath)}`;
+}
+function persistGitSnapshotFiles(input, snapshotId, pages) {
+  const snapshotDir = join4(input.dataDir, "sources", input.sourceId, "snapshots", snapshotId, "files");
+  for (const page of pages) {
+    const filePath = join4(snapshotDir, page.filePath);
+    mkdirSync3(dirname2(filePath), { recursive: true });
+    writeFileSync(filePath, page.markdown, "utf8");
+  }
+}
+async function materializeGitPages(spec, mirrorDir, commitSha, env) {
+  const repoFiles = await listRepoFiles(mirrorDir, commitSha, env);
+  const includedFiles = repoFiles.filter((filePath) => isIncluded(spec, filePath));
+  if (includedFiles.length > spec.repo.maxFiles) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.invalidArgument,
+      `Git source '${spec.id}' matched ${includedFiles.length} files, exceeding maxFiles=${spec.repo.maxFiles}`
+    );
+  }
+  const pages = [];
+  for (const filePath of includedFiles) {
+    const size = await getObjectSize(mirrorDir, commitSha, filePath, env);
+    if (!Number.isFinite(size) || size > spec.repo.textFileMaxBytes) {
+      continue;
+    }
+    const content = await readRepoFile(mirrorDir, commitSha, filePath, env).catch(() => null);
+    if (!content || isProbablyBinary(content)) {
+      continue;
+    }
+    const markdown = content.toString("utf8").trimEnd();
+    if (!markdown.trim()) {
+      continue;
+    }
+    pages.push({
+      url: buildRepoFileUrl(spec, filePath),
+      title: filePath,
+      markdown,
+      pageKind: "file",
+      filePath,
+      language: detectLanguage(filePath)
+    });
+  }
+  return pages.sort((left, right) => left.filePath.localeCompare(right.filePath));
+}
+function assertCanaryPathInScope(spec, check) {
+  if (!isIncluded(spec, check.path)) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.invalidArgument,
+      `Git canary path '${check.path}' is outside the configured include/exclude scope`
+    );
+  }
+}
+async function readCanaryTarget(spec, mirrorDir, commitSha, check, env) {
+  assertCanaryPathInScope(spec, check);
+  const content = await readRepoFile(mirrorDir, commitSha, check.path, env);
+  if (isProbablyBinary(content)) {
+    throw new Error(`Canary target '${check.path}' is binary`);
+  }
+  return {
+    url: buildRepoFileUrl(spec, check.path),
+    title: check.path,
+    markdown: content.toString("utf8").trimEnd(),
+    pageKind: "file",
+    filePath: check.path,
+    language: detectLanguage(check.path)
+  };
+}
+async function fetchGitSource(input) {
+  const spec = input.catalog.getSourceSpec(input.sourceId);
+  if (!spec || !isGitSourceSpec(spec)) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.sourceNotFound,
+      `Unknown git source '${input.sourceId}'`
+    );
+  }
+  const env = input.env ?? process.env;
+  const mirrorDir = await ensureGitMirror(spec, input.dataDir, env);
+  const commitSha = await resolveGitCommit(mirrorDir, spec.repo.ref, env);
+  const pages = await materializeGitPages(spec, mirrorDir, commitSha, env);
+  if (pages.length === 0) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.noPagesFetched,
+      `No text files fetched for git source '${input.sourceId}'`
+    );
+  }
+  const result = input.catalog.recordSuccessfulSnapshot({
+    sourceId: input.sourceId,
+    detectedVersion: commitSha,
+    revisionKey: commitSha,
+    pages
+  });
+  if (!result.reused) {
+    persistGitSnapshotFiles(input, result.snapshotId, pages);
+  }
+  return {
+    snapshotId: result.snapshotId,
+    pageCount: pages.length,
+    reused: result.reused,
+    detectedVersion: commitSha
+  };
+}
+async function runGitSourceCanary(input) {
+  const spec = input.catalog.getSourceSpec(input.sourceId);
+  if (!spec || !isGitSourceSpec(spec)) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.sourceNotFound,
+      `Unknown git source '${input.sourceId}'`
+    );
+  }
+  const env = input.env ?? process.env;
+  const dataDir = input.dataDir ?? join4(process.env.HOME ?? "", ".aiocs", "data");
+  const mirrorDir = await ensureGitMirror(spec, dataDir, env);
+  const commitSha = await resolveGitCommit(mirrorDir, spec.repo.ref, env);
+  const canary = resolveSourceCanary(spec);
+  const checkedAt = nowIso2();
+  const checks = [];
+  for (const check of canary.checks) {
+    try {
+      const page = await readCanaryTarget(spec, mirrorDir, commitSha, check, env);
+      if (check.expectedTitle && !page.title.includes(check.expectedTitle)) {
+        throw new Error(`Expected title to include '${check.expectedTitle}'`);
+      }
+      if (check.expectedText && !page.markdown.includes(check.expectedText)) {
+        throw new Error(`Expected markdown to include '${check.expectedText}'`);
+      }
+      if (page.markdown.trim().length < check.minContentLength) {
+        throw new Error(`Expected content length to be at least ${check.minContentLength}`);
+      }
+      checks.push({
+        path: check.path,
+        status: "pass",
+        title: page.title,
+        markdownLength: page.markdown.trim().length
+      });
+    } catch (error) {
+      checks.push({
+        path: check.path,
+        status: "fail",
+        errorMessage: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  const passCount = checks.filter((check) => check.status === "pass").length;
+  const failCount = checks.length - passCount;
+  const status = failCount > 0 ? "fail" : "pass";
+  const result = {
+    sourceId: input.sourceId,
+    status,
+    checkedAt,
+    summary: {
+      checkCount: checks.length,
+      passCount,
+      failCount
+    },
+    checks
+  };
+  input.catalog.recordCanaryRun({
+    sourceId: input.sourceId,
+    status,
+    checkedAt,
+    details: result
+  });
+  if (status === "fail") {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.canaryFailed,
+      `Git source canary failed for '${input.sourceId}'`,
+      result
+    );
+  }
+  return result;
+}
+
 // src/fetch/extract.ts
 import { JSDOM } from "jsdom";
 import { Readability } from "@mozilla/readability";
@@ -2009,36 +2735,10 @@ async function extractPage(page, strategy) {
   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() {
+function nowIso3() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
 function canonicalizeUrl(raw) {
@@ -2108,14 +2808,14 @@ async function extractRawMarkdownPage(url, response) {
   };
 }
 function persistSnapshotPages(input, snapshotId, pages) {
-  const snapshotDir = join4(input.dataDir, "sources", input.sourceId, "snapshots", snapshotId, "pages");
-  mkdirSync3(snapshotDir, { recursive: true });
+  const snapshotDir = join5(input.dataDir, "sources", input.sourceId, "snapshots", snapshotId, "pages");
+  mkdirSync4(snapshotDir, { recursive: true });
   pages.forEach((page, index) => {
     const filename = `${String(index + 1).padStart(3, "0")}-${slugify(page.title)}.md`;
-    writeFileSync(join4(snapshotDir, filename), page.markdown, "utf8");
+    writeFileSync2(join5(snapshotDir, filename), page.markdown, "utf8");
   });
 }
-function resolveEnvValue(name, env) {
+function resolveEnvValue2(name, env) {
   const value = env[name];
   if (!value) {
     throw new AiocsError(
@@ -2131,13 +2831,13 @@ function resolveEnvValue(name, env) {
 function resolveSourceAuth(spec, env) {
   const scopedHeaders = (spec.auth?.headers ?? []).map((header) => ({
     name: header.name,
-    value: resolveEnvValue(header.valueFromEnv, env),
+    value: resolveEnvValue2(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),
+    value: resolveEnvValue2(cookie.valueFromEnv, env),
     domain: cookie.domain,
     path: cookie.path,
     ...typeof cookie.secure === "boolean" ? { secure: cookie.secure } : {},
@@ -2236,6 +2936,14 @@ async function fetchSourceOnce(input) {
       `Unknown source '${input.sourceId}'`
     );
   }
+  if (isGitSourceSpec(spec)) {
+    const result = await fetchGitSource(input);
+    return {
+      snapshotId: result.snapshotId,
+      pageCount: result.pageCount,
+      reused: result.reused
+    };
+  }
   const session = await createSourceContext(spec, input.env ?? process.env);
   const { page } = session;
   const queue = spec.startUrls.map((url) => canonicalizeUrl(url));
@@ -2362,6 +3070,9 @@ async function runSourceCanaryOnce(input) {
       `Unknown source '${input.sourceId}'`
     );
   }
+  if (isGitSourceSpec(spec)) {
+    return runGitSourceCanary(input);
+  }
   const canary = resolveSourceCanary(spec);
   const session = await createSourceContext(spec, input.env ?? process.env);
   const { page } = session;
@@ -2412,7 +3123,7 @@ async function runSourceCanaryOnce(input) {
   const result = {
     sourceId: input.sourceId,
     status: checks.every((check) => check.status === "pass") ? "pass" : "fail",
-    checkedAt: nowIso2(),
+    checkedAt: nowIso3(),
     summary: {
       checkCount: checks.length,
       passCount: checks.filter((check) => check.status === "pass").length,
@@ -2655,6 +3366,9 @@ var AiocsVectorStore = class {
         pageUrl: point.pageUrl,
         pageTitle: point.pageTitle,
         sectionTitle: point.sectionTitle,
+        pageKind: point.pageKind,
+        filePath: point.filePath,
+        language: point.language,
         modelKey: input.modelKey
       }
     }));
@@ -2867,7 +3581,10 @@ async function processEmbeddingJobs(input) {
             snapshotId: chunk.snapshotId,
             pageUrl: chunk.pageUrl,
             pageTitle: chunk.pageTitle,
-            sectionTitle: chunk.sectionTitle
+            sectionTitle: chunk.sectionTitle,
+            pageKind: chunk.pageKind,
+            filePath: chunk.filePath,
+            language: chunk.language
           }))
         });
         indexedChunkIds.push(...batch.map((chunk) => chunk.chunkId));
@@ -2960,7 +3677,7 @@ function getHybridRuntimeConfig(env = process.env) {
 // 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 resolve4 } from "path";
+import { extname as extname2, join as join6, resolve as resolve4 } from "path";
 var SOURCE_SPEC_EXTENSIONS = /* @__PURE__ */ new Set([".yaml", ".yml", ".json"]);
 function uniqueResolvedPaths(paths) {
   const seen = /* @__PURE__ */ new Set();
@@ -2987,7 +3704,7 @@ 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);
+    const entryPath = join6(rootDir, entry.name);
     if (entry.isDirectory()) {
       discovered.push(...await walkSourceSpecFiles(entryPath));
       continue;
@@ -3007,7 +3724,7 @@ 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() {
+function nowIso4() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
 function parsePositiveInteger2(raw, variableName) {
@@ -3033,7 +3750,7 @@ function parseBoolean(raw, variableName) {
 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 defaultContainerSourceDir = options.containerSourceDir ?? (existsSync2(DEFAULT_CONTAINER_SOURCE_DIR) ? DEFAULT_CONTAINER_SOURCE_DIR : void 0);
+  const defaultContainerSourceDir = options.containerSourceDir ?? (existsSync3(DEFAULT_CONTAINER_SOURCE_DIR) ? DEFAULT_CONTAINER_SOURCE_DIR : void 0);
   const defaultSourceDirs = uniqueResolvedPaths([
     options.bundledSourceDir ?? getBundledSourcesDir(),
     options.userSourceDir ?? getAiocsSourcesDir(env),
@@ -3097,7 +3814,7 @@ async function bootstrapSourceSpecs(input) {
   };
 }
 async function runDaemonCycle(input) {
-  const startedAt = nowIso3();
+  const startedAt = nowIso4();
   const bootstrapped = await bootstrapSourceSpecs({
     catalog: input.catalog,
     sourceSpecDirs: input.sourceSpecDirs,
@@ -3127,6 +3844,7 @@ async function runDaemonCycle(input) {
       const result = await runSourceCanary({
         catalog: input.catalog,
         sourceId,
+        dataDir: input.dataDir,
         env: process.env
       });
       canaried.push({
@@ -3185,7 +3903,7 @@ async function runDaemonCycle(input) {
   }
   return {
     startedAt,
-    finishedAt: nowIso3(),
+    finishedAt: nowIso4(),
     dueSourceIds,
     canaryDueSourceIds,
     bootstrapped,
@@ -3201,7 +3919,7 @@ async function startDaemon(input) {
   const intervalMs = input.config.intervalMinutes * 6e4;
   input.catalog.resetRunningEmbeddingJobs();
   input.catalog.markDaemonStarted({
-    startedAt: nowIso3(),
+    startedAt: nowIso4(),
     intervalMinutes: input.config.intervalMinutes,
     fetchOnStart: input.config.fetchOnStart
   });
@@ -3212,7 +3930,7 @@ async function startDaemon(input) {
     sourceSpecDirs: input.config.sourceSpecDirs
   });
   const runCycle = async (reason) => {
-    const startedAt = nowIso3();
+    const startedAt = nowIso4();
     input.catalog.markDaemonCycleStarted(startedAt);
     input.logger.emit({
       type: "daemon.cycle.started",
@@ -3238,7 +3956,7 @@ async function startDaemon(input) {
       });
     } catch (error) {
       input.catalog.markDaemonCycleCompleted({
-        completedAt: nowIso3(),
+        completedAt: nowIso4(),
         status: "failed"
       });
       throw error;
@@ -3269,7 +3987,7 @@ async function startDaemon(input) {
 // package.json
 var package_default = {
   name: "@bodhi-ventures/aiocs",
-  version: "0.1.2",
+  version: "0.2.0",
   license: "MIT",
   type: "module",
   description: "Local-only documentation store, fetcher, and search CLI for AI agents.",
@@ -3317,28 +4035,28 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@modelcontextprotocol/sdk": "^1.28.0",
-    "@mozilla/readability": "^0.6.0",
+    "@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"
+    "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"
+    "@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"
   }
 };
 
@@ -3352,7 +4070,7 @@ import { resolve as resolve8 } 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 resolve6 } from "path";
+import { basename, dirname as dirname3, join as join7, resolve as resolve6 } from "path";
 import { randomUUID as randomUUID2 } from "crypto";
 import Database2 from "better-sqlite3";
 var CATALOG_DB_FILENAME = "catalog.sqlite";
@@ -3380,7 +4098,7 @@ async function isDirectoryEmpty(path) {
   return (await readdir2(path)).length === 0;
 }
 async function listEntries(root, relativePath = "") {
-  const absolutePath = relativePath ? join6(root, relativePath) : root;
+  const absolutePath = relativePath ? join7(root, relativePath) : root;
   const stats = await stat(absolutePath);
   if (!stats.isDirectory()) {
     return [{
@@ -3396,7 +4114,7 @@ async function listEntries(root, relativePath = "") {
     size: 0
   }] : [];
   for (const childName of childNames.sort()) {
-    entries.push(...await listEntries(root, relativePath ? join6(relativePath, childName) : childName));
+    entries.push(...await listEntries(root, relativePath ? join7(relativePath, childName) : childName));
   }
   return entries;
 }
@@ -3410,12 +4128,12 @@ async function copyIfPresent(from, to, entries, relativePrefix) {
   entries.push(
     ...copiedEntries.map((entry) => ({
       ...entry,
-      relativePath: join6(relativePrefix, entry.relativePath)
+      relativePath: join7(relativePrefix, entry.relativePath)
     }))
   );
 }
 async function copyDataDirForBackup(from, to) {
-  const sourceCatalogPath = join6(from, CATALOG_DB_FILENAME);
+  const sourceCatalogPath = join7(from, CATALOG_DB_FILENAME);
   if (!await pathExists2(sourceCatalogPath)) {
     throw new AiocsError(
       AIOCS_ERROR_CODES.backupSourceMissing,
@@ -3431,10 +4149,13 @@ async function copyDataDirForBackup(from, to) {
       if (name === CATALOG_DB_FILENAME) {
         return false;
       }
+      if (name === "git-mirrors") {
+        return false;
+      }
       return !SQLITE_SIDE_CAR_SUFFIXES.some((suffix) => name === `${CATALOG_DB_FILENAME}${suffix}`);
     }
   });
-  const targetCatalogPath = join6(to, CATALOG_DB_FILENAME);
+  const targetCatalogPath = join7(to, CATALOG_DB_FILENAME);
   const sourceCatalog = new Database2(sourceCatalogPath, { readonly: true });
   try {
     await sourceCatalog.backup(targetCatalogPath);
@@ -3443,7 +4164,7 @@ async function copyDataDirForBackup(from, to) {
   }
 }
 async function loadValidatedBackupPayload(inputDir) {
-  const manifestPath = join6(inputDir, "manifest.json");
+  const manifestPath = join7(inputDir, "manifest.json");
   await assertSourceDirExists(inputDir);
   if (!await pathExists2(manifestPath)) {
     throw new AiocsError(
@@ -3458,21 +4179,21 @@ async function loadValidatedBackupPayload(inputDir) {
       `Invalid backup manifest: ${manifestPath}`
     );
   }
-  const backupDataDir = join6(inputDir, "data");
+  const backupDataDir = join7(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);
+  const backupCatalogPath = join7(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");
+  const backupConfigDir = join7(inputDir, "config");
   return {
     manifest,
     backupDataDir,
@@ -3480,8 +4201,8 @@ async function loadValidatedBackupPayload(inputDir) {
   };
 }
 async function prepareReplacementTarget(backupDir, targetDir) {
-  const parentDir = dirname2(targetDir);
-  const stagingDir = join6(parentDir, `.${basename(targetDir)}.import-${randomUUID2()}`);
+  const parentDir = dirname3(targetDir);
+  const stagingDir = join7(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 });
@@ -3503,13 +4224,13 @@ async function exportBackup(input) {
   }
   await mkdir(outputDir, { recursive: true });
   const entries = [];
-  await copyDataDirForBackup(dataDir, join6(outputDir, "data"));
-  entries.push(...(await listEntries(join6(outputDir, "data"))).map((entry) => ({
+  await copyDataDirForBackup(dataDir, join7(outputDir, "data"));
+  entries.push(...(await listEntries(join7(outputDir, "data"))).map((entry) => ({
     ...entry,
-    relativePath: join6("data", entry.relativePath)
+    relativePath: join7("data", entry.relativePath)
   })));
   if (configDir) {
-    await copyIfPresent(configDir, join6(outputDir, "config"), entries, "config");
+    await copyIfPresent(configDir, join7(outputDir, "config"), entries, "config");
   }
   const manifest = {
     formatVersion: 1,
@@ -3517,7 +4238,7 @@ async function exportBackup(input) {
     packageVersion,
     entries
   };
-  const manifestPath = join6(outputDir, "manifest.json");
+  const manifestPath = join7(outputDir, "manifest.json");
   await writeFile(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
   return {
     outputDir,
@@ -3693,9 +4414,9 @@ async function verifyCoverageAgainstReferences(corpus, referenceFiles) {
 
 // src/doctor.ts
 import { access as access2 } from "fs/promises";
-import { execFile } from "child_process";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile);
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+var execFileAsync2 = promisify2(execFile2);
 function summarize(checks) {
   const passCount = checks.filter((check) => check.status === "pass").length;
   const warnCount = checks.filter((check) => check.status === "warn").length;
@@ -3782,6 +4503,25 @@ async function checkPlaywright() {
     };
   }
 }
+async function checkGit() {
+  try {
+    const { stdout } = await execFileAsync2("git", ["--version"]);
+    return {
+      id: "git",
+      status: "pass",
+      summary: "Git executable is available.",
+      details: {
+        version: stdout.trim()
+      }
+    };
+  } catch (error) {
+    return {
+      id: "git",
+      status: "fail",
+      summary: `Git is not ready: ${toErrorMessage(error)}`
+    };
+  }
+}
 async function checkDaemonConfig(env) {
   try {
     const daemonConfig = parseDaemonConfig(env, {
@@ -4031,7 +4771,7 @@ async function checkEmbeddings(env) {
 }
 async function checkDocker() {
   try {
-    const { stdout } = await execFileAsync("docker", ["info", "--format", "{{json .ServerVersion}}"]);
+    const { stdout } = await execFileAsync2("docker", ["info", "--format", "{{json .ServerVersion}}"]);
     const version = JSON.parse(stdout.trim());
     return {
       id: "docker",
@@ -4047,7 +4787,7 @@ async function checkDocker() {
       return {
         id: "docker",
         status: "warn",
-        summary: "Docker CLI is not installed; Docker-based daemon deployment is unavailable on this machine."
+        summary: "Docker CLI is not installed; Docker-based daemon deployment is unavailable in this environment."
       };
     }
     return {
@@ -4059,6 +4799,7 @@ async function checkDocker() {
 }
 async function runDoctor(env = process.env) {
   const catalogCheck = await checkCatalog(env);
+  const gitCheck = await checkGit();
   const playwrightCheck = await checkPlaywright();
   const { daemonConfigCheck, daemonConfig } = await checkDaemonConfig(env);
   const sourceSpecDirsCheck = await checkSourceSpecDirs(daemonConfig);
@@ -4070,6 +4811,7 @@ async function runDoctor(env = process.env) {
   const dockerCheck = await checkDocker();
   const checks = [
     catalogCheck,
+    gitCheck,
     playwrightCheck,
     daemonConfigCheck,
     sourceSpecDirsCheck,
@@ -4124,6 +4866,19 @@ function withScores(rows, scoreLookup) {
     };
   });
 }
+function matchesChunkFilters(row, filters) {
+  if (filters.pathPatterns && filters.pathPatterns.length > 0) {
+    if (!row.filePath || !matchesPatterns(row.filePath, filters.pathPatterns)) {
+      return false;
+    }
+  }
+  if (filters.languages && filters.languages.length > 0) {
+    if (!row.language || !filters.languages.includes(row.language.toLowerCase())) {
+      return false;
+    }
+  }
+  return true;
+}
 async function searchHybridCatalog(input) {
   const scope = input.catalog.resolveSearchScope({
     query: input.query,
@@ -4131,6 +4886,8 @@ async function searchHybridCatalog(input) {
     ...input.searchInput.sourceIds ? { sourceIds: input.searchInput.sourceIds } : {},
     ...input.searchInput.snapshotId ? { snapshotId: input.searchInput.snapshotId } : {},
     ...input.searchInput.all ? { all: true } : {},
+    ...input.searchInput.pathPatterns ? { pathPatterns: input.searchInput.pathPatterns } : {},
+    ...input.searchInput.languages ? { languages: input.searchInput.languages } : {},
     ...typeof input.searchInput.limit === "number" ? { limit: input.searchInput.limit } : {},
     ...typeof input.searchInput.offset === "number" ? { offset: input.searchInput.offset } : {}
   });
@@ -4193,13 +4950,25 @@ async function searchHybridCatalog(input) {
       );
     }
     const vectorStore = new AiocsVectorStore(input.config);
-    vectorCandidates = await vectorStore.search({
+    const rawVectorCandidates = await vectorStore.search({
       vector: queryVector,
       snapshotIds: scope.snapshotIds,
       sourceIds: scope.sourceIds,
       modelKey,
       limit: windowSize(scope.limit, scope.offset, input.config.vectorCandidateWindow)
     });
+    if (rawVectorCandidates.length > 0 && (scope.pathPatterns || scope.languages)) {
+      const candidateRows = input.catalog.getChunksByIds(rawVectorCandidates.map((candidate) => candidate.chunkId));
+      const allowedIds = new Set(
+        candidateRows.filter((row) => matchesChunkFilters(row, {
+          pathPatterns: scope.pathPatterns,
+          languages: scope.languages
+        })).map((row) => row.chunkId)
+      );
+      vectorCandidates = rawVectorCandidates.filter((candidate) => allowedIds.has(candidate.chunkId));
+    } else {
+      vectorCandidates = rawVectorCandidates;
+    }
   } catch (error) {
     if (input.mode === "auto") {
       return lexicalOnly();
@@ -4355,7 +5124,7 @@ async function refreshDueSources(sourceIdOrAll = "all") {
   return { results };
 }
 async function runSourceCanaries(sourceIdOrAll) {
-  const results = await withCatalog(async ({ catalog }) => {
+  const results = await withCatalog(async ({ catalog, dataDir }) => {
     const sourceIds = sourceIdOrAll === "all" ? catalog.listSources().map((item) => item.id) : [sourceIdOrAll];
     if (sourceIds.length === 0) {
       return [];
@@ -4365,6 +5134,7 @@ async function runSourceCanaries(sourceIdOrAll) {
       canaried.push(await runSourceCanary({
         catalog,
         sourceId,
+        dataDir,
         env: process.env
       }));
     }
@@ -4424,6 +5194,8 @@ async function searchCatalog(query, options) {
         ...explicitSources ? { sourceIds: options.source } : {},
         ...options.snapshot ? { snapshotId: options.snapshot } : {},
         ...options.all ? { all: true } : {},
+        ...options.path && options.path.length > 0 ? { pathPatterns: options.path } : {},
+        ...options.language && options.language.length > 0 ? { languages: options.language } : {},
         ...typeof options.limit === "number" ? { limit: options.limit } : {},
         ...typeof options.offset === "number" ? { offset: options.offset } : {}
       }