@autorag/librarian 2.6.1 → 2.6.2

package/dist/agent/agent.d.ts

@@ -158,6 +158,7 @@ export interface AutoRAGAgentOptions {
     parserOptions?: DefaultParserRegistryOptions;
     dupey?: DupeyCliOptions | false;
     excludeExactDuplicates?: boolean;
+    excludePaths?: readonly string[];
     datasourceSkills?: readonly DatasourceSkill[];
     datasourceAccess?: DatasourceAccessContextOptions;
     /** Non-fatal diagnostics from config/agent construction (e.g. skipped unknown datasources). */
@@ -242,6 +243,7 @@ export declare class AutoRAGAgent {
     private readonly parserOptions;
     private readonly dupeyOptions;
     private readonly excludeExactDuplicates;
+    private readonly excludePaths;
     private readonly baseSystemPromptConfig;
     private readonly droppedCallerToolNames;
     private readonly searchTimeoutMs;

package/dist/cli/config.d.ts

@@ -111,6 +111,8 @@ export interface CliConfig {
         timeoutMs?: number;
     };
     excludeExactDuplicates?: boolean;
+    /** Absolute or workspace-relative files/directories omitted from local indexing. */
+    excludePaths?: string[];
     /** Trusted datasource skill configuration (skill name → config). */
     datasources?: DatasourcesConfig;
     /** Trusted datasource allow-tags/allow-scopes. Absent ⇒ default-deny. */

package/dist/cli/index.js

@@ -2301,7 +2301,7 @@ function isParsedMirrorSkipEntry(value) {
   return isRecord2(value) && typeof value.virtualPath === "string" && typeof value.sourcePath === "string" && isParsedMirrorSkipReason(value.reason) && typeof value.sourceMtimeNs === "number" && typeof value.sourceSizeBytes === "number" && typeof value.updatedAt === "string";
 }
 function isParsedMirrorSkipReason(value) {
-  return value === "duplicate-excluded" || value === "parser-skipped" || value === "parser-failed";
+  return value === "duplicate-excluded" || value === "user-excluded" || value === "parser-skipped" || value === "parser-failed";
 }
 function isParsedMirrorEntry(value) {
   return isRecord2(value) && typeof value.virtualPath === "string" && typeof value.sourcePath === "string" && typeof value.outputPath === "string" && typeof value.parserName === "string" && typeof value.sourceMtimeNs === "number" && typeof value.sourceSizeBytes === "number" && typeof value.updatedAt === "string";
@@ -11043,6 +11043,10 @@ function resolveConfig(input) {
   const configOrigin = dirname10(resolve6(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 searchPaths = flagSearchPaths ?? envSearchPaths ?? fileSearchPaths ?? defaultSearchPaths;
   const flagWorkspacePath = flagString(flags, "workspace");
   const envWorkspacePath = envString(env, "AUTORAG_WORKSPACE");
@@ -11066,6 +11070,8 @@ function resolveConfig(input) {
   };
   if (model)
     config.model = model;
+  if (fileExcludePaths !== undefined)
+    config.excludePaths = fileExcludePaths;
   const normalized = normalizeIndexingConfig({
     minSync: file.minSync
   });
@@ -11182,6 +11188,8 @@ function buildAgentOptions(config) {
     };
   }
   opts.excludeExactDuplicates = config.excludeExactDuplicates ?? true;
+  if (config.excludePaths !== undefined)
+    opts.excludePaths = config.excludePaths;
   if (config.datasources !== undefined) {
     const { skills, unknown } = buildDatasourceSkills(config.datasources, config.workspacePath);
     if (skills.length > 0)
@@ -11437,6 +11445,8 @@ function writeDefaultConfig(path, partial, opts = {}) {
   full.jikji = partial.jikji ?? {};
   full.dupey = partial.dupey ?? { enabled: true };
   full.excludeExactDuplicates = partial.excludeExactDuplicates ?? true;
+  if (partial.excludePaths !== undefined)
+    full.excludePaths = resolveSearchPaths(partial.excludePaths, workspacePath);
   if (partial.parserOptions)
     full.parserOptions = partial.parserOptions;
   if (partial.p2p !== undefined)
@@ -12234,7 +12244,7 @@ var init_cli = __esm(() => {
 // src/dupey/filter.ts
 import { stat as stat5 } from "node:fs/promises";
 import { resolve as resolve8 } from "node:path";
-async function selectExactDuplicateExclusions(root, scan) {
+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)
@@ -12260,11 +12270,12 @@ async function selectExactDuplicateExclusions(root, scan) {
       }
     }));
     ranked.sort((a, b) => b.mtimeMs - a.mtimeMs || a.path.localeCompare(b.path));
-    const keeper = ranked[0]?.path;
+    const candidates = isUnavailable === undefined ? ranked : ranked.filter(({ path }) => !isUnavailable(path));
+    const keeper = candidates[0]?.path;
     if (!keeper)
       continue;
     keepers.add(keeper);
-    for (const candidate of ranked.slice(1))
+    for (const candidate of candidates.slice(1))
       excluded.add(candidate.path);
   }
   return { excluded, keepers, errors };
@@ -14939,7 +14950,7 @@ var init_minsync = __esm(() => {
 import { randomUUID as randomUUID6 } from "node:crypto";
 import { existsSync as existsSync21, mkdirSync as mkdirSync14, renameSync as renameSync7, rmSync as rmSync4, writeFileSync as writeFileSync13 } from "node:fs";
 import { opendir, readFile as readFile5, stat as stat6 } from "node:fs/promises";
-import { dirname as dirname15, extname as extname6, resolve as resolve11 } from "node:path";
+import { dirname as dirname15, extname as extname6, resolve as resolve11, sep as sep4 } from "node:path";
 async function syncParsedMirrors(options) {
   const registry = options.registry ?? createDefaultParserRegistry(options.parserOptions);
   const maxSourceBytes = options.maxSourceBytes ?? DEFAULT_MAX_SOURCE_BYTES;
@@ -14978,6 +14989,13 @@ async function syncParsedMirrors(options) {
     sinceCheckpoint = 0;
   };
   for (const entry of current) {
+    if (isPathExcluded(entry.sourcePath, options.userExcludedSourcePaths)) {
+      deleted += removePrevious(options.root, previous, entry.virtualPath);
+      handledPrevious.add(entry.virtualPath);
+      skipped += 1;
+      recordSkip(entry, "user-excluded");
+      continue;
+    }
     if (options.excludeSourcePaths?.has(entry.sourcePath)) {
       deleted += removePrevious(options.root, previous, entry.virtualPath);
       handledPrevious.add(entry.virtualPath);
@@ -15098,7 +15116,7 @@ async function detectMirrorStaleness(options) {
   const previous = loadMirrorIndex(options.root);
   const diagnostics = [];
   for (const entry of current) {
-    if (options.excludeSourcePaths?.has(entry.sourcePath))
+    if (options.excludeSourcePaths?.has(entry.sourcePath) || isPathExcluded(entry.sourcePath, options.userExcludedSourcePaths))
       continue;
     if (!registry.getForVirtualPath(entry.virtualPath))
       continue;
@@ -15106,9 +15124,10 @@ async function detectMirrorStaleness(options) {
     if (prev !== undefined && prev.sourceMtimeNs === entry.mtimeNs && prev.sourceSizeBytes === entry.sizeBytes)
       continue;
     const prevSkip = previous.skipped?.[entry.virtualPath];
-    if (prevSkip !== undefined && prevSkip.sourceMtimeNs === entry.mtimeNs && prevSkip.sourceSizeBytes === entry.sizeBytes)
+    const honoredSkip = prevSkip?.reason === "user-excluded" ? undefined : prevSkip;
+    if (honoredSkip !== undefined && honoredSkip.sourceMtimeNs === entry.mtimeNs && honoredSkip.sourceSizeBytes === entry.sizeBytes)
       continue;
-    const known = prev ?? prevSkip;
+    const known = prev ?? honoredSkip;
     const reason = known === undefined ? "source-added" : known.sourceMtimeNs !== entry.mtimeNs && known.sourceSizeBytes !== entry.sizeBytes ? "mtime-and-size-changed" : known.sourceMtimeNs !== entry.mtimeNs ? "mtime-changed" : "size-changed";
     diagnostics.push({
       code: "stale-index",
@@ -15133,6 +15152,15 @@ function normalizeExtension2(extension) {
   const lower = extension.toLowerCase();
   return lower.startsWith(".") ? lower : `.${lower}`;
 }
+function isPathExcluded(sourcePath, excluded) {
+  if (excluded === undefined)
+    return false;
+  for (const excludedPath of excluded) {
+    if (sourcePath === excludedPath || sourcePath.startsWith(`${excludedPath}${sep4}`))
+      return true;
+  }
+  return false;
+}
 async function listCurrentFiles(searchPaths, supportedExtensions) {
   const entries = [];
   for (const sourceRoot of planSourceRoots(searchPaths)) {
@@ -16225,7 +16253,7 @@ var init_model_auth = __esm(() => {
 // src/filesystem/cloud-placeholder.ts
 import { execFile as execFile3 } from "node:child_process";
 import { lstat } from "node:fs/promises";
-import { dirname as dirname17, relative as relative6, sep as sep4 } from "node:path";
+import { dirname as dirname17, relative as relative6, sep as sep5 } from "node:path";
 import { promisify as promisify2 } from "node:util";
 function pathLooksLikeCloudRoot(target) {
   const normalized = target.replaceAll("\\", "/");
@@ -24922,6 +24950,7 @@ class AutoRAGAgent {
   parserOptions;
   dupeyOptions;
   excludeExactDuplicates;
+  excludePaths;
   baseSystemPromptConfig;
   droppedCallerToolNames;
   searchTimeoutMs;
@@ -24960,6 +24989,7 @@ class AutoRAGAgent {
     this.parserOptions = resolveParserOptions(options.parserOptions, this.languages);
     this.dupeyOptions = options.dupey ?? {};
     this.excludeExactDuplicates = options.excludeExactDuplicates ?? true;
+    this.excludePaths = (options.excludePaths ?? []).map(pinExcludedPath);
     if (options.minSync !== false) {
       const minSyncOpts = options.minSync ?? { autoInstall: true };
       this.minSyncMethod = new MinSyncVectorMethod({
@@ -25894,7 +25924,8 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
     const staleDiagnostics = await detectMirrorStaleness({
       root: this.workspaceProjectRoot,
       searchPaths: this.searchPaths,
-      parserOptions: this.parserOptions
+      parserOptions: this.parserOptions,
+      userExcludedSourcePaths: new Set(this.excludePaths)
     });
     const diagnostics = [
       ...this.startupDiagnostics,
@@ -26017,7 +26048,8 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
       searchPaths: this.searchPaths,
       force,
       parserOptions: this.parserOptions,
-      excludeSourcePaths: duplicateFilter.excluded
+      excludeSourcePaths: duplicateFilter.excluded,
+      userExcludedSourcePaths: new Set(this.excludePaths)
     });
   }
   async scanMirrorStaleness() {
@@ -26026,7 +26058,8 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
       root: this.workspaceProjectRoot,
       searchPaths: this.searchPaths,
       parserOptions: this.parserOptions,
-      excludeSourcePaths: duplicateFilter.excluded
+      excludeSourcePaths: duplicateFilter.excluded,
+      userExcludedSourcePaths: new Set(this.excludePaths)
     });
     return {
       scanned: 0,
@@ -26041,10 +26074,11 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
     if (!this.excludeExactDuplicates || this.dupeyOptions === false)
       return { excluded: new Set };
     const excluded = new Set;
+    const userExcluded = new Set(this.excludePaths);
     for (const searchPath of this.searchPaths) {
       try {
         const scan = await scanWithDupey(searchPath, this.dupeyOptions || {});
-        const selected = await selectExactDuplicateExclusions(searchPath, scan);
+        const selected = await selectExactDuplicateExclusions(searchPath, scan, (path) => isPathExcluded(path, userExcluded));
         for (const path of selected.excluded)
           excluded.add(path);
       } catch (error) {
@@ -26459,6 +26493,14 @@ function toMinSyncReasonDiagnostic(reason) {
     source: "minsync"
   };
 }
+function pinExcludedPath(path) {
+  const resolvedPath = resolve13(path);
+  try {
+    return join30(realpathSync4(dirname22(resolvedPath)), basename12(resolvedPath));
+  } catch {
+    return resolvedPath;
+  }
+}
 function pinSearchRoot(searchPath) {
   const resolvedPath = resolve13(searchPath);
   let canonicalPath;
@@ -26948,7 +26990,7 @@ var init_memory2 = __esm(() => {
 
 // src/cli/commands/index.ts
 import { existsSync as existsSync28, lstatSync as lstatSync3, rmSync as rmSync6 } from "node:fs";
-import { join as join31, resolve as resolve14, sep as sep5 } from "node:path";
+import { join as join31, resolve as resolve14, sep as sep6 } from "node:path";
 async function runIndex(ctx) {
   const sub = ctx.positionals[0];
   if (sub !== "reset" && sub !== "rebuild") {
@@ -27046,7 +27088,7 @@ function resolveResetScope(methods) {
   };
 }
 function isWithin(target, base) {
-  const prefix = base.endsWith(sep5) ? base : `${base}${sep5}`;
+  const prefix = base.endsWith(sep6) ? base : `${base}${sep6}`;
   return target === base || target.startsWith(prefix);
 }
 var ALL_RESET_TARGETS, ALL_RESET_TARGET_NAMES;
@@ -28965,7 +29007,8 @@ async function runLiteRetrieve(ctx) {
   const staleDiagnostics = await detectMirrorStaleness({
     root: workspacePath,
     searchPaths: lite.config.searchPaths,
-    parserOptions: resolveParserOptions(lite.config.parserOptions, normalizeLanguages(lite.config.languages))
+    parserOptions: resolveParserOptions(lite.config.parserOptions, normalizeLanguages(lite.config.languages)),
+    userExcludedSourcePaths: new Set(lite.config.excludePaths ?? [])
   });
   if (staleDiagnostics.length > 0 && ctx.flags.strict === true) {
     const envelope = {

package/dist/core.js

@@ -192,7 +192,7 @@ function isParsedMirrorSkipEntry(value) {
   return isRecord(value) && typeof value.virtualPath === "string" && typeof value.sourcePath === "string" && isParsedMirrorSkipReason(value.reason) && typeof value.sourceMtimeNs === "number" && typeof value.sourceSizeBytes === "number" && typeof value.updatedAt === "string";
 }
 function isParsedMirrorSkipReason(value) {
-  return value === "duplicate-excluded" || value === "parser-skipped" || value === "parser-failed";
+  return value === "duplicate-excluded" || value === "user-excluded" || value === "parser-skipped" || value === "parser-failed";
 }
 function isParsedMirrorEntry(value) {
   return isRecord(value) && typeof value.virtualPath === "string" && typeof value.sourcePath === "string" && typeof value.outputPath === "string" && typeof value.parserName === "string" && typeof value.sourceMtimeNs === "number" && typeof value.sourceSizeBytes === "number" && typeof value.updatedAt === "string";
@@ -548,7 +548,7 @@ var init_cli = __esm(() => {
 // src/dupey/filter.ts
 import { stat } from "node:fs/promises";
 import { resolve as resolve5 } from "node:path";
-async function selectExactDuplicateExclusions(root, scan) {
+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)
@@ -574,11 +574,12 @@ async function selectExactDuplicateExclusions(root, scan) {
       }
     }));
     ranked.sort((a, b) => b.mtimeMs - a.mtimeMs || a.path.localeCompare(b.path));
-    const keeper = ranked[0]?.path;
+    const candidates = isUnavailable === undefined ? ranked : ranked.filter(({ path }) => !isUnavailable(path));
+    const keeper = candidates[0]?.path;
     if (!keeper)
       continue;
     keepers.add(keeper);
-    for (const candidate of ranked.slice(1))
+    for (const candidate of candidates.slice(1))
       excluded.add(candidate.path);
   }
   return { excluded, keepers, errors };
@@ -5475,7 +5476,7 @@ var init_defaults = __esm(() => {
 import { randomUUID as randomUUID5 } from "node:crypto";
 import { existsSync as existsSync12, mkdirSync as mkdirSync6, renameSync as renameSync5, rmSync as rmSync3, writeFileSync as writeFileSync6 } from "node:fs";
 import { opendir, readFile as readFile3, stat as stat4 } from "node:fs/promises";
-import { dirname as dirname7, extname as extname4, resolve as resolve9 } from "node:path";
+import { dirname as dirname7, extname as extname4, resolve as resolve9, sep as sep4 } from "node:path";
 async function syncParsedMirrors(options) {
   const registry = options.registry ?? createDefaultParserRegistry(options.parserOptions);
   const maxSourceBytes = options.maxSourceBytes ?? DEFAULT_MAX_SOURCE_BYTES;
@@ -5514,6 +5515,13 @@ async function syncParsedMirrors(options) {
     sinceCheckpoint = 0;
   };
   for (const entry of current) {
+    if (isPathExcluded(entry.sourcePath, options.userExcludedSourcePaths)) {
+      deleted += removePrevious(options.root, previous, entry.virtualPath);
+      handledPrevious.add(entry.virtualPath);
+      skipped += 1;
+      recordSkip(entry, "user-excluded");
+      continue;
+    }
     if (options.excludeSourcePaths?.has(entry.sourcePath)) {
       deleted += removePrevious(options.root, previous, entry.virtualPath);
       handledPrevious.add(entry.virtualPath);
@@ -5634,7 +5642,7 @@ async function detectMirrorStaleness(options) {
   const previous = loadMirrorIndex(options.root);
   const diagnostics = [];
   for (const entry of current) {
-    if (options.excludeSourcePaths?.has(entry.sourcePath))
+    if (options.excludeSourcePaths?.has(entry.sourcePath) || isPathExcluded(entry.sourcePath, options.userExcludedSourcePaths))
       continue;
     if (!registry.getForVirtualPath(entry.virtualPath))
       continue;
@@ -5642,9 +5650,10 @@ async function detectMirrorStaleness(options) {
     if (prev !== undefined && prev.sourceMtimeNs === entry.mtimeNs && prev.sourceSizeBytes === entry.sizeBytes)
       continue;
     const prevSkip = previous.skipped?.[entry.virtualPath];
-    if (prevSkip !== undefined && prevSkip.sourceMtimeNs === entry.mtimeNs && prevSkip.sourceSizeBytes === entry.sizeBytes)
+    const honoredSkip = prevSkip?.reason === "user-excluded" ? undefined : prevSkip;
+    if (honoredSkip !== undefined && honoredSkip.sourceMtimeNs === entry.mtimeNs && honoredSkip.sourceSizeBytes === entry.sizeBytes)
       continue;
-    const known = prev ?? prevSkip;
+    const known = prev ?? honoredSkip;
     const reason = known === undefined ? "source-added" : known.sourceMtimeNs !== entry.mtimeNs && known.sourceSizeBytes !== entry.sizeBytes ? "mtime-and-size-changed" : known.sourceMtimeNs !== entry.mtimeNs ? "mtime-changed" : "size-changed";
     diagnostics.push({
       code: "stale-index",
@@ -5669,6 +5678,15 @@ function normalizeExtension2(extension) {
   const lower = extension.toLowerCase();
   return lower.startsWith(".") ? lower : `.${lower}`;
 }
+function isPathExcluded(sourcePath, excluded) {
+  if (excluded === undefined)
+    return false;
+  for (const excludedPath of excluded) {
+    if (sourcePath === excludedPath || sourcePath.startsWith(`${excludedPath}${sep4}`))
+      return true;
+  }
+  return false;
+}
 async function listCurrentFiles(searchPaths, supportedExtensions) {
   const entries = [];
   for (const sourceRoot of planSourceRoots(searchPaths)) {
@@ -6802,7 +6820,7 @@ var init_model_auth = __esm(() => {
 // src/filesystem/cloud-placeholder.ts
 import { execFile as execFile2 } from "node:child_process";
 import { lstat } from "node:fs/promises";
-import { dirname as dirname9, relative as relative6, sep as sep4 } from "node:path";
+import { dirname as dirname9, relative as relative6, sep as sep5 } from "node:path";
 import { promisify as promisify2 } from "node:util";
 function pathLooksLikeCloudRoot(target) {
   const normalized = target.replaceAll("\\", "/");
@@ -15653,6 +15671,7 @@ class AutoRAGAgent {
   parserOptions;
   dupeyOptions;
   excludeExactDuplicates;
+  excludePaths;
   baseSystemPromptConfig;
   droppedCallerToolNames;
   searchTimeoutMs;
@@ -15691,6 +15710,7 @@ class AutoRAGAgent {
     this.parserOptions = resolveParserOptions(options.parserOptions, this.languages);
     this.dupeyOptions = options.dupey ?? {};
     this.excludeExactDuplicates = options.excludeExactDuplicates ?? true;
+    this.excludePaths = (options.excludePaths ?? []).map(pinExcludedPath);
     if (options.minSync !== false) {
       const minSyncOpts = options.minSync ?? { autoInstall: true };
       this.minSyncMethod = new MinSyncVectorMethod({
@@ -16625,7 +16645,8 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
     const staleDiagnostics = await detectMirrorStaleness({
       root: this.workspaceProjectRoot,
       searchPaths: this.searchPaths,
-      parserOptions: this.parserOptions
+      parserOptions: this.parserOptions,
+      userExcludedSourcePaths: new Set(this.excludePaths)
     });
     const diagnostics = [
       ...this.startupDiagnostics,
@@ -16748,7 +16769,8 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
       searchPaths: this.searchPaths,
       force,
       parserOptions: this.parserOptions,
-      excludeSourcePaths: duplicateFilter.excluded
+      excludeSourcePaths: duplicateFilter.excluded,
+      userExcludedSourcePaths: new Set(this.excludePaths)
     });
   }
   async scanMirrorStaleness() {
@@ -16757,7 +16779,8 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
       root: this.workspaceProjectRoot,
       searchPaths: this.searchPaths,
       parserOptions: this.parserOptions,
-      excludeSourcePaths: duplicateFilter.excluded
+      excludeSourcePaths: duplicateFilter.excluded,
+      userExcludedSourcePaths: new Set(this.excludePaths)
     });
     return {
       scanned: 0,
@@ -16772,10 +16795,11 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
     if (!this.excludeExactDuplicates || this.dupeyOptions === false)
       return { excluded: new Set };
     const excluded = new Set;
+    const userExcluded = new Set(this.excludePaths);
     for (const searchPath of this.searchPaths) {
       try {
         const scan = await scanWithDupey(searchPath, this.dupeyOptions || {});
-        const selected = await selectExactDuplicateExclusions(searchPath, scan);
+        const selected = await selectExactDuplicateExclusions(searchPath, scan, (path) => isPathExcluded(path, userExcluded));
         for (const path of selected.excluded)
           excluded.add(path);
       } catch (error) {
@@ -17190,6 +17214,14 @@ function toMinSyncReasonDiagnostic(reason) {
     source: "minsync"
   };
 }
+function pinExcludedPath(path) {
+  const resolvedPath = resolve11(path);
+  try {
+    return join22(realpathSync4(dirname14(resolvedPath)), basename9(resolvedPath));
+  } catch {
+    return resolvedPath;
+  }
+}
 function pinSearchRoot(searchPath) {
   const resolvedPath = resolve11(searchPath);
   let canonicalPath;
@@ -25283,6 +25315,10 @@ function resolveConfig(input) {
   const configOrigin = dirname21(resolve13(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 searchPaths = flagSearchPaths ?? envSearchPaths ?? fileSearchPaths ?? defaultSearchPaths;
   const flagWorkspacePath = flagString(flags, "workspace");
   const envWorkspacePath = envString(env, "AUTORAG_WORKSPACE");
@@ -25306,6 +25342,8 @@ function resolveConfig(input) {
   };
   if (model)
     config.model = model;
+  if (fileExcludePaths !== undefined)
+    config.excludePaths = fileExcludePaths;
   const normalized = normalizeIndexingConfig({
     minSync: file.minSync
   });
@@ -25422,6 +25460,8 @@ function buildAgentOptions(config) {
     };
   }
   opts.excludeExactDuplicates = config.excludeExactDuplicates ?? true;
+  if (config.excludePaths !== undefined)
+    opts.excludePaths = config.excludePaths;
   if (config.datasources !== undefined) {
     const { skills, unknown } = buildDatasourceSkills(config.datasources, config.workspacePath);
     if (skills.length > 0)
@@ -25677,6 +25717,8 @@ function writeDefaultConfig(path, partial, opts = {}) {
   full.jikji = partial.jikji ?? {};
   full.dupey = partial.dupey ?? { enabled: true };
   full.excludeExactDuplicates = partial.excludeExactDuplicates ?? true;
+  if (partial.excludePaths !== undefined)
+    full.excludePaths = resolveSearchPaths(partial.excludePaths, workspacePath);
   if (partial.parserOptions)
     full.parserOptions = partial.parserOptions;
   if (partial.p2p !== undefined)

package/dist/dupey/filter.d.ts

@@ -5,4 +5,4 @@ export interface ExactDuplicateFilterResult {
     readonly errors: readonly string[];
 }
 /** Selects the newest filesystem copy for each exact canonical-text hash. */
-export declare function selectExactDuplicateExclusions(root: string, scan: DupeyScanResult): Promise<ExactDuplicateFilterResult>;
+export declare function selectExactDuplicateExclusions(root: string, scan: DupeyScanResult, isUnavailable?: (path: string) => boolean): Promise<ExactDuplicateFilterResult>;

package/dist/index.js

@@ -192,7 +192,7 @@ function isParsedMirrorSkipEntry(value) {
   return isRecord(value) && typeof value.virtualPath === "string" && typeof value.sourcePath === "string" && isParsedMirrorSkipReason(value.reason) && typeof value.sourceMtimeNs === "number" && typeof value.sourceSizeBytes === "number" && typeof value.updatedAt === "string";
 }
 function isParsedMirrorSkipReason(value) {
-  return value === "duplicate-excluded" || value === "parser-skipped" || value === "parser-failed";
+  return value === "duplicate-excluded" || value === "user-excluded" || value === "parser-skipped" || value === "parser-failed";
 }
 function isParsedMirrorEntry(value) {
   return isRecord(value) && typeof value.virtualPath === "string" && typeof value.sourcePath === "string" && typeof value.outputPath === "string" && typeof value.parserName === "string" && typeof value.sourceMtimeNs === "number" && typeof value.sourceSizeBytes === "number" && typeof value.updatedAt === "string";
@@ -548,7 +548,7 @@ var init_cli = __esm(() => {
 // src/dupey/filter.ts
 import { stat } from "node:fs/promises";
 import { resolve as resolve5 } from "node:path";
-async function selectExactDuplicateExclusions(root, scan) {
+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)
@@ -574,11 +574,12 @@ async function selectExactDuplicateExclusions(root, scan) {
       }
     }));
     ranked.sort((a, b) => b.mtimeMs - a.mtimeMs || a.path.localeCompare(b.path));
-    const keeper = ranked[0]?.path;
+    const candidates = isUnavailable === undefined ? ranked : ranked.filter(({ path }) => !isUnavailable(path));
+    const keeper = candidates[0]?.path;
     if (!keeper)
       continue;
     keepers.add(keeper);
-    for (const candidate of ranked.slice(1))
+    for (const candidate of candidates.slice(1))
       excluded.add(candidate.path);
   }
   return { excluded, keepers, errors };
@@ -5475,7 +5476,7 @@ var init_defaults = __esm(() => {
 import { randomUUID as randomUUID5 } from "node:crypto";
 import { existsSync as existsSync12, mkdirSync as mkdirSync6, renameSync as renameSync5, rmSync as rmSync3, writeFileSync as writeFileSync6 } from "node:fs";
 import { opendir, readFile as readFile3, stat as stat4 } from "node:fs/promises";
-import { dirname as dirname7, extname as extname4, resolve as resolve9 } from "node:path";
+import { dirname as dirname7, extname as extname4, resolve as resolve9, sep as sep4 } from "node:path";
 async function syncParsedMirrors(options) {
   const registry = options.registry ?? createDefaultParserRegistry(options.parserOptions);
   const maxSourceBytes = options.maxSourceBytes ?? DEFAULT_MAX_SOURCE_BYTES;
@@ -5514,6 +5515,13 @@ async function syncParsedMirrors(options) {
     sinceCheckpoint = 0;
   };
   for (const entry of current) {
+    if (isPathExcluded(entry.sourcePath, options.userExcludedSourcePaths)) {
+      deleted += removePrevious(options.root, previous, entry.virtualPath);
+      handledPrevious.add(entry.virtualPath);
+      skipped += 1;
+      recordSkip(entry, "user-excluded");
+      continue;
+    }
     if (options.excludeSourcePaths?.has(entry.sourcePath)) {
       deleted += removePrevious(options.root, previous, entry.virtualPath);
       handledPrevious.add(entry.virtualPath);
@@ -5634,7 +5642,7 @@ async function detectMirrorStaleness(options) {
   const previous = loadMirrorIndex(options.root);
   const diagnostics = [];
   for (const entry of current) {
-    if (options.excludeSourcePaths?.has(entry.sourcePath))
+    if (options.excludeSourcePaths?.has(entry.sourcePath) || isPathExcluded(entry.sourcePath, options.userExcludedSourcePaths))
       continue;
     if (!registry.getForVirtualPath(entry.virtualPath))
       continue;
@@ -5642,9 +5650,10 @@ async function detectMirrorStaleness(options) {
     if (prev !== undefined && prev.sourceMtimeNs === entry.mtimeNs && prev.sourceSizeBytes === entry.sizeBytes)
       continue;
     const prevSkip = previous.skipped?.[entry.virtualPath];
-    if (prevSkip !== undefined && prevSkip.sourceMtimeNs === entry.mtimeNs && prevSkip.sourceSizeBytes === entry.sizeBytes)
+    const honoredSkip = prevSkip?.reason === "user-excluded" ? undefined : prevSkip;
+    if (honoredSkip !== undefined && honoredSkip.sourceMtimeNs === entry.mtimeNs && honoredSkip.sourceSizeBytes === entry.sizeBytes)
       continue;
-    const known = prev ?? prevSkip;
+    const known = prev ?? honoredSkip;
     const reason = known === undefined ? "source-added" : known.sourceMtimeNs !== entry.mtimeNs && known.sourceSizeBytes !== entry.sizeBytes ? "mtime-and-size-changed" : known.sourceMtimeNs !== entry.mtimeNs ? "mtime-changed" : "size-changed";
     diagnostics.push({
       code: "stale-index",
@@ -5669,6 +5678,15 @@ function normalizeExtension2(extension) {
   const lower = extension.toLowerCase();
   return lower.startsWith(".") ? lower : `.${lower}`;
 }
+function isPathExcluded(sourcePath, excluded) {
+  if (excluded === undefined)
+    return false;
+  for (const excludedPath of excluded) {
+    if (sourcePath === excludedPath || sourcePath.startsWith(`${excludedPath}${sep4}`))
+      return true;
+  }
+  return false;
+}
 async function listCurrentFiles(searchPaths, supportedExtensions) {
   const entries = [];
   for (const sourceRoot of planSourceRoots(searchPaths)) {
@@ -6802,7 +6820,7 @@ var init_model_auth = __esm(() => {
 // src/filesystem/cloud-placeholder.ts
 import { execFile as execFile2 } from "node:child_process";
 import { lstat } from "node:fs/promises";
-import { dirname as dirname9, relative as relative6, sep as sep4 } from "node:path";
+import { dirname as dirname9, relative as relative6, sep as sep5 } from "node:path";
 import { promisify as promisify2 } from "node:util";
 function pathLooksLikeCloudRoot(target) {
   const normalized = target.replaceAll("\\", "/");
@@ -15653,6 +15671,7 @@ class AutoRAGAgent {
   parserOptions;
   dupeyOptions;
   excludeExactDuplicates;
+  excludePaths;
   baseSystemPromptConfig;
   droppedCallerToolNames;
   searchTimeoutMs;
@@ -15691,6 +15710,7 @@ class AutoRAGAgent {
     this.parserOptions = resolveParserOptions(options.parserOptions, this.languages);
     this.dupeyOptions = options.dupey ?? {};
     this.excludeExactDuplicates = options.excludeExactDuplicates ?? true;
+    this.excludePaths = (options.excludePaths ?? []).map(pinExcludedPath);
     if (options.minSync !== false) {
       const minSyncOpts = options.minSync ?? { autoInstall: true };
       this.minSyncMethod = new MinSyncVectorMethod({
@@ -16625,7 +16645,8 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
     const staleDiagnostics = await detectMirrorStaleness({
       root: this.workspaceProjectRoot,
       searchPaths: this.searchPaths,
-      parserOptions: this.parserOptions
+      parserOptions: this.parserOptions,
+      userExcludedSourcePaths: new Set(this.excludePaths)
     });
     const diagnostics = [
       ...this.startupDiagnostics,
@@ -16748,7 +16769,8 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
       searchPaths: this.searchPaths,
       force,
       parserOptions: this.parserOptions,
-      excludeSourcePaths: duplicateFilter.excluded
+      excludeSourcePaths: duplicateFilter.excluded,
+      userExcludedSourcePaths: new Set(this.excludePaths)
     });
   }
   async scanMirrorStaleness() {
@@ -16757,7 +16779,8 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
       root: this.workspaceProjectRoot,
       searchPaths: this.searchPaths,
       parserOptions: this.parserOptions,
-      excludeSourcePaths: duplicateFilter.excluded
+      excludeSourcePaths: duplicateFilter.excluded,
+      userExcludedSourcePaths: new Set(this.excludePaths)
     });
     return {
       scanned: 0,
@@ -16772,10 +16795,11 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
     if (!this.excludeExactDuplicates || this.dupeyOptions === false)
       return { excluded: new Set };
     const excluded = new Set;
+    const userExcluded = new Set(this.excludePaths);
     for (const searchPath of this.searchPaths) {
       try {
         const scan = await scanWithDupey(searchPath, this.dupeyOptions || {});
-        const selected = await selectExactDuplicateExclusions(searchPath, scan);
+        const selected = await selectExactDuplicateExclusions(searchPath, scan, (path) => isPathExcluded(path, userExcluded));
         for (const path of selected.excluded)
           excluded.add(path);
       } catch (error) {
@@ -17190,6 +17214,14 @@ function toMinSyncReasonDiagnostic(reason) {
     source: "minsync"
   };
 }
+function pinExcludedPath(path) {
+  const resolvedPath = resolve11(path);
+  try {
+    return join22(realpathSync4(dirname14(resolvedPath)), basename9(resolvedPath));
+  } catch {
+    return resolvedPath;
+  }
+}
 function pinSearchRoot(searchPath) {
   const resolvedPath = resolve11(searchPath);
   let canonicalPath;
@@ -25283,6 +25315,10 @@ function resolveConfig(input) {
   const configOrigin = dirname21(resolve13(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 searchPaths = flagSearchPaths ?? envSearchPaths ?? fileSearchPaths ?? defaultSearchPaths;
   const flagWorkspacePath = flagString(flags, "workspace");
   const envWorkspacePath = envString(env, "AUTORAG_WORKSPACE");
@@ -25306,6 +25342,8 @@ function resolveConfig(input) {
   };
   if (model)
     config.model = model;
+  if (fileExcludePaths !== undefined)
+    config.excludePaths = fileExcludePaths;
   const normalized = normalizeIndexingConfig({
     minSync: file.minSync
   });
@@ -25422,6 +25460,8 @@ function buildAgentOptions(config) {
     };
   }
   opts.excludeExactDuplicates = config.excludeExactDuplicates ?? true;
+  if (config.excludePaths !== undefined)
+    opts.excludePaths = config.excludePaths;
   if (config.datasources !== undefined) {
     const { skills, unknown } = buildDatasourceSkills(config.datasources, config.workspacePath);
     if (skills.length > 0)
@@ -25677,6 +25717,8 @@ function writeDefaultConfig(path, partial, opts = {}) {
   full.jikji = partial.jikji ?? {};
   full.dupey = partial.dupey ?? { enabled: true };
   full.excludeExactDuplicates = partial.excludeExactDuplicates ?? true;
+  if (partial.excludePaths !== undefined)
+    full.excludePaths = resolveSearchPaths(partial.excludePaths, workspacePath);
   if (partial.parserOptions)
     full.parserOptions = partial.parserOptions;
   if (partial.p2p !== undefined)
@@ -26211,6 +26253,7 @@ export {
   groupUnsearchedSurfaces,
   isDatasourceSource,
   isDue,
+  isPathExcluded,
   jikjiExecutableName,
   jikjiFindDiagnostic,
   jikjiPrepareDiagnostic,

package/dist/mirror/index-store.d.ts

@@ -8,7 +8,7 @@ export interface ParsedMirrorEntry {
     readonly updatedAt: string;
 }
 /** Why refresh deliberately left a source out of the parsed mirror. */
-export type ParsedMirrorSkipReason = "duplicate-excluded" | "parser-skipped" | "parser-failed";
+export type ParsedMirrorSkipReason = "duplicate-excluded" | "user-excluded" | "parser-skipped" | "parser-failed";
 /**
  * A source the last refresh decided not to mirror, pinned to the exact version it
  * decided on. Staleness checks compare against this record instead of re-deriving

package/dist/mirror/index.d.ts

@@ -2,4 +2,4 @@ export type { ParsedMirrorEntry, ParsedMirrorIndex } from "./index-store.js";
 export { emptyMirrorIndex, loadMirrorIndex, saveMirrorIndex } from "./index-store.js";
 export { parsedMirrorIndexPath, parsedMirrorRoot, parsedOutputPath, refreshReadinessPath } from "./paths.js";
 export type { ParsedMirrorDiagnostic, ParsedMirrorDiagnosticCode, ParsedMirrorSyncOptions, ParsedMirrorSyncResult, } from "./sync.js";
-export { DEFAULT_MAX_SOURCE_BYTES, detectMirrorStaleness, syncParsedMirrors } from "./sync.js";
+export { DEFAULT_MAX_SOURCE_BYTES, detectMirrorStaleness, isPathExcluded, syncParsedMirrors } from "./sync.js";

package/dist/mirror/sync.d.ts

@@ -12,6 +12,8 @@ export interface ParsedMirrorSyncOptions {
     readonly maxSourceBytes?: number;
     /** Absolute source paths omitted from parsed mirrors (for example exact duplicate copies). */
     readonly excludeSourcePaths?: ReadonlySet<string>;
+    /** Absolute source paths or directories omitted by the user. */
+    readonly userExcludedSourcePaths?: ReadonlySet<string>;
 }
 export type ParsedMirrorDiagnosticCode = "unsupported-file" | "parser-skipped" | "parser-failed" | "duplicate-excluded" | "deleted-mirror" | "stale-index" | "pdf-extract-thin" | "parser-warning";
 /** Path-opaque refresh diagnostic. `source` is an opaque virtual path, never a real fs path. */
@@ -42,3 +44,4 @@ export declare function syncParsedMirrors(options: ParsedMirrorSyncOptions): Pro
  * getRefreshStatus).
  */
 export declare function detectMirrorStaleness(options: ParsedMirrorSyncOptions): Promise<ParsedMirrorDiagnostic[]>;
+export declare function isPathExcluded(sourcePath: string, excluded: ReadonlySet<string> | undefined): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autorag/librarian",
-  "version": "2.6.1",
+  "version": "2.6.2",
   "description": "Self-evolving librarian agent on Pi framework with pluggable retrieval methods",
   "license": "MIT",
   "repository": {

package/skills/autorag/SKILL.md

@@ -41,6 +41,14 @@ near/contains families require human review. Exact duplicate exclusion during
 refresh is enabled by default and can be disabled with
 `"excludeExactDuplicates": false` in `config.json`.
 
+### Excluding local files from the index
+
+`"excludePaths"` in `config.json` lists files or folders (absolute, or relative
+to `workspacePath`) that refresh keeps out of the parsed mirror and MinSync.
+A folder entry excludes everything under it. Removing an entry and running
+`autorag refresh --method minsync` indexes the file again. Excluded sources are
+recorded as `user-excluded` skips, so they are not reported as stale.
+
 `status` is model-free and path-opaque. `health` resolves the single model,
 checks credential presence, and normally probes one live completion. If the
 model, authentication, configuration, or indexes are unhealthy, use