@autorag/librarian 2.10.3 → 2.10.4

package/dist/cli/index.js

@@ -2657,7 +2657,7 @@ function chatCrawler(id) {
     hierarchy: (metadata) => ["chats", str(metadata.chatName) ?? str(metadata.chatId) ?? "unknown"]
   };
 }
-var str = (value) => typeof value === "string" && value.length > 0 ? value : undefined, slack, CRAWLER_DESCRIPTORS;
+var str = (value) => typeof value === "string" && value.length > 0 ? value : undefined, slack, kakao, CRAWLER_DESCRIPTORS;
 var init_descriptors = __esm(() => {
   slack = {
     id: "slack",
@@ -2688,10 +2688,32 @@ var init_descriptors = __esm(() => {
       str(metadata.channelName) ?? str(metadata.channelId) ?? "unknown"
     ]
   };
+  kakao = {
+    id: "kakao",
+    keyExpression: "m.chunk_id",
+    chunkId: (key) => key,
+    fromClause: "chunks m",
+    liveWhere: "length(trim(coalesce(m.text, ''))) > 0 and not (json_valid(m.text) and (json_extract(m.text, '$.feedType') is not null or json_extract(m.text, '$.csIP') is not null))",
+    textExpression: "coalesce(m.text, '')",
+    titleExpression: "m.chat_name",
+    epochSecondsExpression: "unixepoch(m.started_at)",
+    fts: { table: "chunks_fts", joinOn: "chunks_fts.rowid = m.rowid" },
+    metadata: [
+      { sql: "m.chat_id", key: "chatId" },
+      { sql: "m.chat_name", key: "chatName" },
+      { sql: "m.sender_nickname", key: "senderNickname" },
+      { sql: "m.started_at", key: "startedAt" },
+      { sql: "m.ended_at", key: "endedAt" }
+    ],
+    channelIdExpression: "m.chat_id",
+    channelNameExpression: "m.chat_name",
+    hierarchy: (metadata) => ["chats", str(metadata.chatName) ?? str(metadata.chatId) ?? "unknown"]
+  };
   CRAWLER_DESCRIPTORS = {
     slack,
     telegram: chatCrawler("telegram"),
-    whatsapp: chatCrawler("whatsapp")
+    whatsapp: chatCrawler("whatsapp"),
+    kakao
   };
 });
 
@@ -8054,6 +8076,504 @@ var init_skip = __esm(() => {
   MINSYNC_METHOD_NAMES = new Set(["minsync", "hybrid", "bm25"]);
 });
 
+// src/datasource/sidecar/fusion.ts
+function encodeVector(vector) {
+  const floats = Float32Array.from(vector);
+  return new Uint8Array(floats.buffer, floats.byteOffset, floats.byteLength);
+}
+function decodeVector(blob) {
+  if (blob.byteLength % Float32Array.BYTES_PER_ELEMENT !== 0)
+    return;
+  return new Float32Array(new Uint8Array(blob).buffer);
+}
+function cosine2(a, b) {
+  if (a.length === 0 || a.length !== b.length)
+    return 0;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let index = 0;index < a.length; index += 1) {
+    const x = a[index] ?? 0;
+    const y = b[index] ?? 0;
+    dot += x * y;
+    normA += x * x;
+    normB += y * y;
+  }
+  if (normA === 0 || normB === 0)
+    return 0;
+  return dot / Math.sqrt(normA * normB);
+}
+function topKByCosine(query, rows, k) {
+  if (k <= 0)
+    return [];
+  const scored = [];
+  for (const row of rows) {
+    const score = cosine2(query, row.vector);
+    if (score > 0)
+      scored.push({ key: row.key, score });
+  }
+  scored.sort((a, b) => b.score - a.score || a.key.localeCompare(b.key));
+  return scored.slice(0, k);
+}
+function reciprocalRankFusion(lists) {
+  const scores = new Map;
+  for (const list of lists) {
+    const seen = new Set;
+    for (const [index, key] of list.entries()) {
+      if (seen.has(key))
+        continue;
+      seen.add(key);
+      scores.set(key, (scores.get(key) ?? 0) + 1 / (RRF_K + index + 1));
+    }
+  }
+  return [...scores.entries()].map(([key, score]) => ({ key, score })).sort((a, b) => b.score - a.score);
+}
+var RRF_K = 60;
+
+// src/datasource/sidecar/index.ts
+import { createHash as createHash6 } from "node:crypto";
+import { mkdirSync as mkdirSync7, statSync } from "node:fs";
+import { dirname as dirname11 } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { pathToFileURL } from "node:url";
+
+class CrawlerSidecar {
+  descriptor;
+  options;
+  select;
+  where;
+  opened;
+  attached;
+  lastSemantic;
+  constructor(options) {
+    this.options = options;
+    const { descriptor } = options;
+    this.descriptor = descriptor;
+    const metadataColumns = descriptor.metadata.map((column, index) => `${column.sql} as m${index}`);
+    this.select = [
+      `${descriptor.keyExpression} as k`,
+      `${descriptor.textExpression} as content`,
+      `${descriptor.titleExpression ?? "null"} as title`,
+      `${descriptor.epochSecondsExpression ?? "null"} as epoch`,
+      ...metadataColumns
+    ].join(", ");
+    const scope = descriptor.scopeExpression !== undefined && options.workspaceId !== undefined;
+    const allowlist = [
+      ...(options.channelIds?.length ?? 0) > 0 ? [`${descriptor.channelIdExpression} in (${options.channelIds?.map(() => "?").join(", ")})`] : [],
+      ...(options.channelNames?.length ?? 0) > 0 ? [`${descriptor.channelNameExpression} in (${options.channelNames?.map(() => "?").join(", ")})`] : []
+    ];
+    this.where = [
+      descriptor.liveWhere,
+      ...scope ? [`${descriptor.scopeExpression} = ?`] : [],
+      ...allowlist.length > 0 ? [`(${allowlist.join(" or ")})`] : []
+    ].join(" and ");
+  }
+  get db() {
+    if (this.opened !== undefined)
+      return this.opened;
+    mkdirSync7(dirname11(this.options.sidecarDbPath), { recursive: true });
+    const db = new DatabaseSync(this.options.sidecarDbPath);
+    db.exec(`pragma busy_timeout = ${BUSY_TIMEOUT_MS}`);
+    db.exec("pragma journal_mode = wal");
+    db.exec(`
+			create table if not exists sidecar_meta (k text primary key, v text not null);
+			create table if not exists sidecar_vec (message_key text primary key, hash text not null, vec blob not null);
+		`);
+    this.opened = db;
+    return db;
+  }
+  attachCrawler() {
+    let file;
+    try {
+      const { dev, ino } = statSync(this.options.crawlerDbPath);
+      file = { dev, ino };
+    } catch {
+      this.detachCrawler();
+      return false;
+    }
+    if (this.attached !== undefined) {
+      if (this.attached.dev === file.dev && this.attached.ino === file.ino)
+        return true;
+      this.detachCrawler();
+    }
+    const crawlerUri = `${pathToFileURL(this.options.crawlerDbPath).href}?mode=ro`.replaceAll("'", "''");
+    try {
+      this.db.exec(`attach database '${crawlerUri}' as crawler`);
+    } catch {
+      return false;
+    }
+    const { descriptor } = this.options;
+    try {
+      this.db.prepare(`select ${this.select} from ${descriptor.fromClause} where ${this.where} limit 0`).all(...this.whereParams());
+      this.db.prepare(`select 1 from ${descriptor.fts.table} limit 0`).all();
+    } catch {
+      this.db.exec("detach database crawler");
+      return false;
+    }
+    this.attached = file;
+    this.lastSemantic = undefined;
+    return true;
+  }
+  detachCrawler() {
+    if (this.attached === undefined)
+      return;
+    this.attached = undefined;
+    this.lastSemantic = undefined;
+    try {
+      this.opened?.exec("detach database crawler");
+    } catch {}
+  }
+  get semanticEnabled() {
+    return this.options.embedder !== undefined;
+  }
+  close() {
+    this.opened?.close();
+    this.opened = undefined;
+    this.attached = undefined;
+    this.lastSemantic = undefined;
+  }
+  whereParams() {
+    const { descriptor, workspaceId, channelIds = [], channelNames = [] } = this.options;
+    return [
+      ...descriptor.scopeExpression !== undefined && workspaceId !== undefined ? [workspaceId] : [],
+      ...channelIds,
+      ...channelNames
+    ];
+  }
+  searchLexical(query, topK) {
+    const match = toMatchQuery(query);
+    if (match === undefined || topK <= 0 || !this.attachCrawler())
+      return [];
+    const { descriptor } = this.options;
+    const rows = this.db.prepare(`select ${this.select}, bm25(${descriptor.fts.table}) as rank
+				from ${descriptor.fromClause} join ${descriptor.fts.table} on ${descriptor.fts.joinOn}
+				where ${descriptor.fts.table} match ? and ${this.where}
+				order by rank limit ?`).all(match, ...this.whereParams(), topK);
+    return rows.map((row) => this.toHit(this.toRow(row), -Number(row.rank)));
+  }
+  async searchSemantic(query, topK) {
+    const trimmed = query.trim();
+    if (this.options.embedder === undefined || trimmed.length === 0 || topK <= 0 || !this.attachCrawler())
+      return [];
+    const ranked = await this.rankSemantic(trimmed, topK * POOL_FACTOR);
+    if (ranked.length === 0)
+      return [];
+    const live = this.hydrate(ranked.map((entry) => entry.key));
+    const hits = [];
+    for (const entry of ranked) {
+      const row = live.get(entry.key);
+      if (row !== undefined)
+        hits.push(this.toHit(row, entry.score));
+      if (hits.length >= topK)
+        break;
+    }
+    return hits;
+  }
+  async rankSemantic(query, pool) {
+    const now = Date.now();
+    let cached = this.lastSemantic;
+    if (cached === undefined || cached.query !== query || now - cached.at > SEMANTIC_REUSE_MS) {
+      const embedder = this.options.embedder;
+      if (embedder === undefined)
+        return [];
+      cached = {
+        query,
+        at: now,
+        vector: embedder.embed([query]).then((vectors) => vectors[0], () => {
+          return;
+        }),
+        ranked: undefined
+      };
+      this.lastSemantic = cached;
+    }
+    const vector = await cached.vector;
+    if (vector === undefined) {
+      if (this.lastSemantic === cached)
+        this.lastSemantic = undefined;
+      return [];
+    }
+    if (cached.ranked === undefined || cached.ranked.pool < pool) {
+      const wide = pool * POOL_FACTOR;
+      cached.ranked = { pool: wide, keys: topKByCosine(vector, this.storedVectors(), wide) };
+    }
+    return cached.ranked.keys.slice(0, pool);
+  }
+  async searchHybrid(query, topK) {
+    if (topK <= 0)
+      return [];
+    const pool = topK * POOL_FACTOR;
+    const lexical = this.searchLexical(query, pool);
+    const semantic = await this.searchSemantic(query, pool);
+    if (semantic.length === 0)
+      return lexical.slice(0, topK);
+    const byKey = new Map;
+    for (const hit of [...semantic, ...lexical])
+      byKey.set(hit.key, hit);
+    const fused = [];
+    for (const entry of reciprocalRankFusion([lexical.map((hit) => hit.key), semantic.map((hit) => hit.key)])) {
+      const hit = byKey.get(entry.key);
+      if (hit !== undefined)
+        fused.push({ ...hit, score: entry.score });
+      if (fused.length >= topK)
+        break;
+    }
+    return fused;
+  }
+  async sync() {
+    const { embedder } = this.options;
+    if (embedder === undefined)
+      return { ok: false, message: "no embedder configured" };
+    if (!this.attachCrawler())
+      return { ok: false, message: "crawler archive not available yet" };
+    let identity;
+    try {
+      identity = await embedder.identity();
+    } catch (error) {
+      return { ok: false, message: errorMessage(error) };
+    }
+    this.adoptIdentity(identity);
+    const pruned = this.prune();
+    const pending = this.pendingKeys();
+    const batchSize = Math.max(1, this.options.batchSize ?? DEFAULT_BATCH_SIZE);
+    const budget = Math.max(1, this.options.maxEmbedPerSync ?? DEFAULT_MAX_EMBED_PER_SYNC);
+    const target = Math.min(pending.length, budget);
+    const embed = async (rows) => {
+      const vectors = await embedder.embed(rows.map((row) => row.input));
+      if (vectors.length !== rows.length) {
+        throw new Error(`embedder returned ${vectors.length} vectors for ${rows.length} messages`);
+      }
+      const wrong = vectors.find((vector) => vector.length !== identity.dimension);
+      if (wrong !== undefined) {
+        throw new Error(`embedder returned a ${wrong.length}-dimension vector, expected ${identity.dimension}`);
+      }
+      return vectors;
+    };
+    let embedded = 0;
+    let skipped = 0;
+    for (let offset = 0;offset < target; offset += batchSize) {
+      const rows = [...this.hydrate(pending.slice(offset, Math.min(offset + batchSize, target))).values()];
+      if (rows.length === 0)
+        continue;
+      try {
+        this.store(rows, await embed(rows));
+        embedded += rows.length;
+      } catch (batchError) {
+        const rejected = [];
+        let lastError = batchError;
+        for (const row of rows) {
+          try {
+            this.store([row], await embed([row]));
+            embedded += 1;
+          } catch (error) {
+            rejected.push(row);
+            lastError = error;
+          }
+        }
+        if (rejected.length === 0)
+          continue;
+        if (embedded === 0)
+          return { ok: false, message: errorMessage(lastError) };
+        this.store(rejected, undefined);
+        skipped += rejected.length;
+      }
+    }
+    return { ok: true, embedded, skipped, pruned, remaining: pending.length - embedded - skipped };
+  }
+  adoptIdentity(identity) {
+    const serialized = JSON.stringify(identity);
+    const current = this.db.prepare("select v from sidecar_meta where k = ?").get(IDENTITY_KEY);
+    if (current?.v === serialized)
+      return;
+    this.transaction(() => {
+      this.db.exec("delete from sidecar_vec");
+      this.db.prepare("insert or replace into sidecar_meta (k, v) values (?, ?)").run(IDENTITY_KEY, serialized);
+    });
+    this.lastSemantic = undefined;
+  }
+  prune() {
+    const { descriptor } = this.options;
+    const result = this.db.prepare(`delete from sidecar_vec where message_key not in (
+					select ${descriptor.keyExpression} from ${descriptor.fromClause} where ${this.where}
+				)`).run(...this.whereParams());
+    if (Number(result.changes) > 0)
+      this.lastSemantic = undefined;
+    return Number(result.changes);
+  }
+  pendingKeys() {
+    const { descriptor } = this.options;
+    const rows = this.db.prepare(`select ${this.select}, v.hash as stored_hash
+				from ${descriptor.fromClause}
+				left join sidecar_vec v on v.message_key = ${descriptor.keyExpression}
+				where ${this.where}`).iterate(...this.whereParams());
+    const pending = [];
+    for (const row of rows) {
+      if (row.stored_hash !== this.toRow(row).hash)
+        pending.push(String(row.k));
+    }
+    return pending;
+  }
+  hydrate(keys) {
+    const { descriptor } = this.options;
+    const out = new Map;
+    if (keys.length === 0)
+      return out;
+    const rows = this.db.prepare(`select ${this.select} from ${descriptor.fromClause}
+				where ${descriptor.keyExpression} in (${keys.map(() => "?").join(", ")}) and ${this.where}`).all(...keys, ...this.whereParams());
+    const byKey = new Map(rows.map((row) => [String(row.k), this.toRow(row)]));
+    for (const key of keys) {
+      const row = byKey.get(key);
+      if (row !== undefined)
+        out.set(key, row);
+    }
+    return out;
+  }
+  store(rows, vectors) {
+    const upsert = this.db.prepare("insert or replace into sidecar_vec (message_key, hash, vec) values (?, ?, ?)");
+    this.transaction(() => {
+      for (const [index, row] of rows.entries()) {
+        upsert.run(row.key, row.hash, encodeVector(vectors?.[index] ?? []));
+      }
+    });
+    this.lastSemantic = undefined;
+  }
+  *storedVectors() {
+    const rows = this.db.prepare("select message_key, vec from sidecar_vec where length(vec) > 0").iterate();
+    for (const row of rows) {
+      const vector = row.vec instanceof Uint8Array ? decodeVector(row.vec) : undefined;
+      if (vector !== undefined)
+        yield { key: String(row.message_key), vector };
+    }
+  }
+  transaction(work) {
+    this.db.exec("begin immediate");
+    try {
+      work();
+      this.db.exec("commit");
+    } catch (error) {
+      this.db.exec("rollback");
+      throw error;
+    }
+  }
+  toRow(row) {
+    const metadata = {};
+    for (const [index, column] of this.options.descriptor.metadata.entries()) {
+      const value = row[`m${index}`];
+      if (typeof value === "string" && value.length > 0 || typeof value === "number")
+        metadata[column.key] = String(value);
+    }
+    const title = typeof row.title === "string" && row.title.length > 0 ? row.title : undefined;
+    const epoch = typeof row.epoch === "number" && Number.isFinite(row.epoch) ? row.epoch : undefined;
+    const content = String(row.content ?? "");
+    const input = `${title ?? ""}
+${content}`.slice(0, MAX_EMBED_INPUT_CHARS);
+    return {
+      key: String(row.k),
+      content,
+      title,
+      epoch,
+      metadata,
+      input,
+      hash: createHash6("sha1").update(input).digest("hex")
+    };
+  }
+  toHit(row, score) {
+    return {
+      key: row.key,
+      content: row.content,
+      score,
+      ...row.title !== undefined ? { title: row.title } : {},
+      ...row.epoch !== undefined ? { publishedAt: Math.round(row.epoch * 1000) } : {},
+      metadata: row.metadata
+    };
+  }
+}
+function toMatchQuery(text) {
+  const terms = [...new Set(text.match(/[\p{L}\p{N}_]+/gu) ?? [])];
+  return terms.length === 0 ? undefined : terms.map((term) => `"${term}"`).join(" OR ");
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var DEFAULT_BATCH_SIZE = 256, DEFAULT_MAX_EMBED_PER_SYNC = 2048, MAX_EMBED_INPUT_CHARS = 8192, BUSY_TIMEOUT_MS = 5000, POOL_FACTOR = 3, SEMANTIC_REUSE_MS = 1e4, IDENTITY_KEY = "identity";
+var init_sidecar = () => {};
+
+// src/datasource/sidecar/methods.ts
+function sidecarMethodName(datasourceId, mode) {
+  return mode === "bm25" ? `${datasourceId}-sidecar-bm25` : `${datasourceId}-${mode}`;
+}
+
+class SidecarRetrievalMethod {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  describe() {
+    const { datasourceId, skillType, mode, tags } = this.options;
+    const { type, text, capabilities } = DESCRIPTIONS[mode];
+    return {
+      name: sidecarMethodName(datasourceId, mode),
+      type,
+      description: `${text} over ${skillType} via a read-only sidecar index`,
+      status: "active",
+      capabilities: [...capabilities, "scoped", "path-opaque-sources"],
+      datasourceId,
+      tags
+    };
+  }
+  async retrieve(query, options) {
+    const trimmed = query.trim();
+    if (trimmed.length === 0)
+      return [];
+    const topK = options.topK ?? DEFAULT_TOP_K5;
+    const { sidecar, mode } = this.options;
+    const hits = mode === "bm25" ? sidecar.searchLexical(trimmed, topK) : mode === "semantic" ? await sidecar.searchSemantic(trimmed, topK) : await sidecar.searchHybrid(trimmed, topK);
+    const results = [];
+    for (const hit of hits) {
+      const result = this.toResult(hit, options);
+      if (result !== undefined)
+        results.push(result);
+    }
+    return results;
+  }
+  toResult(hit, options) {
+    const { descriptor, datasourceId, instanceId, mode } = this.options;
+    const chunkId = descriptor.chunkId(hit.key, hit.metadata);
+    const source = datasourceSourcePath(datasourceId, instanceId, chunkId);
+    if (!matchesDatasourceScope(source, options.scope))
+      return;
+    const method = sidecarMethodName(datasourceId, mode);
+    return {
+      id: `${datasourceId}:${instanceId}:${chunkId}`,
+      content: hit.content,
+      source,
+      score: hit.score,
+      metadata: {
+        ...hit.metadata,
+        method,
+        datasourceId,
+        instanceId,
+        backend: "sidecar",
+        ...hit.title !== undefined ? { title: hit.title } : {},
+        hierarchy: descriptor.hierarchy(hit.metadata).join("/"),
+        ...hit.publishedAt !== undefined ? { publishedAt: hit.publishedAt } : {}
+      }
+    };
+  }
+}
+var DEFAULT_TOP_K5 = 20, DESCRIPTIONS;
+var init_methods4 = __esm(() => {
+  init_scope2();
+  DESCRIPTIONS = {
+    bm25: { type: "bm25", text: "BM25-ranked FTS5 retrieval", capabilities: ["lexical", "fts5", "bm25"] },
+    semantic: { type: "vector", text: "Semantic (embedding) retrieval", capabilities: ["semantic"] },
+    hybrid: {
+      type: "hybrid",
+      text: "Hybrid BM25 + semantic retrieval (reciprocal rank fusion)",
+      capabilities: ["lexical", "semantic", "hybrid"]
+    }
+  };
+});
+
 // src/datasource/skills/lazykatok/skill.ts
 class LazykatokSkill {
   client;
@@ -8061,6 +8581,7 @@ class LazykatokSkill {
   instances;
   pollingIntervalMs;
   tags;
+  sidecar;
   lastIndexedAt;
   constructor(options) {
     this.client = options.client;
@@ -8069,6 +8590,11 @@ class LazykatokSkill {
     this.pollingIntervalMs = options.pollingIntervalMs ?? DEFAULT_POLLING_INTERVAL_MS3;
     this.tags = options.tags ?? DEFAULT_KAKAO_TAGS2;
     this.lastIndexedAt = options.lastIndexedAt;
+    this.sidecar = options.sidecar === undefined ? undefined : new CrawlerSidecar({
+      ...options.sidecar,
+      channelIds: options.channelIds ?? options.sidecar.channelIds ?? [],
+      channelNames: options.channelNames ?? options.sidecar.channelNames ?? []
+    });
   }
   describe() {
     return {
@@ -8100,6 +8626,17 @@ class LazykatokSkill {
       const sync = await this.client.sync(options?.signal);
       if (!sync.ok)
         return this.fail("datasource-index-failed", sync);
+      if (this.sidecar !== undefined) {
+        this.lastIndexedAt = Date.now();
+        return {
+          ok: true,
+          instanceId: this.instanceId,
+          skill: KAKAO_DATASOURCE_ID2,
+          chunkCount: syncChunkCount(sync),
+          indexedAt: this.lastIndexedAt,
+          diagnostics: await this.syncSidecar()
+        };
+      }
       const indexResult = await this.client.index(options?.signal);
       if (!indexResult.ok)
         return this.fail("datasource-index-failed", indexResult);
@@ -8123,12 +8660,75 @@ class LazykatokSkill {
       });
     }
   }
+  close() {
+    this.sidecar?.close();
+  }
   retrievalMethods() {
+    const cliBm25 = new LazykatokBm25Method({ client: this.client, instanceId: this.instanceId, tags: this.tags });
+    const { sidecar } = this;
+    if (sidecar === undefined) {
+      return [
+        cliBm25,
+        new LazykatokSemanticMethod({ client: this.client, instanceId: this.instanceId, tags: this.tags })
+      ];
+    }
+    const shared = {
+      sidecar,
+      descriptor: sidecar.descriptor,
+      datasourceId: KAKAO_DATASOURCE_ID2,
+      skillType: KAKAO_SKILL_TYPE,
+      instanceId: this.instanceId,
+      tags: this.tags
+    };
+    const bm25 = new SidecarRetrievalMethod({ ...shared, mode: "bm25" });
+    if (!sidecar.semanticEnabled)
+      return [cliBm25, bm25];
     return [
-      new LazykatokBm25Method({ client: this.client, instanceId: this.instanceId, tags: this.tags }),
-      new LazykatokSemanticMethod({ client: this.client, instanceId: this.instanceId, tags: this.tags })
+      cliBm25,
+      bm25,
+      new SidecarRetrievalMethod({ ...shared, mode: "semantic" }),
+      new SidecarRetrievalMethod({ ...shared, mode: "hybrid" })
     ];
   }
+  async syncSidecar() {
+    if (this.sidecar === undefined || !this.sidecar.semanticEnabled)
+      return [];
+    const base = { instanceId: this.instanceId, source: KAKAO_DATASOURCE_ID2 };
+    let result;
+    try {
+      result = await this.sidecar.sync();
+    } catch (error) {
+      result = { ok: false, message: error instanceof Error ? error.message : String(error) };
+    }
+    if (!result.ok) {
+      return [
+        {
+          code: "datasource-index-failed",
+          severity: "warning",
+          message: `semantic-unavailable: ${result.message}`.slice(0, 300),
+          ...base
+        }
+      ];
+    }
+    const diagnostics = [];
+    if (result.skipped > 0) {
+      diagnostics.push({
+        code: "datasource-index-partial",
+        severity: "warning",
+        message: `semantic index skipped ${result.skipped} message(s) the embedder rejected; they stay searchable by BM25 and are retried when edited`,
+        ...base
+      });
+    }
+    if (result.remaining > 0) {
+      diagnostics.push({
+        code: "datasource-index-partial",
+        severity: "info",
+        message: `semantic index catching up: ${result.embedded} embedded this refresh, ${result.remaining} remaining; hybrid search uses BM25 for the rest until a later refresh`,
+        ...base
+      });
+    }
+    return diagnostics;
+  }
   describeSources() {
     return this.instances.map((instanceId) => ({
       source: datasourceSourcePath(KAKAO_DATASOURCE_ID2, instanceId),
@@ -8202,10 +8802,22 @@ class LazykatokSkill {
     };
   }
 }
+function syncChunkCount(sync) {
+  if (!("data" in sync) || typeof sync.data !== "object" || sync.data === null)
+    return 0;
+  const meta = "metadata" in sync.data && typeof sync.data.metadata === "object" && sync.data.metadata !== null ? sync.data.metadata : undefined;
+  if (typeof meta?.chunks === "number")
+    return meta.chunks;
+  if ("messageCount" in sync.data && typeof sync.data.messageCount === "number")
+    return sync.data.messageCount;
+  return 0;
+}
 var KAKAO_DATASOURCE_ID2 = "kakao", KAKAO_SKILL_TYPE = "kakaotalk", DEFAULT_INSTANCE_ID4 = "default", DEFAULT_POLLING_INTERVAL_MS3, DEFAULT_KAKAO_TAGS2;
 var init_skill7 = __esm(() => {
   init_skip();
   init_scope2();
+  init_sidecar();
+  init_methods4();
   init_methods3();
   DEFAULT_POLLING_INTERVAL_MS3 = 15 * 60 * 1000;
   DEFAULT_KAKAO_TAGS2 = ["kakaotalk", "personal", "pii"];
@@ -8221,7 +8833,7 @@ var init_lazykatok = __esm(() => {
 
 // src/datasource/skills/mail-export/connector.ts
 import { readdir as readdir2, readFile as readFile4, stat as stat3 } from "node:fs/promises";
-import { basename as basename5, dirname as dirname11, extname as extname3, join as join14 } from "node:path";
+import { basename as basename5, dirname as dirname12, extname as extname3, join as join14 } from "node:path";
 import { simpleParser as simpleParser2 } from "mailparser";
 
 class MailExportConnector {
@@ -8282,7 +8894,7 @@ class MailExportConnector {
         continue;
       }
       const stem = basename5(file, extname3(file));
-      const mailboxDir = basename5(dirname11(file));
+      const mailboxDir = basename5(dirname12(file));
       const hierarchy = ["mailboxes", mailboxDir, stem];
       const extension = extname3(file).toLowerCase();
       const rawMessages = extension === ".mbox" ? splitMbox(bytes.toString("utf8")) : [bytes.toString("utf8")];
@@ -8392,14 +9004,14 @@ var init_mail_export = __esm(() => {
 });
 
 // src/datasource/skills/mailcrawl/config.ts
-import { chmodSync, mkdirSync as mkdirSync7 } from "node:fs";
+import { chmodSync, mkdirSync as mkdirSync8 } from "node:fs";
 function validateMailcrawlInstanceId(instanceId) {
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(instanceId)) {
     throw new Error("mailcrawl instanceId must be a safe single path segment");
   }
 }
 function ensurePrivateMailcrawlDataDir(path) {
-  mkdirSync7(path, { recursive: true, mode: 448 });
+  mkdirSync8(path, { recursive: true, mode: 448 });
   if (process.platform !== "win32")
     chmodSync(path, 448);
 }
@@ -8827,7 +9439,7 @@ class MailcrawlMethod {
   }
 }
 var modes, MAILCRAWL_MODES;
-var init_methods4 = __esm(() => {
+var init_methods5 = __esm(() => {
   init_errors2();
   init_scope2();
   modes = ["bm25", "semantic", "hybrid"];
@@ -8977,515 +9589,17 @@ var init_skill9 = __esm(() => {
   init_scope2();
   init_client5();
   init_config3();
-  init_methods4();
+  init_methods5();
   TAGS = ["mailcrawl", "email", "pii"];
 });
 
 // src/datasource/skills/mailcrawl/index.ts
 var init_mailcrawl = __esm(() => {
   init_client5();
-  init_methods4();
+  init_methods5();
   init_skill9();
 });
 
-// src/datasource/sidecar/fusion.ts
-function encodeVector(vector) {
-  const floats = Float32Array.from(vector);
-  return new Uint8Array(floats.buffer, floats.byteOffset, floats.byteLength);
-}
-function decodeVector(blob) {
-  if (blob.byteLength % Float32Array.BYTES_PER_ELEMENT !== 0)
-    return;
-  return new Float32Array(new Uint8Array(blob).buffer);
-}
-function cosine2(a, b) {
-  if (a.length === 0 || a.length !== b.length)
-    return 0;
-  let dot = 0;
-  let normA = 0;
-  let normB = 0;
-  for (let index = 0;index < a.length; index += 1) {
-    const x = a[index] ?? 0;
-    const y = b[index] ?? 0;
-    dot += x * y;
-    normA += x * x;
-    normB += y * y;
-  }
-  if (normA === 0 || normB === 0)
-    return 0;
-  return dot / Math.sqrt(normA * normB);
-}
-function topKByCosine(query, rows, k) {
-  if (k <= 0)
-    return [];
-  const scored = [];
-  for (const row of rows) {
-    const score = cosine2(query, row.vector);
-    if (score > 0)
-      scored.push({ key: row.key, score });
-  }
-  scored.sort((a, b) => b.score - a.score || a.key.localeCompare(b.key));
-  return scored.slice(0, k);
-}
-function reciprocalRankFusion(lists) {
-  const scores = new Map;
-  for (const list of lists) {
-    const seen = new Set;
-    for (const [index, key] of list.entries()) {
-      if (seen.has(key))
-        continue;
-      seen.add(key);
-      scores.set(key, (scores.get(key) ?? 0) + 1 / (RRF_K + index + 1));
-    }
-  }
-  return [...scores.entries()].map(([key, score]) => ({ key, score })).sort((a, b) => b.score - a.score);
-}
-var RRF_K = 60;
-
-// src/datasource/sidecar/index.ts
-import { createHash as createHash6 } from "node:crypto";
-import { mkdirSync as mkdirSync8, statSync } from "node:fs";
-import { dirname as dirname12 } from "node:path";
-import { DatabaseSync } from "node:sqlite";
-import { pathToFileURL } from "node:url";
-
-class CrawlerSidecar {
-  descriptor;
-  options;
-  select;
-  where;
-  opened;
-  attached;
-  lastSemantic;
-  constructor(options) {
-    this.options = options;
-    const { descriptor } = options;
-    this.descriptor = descriptor;
-    const metadataColumns = descriptor.metadata.map((column, index) => `${column.sql} as m${index}`);
-    this.select = [
-      `${descriptor.keyExpression} as k`,
-      `${descriptor.textExpression} as content`,
-      `${descriptor.titleExpression ?? "null"} as title`,
-      `${descriptor.epochSecondsExpression ?? "null"} as epoch`,
-      ...metadataColumns
-    ].join(", ");
-    const scope = descriptor.scopeExpression !== undefined && options.workspaceId !== undefined;
-    const allowlist = [
-      ...(options.channelIds?.length ?? 0) > 0 ? [`${descriptor.channelIdExpression} in (${options.channelIds?.map(() => "?").join(", ")})`] : [],
-      ...(options.channelNames?.length ?? 0) > 0 ? [`${descriptor.channelNameExpression} in (${options.channelNames?.map(() => "?").join(", ")})`] : []
-    ];
-    this.where = [
-      descriptor.liveWhere,
-      ...scope ? [`${descriptor.scopeExpression} = ?`] : [],
-      ...allowlist.length > 0 ? [`(${allowlist.join(" or ")})`] : []
-    ].join(" and ");
-  }
-  get db() {
-    if (this.opened !== undefined)
-      return this.opened;
-    mkdirSync8(dirname12(this.options.sidecarDbPath), { recursive: true });
-    const db = new DatabaseSync(this.options.sidecarDbPath);
-    db.exec(`pragma busy_timeout = ${BUSY_TIMEOUT_MS}`);
-    db.exec("pragma journal_mode = wal");
-    db.exec(`
-			create table if not exists sidecar_meta (k text primary key, v text not null);
-			create table if not exists sidecar_vec (message_key text primary key, hash text not null, vec blob not null);
-		`);
-    this.opened = db;
-    return db;
-  }
-  attachCrawler() {
-    let file;
-    try {
-      const { dev, ino } = statSync(this.options.crawlerDbPath);
-      file = { dev, ino };
-    } catch {
-      this.detachCrawler();
-      return false;
-    }
-    if (this.attached !== undefined) {
-      if (this.attached.dev === file.dev && this.attached.ino === file.ino)
-        return true;
-      this.detachCrawler();
-    }
-    const crawlerUri = `${pathToFileURL(this.options.crawlerDbPath).href}?mode=ro`.replaceAll("'", "''");
-    try {
-      this.db.exec(`attach database '${crawlerUri}' as crawler`);
-    } catch {
-      return false;
-    }
-    const { descriptor } = this.options;
-    try {
-      this.db.prepare(`select ${this.select} from ${descriptor.fromClause} where ${this.where} limit 0`).all(...this.whereParams());
-      this.db.prepare(`select 1 from ${descriptor.fts.table} limit 0`).all();
-    } catch {
-      this.db.exec("detach database crawler");
-      return false;
-    }
-    this.attached = file;
-    this.lastSemantic = undefined;
-    return true;
-  }
-  detachCrawler() {
-    if (this.attached === undefined)
-      return;
-    this.attached = undefined;
-    this.lastSemantic = undefined;
-    try {
-      this.opened?.exec("detach database crawler");
-    } catch {}
-  }
-  get semanticEnabled() {
-    return this.options.embedder !== undefined;
-  }
-  close() {
-    this.opened?.close();
-    this.opened = undefined;
-    this.attached = undefined;
-    this.lastSemantic = undefined;
-  }
-  whereParams() {
-    const { descriptor, workspaceId, channelIds = [], channelNames = [] } = this.options;
-    return [
-      ...descriptor.scopeExpression !== undefined && workspaceId !== undefined ? [workspaceId] : [],
-      ...channelIds,
-      ...channelNames
-    ];
-  }
-  searchLexical(query, topK) {
-    const match = toMatchQuery(query);
-    if (match === undefined || topK <= 0 || !this.attachCrawler())
-      return [];
-    const { descriptor } = this.options;
-    const rows = this.db.prepare(`select ${this.select}, bm25(${descriptor.fts.table}) as rank
-				from ${descriptor.fromClause} join ${descriptor.fts.table} on ${descriptor.fts.joinOn}
-				where ${descriptor.fts.table} match ? and ${this.where}
-				order by rank limit ?`).all(match, ...this.whereParams(), topK);
-    return rows.map((row) => this.toHit(this.toRow(row), -Number(row.rank)));
-  }
-  async searchSemantic(query, topK) {
-    const trimmed = query.trim();
-    if (this.options.embedder === undefined || trimmed.length === 0 || topK <= 0 || !this.attachCrawler())
-      return [];
-    const ranked = await this.rankSemantic(trimmed, topK * POOL_FACTOR);
-    if (ranked.length === 0)
-      return [];
-    const live = this.hydrate(ranked.map((entry) => entry.key));
-    const hits = [];
-    for (const entry of ranked) {
-      const row = live.get(entry.key);
-      if (row !== undefined)
-        hits.push(this.toHit(row, entry.score));
-      if (hits.length >= topK)
-        break;
-    }
-    return hits;
-  }
-  async rankSemantic(query, pool) {
-    const now = Date.now();
-    let cached = this.lastSemantic;
-    if (cached === undefined || cached.query !== query || now - cached.at > SEMANTIC_REUSE_MS) {
-      const embedder = this.options.embedder;
-      if (embedder === undefined)
-        return [];
-      cached = {
-        query,
-        at: now,
-        vector: embedder.embed([query]).then((vectors) => vectors[0], () => {
-          return;
-        }),
-        ranked: undefined
-      };
-      this.lastSemantic = cached;
-    }
-    const vector = await cached.vector;
-    if (vector === undefined) {
-      if (this.lastSemantic === cached)
-        this.lastSemantic = undefined;
-      return [];
-    }
-    if (cached.ranked === undefined || cached.ranked.pool < pool) {
-      const wide = pool * POOL_FACTOR;
-      cached.ranked = { pool: wide, keys: topKByCosine(vector, this.storedVectors(), wide) };
-    }
-    return cached.ranked.keys.slice(0, pool);
-  }
-  async searchHybrid(query, topK) {
-    if (topK <= 0)
-      return [];
-    const pool = topK * POOL_FACTOR;
-    const lexical = this.searchLexical(query, pool);
-    const semantic = await this.searchSemantic(query, pool);
-    if (semantic.length === 0)
-      return lexical.slice(0, topK);
-    const byKey = new Map;
-    for (const hit of [...semantic, ...lexical])
-      byKey.set(hit.key, hit);
-    const fused = [];
-    for (const entry of reciprocalRankFusion([lexical.map((hit) => hit.key), semantic.map((hit) => hit.key)])) {
-      const hit = byKey.get(entry.key);
-      if (hit !== undefined)
-        fused.push({ ...hit, score: entry.score });
-      if (fused.length >= topK)
-        break;
-    }
-    return fused;
-  }
-  async sync() {
-    const { embedder } = this.options;
-    if (embedder === undefined)
-      return { ok: false, message: "no embedder configured" };
-    if (!this.attachCrawler())
-      return { ok: false, message: "crawler archive not available yet" };
-    let identity;
-    try {
-      identity = await embedder.identity();
-    } catch (error) {
-      return { ok: false, message: errorMessage(error) };
-    }
-    this.adoptIdentity(identity);
-    const pruned = this.prune();
-    const pending = this.pendingKeys();
-    const batchSize = Math.max(1, this.options.batchSize ?? DEFAULT_BATCH_SIZE);
-    const budget = Math.max(1, this.options.maxEmbedPerSync ?? DEFAULT_MAX_EMBED_PER_SYNC);
-    const target = Math.min(pending.length, budget);
-    const embed = async (rows) => {
-      const vectors = await embedder.embed(rows.map((row) => row.input));
-      if (vectors.length !== rows.length) {
-        throw new Error(`embedder returned ${vectors.length} vectors for ${rows.length} messages`);
-      }
-      const wrong = vectors.find((vector) => vector.length !== identity.dimension);
-      if (wrong !== undefined) {
-        throw new Error(`embedder returned a ${wrong.length}-dimension vector, expected ${identity.dimension}`);
-      }
-      return vectors;
-    };
-    let embedded = 0;
-    let skipped = 0;
-    for (let offset = 0;offset < target; offset += batchSize) {
-      const rows = [...this.hydrate(pending.slice(offset, Math.min(offset + batchSize, target))).values()];
-      if (rows.length === 0)
-        continue;
-      try {
-        this.store(rows, await embed(rows));
-        embedded += rows.length;
-      } catch (batchError) {
-        const rejected = [];
-        let lastError = batchError;
-        for (const row of rows) {
-          try {
-            this.store([row], await embed([row]));
-            embedded += 1;
-          } catch (error) {
-            rejected.push(row);
-            lastError = error;
-          }
-        }
-        if (rejected.length === 0)
-          continue;
-        if (embedded === 0)
-          return { ok: false, message: errorMessage(lastError) };
-        this.store(rejected, undefined);
-        skipped += rejected.length;
-      }
-    }
-    return { ok: true, embedded, skipped, pruned, remaining: pending.length - embedded - skipped };
-  }
-  adoptIdentity(identity) {
-    const serialized = JSON.stringify(identity);
-    const current = this.db.prepare("select v from sidecar_meta where k = ?").get(IDENTITY_KEY);
-    if (current?.v === serialized)
-      return;
-    this.transaction(() => {
-      this.db.exec("delete from sidecar_vec");
-      this.db.prepare("insert or replace into sidecar_meta (k, v) values (?, ?)").run(IDENTITY_KEY, serialized);
-    });
-    this.lastSemantic = undefined;
-  }
-  prune() {
-    const { descriptor } = this.options;
-    const result = this.db.prepare(`delete from sidecar_vec where message_key not in (
-					select ${descriptor.keyExpression} from ${descriptor.fromClause} where ${this.where}
-				)`).run(...this.whereParams());
-    if (Number(result.changes) > 0)
-      this.lastSemantic = undefined;
-    return Number(result.changes);
-  }
-  pendingKeys() {
-    const { descriptor } = this.options;
-    const rows = this.db.prepare(`select ${this.select}, v.hash as stored_hash
-				from ${descriptor.fromClause}
-				left join sidecar_vec v on v.message_key = ${descriptor.keyExpression}
-				where ${this.where}`).iterate(...this.whereParams());
-    const pending = [];
-    for (const row of rows) {
-      if (row.stored_hash !== this.toRow(row).hash)
-        pending.push(String(row.k));
-    }
-    return pending;
-  }
-  hydrate(keys) {
-    const { descriptor } = this.options;
-    const out = new Map;
-    if (keys.length === 0)
-      return out;
-    const rows = this.db.prepare(`select ${this.select} from ${descriptor.fromClause}
-				where ${descriptor.keyExpression} in (${keys.map(() => "?").join(", ")}) and ${this.where}`).all(...keys, ...this.whereParams());
-    const byKey = new Map(rows.map((row) => [String(row.k), this.toRow(row)]));
-    for (const key of keys) {
-      const row = byKey.get(key);
-      if (row !== undefined)
-        out.set(key, row);
-    }
-    return out;
-  }
-  store(rows, vectors) {
-    const upsert = this.db.prepare("insert or replace into sidecar_vec (message_key, hash, vec) values (?, ?, ?)");
-    this.transaction(() => {
-      for (const [index, row] of rows.entries()) {
-        upsert.run(row.key, row.hash, encodeVector(vectors?.[index] ?? []));
-      }
-    });
-    this.lastSemantic = undefined;
-  }
-  *storedVectors() {
-    const rows = this.db.prepare("select message_key, vec from sidecar_vec where length(vec) > 0").iterate();
-    for (const row of rows) {
-      const vector = row.vec instanceof Uint8Array ? decodeVector(row.vec) : undefined;
-      if (vector !== undefined)
-        yield { key: String(row.message_key), vector };
-    }
-  }
-  transaction(work) {
-    this.db.exec("begin immediate");
-    try {
-      work();
-      this.db.exec("commit");
-    } catch (error) {
-      this.db.exec("rollback");
-      throw error;
-    }
-  }
-  toRow(row) {
-    const metadata = {};
-    for (const [index, column] of this.options.descriptor.metadata.entries()) {
-      const value = row[`m${index}`];
-      if (typeof value === "string" && value.length > 0 || typeof value === "number")
-        metadata[column.key] = String(value);
-    }
-    const title = typeof row.title === "string" && row.title.length > 0 ? row.title : undefined;
-    const epoch = typeof row.epoch === "number" && Number.isFinite(row.epoch) ? row.epoch : undefined;
-    const content = String(row.content ?? "");
-    const input = `${title ?? ""}
-${content}`.slice(0, MAX_EMBED_INPUT_CHARS);
-    return {
-      key: String(row.k),
-      content,
-      title,
-      epoch,
-      metadata,
-      input,
-      hash: createHash6("sha1").update(input).digest("hex")
-    };
-  }
-  toHit(row, score) {
-    return {
-      key: row.key,
-      content: row.content,
-      score,
-      ...row.title !== undefined ? { title: row.title } : {},
-      ...row.epoch !== undefined ? { publishedAt: Math.round(row.epoch * 1000) } : {},
-      metadata: row.metadata
-    };
-  }
-}
-function toMatchQuery(text) {
-  const terms = [...new Set(text.match(/[\p{L}\p{N}_]+/gu) ?? [])];
-  return terms.length === 0 ? undefined : terms.map((term) => `"${term}"`).join(" OR ");
-}
-function errorMessage(error) {
-  return error instanceof Error ? error.message : String(error);
-}
-var DEFAULT_BATCH_SIZE = 256, DEFAULT_MAX_EMBED_PER_SYNC = 2048, MAX_EMBED_INPUT_CHARS = 8192, BUSY_TIMEOUT_MS = 5000, POOL_FACTOR = 3, SEMANTIC_REUSE_MS = 1e4, IDENTITY_KEY = "identity";
-var init_sidecar = () => {};
-
-// src/datasource/sidecar/methods.ts
-function sidecarMethodName(datasourceId, mode) {
-  return mode === "bm25" ? `${datasourceId}-sidecar-bm25` : `${datasourceId}-${mode}`;
-}
-
-class SidecarRetrievalMethod {
-  options;
-  constructor(options) {
-    this.options = options;
-  }
-  describe() {
-    const { datasourceId, skillType, mode, tags } = this.options;
-    const { type, text, capabilities } = DESCRIPTIONS[mode];
-    return {
-      name: sidecarMethodName(datasourceId, mode),
-      type,
-      description: `${text} over ${skillType} via a read-only sidecar index`,
-      status: "active",
-      capabilities: [...capabilities, "scoped", "path-opaque-sources"],
-      datasourceId,
-      tags
-    };
-  }
-  async retrieve(query, options) {
-    const trimmed = query.trim();
-    if (trimmed.length === 0)
-      return [];
-    const topK = options.topK ?? DEFAULT_TOP_K5;
-    const { sidecar, mode } = this.options;
-    const hits = mode === "bm25" ? sidecar.searchLexical(trimmed, topK) : mode === "semantic" ? await sidecar.searchSemantic(trimmed, topK) : await sidecar.searchHybrid(trimmed, topK);
-    const results = [];
-    for (const hit of hits) {
-      const result = this.toResult(hit, options);
-      if (result !== undefined)
-        results.push(result);
-    }
-    return results;
-  }
-  toResult(hit, options) {
-    const { descriptor, datasourceId, instanceId, mode } = this.options;
-    const chunkId = descriptor.chunkId(hit.key, hit.metadata);
-    const source = datasourceSourcePath(datasourceId, instanceId, chunkId);
-    if (!matchesDatasourceScope(source, options.scope))
-      return;
-    const method = sidecarMethodName(datasourceId, mode);
-    return {
-      id: `${datasourceId}:${instanceId}:${chunkId}`,
-      content: hit.content,
-      source,
-      score: hit.score,
-      metadata: {
-        ...hit.metadata,
-        method,
-        datasourceId,
-        instanceId,
-        backend: "sidecar",
-        ...hit.title !== undefined ? { title: hit.title } : {},
-        hierarchy: descriptor.hierarchy(hit.metadata).join("/"),
-        ...hit.publishedAt !== undefined ? { publishedAt: hit.publishedAt } : {}
-      }
-    };
-  }
-}
-var DEFAULT_TOP_K5 = 20, DESCRIPTIONS;
-var init_methods5 = __esm(() => {
-  init_scope2();
-  DESCRIPTIONS = {
-    bm25: { type: "bm25", text: "BM25-ranked FTS5 retrieval", capabilities: ["lexical", "fts5", "bm25"] },
-    semantic: { type: "vector", text: "Semantic (embedding) retrieval", capabilities: ["semantic"] },
-    hybrid: {
-      type: "hybrid",
-      text: "Hybrid BM25 + semantic retrieval (reciprocal rank fusion)",
-      capabilities: ["lexical", "semantic", "hybrid"]
-    }
-  };
-});
-
 // src/datasource/crawler-skill.ts
 class CrawlerDatasourceSkill {
   definition;
@@ -9766,7 +9880,7 @@ var init_crawler_skill = __esm(() => {
   init_errors2();
   init_scope2();
   init_sidecar();
-  init_methods5();
+  init_methods4();
   DEFAULT_POLLING_INTERVAL_MS4 = 15 * 60 * 1000;
 });
 
@@ -11555,14 +11669,27 @@ var init_factory = __esm(() => {
       ...config.channels?.ids !== undefined ? { chatIds: config.channels.ids } : {},
       ...larkConnectorOptions(config.connector)
     }),
-    kakao: (config, _workspaceRoot, _registrationName) => new LazykatokSkill({
-      client: new LazykatokClient({
-        ...config.connector
-      }),
-      ...config.instanceId !== undefined ? { instanceId: config.instanceId } : {},
-      ...config.pollingIntervalMs !== undefined ? { pollingIntervalMs: config.pollingIntervalMs } : {},
-      ...config.tags !== undefined ? { tags: config.tags } : {}
-    }),
+    kakao: (config, workspaceRoot, registrationName) => {
+      const connector = config.connector ?? {};
+      const dataDir = typeof connector.workspacePath === "string" && connector.workspacePath.length > 0 ? connector.workspacePath : join16(homedir4(), "Library", "Application Support", "katok");
+      const sidecar = resolveSidecarOptions({
+        descriptor: CRAWLER_DESCRIPTORS.kakao,
+        connector: config.connector,
+        workspaceRoot,
+        registrationName,
+        instanceId: config.instanceId ?? "default",
+        defaultCrawlerDb: join16(dataDir, "archive.sqlite3")
+      });
+      return new LazykatokSkill({
+        client: new LazykatokClient(connector),
+        ...config.instanceId !== undefined ? { instanceId: config.instanceId } : {},
+        ...config.pollingIntervalMs !== undefined ? { pollingIntervalMs: config.pollingIntervalMs } : {},
+        ...config.tags !== undefined ? { tags: config.tags } : {},
+        channelIds: config.channels?.ids,
+        channelNames: config.channels?.names,
+        ...sidecar === undefined ? {} : { sidecar }
+      });
+    },
     github: (config, workspaceRoot, registrationName) => new GitHubSkill({
       ...common(config, workspaceRoot),
       skillName: registrationName,
@@ -12227,7 +12354,7 @@ function migrateLegacyConfig(configPath, legacyPath) {
   const legacy = readConfigFile(legacyPath, true);
   const legacyBytes = readFileSync14(legacyPath);
   const migrated = normalizeLegacyConfigPaths(legacy ?? {}, dirname13(legacyPath));
-  const migratedPathsUnchanged = legacy?.workspacePath === migrated.workspacePath && legacy?.memoryPath === migrated.memoryPath && JSON.stringify(legacy?.searchPaths) === JSON.stringify(migrated.searchPaths);
+  const migratedPathsUnchanged = legacy?.workspacePath === migrated.workspacePath && legacy?.memoryPath === migrated.memoryPath && JSON.stringify(legacy?.searchPaths) === JSON.stringify(migrated.searchPaths) && JSON.stringify(legacy?.excludePaths) === JSON.stringify(migrated.excludePaths);
   const migratedBytes = migratedPathsUnchanged ? legacyBytes : `${JSON.stringify(migrated, null, 2)}
 `;
   mkdirSync11(dirname13(configPath), { recursive: true });
@@ -12265,15 +12392,25 @@ function resolveConfigFileReadOnly(configPath, explicit, legacyPath) {
 function resolveSearchPaths(searchPaths, origin) {
   return searchPaths.map((searchPath) => resolvePersistedPath(searchPath, origin));
 }
+function resolveExcludePaths(value, origin) {
+  if (value === undefined)
+    return;
+  if (!Array.isArray(value) || value.some((path) => typeof path !== "string" || path.length === 0)) {
+    throw new ConfigError("Config field 'excludePaths' must be a non-empty string array");
+  }
+  return resolveSearchPaths(value, origin);
+}
 function resolvePersistedPath(path, origin) {
   return isAbsolute5(path) ? path : resolve7(origin, path);
 }
 function normalizeLegacyConfigPaths(partial, origin) {
   const workspacePath = resolvePersistedPath(partial.workspacePath ?? ".", origin);
+  const excludePaths = resolveExcludePaths(partial.excludePaths, workspacePath);
   return {
     ...partial,
     workspacePath,
     ...partial.searchPaths === undefined ? {} : { searchPaths: resolveSearchPaths(partial.searchPaths, workspacePath) },
+    ...excludePaths === undefined ? {} : { excludePaths },
     ...partial.memoryPath === undefined ? {} : { memoryPath: resolvePersistedPath(partial.memoryPath, workspacePath) }
   };
 }
@@ -12728,10 +12865,7 @@ function resolveConfig(input) {
   const configOrigin = dirname13(resolve7(configPath));
   const fileWorkspacePath = typeof file.workspacePath === "string" ? resolvePersistedPath(file.workspacePath, configOrigin) : undefined;
   const fileSearchPaths = file.searchPaths ? resolveSearchPaths(file.searchPaths, fileWorkspacePath ?? configOrigin) : undefined;
-  if (file.excludePaths !== undefined && (!Array.isArray(file.excludePaths) || file.excludePaths.some((path) => typeof path !== "string" || path.length === 0))) {
-    throw new ConfigError("Config field 'excludePaths' must be a non-empty string array");
-  }
-  const fileExcludePaths = file.excludePaths ? resolveSearchPaths(file.excludePaths, fileWorkspacePath ?? configOrigin) : undefined;
+  const fileExcludePaths = resolveExcludePaths(file.excludePaths, fileWorkspacePath ?? configOrigin);
   const searchPaths = flagSearchPaths ?? envSearchPaths ?? fileSearchPaths ?? defaultSearchPaths;
   const flagWorkspacePath = flagString(flags, "workspace");
   const envWorkspacePath = envString(env, "AUTORAG_WORKSPACE");
@@ -13467,7 +13601,7 @@ function writeDefaultConfig(path, partial, opts = {}) {
   full.dupey = partial.dupey ?? { enabled: true };
   full.excludeExactDuplicates = partial.excludeExactDuplicates ?? true;
   if (partial.excludePaths !== undefined)
-    full.excludePaths = resolveSearchPaths(partial.excludePaths, workspacePath);
+    full.excludePaths = resolveExcludePaths(partial.excludePaths, workspacePath);
   if (partial.limits !== undefined)
     full.limits = normalizeLimitsConfig(partial.limits);
   if (partial.refresh !== undefined)
@@ -13611,7 +13745,7 @@ var init_config4 = __esm(() => {
 
 // src/cli/commands/init.ts
 import { existsSync as existsSync11, readFileSync as readFileSync15 } from "node:fs";
-import { dirname as dirname14 } from "node:path";
+import { dirname as dirname14, resolve as resolve8 } from "node:path";
 async function runInit(ctx) {
   const flags = ctx.flags;
   const partial = {};
@@ -13619,6 +13753,14 @@ async function runInit(ctx) {
   if (searchPathsFlag) {
     partial.searchPaths = searchPathsFlag.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
   }
+  const excludedPaths = ctx.repeatedFlags?.exclude ?? (typeof flags.exclude === "string" ? [flags.exclude] : undefined);
+  if (flags.exclude !== undefined || excludedPaths !== undefined) {
+    if (excludedPaths === undefined || excludedPaths.length === 0 || excludedPaths.some((path) => path.trim().length === 0)) {
+      ctx.stderr(renderError(new ConfigError("--exclude requires a non-empty path"), { json: ctx.json, debug: ctx.debug }));
+      return 2;
+    }
+    partial.excludePaths = excludedPaths.map((path) => resolve8(ctx.cwd, path));
+  }
   if (typeof flags.workspace === "string")
     partial.workspacePath = flags.workspace;
   if (typeof flags["memory-path"] === "string")
@@ -13683,6 +13825,7 @@ async function runInit(ctx) {
       const legacy = JSON.parse(readFileSync15(legacyPath, "utf8"));
       const normalizedLegacy = normalizeLegacyConfigPaths(legacy, dirname14(legacyPath));
       partial.searchPaths ??= normalizedLegacy.searchPaths;
+      partial.excludePaths ??= normalizedLegacy.excludePaths;
       partial.workspacePath ??= normalizedLegacy.workspacePath;
       partial.memoryPath ??= normalizedLegacy.memoryPath;
       partial.model ??= legacy.model;
@@ -14265,9 +14408,9 @@ var init_retry = __esm(() => {
 
 // src/dupey/cli.ts
 import { spawn as spawn10 } from "node:child_process";
-import { resolve as resolve8 } from "node:path";
+import { resolve as resolve9 } from "node:path";
 async function scanWithDupey(dir, options = {}) {
-  const absoluteDir = resolve8(dir);
+  const absoluteDir = resolve9(dir);
   const stdout = options.run ? await options.run(["scan", absoluteDir, "--json"]) : await spawnDupey(options.executable ?? "dupey", ["scan", absoluteDir, "--json"], options);
   let parsed;
   try {
@@ -14337,13 +14480,13 @@ var init_cli = __esm(() => {
 
 // src/dupey/filter.ts
 import { stat as stat5 } from "node:fs/promises";
-import { resolve as resolve9 } from "node:path";
+import { resolve as resolve10 } from "node:path";
 async function selectExactDuplicateExclusions(root, scan, isUnavailable) {
   const byHash = new Map;
   for (const file of scan.files) {
     if (typeof file.content_hash !== "string" || file.content_hash.length === 0)
       continue;
-    const path = resolve9(root, file.path);
+    const path = resolve10(root, file.path);
     const group = byHash.get(file.content_hash) ?? [];
     group.push(path);
     byHash.set(file.content_hash, group);
@@ -14380,7 +14523,7 @@ function dupeyExactRanking(scan) {
         return;
       const path = entry.path;
       if (typeof path === "string")
-        ranking.set(resolve9(path), index);
+        ranking.set(resolve10(path), index);
     });
   }
   return ranking;
@@ -14536,14 +14679,33 @@ function errorMessage2(error) {
 var MANIFEST_FILENAME = "manifest.json";
 var init_bundle = () => {};
 
+// src/filesystem/path-exclusions.ts
+import { posix as posix2, win32 as win322 } from "node:path";
+function createPathExclusionMatcher(excludedPaths, platform = process.platform) {
+  const paths = platform === "win32" ? win322 : posix2;
+  const normalize = (path) => {
+    const absolute = paths.resolve(path);
+    return platform === "win32" ? absolute.toLowerCase() : absolute;
+  };
+  const excluded = excludedPaths.map((path) => {
+    const absolute = normalize(path);
+    return { absolute, prefix: absolute.endsWith(paths.sep) ? absolute : `${absolute}${paths.sep}` };
+  });
+  return (path) => {
+    const absolute = normalize(path);
+    return excluded.some((entry) => absolute === entry.absolute || absolute.startsWith(entry.prefix));
+  };
+}
+var init_path_exclusions = () => {};
+
 // src/everything/client.ts
 import { spawn as spawn11 } from "node:child_process";
 import { createHash as createHash9 } from "node:crypto";
 import { mkdirSync as mkdirSync13, writeFileSync as writeFileSync11 } from "node:fs";
-import { join as join22, resolve as resolve10 } from "node:path";
+import { join as join22, resolve as resolve11 } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 function everythingInstanceName(root) {
-  return `autorag-${createHash9("sha256").update(resolve10(root).toLowerCase()).digest("hex").slice(0, 12)}`;
+  return `autorag-${createHash9("sha256").update(resolve11(root).toLowerCase()).digest("hex").slice(0, 12)}`;
 }
 function buildEverythingIni(input) {
   const list = (values) => values.map((value) => `"${value.replace(/\\/g, "\\\\")}"`).join(",");
@@ -14653,6 +14815,7 @@ class EverythingClient {
   run;
   launch;
   stateDir;
+  isExcludedPath;
   binaries;
   operation = Promise.resolve();
   constructor(options) {
@@ -14662,6 +14825,7 @@ class EverythingClient {
     this.run = options.run ?? runProcess;
     this.launch = options.launch ?? launchDetached;
     this.stateDir = join22(options.root, ".autorag", "everything");
+    this.isExcludedPath = createPathExclusionMatcher(options.excludeFolders ?? [], "win32");
   }
   isSupported() {
     return this.platform === "win32";
@@ -14681,6 +14845,9 @@ class EverythingClient {
       }
       const es = { ok: true, esPath: binaries.esPath };
       const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS6;
+      if ((this.options.excludeFolders?.length ?? 0) > 0) {
+        return this.searchWithExclusions(es.esPath, request, timeoutMs);
+      }
       const args = buildEverythingSearchArgs(this.instanceName, request, timeoutMs);
       const result = await this.run(es.esPath, args, timeoutMs + 5000);
       if (result.code !== 0)
@@ -14692,6 +14859,50 @@ class EverythingClient {
       }
     });
   }
+  async searchWithExclusions(esPath, request, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    const offset = request.offset ?? 0;
+    const maxResults = request.maxResults ?? DEFAULT_MAX_RESULTS;
+    const results = [];
+    let skipped = 0;
+    let nativeOffset = 0;
+    const timedOut = () => ({
+      ok: false,
+      reason: "search-failed",
+      message: `Everything search exceeded ${timeoutMs}ms while filtering excluded paths; narrow the query or increase the Everything timeout.`
+    });
+    for (;; ) {
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0)
+        return timedOut();
+      const args = buildEverythingSearchArgs(this.instanceName, { ...request, offset: nativeOffset, maxResults: MAX_FILTER_CANDIDATES }, remainingMs);
+      const response = await this.run(esPath, args, remainingMs + 5000);
+      if (response.code !== 0)
+        return this.failure("search-failed", esPath, args, response);
+      if (Date.now() >= deadline)
+        return timedOut();
+      let entries;
+      try {
+        entries = parseEverythingJson(response.stdout);
+      } catch (error) {
+        return { ok: false, reason: "search-failed", message: error.message };
+      }
+      for (const entry of entries) {
+        if (this.isExcludedPath(entry.path))
+          continue;
+        if (skipped < offset) {
+          skipped += 1;
+          continue;
+        }
+        results.push(entry);
+        if (results.length >= maxResults)
+          return { ok: true, results };
+      }
+      if (entries.length < MAX_FILTER_CANDIDATES)
+        return { ok: true, results };
+      nativeOffset += entries.length;
+    }
+  }
   index() {
     return this.serialize(async () => {
       const es = await this.ensureRunning(true);
@@ -14765,7 +14976,8 @@ class EverythingClient {
       excludeFolders: [
         ...new Set([
           join22(this.options.root, ".autorag"),
-          ...this.options.folders.map((folder) => join22(folder, ".autorag"))
+          ...this.options.folders.map((folder) => join22(folder, ".autorag")),
+          ...this.options.excludeFolders ?? []
         ])
       ]
     }));
@@ -14859,8 +15071,9 @@ function launchDetached(command, args) {
   child.on("error", () => {});
   child.unref();
 }
-var DEFAULT_TIMEOUT_MS6 = 30000, DEFAULT_STARTUP_TIMEOUT_MS = 20000, DEFAULT_INDEX_TIMEOUT_MS2, DEFAULT_POLL_INTERVAL_MS = 250, DEFAULT_MAX_RESULTS = 100, MAX_OUTPUT_BYTES, VERSION_PATTERN;
+var DEFAULT_TIMEOUT_MS6 = 30000, DEFAULT_STARTUP_TIMEOUT_MS = 20000, DEFAULT_INDEX_TIMEOUT_MS2, DEFAULT_POLL_INTERVAL_MS = 250, DEFAULT_MAX_RESULTS = 100, MAX_FILTER_CANDIDATES = 1000, MAX_OUTPUT_BYTES, VERSION_PATTERN;
 var init_client7 = __esm(() => {
+  init_path_exclusions();
   init_bundle();
   DEFAULT_INDEX_TIMEOUT_MS2 = 10 * 60000;
   MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
@@ -14880,6 +15093,7 @@ function compare(a, b) {
   return a < b ? -1 : a > b ? 1 : 0;
 }
 async function walkFileSearch(folders, request, options = {}) {
+  const isExcluded = createPathExclusionMatcher(options.excludeFolders ?? []);
   const maxVisited = options.maxVisited ?? DEFAULT_MAX_VISITED;
   const maxMatches = options.maxMatches ?? DEFAULT_MAX_MATCHES;
   const deadline = Date.now() + (options.deadlineMs ?? DEFAULT_DEADLINE_MS);
@@ -14902,6 +15116,8 @@ async function walkFileSearch(folders, request, options = {}) {
   outer:
     while (pending.length > 0) {
       const dir = pending.pop();
+      if (isExcluded(dir))
+        continue;
       if (Date.now() >= deadline) {
         truncated = true;
         break;
@@ -14919,6 +15135,8 @@ async function walkFileSearch(folders, request, options = {}) {
         }
         visited += 1;
         const path = join23(dir, dirent.name);
+        if (isExcluded(path))
+          continue;
         if (dirent.isDirectory()) {
           if (dirent.name === ".autorag")
             continue;
@@ -14953,6 +15171,8 @@ async function walkFileSearch(folders, request, options = {}) {
       }
     }
   for (const folder of folders) {
+    if (isExcluded(folder))
+      continue;
     if (!underPath(folder) || !matches(folder))
       continue;
     if (request.kind === "files")
@@ -14979,6 +15199,7 @@ async function walkFileSearch(folders, request, options = {}) {
 }
 var DEFAULT_MAX_VISITED = 500000, DEFAULT_DEADLINE_MS = 20000, DEFAULT_MAX_MATCHES = 1e4, SORT_ORDERS;
 var init_walk = __esm(() => {
+  init_path_exclusions();
   SORT_ORDERS = {
     "name-ascending": (a, b) => compare(a.name, b.name),
     "name-descending": (a, b) => compare(b.name, a.name),
@@ -14995,14 +15216,14 @@ var init_walk = __esm(() => {
 import { spawn as spawn12 } from "node:child_process";
 import { createHash as createHash10 } from "node:crypto";
 import { existsSync as existsSync15, mkdirSync as mkdirSync14, readFileSync as readFileSync18, realpathSync as realpathSync2, rmSync as rmSync4, writeFileSync as writeFileSync12 } from "node:fs";
-import { basename as basename9, join as join24, resolve as resolve11, sep as sep4 } from "node:path";
+import { basename as basename9, join as join24, resolve as resolve12, sep as sep4 } from "node:path";
 import { setTimeout as sleep2 } from "node:timers/promises";
 function fsearchSocketPath(dbPath) {
   let canonical;
   try {
     canonical = realpathSync2(dbPath);
   } catch {
-    canonical = resolve11(dbPath);
+    canonical = resolve12(dbPath);
   }
   const hash = createHash10("sha256").update(canonical).digest("hex").slice(0, 12);
   return `/tmp/autorag-fsearch-${process.getuid?.() ?? 0}-${hash}.sock`;
@@ -15088,6 +15309,7 @@ class FSearchClient {
   launch;
   isAlive;
   kill;
+  isExcludedPath;
   stateDir;
   dbPath;
   pidPath;
@@ -15100,6 +15322,7 @@ class FSearchClient {
     this.launch = options.launch ?? launchDetached2;
     this.isAlive = options.isProcessAlive ?? defaultIsProcessAlive;
     this.kill = options.killProcess ?? ((pid) => process.kill(pid, "SIGTERM"));
+    this.isExcludedPath = createPathExclusionMatcher(options.excludeFolders ?? []);
     this.stateDir = join24(options.root, ".autorag", "fsearch");
     this.dbPath = join24(this.stateDir, "fsearch.db");
     this.pidPath = join24(this.stateDir, "watch.pid");
@@ -15117,6 +15340,7 @@ class FSearchClient {
       if (unavailable !== undefined || !binary.ok) {
         try {
           const walked = await walkFileSearch(this.options.folders, request, {
+            excludeFolders: this.options.excludeFolders,
             maxVisited: this.options.walkMaxVisited,
             deadlineMs: this.options.walkDeadlineMs
           });
@@ -15131,7 +15355,9 @@ class FSearchClient {
           return { ok: false, reason: "search-failed", message: error.message };
         }
       }
-      const args = buildFSearchSearchArgs(this.dbPath, this.socketPath(), request);
+      const hasExclusions = (this.options.excludeFolders?.length ?? 0) > 0;
+      const nativeRequest = hasExclusions ? { ...request, offset: 0, maxResults: MAX_RESULTS_CAP } : request;
+      const args = buildFSearchSearchArgs(this.dbPath, this.socketPath(), nativeRequest);
       const result = await this.run(binary.path, args, this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS7);
       if (result.code !== 0)
         return this.failure("search-failed", binary.path, args, result);
@@ -15142,6 +15368,10 @@ class FSearchClient {
         return { ok: false, reason: "search-failed", message: error.message };
       }
       let entries = parsed.entries;
+      if (hasExclusions) {
+        const isExcluded = this.isExcludedPath;
+        entries = entries.filter((entry) => !isExcluded(entry.path));
+      }
       if (request.path !== undefined) {
         const prefix = request.path.endsWith(sep4) ? request.path : `${request.path}${sep4}`;
         entries = entries.filter((entry) => entry.path === request.path || entry.path.startsWith(prefix));
@@ -15151,7 +15381,16 @@ class FSearchClient {
       const maxResults = Math.min(request.maxResults ?? DEFAULT_MAX_RESULTS2, MAX_RESULTS_CAP);
       if (entries.length > maxResults)
         entries = entries.slice(0, maxResults);
-      return { ok: true, backend: "fsearch-cli", results: entries, total: parsed.total };
+      return {
+        ok: true,
+        backend: "fsearch-cli",
+        results: entries,
+        total: parsed.total,
+        ...hasExclusions && parsed.total !== undefined && parsed.total > parsed.entries.length && entries.length < maxResults ? {
+          truncated: true,
+          note: `FSearch checked ${parsed.entries.length} of ${parsed.total} native matches before exclusions (candidate limit ${MAX_RESULTS_CAP}); results may be incomplete. Narrow the query.`
+        } : {}
+      };
     });
   }
   index() {
@@ -15345,6 +15584,7 @@ function defaultIsProcessAlive(pid) {
 }
 var DEFAULT_TIMEOUT_MS7 = 30000, DEFAULT_STARTUP_TIMEOUT_MS2 = 1e4, STOP_TIMEOUT_MS = 2000, DEFAULT_INDEX_TIMEOUT_MS3, DEFAULT_POLL_INTERVAL_MS2 = 250, DEFAULT_MAX_RESULTS2 = 100, MAX_RESULTS_CAP = 1000, MAX_OUTPUT_BYTES2, SORT_KEYS;
 var init_client8 = __esm(() => {
+  init_path_exclusions();
   init_walk();
   DEFAULT_INDEX_TIMEOUT_MS3 = 10 * 60000;
   MAX_OUTPUT_BYTES2 = 8 * 1024 * 1024;
@@ -15416,7 +15656,7 @@ var init_diagnostics = __esm(() => {
 
 // src/jikji/answer-pack.ts
 import { realpathSync as realpathSync3 } from "node:fs";
-import { isAbsolute as isAbsolute7, join as join25, relative as relative3, resolve as resolve12 } from "node:path";
+import { isAbsolute as isAbsolute7, join as join25, relative as relative3, resolve as resolve13 } from "node:path";
 function isRecord10(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -15546,7 +15786,7 @@ function normalizeJikjiAnswerPath(rawPath, sourceRoots) {
     } else {
       if (normalized.split("/").includes(".."))
         continue;
-      candidate = resolve12(realRoot, normalized);
+      candidate = resolve13(realRoot, normalized);
     }
     let realCandidate;
     try {
@@ -15983,7 +16223,7 @@ var init_client9 = __esm(() => {
 });
 
 // src/jikji/path-map.ts
-import { isAbsolute as isAbsolute8, relative as relative4, resolve as resolve13, sep as sep5 } from "node:path";
+import { isAbsolute as isAbsolute8, relative as relative4, resolve as resolve14, sep as sep5 } from "node:path";
 function planJikjiSourceRoots(searchPaths) {
   return planSourceRoots(searchPaths).map((sourceRoot) => ({
     ...sourceRoot,
@@ -15991,7 +16231,7 @@ function planJikjiSourceRoots(searchPaths) {
   }));
 }
 function outermostJikjiRoots(searchPaths) {
-  const unique = [...new Set(searchPaths.map((searchPath) => resolve13(searchPath)))];
+  const unique = [...new Set(searchPaths.map((searchPath) => resolve14(searchPath)))];
   return unique.filter((candidate) => !unique.some((other) => {
     if (other === candidate)
       return false;
@@ -16012,13 +16252,13 @@ function resolveReturnedPath(rootPath, returnedPath) {
     return;
   if (normalized.split("/").includes(".."))
     return;
-  return resolve13(rootPath, normalized);
+  return resolve14(rootPath, normalized);
 }
 function isUnsafeReturnedPath(normalizedPath) {
   return normalizedPath.startsWith("/") || /^[A-Za-z]:\//.test(normalizedPath) || normalizedPath.startsWith("//") || /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(normalizedPath);
 }
 function isWithinRoot(rootPath, sourcePath) {
-  const rel = relative4(resolve13(rootPath), resolve13(sourcePath));
+  const rel = relative4(resolve14(rootPath), resolve14(sourcePath));
   return rel === "" || !rel.startsWith("..") && !rel.includes(`..${sep5}`) && !isAbsolute8(rel);
 }
 var init_path_map = __esm(() => {
@@ -18314,7 +18554,7 @@ var init_isolated = __esm(() => {
 // src/mirror/sync.ts
 import { existsSync as existsSync24, rmSync as rmSync8 } from "node:fs";
 import { opendir, readFile as readFile5, stat as stat7 } from "node:fs/promises";
-import { extname as extname5, resolve as resolve14, sep as sep7 } from "node:path";
+import { extname as extname5, resolve as resolve15, sep as sep7 } from "node:path";
 import { setTimeout as sleep3 } from "node:timers/promises";
 function errorCode(error) {
   if (!(error instanceof Error))
@@ -18832,7 +19072,7 @@ async function collectFiles(state, directory, depth) {
         continue;
       if (PRODUCT_ARTIFACT_FILE_NAMES.has(entry.name))
         continue;
-      const sourcePath = resolve14(directory, entry.name);
+      const sourcePath = resolve15(directory, entry.name);
       if (entry.isDirectory()) {
         if (depth + 1 > state.limits.maxDepth) {
           listing.unreliablePrefixes.push(sourceIdentifier(sourceRoot, sourcePath));
@@ -20015,12 +20255,43 @@ function digitsEndAt(text, from) {
     end += 1;
   return end;
 }
-function continuesAsProse(answer, from) {
-  if (answer[from] !== " " && answer[from] !== " ")
+function continuesAsProse(answer, openIndex, from) {
+  let cursor = from;
+  let leadingEmphasis = 0;
+  while (openIndex - 1 - leadingEmphasis >= 0 && (answer[openIndex - 1 - leadingEmphasis] === "*" || answer[openIndex - 1 - leadingEmphasis] === "_")) {
+    leadingEmphasis += 1;
+  }
+  if (leadingEmphasis > 0) {
+    let trailingEmphasis = 0;
+    while (cursor + trailingEmphasis < answer.length && trailingEmphasis < leadingEmphasis && answer[cursor + trailingEmphasis] === answer[openIndex - 1 - trailingEmphasis]) {
+      trailingEmphasis += 1;
+    }
+    if (trailingEmphasis === leadingEmphasis)
+      cursor += trailingEmphasis;
+  }
+  const tokenStart = openIndex - leadingEmphasis;
+  const linePrefix = answer.slice(answer.lastIndexOf(`
+`, tokenStart - 1) + 1, tokenStart);
+  const atHeadingStart = /^[ \t>*-]*$/u.test(linePrefix);
+  if (atHeadingStart && answer[cursor] === ":")
+    cursor += 1;
+  if (answer[cursor] !== " " && answer[cursor] !== " ")
     return false;
-  const next = answer.codePointAt(from + 1);
+  cursor += 1;
+  while (cursor < answer.length && (answer[cursor] === "*" || answer[cursor] === "_" || answer[cursor] === '"' || answer[cursor] === "'" || answer[cursor] === "“" || answer[cursor] === "‘")) {
+    cursor += 1;
+  }
+  const next = answer.codePointAt(cursor);
   return next !== undefined && /[\p{L}\p{N}]/u.test(String.fromCodePoint(next));
 }
+function isLegalPinpoint(answer, openIndex, afterCloseIndex) {
+  if (PINPOINT_RANGE_AHEAD.test(answer.slice(afterCloseIndex, afterCloseIndex + 16)))
+    return true;
+  if (PINPOINT_RANGE_BEHIND.test(answer.slice(Math.max(0, openIndex - 16), openIndex)))
+    return true;
+  const prefixWindow = answer.slice(Math.max(0, openIndex - 120), openIndex);
+  return PARA_PINPOINT_PREFIX.test(prefixWindow) || CLAUSE_START_AT_PREFIX.test(prefixWindow) || CASE_CITATION_AT_PREFIX.test(prefixWindow);
+}
 function evidenceMarkerAt(answer, index) {
   const ids = [];
   let cursor = index + 1;
@@ -20086,7 +20357,7 @@ function answerMarkers(answer, isFile = () => false) {
     }
     if (char === "[") {
       const digitsEnd = digitsEndAt(answer, index + 1);
-      if (digitsEnd > index + 1 && answer[digitsEnd] === "]" && answer[digitsEnd + 1] !== "(" && !continuesAsProse(answer, digitsEnd + 1)) {
+      if (digitsEnd > index + 1 && answer[digitsEnd] === "]" && answer[digitsEnd + 1] !== "(" && !continuesAsProse(answer, index, digitsEnd + 1) && !isLegalPinpoint(answer, index, digitsEnd + 1)) {
         markers.push({
           kind: "number",
           start: leadingStart(index),
@@ -20158,7 +20429,14 @@ function assertResultsMappingOneToOne(label, results, mapping) {
   ].filter((note) => note !== undefined);
   throw new Error(`${label}: result numbers and mapping numbers must be one-to-one, but results contain ${formatCitationList(resultNumbers)} ` + `and mapping contains ${formatCitationList(mappingNumbers)}` + (duplicateNotes.length > 0 ? ` (${duplicateNotes.join("; ")})` : "") + ". Give every result a unique number with exactly one mapping entry carrying the same number and no mapping entry without a result.");
 }
-var MAX_FILE_MARKER_CLOSERS = 8, FILE_MARKER_PREFIX = "[file:";
+var MAX_FILE_MARKER_CLOSERS = 8, FILE_MARKER_PREFIX = "[file:", PARA_PINPOINT_PREFIX, CLAUSE_START_AT_PREFIX, CASE_CITATION_AT_PREFIX, PINPOINT_RANGE_AHEAD, PINPOINT_RANGE_BEHIND;
+var init_citations = __esm(() => {
+  PARA_PINPOINT_PREFIX = /(?:^|[^\p{L}\p{N}])(?:paras?\.?|paragraphs?)(?:[ \t\u00a0]+\[\d+\][ \t\u00a0]*(?:[-–—]|,(?:[ \t\u00a0]*(?:and|or)\b)?|and\b|or\b))*[ \t\u00a0]*$/iu;
+  CLAUSE_START_AT_PREFIX = /(?:^|[\n.!?؛;:()]|[>*-])[ \t\u00a0]*At(?:[ \t\u00a0]+\[\d+\][ \t\u00a0]*(?:[-–—]|,(?:[ \t\u00a0]*(?:and|or)\b)?|and\b|or\b))*[ \t\u00a0]+$/u;
+  CASE_CITATION_AT_PREFIX = /(?:\[\d{4}\][^\n.;]*?|\b(?:v|vs\.?)\s+[^\n.;]{1,60}?|\bs(?:ection)?[ \t\u00a0]+\d+[A-Za-z]?(?:\(\d+\))?[^\n.;]{0,30}?)[ \t\u00a0]+at(?:[ \t\u00a0]+\[\d+\][ \t\u00a0]*(?:[-–—]|,(?:[ \t\u00a0]*(?:and|or)\b)?|and\b|or\b))*[ \t\u00a0]+$/iu;
+  PINPOINT_RANGE_AHEAD = /^[ \t\u00a0]*[-–—][ \t\u00a0]*\[\d+\]/u;
+  PINPOINT_RANGE_BEHIND = /\[\d+\][ \t\u00a0]*[-–—][ \t\u00a0]*$/u;
+});
 
 // src/agent/evidence-ledger.ts
 import { createHash as createHash15 } from "node:crypto";
@@ -20442,6 +20720,7 @@ function deriveResultsFromAnswer(text, ledger, options) {
 }
 var MAX_EXCERPT_CHARS = 400, MAX_CLAIM_CHARS = 280, CLAIM_LOOKBACK_CHARS = 600, SENTENCE_END, LEADING_LIST_MARK, EVIDENCE_MARKER_TEXT, LEADING_BLANK;
 var init_answer_citations = __esm(() => {
+  init_citations();
   init_evidence_ledger();
   SENTENCE_END = /[.!?。！？]/u;
   LEADING_LIST_MARK = /^[\s\-*•>]+/u;
@@ -20450,7 +20729,7 @@ var init_answer_citations = __esm(() => {
 });
 
 // src/agent/answer-guidelines.ts
-var ANSWER_IMAGE_EMBED_RULE = "**Images**: when a retrieved result is itself an image file (png, jpg, jpeg, gif, webp, svg, bmp, avif, heic, tiff) and showing it answers the question, embed it in the answer as a markdown image on its own line: `![short description](<absolute source path>)`, followed by its citation, e.g. `![Q3 revenue chart](</data/reports/q3 chart.png>) [e2]`. Use only the real source path of retrieved evidence. Never invent a path, use relative paths, or embed remote URLs. Apart from these image embeds, the no-file-paths rule stands.", ANSWER_IMAGE_DELTA_RULE = "An image already embedded in the first answer must not be embedded again.", ANSWER_CITATION_RULE = "**Citations**: cite supporting evidence inline with the evidence id shown next to each retrieved result, in square brackets (e.g. [e3], or [e3][e7] for two). Copy ids exactly; never invent one. For a local file you opened yourself with `bash`, cite `[file:<absolute path>]`. Cite the evidence that backs a sentence at the end of that sentence. Do not cite numbers, paths, or anything else.";
+var ANSWER_IMAGE_EMBED_RULE = "**Images**: when a retrieved result is itself an image file (png, jpg, jpeg, gif, webp, svg, bmp, avif, heic, tiff) and showing it answers the question, embed it in the answer as a markdown image on its own line: `![short description](<absolute source path>)`, followed by its citation, e.g. `![Q3 revenue chart](</data/reports/q3 chart.png>) [e2]`. Use only the real source path of retrieved evidence. Never invent a path, use relative paths, or embed remote URLs. Apart from these image embeds, the no-file-paths rule stands.", ANSWER_IMAGE_DELTA_RULE = "An image already embedded in the first answer must not be embedded again.", ANSWER_CITATION_RULE = "**Citations**: cite supporting evidence inline with the evidence id shown next to each retrieved result, in square brackets (e.g. [e3], or [e3][e7] for two). Copy ids exactly; never invent one. For a local file you opened yourself with `bash`, cite `[file:<absolute path>]`. Cite the evidence that backs a sentence at the end of that sentence. Do not cite numbers, paths, or anything else.", ANSWER_DELIVERABLE_RULE = '**Deliverables and artifacts**: if the user asks you to draft, write, generate, or prepare a deliverable or artifact (a reply email, letter, legal opinion, summary document, standard-format case citation block, checklist, report, or workflow document — including requests phrased as "how should I reply..." to a specific message), produce the finished, ready-to-use artifact as a file (using `write`, `edit`, or `bash` in local sessions, without overwriting existing source files) in a file format, extension, and structure aligned with the context and domain (e.g. `.eml` or `.md`/`.txt` with headers for an email reply; `.md`, `.txt`, `.docx`, `.hwp`, or `.pdf` matching workspace conventions for a legal opinion, insertable case-citation block, or summary document; `.csv`, `.xlsx`, or `.json` for structured tabular data), containing the complete unabridged artifact (including required headers, precedent passages, pinpoint paragraphs, and standard-format citations) inside the file instead of merely describing how to produce it. Do NOT dump the full artifact text into your reply: unless the user explicitly requests otherwise, keep your reply concise within the at-most-5-bullet direct-answer format, clearly stating the created file\'s exact path/location and briefly summarizing what was generated with inline citations to the underlying source evidence (`[eN]` or `[file:<source path>]`); never cite the newly created deliverable file itself as `[file:...]`.', ANSWER_DELIVERABLE_DELTA_RULE = "If a deliverable or artifact was requested and the first answer could not write the file yet (the fast phase runs without tool calls) or only gave advice about it, create the complete context-aligned deliverable file now during verification and report the created file's location and a brief summary concisely.";
 
 // src/agent/datasource-skill.ts
 import { Type as Type3 } from "typebox";
@@ -22651,7 +22930,7 @@ var init_egress_gate = __esm(() => {
 
 // src/p2p/policy.ts
 import { existsSync as existsSync26, mkdirSync as mkdirSync21, readFileSync as readFileSync23, writeFileSync as writeFileSync17 } from "node:fs";
-import { basename as basename13, dirname as dirname23, join as join36, resolve as resolve15 } from "node:path";
+import { basename as basename13, dirname as dirname23, join as join36, resolve as resolve16 } from "node:path";
 import { parse as parseToml2 } from "smol-toml";
 function isRecord17(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -22934,7 +23213,7 @@ class PolicyStore {
     if (typeof normalizedOptions.workspacePath !== "string" || normalizedOptions.workspacePath.length === 0) {
       throw new PolicyError("workspacePath must be a non-empty path");
     }
-    this.workspacePath = resolve15(normalizedOptions.workspacePath);
+    this.workspacePath = resolve16(normalizedOptions.workspacePath);
     this.sourceRoots = normalizedOptions.sourceRoots;
     const globalConfigPath = normalizedOptions.globalConfigPath ?? resolveGlobalConfigPath(normalizedOptions.homePath);
     const workspacePolicyPath = normalizedOptions.workspacePolicyPath ?? join36(this.workspacePath, ".autorag", "p2p", "policy.toml");
@@ -24365,6 +24644,7 @@ function recordStructuredResultsSession(sessionId, query, details, memory, compo
 }
 var init_search_documents = __esm(() => {
   init_memory();
+  init_citations();
 });
 
 // src/agent/search-all-tool.ts
@@ -24668,6 +24948,10 @@ function buildSystemPrompt(config) {
   const modelId = config.modelId ?? "the configured model";
   const toolLines = [
     toolLine(config, "bash", "read and inspect configured document collections with ls, find, grep, cat, and similar tools, and — in local sessions — organize local files when the user asks (rename, move, copy, create folders, move to trash)"),
+    ...config.remoteSession ? [] : [
+      toolLine(config, "write", "create a new file in local sessions — use this to produce requested deliverables and artifacts in a file format aligned with the request and context without overwriting existing source files"),
+      toolLine(config, "edit", "surgically update an existing deliverable or config file when the user asks (local sessions only)")
+    ],
     toolLine(config, "jikji_find", "local discovery through Jikji answer packs"),
     toolLine(config, "everything_search", "instant Windows file/folder name search (voidtools Everything) across the configured search folders"),
     toolLine(config, "fsearch_search", "instant macOS/Linux file/folder name search (fsearch-cli/FSearch) across the configured search folders, with a slow filesystem-walk fallback"),
@@ -24684,6 +24968,12 @@ function buildSystemPrompt(config) {
     ...config.toolNames.filter((name) => name.startsWith("search_datasource_")).map((name) => `- **${name}**: search only the ${name.slice("search_datasource_".length).replace(/_/g, "-")} datasource connection, spawning no other datasource CLIs`),
     ...config.toolNames.filter((name) => ![
       "bash",
+      "read",
+      "write",
+      "edit",
+      "grep",
+      "find",
+      "ls",
       "jikji_find",
       "everything_search",
       "fsearch_search",
@@ -24816,8 +25106,9 @@ Your answer is your final reply, written as plain text, never as a tool call. Ci
 ## Answer Guidelines
 
 - **Complete vs. delta answer**: When no first answer reached the caller, give the complete core answer. When a first answer was already delivered, return only the delta against it — corrections and newly verified findings — and never repeat its unchanged content; if nothing changed, confirm the first answer in one short line.
-- **Bullet-point core answer**: Provide the core answer to the user's question in at most 5 bullet points. If additional explanation or context is necessary, append it after the bullet points.
-- **Direct answer only**: The caller only needs the answer to their question. Never include specific file paths, datasource descriptions, or retrieval mechanics/principles in the answer (source paths are attached to each citation from the evidence ids you cite). Do not quote raw chunk text.
+- **Bullet-point core answer**: Unless the user explicitly requests a different format or length, provide the core answer to the user's question in at most 5 bullet points. If additional explanation or context is necessary, append it after the bullet points.
+- **Direct answer only**: Unless the user explicitly requests otherwise, the caller only needs the direct answer to their question. Never include specific file paths, datasource descriptions, or retrieval mechanics/principles in the answer (source paths are attached to each citation from the evidence ids you cite). Do not quote raw chunk text.
+- ${ANSWER_DELIVERABLE_RULE} ${ANSWER_DELIVERABLE_DELTA_RULE}
 - ${ANSWER_CITATION_RULE}
 - ${ANSWER_IMAGE_EMBED_RULE} ${ANSWER_IMAGE_DELTA_RULE}
 - **No per-source negative reports**: Never report individual negative findings per source (e.g. "no information found in Slack" or "checked Drive but found nothing"). Simply omit unproductive sources from the answer and focus on what was found or provide a concise overall conclusion.
@@ -30473,7 +30764,7 @@ var init_web_search_tool = __esm(() => {
 // src/agent/agent.ts
 import { randomUUID as randomUUID8 } from "node:crypto";
 import { existsSync as existsSync31, watch as fsWatch, mkdirSync as mkdirSync25, realpathSync as realpathSync5, statSync as statSync3, writeFileSync as writeFileSync22 } from "node:fs";
-import { basename as basename14, dirname as dirname27, join as join41, resolve as resolve16 } from "node:path";
+import { basename as basename14, dirname as dirname27, join as join41, resolve as resolve17 } from "node:path";
 import { clampThinkingLevel } from "@earendil-works/pi-ai/compat";
 import { getAgentDir as getAgentDir4 } from "@earendil-works/pi-coding-agent";
 function positiveLimit(value, fallback, path) {
@@ -30633,7 +30924,7 @@ class AutoRAGAgent {
     this.datasourceVirtualScopePrefixes = this.datasourceSkills.map((skill) => normalizeVirtualPath2(`/${skill.describe().name}`));
     this.startupDiagnostics = options.startupDiagnostics ?? [];
     this.datasourceAgentSkills = this.buildDatasourceAgentSkills();
-    this.configuredSearchPaths = options.searchPaths.map((searchPath) => resolve16(searchPath));
+    this.configuredSearchPaths = options.searchPaths.map((searchPath) => resolve17(searchPath));
     this.languages = options.languages ?? DEFAULT_LANGUAGES;
     this.searchPaths = options.searchPaths.map(pinSearchRoot);
     this.jikjiRoots = outermostJikjiRoots(this.searchPaths);
@@ -30680,7 +30971,8 @@ class AutoRAGAgent {
       const everythingClient = new EverythingClient({
         ...options.everything ?? {},
         root: this.workspaceProjectRoot,
-        folders: this.searchPaths
+        folders: this.searchPaths,
+        excludeFolders: this.excludePaths
       });
       if (everythingClient.isSupported())
         this.everythingClient = everythingClient;
@@ -30786,8 +31078,9 @@ class AutoRAGAgent {
       return true;
     });
     this.tools = tools;
+    const builtinToolNames = this.remoteSession ? PI_BUILTIN_TOOL_NAMES.filter((name) => name !== "write" && name !== "edit") : PI_BUILTIN_TOOL_NAMES;
     const toolNames = [
-      ...PI_BUILTIN_TOOL_NAMES,
+      ...builtinToolNames,
       ...tools.map((tool) => tool.name),
       ...this.jevExtension !== undefined ? [JEV_TOOL_NAME] : []
     ];
@@ -30803,7 +31096,7 @@ class AutoRAGAgent {
     this.innerAgent = {
       state: {
         systemPrompt,
-        tools: [...PI_BUILTIN_TOOL_NAMES.map((name) => ({ name })), ...tools],
+        tools: [...builtinToolNames.map((name) => ({ name })), ...tools],
         messages: []
       },
       transformContext: (messages) => this.withMemoryContext(messages)
@@ -31120,6 +31413,7 @@ ${context.text}
         ...this.jevExtension !== undefined ? [this.jevExtension] : []
       ],
       ...this.jevExtension !== undefined ? { extensionToolNames: [JEV_TOOL_NAME] } : {},
+      remoteSession: this.remoteSession,
       ...this.updateNotice === undefined ? {} : { updateNotice: this.updateNotice }
     });
     this.boundPiRuntime = runtime.runtime;
@@ -31574,7 +31868,7 @@ Warning: the edited config did not validate, so the previous config was restored
             result.summary,
             ...result.evidence.map((evidence) => evidence.excerpt)
           ])
-        ], [this.workspaceProjectRoot, ...this.searchPaths].map((root) => resolve16(root)));
+        ], [this.workspaceProjectRoot, ...this.searchPaths].map((root) => resolve17(root)));
         if (!scan.ok)
           throw new RemoteSessionRejectedError(scan.code);
       }
@@ -32046,8 +32340,9 @@ ${baseline}
 ` + `Produce the best complete, self-contained answer you can RIGHT NOW from this evidence. Do NOT call any search, retrieval, or file-reading tools and do NOT wait for more evidence. ` + `If the query is answerable from general knowledge alone, answer directly.
 
 ` + `Formatting and content rules for the answer:
-` + `- Provide the core answer to the user's question in at most 5 bullet points. If additional explanation is necessary, append it after the bullet points.
-` + `- Answer the question directly. Do not include specific file paths, datasource descriptions, or retrieval mechanics in the answer text.
+` + `- Unless the user explicitly requests a different format or length, provide the core answer to the user's question in at most 5 bullet points. If additional explanation is necessary, append it after the bullet points.
+` + `- Unless the user explicitly requests otherwise, answer the question directly. Do not include specific file paths, datasource descriptions, or retrieval mechanics in the answer text.
+` + `- ${ANSWER_DELIVERABLE_RULE}
 ` + `- ${ANSWER_CITATION_RULE}
 ` + `- ${ANSWER_IMAGE_EMBED_RULE}
 ` + `- Do not report per-source negative findings (e.g. "no information found in Slack" or "checked Drive but found nothing").
@@ -32086,12 +32381,14 @@ ${baseline}
 ` + `- NEVER restate or re-list first-answer facts that remain correct, and never repeat its bullet list.
 ` + `- Mark each item clearly as a correction or as a new finding.
 ` + `- If verification changed nothing and found nothing new, say so in one short line (the first answer is confirmed as-is) instead of restating it.
+` + `- ${ANSWER_DELIVERABLE_RULE} ${ANSWER_DELIVERABLE_DELTA_RULE}
 ` + `- ${ANSWER_CITATION_RULE} A correction or new finding that relies on evidence the first answer cited must cite that evidence's id again.
 ` + `- ${ANSWER_IMAGE_EMBED_RULE} ${ANSWER_IMAGE_DELTA_RULE}
 ` + `- Do not report per-source negative findings (e.g. "no information found in Slack").
 ` + `- When evidence conflicts, treat the freshest (most recent) information as the correct source of truth.` : `Formatting and content rules for the final answer (COMPLETE — no first answer reached the caller):
-` + `- Provide the core answer to the user's question in at most 5 bullet points. If additional explanation is necessary, append it after the bullet points.
-` + `- Answer the question directly. Do not include specific file paths, datasource descriptions, or retrieval mechanics in the answer text.
+` + `- Unless the user explicitly requests a different format or length, provide the core answer to the user's question in at most 5 bullet points. If additional explanation is necessary, append it after the bullet points.
+` + `- Unless the user explicitly requests otherwise, answer the question directly. Do not include specific file paths, datasource descriptions, or retrieval mechanics in the answer text.
+` + `- ${ANSWER_DELIVERABLE_RULE}${fastAnswer !== undefined ? ` ${ANSWER_DELIVERABLE_DELTA_RULE}` : ""}
 ` + `- ${ANSWER_CITATION_RULE}
 ` + `- ${ANSWER_IMAGE_EMBED_RULE}
 ` + `- Do not report per-source negative findings (e.g. "no information found in Slack").
@@ -32119,8 +32416,9 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
 ` + `Treat candidates as unverified evidence, verify important claims against source files when needed, and use additional tools when needed. ` + `Judge relevance, conflicts, freshness, and sufficiency in this agent loop.
 
 ` + `Formatting and content rules for the answer:
-` + `- Provide the core answer to the user's question in at most 5 bullet points. If additional explanation is necessary, append it after the bullet points.
-` + `- Answer the question directly. Do not include specific file paths, datasource descriptions, or retrieval mechanics in the answer text.
+` + `- Unless the user explicitly requests a different format or length, provide the core answer to the user's question in at most 5 bullet points. If additional explanation is necessary, append it after the bullet points.
+` + `- Unless the user explicitly requests otherwise, answer the question directly. Do not include specific file paths, datasource descriptions, or retrieval mechanics in the answer text.
+` + `- ${ANSWER_DELIVERABLE_RULE}
 ` + `- ${ANSWER_CITATION_RULE}
 ` + `- ${ANSWER_IMAGE_EMBED_RULE}
 ` + `- Do not report per-source negative findings (e.g. "no information found in Slack").
@@ -32405,7 +32703,7 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
   }
   startWatchRefresh(options = {}) {
     this.refreshState = { ...this.refreshState, watchLimited: false, watchFailed: false };
-    const dirs = this.searchPaths.map((searchPath) => resolve16(searchPath));
+    const dirs = this.searchPaths.map((searchPath) => resolve17(searchPath));
     const watcherFactory = options.watcherFactory ?? this.defaultWatcherFactory();
     return createWatchRefresh({
       dirs,
@@ -32582,7 +32880,7 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
     const evidencePack = [];
     const allPaths = [];
     for (const entry of entries) {
-      const originRoot = sourceRoots.find((sr) => sr.rootPath === resolve16(entry.root));
+      const originRoot = sourceRoots.find((sr) => sr.rootPath === resolve17(entry.root));
       if (originRoot === undefined)
         continue;
       const originRoots = [originRoot];
@@ -32995,7 +33293,7 @@ function toMinSyncReasonDiagnostic(reason) {
   };
 }
 function pinExcludedPath(path) {
-  const resolvedPath = resolve16(path);
+  const resolvedPath = resolve17(path);
   try {
     return join41(realpathSync5(dirname27(resolvedPath)), basename14(resolvedPath));
   } catch {
@@ -33003,7 +33301,7 @@ function pinExcludedPath(path) {
   }
 }
 function pinSearchRoot(searchPath) {
-  const resolvedPath = resolve16(searchPath);
+  const resolvedPath = resolve17(searchPath);
   let canonicalPath;
   try {
     canonicalPath = realpathSync5(resolvedPath);
@@ -33456,7 +33754,7 @@ var init_memory2 = __esm(() => {
 
 // src/cli/commands/index.ts
 import { existsSync as existsSync32, lstatSync as lstatSync3, rmSync as rmSync11 } from "node:fs";
-import { join as join42, resolve as resolve17, sep as sep8 } from "node:path";
+import { join as join42, resolve as resolve18, sep as sep8 } from "node:path";
 async function runIndex2(ctx) {
   const sub = ctx.positionals[0];
   if (sub !== "reset" && sub !== "rebuild") {
@@ -33472,8 +33770,8 @@ async function runIndex2(ctx) {
   }
   const methods = parseMethodFlag(ctx.flags.method);
   const { targetNames, targetSubdirs, refreshMethods } = resolveResetScope(methods);
-  const autoragDir = resolve17(config.workspacePath, ".autorag");
-  const targets = targetSubdirs.map((subdir) => resolve17(config.workspacePath, subdir));
+  const autoragDir = resolve18(config.workspacePath, ".autorag");
+  const targets = targetSubdirs.map((subdir) => resolve18(config.workspacePath, subdir));
   for (const dir of [autoragDir, ...targets]) {
     if (existsSync32(dir) && lstatSync3(dir).isSymbolicLink()) {
       ctx.stderr(renderError(new Error("Refusing to reset: an index path is a symlink, not a real directory."), {
@@ -33835,12 +34133,12 @@ var init_health = __esm(() => {
 });
 
 // src/cli/commands/duplicates.ts
-import { resolve as resolve18 } from "node:path";
+import { resolve as resolve19 } from "node:path";
 async function runDuplicates(ctx, scanner = (path) => scanWithDupey(path)) {
   try {
     const config = resolveConfig({ flags: ctx.flags, cwd: ctx.cwd });
     const requested = ctx.positionals[0];
-    const roots = requested ? [resolve18(ctx.cwd, requested)] : config.searchPaths.map((path) => resolve18(path));
+    const roots = requested ? [resolve19(ctx.cwd, requested)] : config.searchPaths.map((path) => resolve19(path));
     const scans = await Promise.all(roots.map((root) => scanner(root)));
     const exactGroups = scans.flatMap(exactGroupsFromScan);
     const extractionErrors = scans.flatMap((scan) => scan.errors);
@@ -35136,7 +35434,7 @@ var init_results = __esm(() => {
     confidence: Type18.Optional(Type18.Number({ description: "Evidence confidence, 0..1", minimum: 0, maximum: 1 }))
   });
   answerSchema = Type18.String({
-    description: `Answer for the caller. At most 5 bullet points (plus optional explanation); reference results by bracketed number (e.g. [1], [2]) without file paths or raw chunk text, except the image-embed exception below. ${ANSWER_CITATION_RULE} ${ANSWER_IMAGE_EMBED_RULE}`
+    description: `Answer for the caller. Unless the user explicitly requests otherwise, provide at most 5 bullet points (plus optional explanation) and answer directly; reference results by bracketed number (e.g. [1], [2]) without file paths or raw chunk text, except the image-embed exception below. ${ANSWER_DELIVERABLE_RULE} ${ANSWER_CITATION_RULE} ${ANSWER_IMAGE_EMBED_RULE}`
   });
   warningsSchema = Type18.Optional(Type18.Array(Type18.String(), { description: "Optional warnings about this result set" }));
   curatedResultFields = {
@@ -35313,7 +35611,8 @@ Usage: autorag lite <subcommand> [args] [flags]
 Subcommands:
   autorag lite init
                        Write the configured model-free lifecycle config
-                       (--search-paths PATHS  --workspace DIR  --memory-path FILE  --force)
+                       (--search-paths PATHS  --exclude PATH  --workspace DIR  --memory-path FILE  --force)
+                       --exclude may be repeated; relative paths use the current directory
   autorag lite refresh Run an incremental index refresh (no model required)
                        (--full  --force  --method minsync,parsed,datasources,jikji,everything,fsearch,all)
   autorag lite watch  Watch configured roots (or --once for one refresh tick)
@@ -35389,6 +35688,7 @@ var COMMAND_USAGE = {
     "",
     "Flags:",
     "  --search-paths <csv>          Folders to index/search",
+    "  --exclude <path>              Exclude a file or folder (repeatable; relative to the current directory)",
     "  --languages <csv>             OCR/parser languages",
     "  --workspace <dir>             Workspace that owns .autorag state",
     "  --memory-path <file>          Retrieval memory file",
@@ -35657,6 +35957,7 @@ var BOOLEAN_FLAGS = new Set([
 var VALUE_FLAGS = new Set([
   "config",
   "search-paths",
+  "exclude",
   "languages",
   "workspace",
   "memory-path",
@@ -35786,6 +36087,7 @@ Run: autorag <command> --help   for command-specific usage.
 function parseArgs(argv) {
   const positionals = [];
   const flags = {};
+  const repeatedFlags = {};
   for (let i = 0;i < argv.length; i++) {
     const token = argv[i];
     if (token === "-h") {
@@ -35806,22 +36108,27 @@ function parseArgs(argv) {
     if (!BOOLEAN_FLAGS.has(key) && !VALUE_FLAGS.has(key)) {
       return { error: `Unknown flag: --${key}` };
     }
-    if (eq !== -1) {
-      flags[key] = body.slice(eq + 1);
-      continue;
-    }
-    if (BOOLEAN_FLAGS.has(key)) {
+    if (eq === -1 && BOOLEAN_FLAGS.has(key)) {
       flags[key] = true;
       continue;
     }
-    const next = argv[i + 1];
-    if (next === undefined || next.startsWith("--")) {
+    const value = eq === -1 ? argv[++i] : body.slice(eq + 1);
+    if (value === undefined || eq === -1 && value.startsWith("--")) {
       return { error: `Flag --${key} requires a value` };
     }
-    flags[key] = next;
-    i++;
+    if (key === "exclude") {
+      if (value.trim().length === 0)
+        return { error: "Flag --exclude requires a non-empty path" };
+      repeatedFlags[key] ??= [];
+      repeatedFlags[key].push(value);
+    }
+    flags[key] = value;
   }
-  return { positionals, flags };
+  return {
+    positionals,
+    flags,
+    ...Object.keys(repeatedFlags).length > 0 ? { repeatedFlags } : {}
+  };
 }
 function promptYesNo(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -35943,6 +36250,7 @@ ${USAGE2}`);
   const ctx = {
     positionals: positionals.slice(1),
     flags,
+    ...parsed.repeatedFlags === undefined ? {} : { repeatedFlags: parsed.repeatedFlags },
     json,
     debug,
     cwd: process.cwd(),