Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

56.9 KB
Raw Blame
import { execFile as execFileCb, spawnSync } from 'node:child_process';
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { readdir, readFile as readFileAsync } from 'node:fs/promises';
import { homedir } from 'node:os';
import { dirname, extname, join, relative, resolve } from 'node:path';
import { promisify } from 'node:util';
import {
  attachmentFolderSegmentMatcher,
  BESIDE_DOCUMENT_ATTACHMENT_FOLDER_PATH,
  DEFAULT_ATTACHMENT_FOLDER_PATH,
  isValidAttachmentFolderPath,
  LEGACY_SKILL_STORE_ROOT,
  LINKABLE_ASSET_EXTENSIONS,
  normalizeAttachmentFolderPath,
  OK_DIR,
} from '@inkeep/open-knowledge-core';
import ignore, { type Ignore } from 'ignore';
import { isReservedForUserTree } from './cc1-broadcast.ts';
import { withHiddenWindowsConsole } from './child-process-windows-hide.ts';
import { isSupportedDocFile, stripDocExtension } from './doc-extensions.ts';
import { isProjectRoot } from './fs/find-project-root.ts';
import { getLogger } from './logger.ts';
import { incrementInPlaceSkillRescanFailures } from './metrics.ts';
import { escapesRoot, toPosix } from './path-utils.ts';
import { withSpan } from './telemetry.ts';

const log = getLogger('content-filter');

const execFileAsync = promisify(execFileCb);

const EDITOR_HOST_DIRS = ['.claude', '.cursor', '.codex', '.agents', '.opencode', '.pi'] as const;

const BUILTIN_SKIP_DIRS = new Set([
  'node_modules',
  '.venv',
  'venv',
  'env',
  '__pycache__',
  'vendor',
  'dist',
  'build',
  'out',
  'output',
  '.next',
  '.nuxt',
  '.svelte-kit',
  '.astro',
  '.turbo',
  '.cache',
  '.parcel-cache',
  'coverage',
  '.git',
  '.ok',
  '.open-knowledge',
  '.openknowledge',
  ...EDITOR_HOST_DIRS,
  'Library',
  'Applications',
  '.Trash',
]);

const ALWAYS_SKIP_DIRS = new Set<string>([
  '.git',
  'node_modules',
  '.ok',
  '.open-knowledge',
  '.openknowledge',
  ...EDITOR_HOST_DIRS,
]);

const OK_ALWAYS_SKIP_CHILDREN = new Set(['worktrees', 'local']);

function isBuiltinSkipDirName(name: string): boolean {
  return BUILTIN_SKIP_DIRS.has(name) || ALWAYS_SKIP_DIRS.has(name.toLowerCase());
}

const LEADING_DOTS_ONLY_SEGMENT = /^\.+(?:\/|$)/;

function hasDotsOnlyLeadingSegment(projectRelPath: string): boolean {
  return LEADING_DOTS_ONLY_SEGMENT.test(projectRelPath);
}

function isOutsideIgnoreScope(projectRelPath: string): boolean {
  return escapesRoot(projectRelPath) || hasDotsOnlyLeadingSegment(projectRelPath);
}

type AttachmentFolderSegment = (candidate: string) => boolean;

type AttachmentFolderShape =
  | { kind: 'sibling' }
  | { kind: 'content-root' }
  | { kind: 'fixed'; segments: readonly AttachmentFolderSegment[] }
  | { kind: 'doc-relative'; segments: readonly AttachmentFolderSegment[] };

function attachmentFolderShape(value: string): AttachmentFolderShape {
  const normalized = normalizeAttachmentFolderPath(value);
  if (!isValidAttachmentFolderPath(normalized)) {
    throw new Error('Invalid attachment folder path');
  }
  if (normalized === BESIDE_DOCUMENT_ATTACHMENT_FOLDER_PATH) return { kind: 'sibling' };
  if (normalized === '/' || normalized === '.') return { kind: 'content-root' };

  const docRelative = normalized.startsWith('./');
  const segments = (docRelative ? normalized.slice(2) : normalized)
    .split('/')
    .filter((segment) => segment !== '' && segment !== '.')
    .map(attachmentFolderSegmentMatcher);
  if (segments.length === 0) return docRelative ? { kind: 'sibling' } : { kind: 'content-root' };
  return { kind: docRelative ? 'doc-relative' : 'fixed', segments };
}

function segmentsMatchAt(
  dirSegments: readonly string[],
  start: number,
  segments: readonly AttachmentFolderSegment[],
): boolean {
  return segments.every((matches, offset) => matches(dirSegments[start + offset] ?? ''));
}

function assertNeverAttachmentShape(shape: never): never {
  throw new Error(`[AttachmentFolderShape] unhandled variant: ${JSON.stringify(shape)}`);
}

function isConfiguredAttachmentAsset(
  relativePath: string,
  shape: AttachmentFolderShape,
  hasDocumentInDir: (dir: string) => boolean,
): boolean {
  const ext = extname(relativePath).slice(1).toLowerCase();
  if (!LINKABLE_ASSET_EXTENSIONS.has(ext) || shape.kind === 'sibling') return false;

  const lastSlash = relativePath.lastIndexOf('/');
  const fileDir = lastSlash === -1 ? '' : relativePath.slice(0, lastSlash);
  if (shape.kind === 'content-root') return fileDir === '';
  const dirSegments = fileDir === '' ? [] : fileDir.split('/');
  if (shape.kind === 'fixed') {
    return (
      dirSegments.length >= shape.segments.length && segmentsMatchAt(dirSegments, 0, shape.segments)
    );
  }
  if (shape.kind === 'doc-relative') {
    for (let start = 0; start <= dirSegments.length - shape.segments.length; start++) {
      if (!segmentsMatchAt(dirSegments, start, shape.segments)) continue;
      const parentDir = dirSegments.slice(0, start).join('/');
      if (hasDocumentInDir(parentDir)) return true;
    }
    return false;
  }
  return assertNeverAttachmentShape(shape);
}

function pathHasAlwaysSkipSegment(relativePath: string, showOk?: boolean): boolean {
  const segments = relativePath.split('/');
  for (let i = 0; i < segments.length; i++) {
    const segment = segments[i];
    const canonicalSegment = segment.toLowerCase();
    if (!ALWAYS_SKIP_DIRS.has(canonicalSegment)) continue;
    if (
      showOk &&
      canonicalSegment === OK_DIR &&
      !OK_ALWAYS_SKIP_CHILDREN.has((segments[i + 1] ?? '').toLowerCase())
    ) {
      continue;
    }
    return true;
  }
  return false;
}

export function isSkillBundlePathWithheld(below: string): boolean {
  return pathHasAlwaysSkipSegment(below) || isAlwaysSkipFile(below);
}

function skillDescendantIsSkipped(relativePath: string, root: string): boolean {
  return isSkillBundlePathWithheld(relativePath.slice(root.length + 1));
}

function isSkillContentFile(relativePath: string): boolean {
  return (
    relativePath.startsWith(`${LEGACY_SKILL_STORE_ROOT}/`) &&
    !skillDescendantIsSkipped(relativePath, LEGACY_SKILL_STORE_ROOT)
  );
}

function isSkillContentAncestorDir(relativePath: string): boolean {
  return (
    relativePath === '.ok' ||
    relativePath === LEGACY_SKILL_STORE_ROOT ||
    isSkillContentFile(relativePath)
  );
}

const WATCHER_CARVE_OUT_CAPABLE_DIRS = new Set<string>([OK_DIR, ...EDITOR_HOST_DIRS]);
const WATCHER_SAFE_BUILTIN_SKIP_DIRS = new Set(
  [...BUILTIN_SKIP_DIRS].filter((dir) => !WATCHER_CARVE_OUT_CAPABLE_DIRS.has(dir)),
);

export const WATCHER_STRUCTURAL_IGNORE_DIRS = [
  '.git',
  'node_modules',
  '.ok/local',
  '.ok/worktrees',
] as const;

const WATCHER_STRUCTURAL_IGNORE_GLOBS = WATCHER_STRUCTURAL_IGNORE_DIRS.flatMap((dir) => [
  dir,
  `${dir}/**`,
  `**/${dir}`,
  `**/${dir}/**`,
]);

function watcherPatternIsConfinedToAlwaysSkippedTree(pattern: string): boolean {
  const segments = pattern.replace(/^\/+/, '').replace(/\/+$/, '').split('/');
  if (segments.includes('..')) return false;

  if (segments.some((segment) => WATCHER_SAFE_BUILTIN_SKIP_DIRS.has(segment))) {
    return true;
  }

  return segments.some(
    (segment, index) =>
      segment.toLowerCase() === OK_DIR &&
      OK_ALWAYS_SKIP_CHILDREN.has((segments[index + 1] ?? '').toLowerCase()),
  );
}

const WATCHER_MANAGED_CONTENT_PROBES = [
  '.gitignore',
  '.ok',
  '.ok/config.yml',
  '.ok/.gitignore',
  '.ok/schemas/frontmatter.json',
  '.ok/templates/example.md',
  '.ok/skills/example/SKILL.md',
  'docs/.ok',
  'docs/.ok/frontmatter.yml',
  'docs/.ok/templates/example.md',
  ...EDITOR_HOST_DIRS.flatMap((dir) => [dir, `${dir}/skills/example/SKILL.md`]),
] as const;

function patternIsUnsafeForWatcherIgnore(pattern: string): boolean {
  const candidate = pattern.trim();
  if (!candidate || candidate.startsWith('!') || candidate.startsWith('#')) return false;
  const segments = candidate.replace(/^\/+/, '').replace(/\/+$/, '').split('/');
  if (segments.includes('..')) return true;
  if (watcherPatternIsConfinedToAlwaysSkippedTree(candidate)) return false;
  if (segments.some((segment) => WATCHER_CARVE_OUT_CAPABLE_DIRS.has(segment))) return true;

  try {
    const matcher = ignore().add(candidate);
    return WATCHER_MANAGED_CONTENT_PROBES.some((path) => matcher.ignores(path));
  } catch {
    return true;
  }
}

function buildWatcherIgnoreGlobs(patterns: readonly string[]): string[] {
  const retained = patterns.filter(
    (pattern) =>
      pattern.length > 0 &&
      !pattern.startsWith('!') &&
      !pattern.startsWith('#') &&
      !patternIsUnsafeForWatcherIgnore(pattern),
  );
  return [...new Set([...retained, ...WATCHER_STRUCTURAL_IGNORE_GLOBS])];
}

function templateFolderPrefixIsSkipped(segments: string[], okIndex: number): boolean {
  for (let i = 0; i < okIndex; i++) {
    if (isBuiltinSkipDirName(segments[i])) return true;
  }
  return false;
}

function isTemplateContentFile(relativePath: string): boolean {
  const segments = relativePath.split('/');
  const n = segments.length;
  if (n < 3) return false;
  if (
    segments[n - 3] !== OK_DIR ||
    segments[n - 2] !== 'templates' ||
    extname(segments[n - 1]) !== '.md'
  ) {
    return false;
  }
  return !templateFolderPrefixIsSkipped(segments, n - 3);
}

function isTemplateContentAncestorDir(relativePath: string): boolean {
  const segments = relativePath.split('/');
  const n = segments.length;
  if (segments[n - 1] === OK_DIR) {
    return !templateFolderPrefixIsSkipped(segments, n - 1);
  }
  if (n >= 2 && segments[n - 1] === 'templates' && segments[n - 2] === OK_DIR) {
    return !templateFolderPrefixIsSkipped(segments, n - 2);
  }
  return false;
}

/**
 * True for a FILE on the shareable `.ok` artifact allow-list. Exported because the symlink guard's
 * `.ok` write exemption must consult THIS predicate on the resolved path: one predicate for
 * whether a path is in sync scope, never a parallel copy that can drift (precedent #55).
 */
export function isShareableOkArtifact(relativePath: string): boolean {
  const segments = relativePath.split('/');
  const n = segments.length;
  if (segments[0] === OK_DIR) {
    if (n === 2 && (segments[1] === 'config.yml' || segments[1] === '.gitignore')) return true;
    if (n === 3 && segments[1] === 'schemas' && segments[2].toLowerCase().endsWith('.json')) {
      return true;
    }
  }
  if (isTemplateContentFile(relativePath)) return true;
  if (n >= 2 && segments[n - 1] === 'frontmatter.yml' && segments[n - 2] === OK_DIR) {
    return !templateFolderPrefixIsSkipped(segments, n - 2);
  }
  return false;
}

function isShareableOkArtifactAncestorDir(relativePath: string): boolean {
  if (relativePath === OK_DIR || relativePath === `${OK_DIR}/schemas`) return true;
  return isTemplateContentAncestorDir(relativePath);
}

function isUnderSkillRoot(relativePath: string, roots: ReadonlySet<string>): boolean {
  for (const root of roots) {
    if (relativePath === root || relativePath.startsWith(`${root}/`)) return true;
  }
  return false;
}

function isInPlaceSkillFile(relativePath: string, dirs: ReadonlySet<string>): boolean {
  if (dirs.size === 0) return false;
  for (const d of dirs) {
    if (relativePath.startsWith(`${d}/`) && !skillDescendantIsSkipped(relativePath, d)) {
      return true;
    }
  }
  return false;
}

function isInPlaceSkillAncestorDir(relativePath: string, dirs: ReadonlySet<string>): boolean {
  if (dirs.size === 0) return false;
  for (const d of dirs) {
    if (
      d === relativePath ||
      d.startsWith(`${relativePath}/`) ||
      (relativePath.startsWith(`${d}/`) && !skillDescendantIsSkipped(relativePath, d))
    ) {
      return true;
    }
  }
  return false;
}

const BUILTIN_SKIP_FILES = new Set<string>([
  '.ds_store',
  '.localized',
  'thumbs.db',
  'desktop.ini',
  '.directory',
]);

function isAlwaysSkipFile(relativePath: string): boolean {
  return BUILTIN_SKIP_FILES.has(
    relativePath.slice(relativePath.lastIndexOf('/') + 1).toLowerCase(),
  );
}

const SECRET_BEARING_DIRS = new Set(['.ssh', '.aws', '.gnupg', '.kube', '.docker']);

export function pathHasSecretBearingDirSegment(relativePath: string): boolean {
  for (const segment of relativePath.split('/')) {
    if (SECRET_BEARING_DIRS.has(segment.toLowerCase())) return true;
  }
  return false;
}

const SECRET_CREDENTIAL_BASENAMES = new Set([
  'credentials',
  '.netrc',
  '.npmrc',
  '.pgpass',
  '.git-credentials',
]);
const SECRET_KEY_SUFFIXES = ['.pem', '.key', '.p12', '.pfx', '.keystore', '.jks', '.ppk'] as const;
export function isSecretBearingFile(relativePath: string): boolean {
  const lower = relativePath.slice(relativePath.lastIndexOf('/') + 1).toLowerCase();
  if (lower === '.env' || lower.startsWith('.env.')) return true;
  if (SECRET_CREDENTIAL_BASENAMES.has(lower)) return true;
  if (
    lower.startsWith('id_rsa') ||
    lower.startsWith('id_ed25519') ||
    lower.startsWith('id_ecdsa') ||
    lower.startsWith('id_dsa')
  ) {
    return true;
  }
  for (const suffix of SECRET_KEY_SUFFIXES) {
    if (lower.endsWith(suffix)) return true;
  }
  return false;
}

function isSingleDocAncestorDir(relativeDir: string, singleDocRelPath: string): boolean {
  return singleDocRelPath === relativeDir || singleDocRelPath.startsWith(`${relativeDir}/`);
}

/**
 * Consulted by both `isExcluded` and `isDirExcluded` so a walker pruning directories and a caller
 * classifying a single path agree (precedent #55).
 */
function createDescendantProjectGate(
  projectDir: string,
  contentDir: string,
  singleDocRelPath: string | undefined,
  isContentScopeExcluded?: (absolutePath: string) => boolean,
): {
  isInside: (relativePath: string, syncScope?: { pathBase: 'content' | 'project' }) => boolean;
  reset: () => void;
} {
  const enabled = singleDocRelPath === undefined;
  const cache = new Map<string, boolean>();

  function isRoot(absoluteDir: string): boolean {
    const cached = cache.get(absoluteDir);
    if (cached !== undefined) return cached;
    let hit: boolean;
    try {
      hit = isProjectRoot(absoluteDir);
    } catch {
      return false;
    }
    cache.set(absoluteDir, hit);
    return hit;
  }

  return {
    isInside(relativePath: string, syncScope?: { pathBase: 'content' | 'project' }): boolean {
      if (!enabled || relativePath === '') return false;
      const base = syncScope?.pathBase === 'project' ? projectDir : contentDir;
      if (isContentScopeExcluded?.(resolve(base, relativePath))) return true;
      let prefix = base;
      for (const segment of relativePath.split('/')) {
        prefix = join(prefix, segment);
        if (isRoot(prefix)) return true;
      }
      return false;
    },
    reset(): void {
      cache.clear();
    },
  };
}

const IGNORE_FILE_NAMES = ['.gitignore', '.okignore'] as const;

/**
 * Mirroring these into `ContentFilter` keeps the sync walker and `git add` agreed on scope
 * (precedent #55).
 */
function loadGitExcludeSources(projectDir: string, bytesAcc: { value: number }): string[] {
  const commonDir = readGitCommonDirSync(projectDir);
  if (commonDir === null) return [];

  const patterns: string[] = [];
  appendExcludeFileIfExists(join(commonDir, 'info', 'exclude'), bytesAcc, patterns, 'info/exclude');

  const globalExcludePath = resolveGlobalExcludesfileSync(projectDir);
  if (globalExcludePath) {
    appendExcludeFileIfExists(globalExcludePath, bytesAcc, patterns, 'global excludesfile');
  }

  return patterns;
}

async function loadGitExcludeSourcesAsync(
  projectDir: string,
  bytesAcc: { value: number },
): Promise<string[]> {
  const commonDir = await readGitCommonDirAsync(projectDir);
  if (commonDir === null) return [];

  const patterns: string[] = [];
  await appendExcludeFileIfExistsAsync(
    join(commonDir, 'info', 'exclude'),
    bytesAcc,
    patterns,
    'info/exclude',
  );

  const globalExcludePath = await resolveGlobalExcludesfileAsync(projectDir);
  if (globalExcludePath) {
    await appendExcludeFileIfExistsAsync(
      globalExcludePath,
      bytesAcc,
      patterns,
      'global excludesfile',
    );
  }

  return patterns;
}

function readGitCommonDirSync(projectDir: string): string | null {
  const probe = spawnSync(
    'git',
    ['rev-parse', '--git-common-dir'],
    withHiddenWindowsConsole({
      cwd: projectDir,
      encoding: 'utf-8',
      timeout: 5_000,
    }),
  );
  if (probe.status !== 0 || !probe.stdout) return null;
  return resolve(projectDir, probe.stdout.trim());
}

async function readGitCommonDirAsync(projectDir: string): Promise<string | null> {
  try {
    const { stdout } = await execFileAsync(
      'git',
      ['rev-parse', '--git-common-dir'],
      withHiddenWindowsConsole({
        cwd: projectDir,
        encoding: 'utf-8',
        timeout: 5_000,
      }),
    );
    if (!stdout) return null;
    return resolve(projectDir, stdout.trim());
  } catch {
    return null;
  }
}

function resolveGlobalExcludesfileSync(projectDir: string): string | null {
  const configProbe = spawnSync(
    'git',
    ['config', '--get', '--type=path', 'core.excludesfile'],
    withHiddenWindowsConsole({
      cwd: projectDir,
      encoding: 'utf-8',
      timeout: 5_000,
    }),
  );
  if (configProbe.status === 0 && configProbe.stdout) {
    const raw = configProbe.stdout.trim();
    if (raw) return raw;
  }
  return xdgGlobalIgnoreDefault();
}

async function resolveGlobalExcludesfileAsync(projectDir: string): Promise<string | null> {
  try {
    const { stdout } = await execFileAsync(
      'git',
      ['config', '--get', '--type=path', 'core.excludesfile'],
      withHiddenWindowsConsole({ cwd: projectDir, encoding: 'utf-8', timeout: 5_000 }),
    );
    const raw = stdout.trim();
    if (raw) return raw;
  } catch {}
  return xdgGlobalIgnoreDefault();
}

function xdgGlobalIgnoreDefault(): string {
  const xdg = process.env.XDG_CONFIG_HOME?.trim();
  const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.config');
  return join(base, 'git', 'ignore');
}

function appendExcludeFileIfExists(
  path: string,
  bytesAcc: { value: number },
  patterns: string[],
  label: string,
): void {
  if (!existsSync(path)) return;
  try {
    const content = readFileSync(path, 'utf-8');
    bytesAcc.value += content.length;
    patterns.push(...parseIgnorePatterns(content));
  } catch (err) {
    log.warn({ path, err }, `Failed to read ${label} at ${path}`);
  }
}

async function appendExcludeFileIfExistsAsync(
  path: string,
  bytesAcc: { value: number },
  patterns: string[],
  label: string,
): Promise<void> {
  if (!existsSync(path)) return;
  try {
    const content = await readFileAsync(path, 'utf-8');
    bytesAcc.value += content.length;
    patterns.push(...parseIgnorePatterns(content));
  } catch (err) {
    log.warn({ path, err }, `Failed to read ${label} at ${path}`);
  }
}

export interface ContentFilterOptions {
  projectDir: string;
  contentDir: string;
  isContentScopeExcluded?: (absolutePath: string) => boolean;
  singleDocRelPath?: string;
  attachmentFolderPath?: string;
  inPlaceSkillDirs?: ReadonlySet<string>;
  skillRootPaths?: ReadonlySet<string>;
  rescanInPlaceSkillDirs?: (priorAdmission: ReadonlySet<string>) => ReadonlySet<string>;
  onAfterRebuild?: () => void;
}

export type RebuildResult =
  | {
      ok: true;
      patternCount: number;
      nestedFileCount: number;
      bytes: number;
      durationMs: number;
    }
  | {
      ok: false;
      error: { message: string };
    };

interface ContentFilterCommonReadOpts {
  respectOkignore?: boolean;
  showOk?: boolean;
}

type ContentFilterOrdinaryReadOpts = ContentFilterCommonReadOpts & {
  bypassFilters?: boolean;
  syncScope?: never;
};

type ContentFilterSyncReadOpts = ContentFilterCommonReadOpts & {
  bypassFilters?: never;
  /**
   * Paths the unified ignore rules reject stay refused even with the scope: the gather walk and
   * `git add` must agree on every path (precedent #55), and a local-only project's blanket `.ok/`
   * exclude covers exactly this set.
   */
  syncScope: { pathBase: 'content' | 'project' };
};

type ContentFilterReadOpts = ContentFilterOrdinaryReadOpts | ContentFilterSyncReadOpts;

type ContentFilterPathReadOpts = Omit<ContentFilterOrdinaryReadOpts, 'syncScope'>;

export interface ContentFilter {
  isExcluded(relativePath: string, opts?: ContentFilterReadOpts): boolean;
  isDirExcluded(relativePath: string, opts?: ContentFilterReadOpts): boolean;
  isPathIgnored(relativePath: string, opts?: ContentFilterPathReadOpts): boolean;
  isExcludedByIgnoreFiles(relativePath: string): boolean;
  getWatcherIgnoreGlobs(): string[];
  incrementMdDir(dir: string): void;
  decrementMdDir(dir: string): void;
  rebuildDirCount(): void;
  setAttachmentFolderPath(value: string): void;
  rebuildIgnorePatterns(): Promise<RebuildResult>;

  refreshInPlaceSkillDirs(): void;
  inPlaceSkillDirsFingerprint(): string;
  peekFreshInPlaceSkillDirsFingerprint(): string;
}

function createSkillRescanReporter(): { failed(err: unknown): void; succeeded(): void } {
  let faulted = false;
  return {
    failed(err) {
      incrementInPlaceSkillRescanFailures();
      if (faulted) return;
      faulted = true;
      log.warn(
        { err },
        'in-place skill re-scan failed; the previous allow-list stays until a re-scan succeeds, and further failures are only counted',
      );
    },
    succeeded() {
      if (!faulted) return;
      faulted = false;
      log.info({}, 'in-place skill re-scan works again');
    },
  };
}

export function createContentFilter(opts: ContentFilterOptions): ContentFilter {
  const { projectDir, contentDir, onAfterRebuild, singleDocRelPath } = opts;
  let inPlaceSkillDirs: ReadonlySet<string> = opts.inPlaceSkillDirs ?? new Set();
  const skillRescan = createSkillRescanReporter();
  let configuredAttachmentFolder = attachmentFolderShape(
    opts.attachmentFolderPath ?? DEFAULT_ATTACHMENT_FOLDER_PATH,
  );
  const skillRootPaths: ReadonlySet<string> = opts.skillRootPaths ?? new Set();
  const descendantProjects = createDescendantProjectGate(
    projectDir,
    contentDir,
    singleDocRelPath,
    opts.isContentScopeExcluded,
  );

  const contentRelPrefix = toPosix(relative(projectDir, contentDir));
  const contentOutsideProject = isOutsideIgnoreScope(contentRelPrefix);

  let ig: Ignore;
  let okignoreIg: Ignore;
  let rootIgnorePatterns: string[];
  let watcherIgnoreGlobs: string[];
  let lastPatternCount = 0;
  let lastNestedFileCount = 0;
  let lastBytes = 0;

  function buildPatternState(): {
    patternCount: number;
    nestedFileCount: number;
    bytes: number;
  } {
    const newIg = ignore();
    const newOkignoreIg = ignore();

    newIg.add('.git');

    const newRootPatterns: string[] = [];
    let bytes = 0;
    let nestedFileCount = 0;

    for (const name of IGNORE_FILE_NAMES) {
      const path = join(projectDir, name);
      if (!existsSync(path)) continue;
      try {
        const content = readFileSync(path, 'utf-8');
        bytes += content.length;
        const patterns = parseIgnorePatterns(content);
        newRootPatterns.push(...patterns);
        newIg.add(patterns);
        if (name === '.okignore') newOkignoreIg.add(patterns);
      } catch (err) {
        log.warn({ path, err }, `Failed to read ${name} at ${path}`);
      }
    }

    if (contentRelPrefix && !contentOutsideProject) {
      for (const name of IGNORE_FILE_NAMES) {
        const path = join(contentDir, name);
        if (!existsSync(path)) continue;
        try {
          const content = readFileSync(path, 'utf-8');
          bytes += content.length;
          nestedFileCount++;
          const patterns = parseIgnorePatterns(content);
          const prefixed = patterns.map((p) => prefixPattern(p, contentRelPrefix));
          newIg.add(prefixed);
          if (name === '.okignore') newOkignoreIg.add(prefixed);
        } catch (err) {
          log.warn({ path, err }, `Failed to read ${name} at ${path}`);
        }
      }
    }

    const bytesAcc = { value: bytes };
    nestedFileCount += loadNestedIgnoreFiles(
      contentDir,
      projectDir,
      newIg,
      newOkignoreIg,
      bytesAcc,
    );
    bytes = bytesAcc.value;

    const gitExcludePatterns = loadGitExcludeSources(projectDir, bytesAcc);
    bytes = bytesAcc.value;
    if (gitExcludePatterns.length > 0) {
      newRootPatterns.push(...gitExcludePatterns);
      newIg.add(gitExcludePatterns);
    }

    const newWatcherGlobs = buildWatcherIgnoreGlobs(newRootPatterns);

    ig = newIg;
    okignoreIg = newOkignoreIg;
    rootIgnorePatterns = newRootPatterns;
    watcherIgnoreGlobs = newWatcherGlobs;
    lastPatternCount = newRootPatterns.length;
    lastNestedFileCount = nestedFileCount;
    lastBytes = bytes;

    return {
      patternCount: lastPatternCount,
      nestedFileCount: lastNestedFileCount,
      bytes: lastBytes,
    };
  }

  buildPatternState();

  const dirCount = new Map<string, number>();

  function isIgnored(
    relativePath: string,
    syncScope?: ContentFilterReadOpts['syncScope'],
  ): boolean {
    if (contentOutsideProject && syncScope?.pathBase !== 'project') return false;
    const projectRelPath =
      syncScope?.pathBase === 'project' || !contentRelPrefix
        ? relativePath
        : `${contentRelPrefix}/${relativePath}`;
    if (hasDotsOnlyLeadingSegment(projectRelPath)) return false;
    return ig.ignores(projectRelPath);
  }

  function syncProjectRelPath(
    relativePath: string,
    syncScope: NonNullable<ContentFilterReadOpts['syncScope']>,
  ): string {
    return syncScope.pathBase === 'project' || !contentRelPrefix
      ? relativePath
      : `${contentRelPrefix}/${relativePath}`;
  }

  function isOkIgnored(relativePath: string): boolean {
    if (contentOutsideProject) return false;
    const projectRelPath = contentRelPrefix ? `${contentRelPrefix}/${relativePath}` : relativePath;
    if (hasDotsOnlyLeadingSegment(projectRelPath)) return false;
    return okignoreIg.ignores(projectRelPath);
  }

  const refreshDirCount = (): void => {
    if (singleDocRelPath !== undefined) return;
    populateDirCount(contentDir, '', isIgnored, dirCount);
  };

  refreshDirCount();

  function isReservedDocName(relativePath: string): boolean {
    const docName = stripDocExtension(relativePath);
    return isReservedForUserTree(docName);
  }

  function isRejectedByConfigurableRules(relativePath: string): boolean {
    for (const segment of relativePath.split('/')) {
      if (isBuiltinSkipDirName(segment)) return true;
    }

    if (contentOutsideProject) return false;
    return isIgnored(relativePath);
  }

  let rebuildInFlight: Promise<RebuildResult> | null = null;
  let rebuildTrailing: Promise<RebuildResult> | null = null;

  return {
    isExcluded(relativePath: string, opts?: ContentFilterReadOpts): boolean {
      if (isReservedDocName(relativePath)) return true;

      if (isSecretBearingFile(relativePath)) return true;
      if (pathHasSecretBearingDirSegment(relativePath)) return true;

      if (descendantProjects.isInside(relativePath, opts?.syncScope)) return true;

      if (
        !opts?.bypassFilters &&
        isUnderSkillRoot(relativePath, skillRootPaths) &&
        !isInPlaceSkillFile(relativePath, inPlaceSkillDirs)
      ) {
        return true;
      }

      if (
        !opts?.bypassFilters &&
        (isSkillContentFile(relativePath) ||
          (isInPlaceSkillFile(relativePath, inPlaceSkillDirs) && !isIgnored(relativePath)))
      ) {
        if (singleDocRelPath !== undefined) return relativePath !== singleDocRelPath;
        if (isSupportedDocFile(relativePath)) return false;
        const ext = extname(relativePath).slice(1).toLowerCase();
        return !LINKABLE_ASSET_EXTENSIONS.has(ext);
      }

      if (!opts?.bypassFilters && isTemplateContentFile(relativePath)) {
        if (singleDocRelPath !== undefined) return relativePath !== singleDocRelPath;
        return false;
      }

      if (
        !opts?.bypassFilters &&
        opts?.syncScope !== undefined &&
        isShareableOkArtifact(syncProjectRelPath(relativePath, opts.syncScope)) &&
        !isIgnored(relativePath, opts.syncScope)
      ) {
        if (singleDocRelPath !== undefined) return relativePath !== singleDocRelPath;
        return false;
      }

      if (pathHasAlwaysSkipSegment(relativePath, opts?.showOk)) return true;

      if (isAlwaysSkipFile(relativePath)) return true;

      if (singleDocRelPath !== undefined) return relativePath !== singleDocRelPath;

      if (opts?.bypassFilters) {
        return opts.respectOkignore === true && isOkIgnored(relativePath);
      }

      if (isRejectedByConfigurableRules(relativePath)) return true;

      if (isSupportedDocFile(relativePath)) return false;

      if (
        isConfiguredAttachmentAsset(
          relativePath,
          configuredAttachmentFolder,
          (dir) => (dirCount.get(dir) ?? 0) > 0,
        )
      )
        return false;

      const ext = extname(relativePath).slice(1).toLowerCase();
      if (LINKABLE_ASSET_EXTENSIONS.has(ext)) {
        const dir = dirname(relativePath);
        const normalizedDir = dir === '.' ? '' : dir;
        if ((dirCount.get(normalizedDir) ?? 0) > 0) return false;
      }

      return true;
    },

    isDirExcluded(relativePath: string, opts?: ContentFilterReadOpts): boolean {
      if (pathHasSecretBearingDirSegment(relativePath)) return true;
      if (descendantProjects.isInside(relativePath, opts?.syncScope)) return true;
      if (
        !opts?.bypassFilters &&
        (isSkillContentAncestorDir(relativePath) ||
          isTemplateContentAncestorDir(relativePath) ||
          (opts?.syncScope !== undefined &&
            isShareableOkArtifactAncestorDir(syncProjectRelPath(relativePath, opts.syncScope))) ||
          isInPlaceSkillAncestorDir(relativePath, inPlaceSkillDirs))
      )
        return false;
      if (pathHasAlwaysSkipSegment(relativePath, opts?.showOk)) return true;
      if (singleDocRelPath !== undefined) {
        return !isSingleDocAncestorDir(relativePath, singleDocRelPath);
      }
      if (opts?.bypassFilters) {
        return (
          opts.respectOkignore === true &&
          (isOkIgnored(relativePath) || isOkIgnored(`${relativePath}/`))
        );
      }
      for (const segment of relativePath.split('/')) {
        if (isBuiltinSkipDirName(segment)) return true;
      }
      if (contentOutsideProject) return false;
      return (
        isIgnored(relativePath, opts?.syncScope) || isIgnored(`${relativePath}/`, opts?.syncScope)
      );
    },

    isPathIgnored(relativePath: string, opts?: ContentFilterPathReadOpts): boolean {
      if (isReservedDocName(relativePath)) return true;
      if (isSecretBearingFile(relativePath)) return true;
      if (pathHasSecretBearingDirSegment(relativePath)) return true;
      if (
        isSkillContentFile(relativePath) ||
        (isInPlaceSkillFile(relativePath, inPlaceSkillDirs) && !isIgnored(relativePath))
      )
        return false;
      if (isTemplateContentFile(relativePath)) return false;
      if (pathHasAlwaysSkipSegment(relativePath)) return true;
      if (isAlwaysSkipFile(relativePath)) return true;
      if (opts?.bypassFilters) return false;
      return isRejectedByConfigurableRules(relativePath);
    },

    isExcludedByIgnoreFiles(relativePath: string): boolean {
      if (relativePath.split('/').some(isBuiltinSkipDirName)) return false;
      if (contentOutsideProject) return false;
      return isIgnored(relativePath);
    },

    getWatcherIgnoreGlobs(): string[] {
      return watcherIgnoreGlobs;
    },

    incrementMdDir(dir: string): void {
      const normalizedDir = dir === '.' ? '' : dir;
      dirCount.set(normalizedDir, (dirCount.get(normalizedDir) ?? 0) + 1);
    },

    decrementMdDir(dir: string): void {
      const normalizedDir = dir === '.' ? '' : dir;
      const current = dirCount.get(normalizedDir) ?? 0;
      if (current <= 1) {
        dirCount.delete(normalizedDir);
      } else {
        dirCount.set(normalizedDir, current - 1);
      }
    },

    rebuildDirCount(): void {
      const prev = new Map(dirCount);
      dirCount.clear();
      try {
        refreshDirCount();
      } catch (err) {
        for (const [k, v] of prev) dirCount.set(k, v);
        log.warn(
          { err: err instanceof Error ? err : new Error(String(err)) },
          'content-filter rebuildDirCount walk failed — retaining previous counts',
        );
      }
    },

    setAttachmentFolderPath(value: string): void {
      configuredAttachmentFolder = attachmentFolderShape(value);
    },

    refreshInPlaceSkillDirs(): void {
      if (!opts.rescanInPlaceSkillDirs) return;
      try {
        inPlaceSkillDirs = opts.rescanInPlaceSkillDirs(inPlaceSkillDirs);
        skillRescan.succeeded();
      } catch (err) {
        skillRescan.failed(err);
      }
    },

    inPlaceSkillDirsFingerprint(): string {
      return [...inPlaceSkillDirs].sort().join('\n');
    },

    peekFreshInPlaceSkillDirsFingerprint(): string {
      if (!opts.rescanInPlaceSkillDirs) return [...inPlaceSkillDirs].sort().join('\n');
      try {
        return [...opts.rescanInPlaceSkillDirs(inPlaceSkillDirs)].sort().join('\n');
      } catch {
        return [...inPlaceSkillDirs].sort().join('\n');
      }
    },

    async rebuildIgnorePatterns(): Promise<RebuildResult> {
      const startRun = (runOnce: () => Promise<RebuildResult>): Promise<RebuildResult> => {
        rebuildInFlight = runOnce().finally(() => {
          rebuildInFlight = null;
        });
        return rebuildInFlight;
      };
      const runRebuild = async (): Promise<RebuildResult> => {
        descendantProjects.reset();
        if (opts.rescanInPlaceSkillDirs) {
          try {
            inPlaceSkillDirs = opts.rescanInPlaceSkillDirs(inPlaceSkillDirs);
            skillRescan.succeeded();
          } catch (err) {
            skillRescan.failed(err);
          }
        }

        const prevIg = ig;
        const prevOkignoreIg = okignoreIg;
        const prevRootPatterns = rootIgnorePatterns;
        const prevWatcherGlobs = watcherIgnoreGlobs;
        const prevPatternCount = lastPatternCount;
        const prevNestedFileCount = lastNestedFileCount;
        const prevBytes = lastBytes;

        const startedAt = Date.now();

        return withSpan('config.ignore.rebuild', { attributes: {} }, async (span) => {
          try {
            const counts = buildPatternState();
            dirCount.clear();
            if (singleDocRelPath === undefined) {
              await populateDirCountYielding(contentDir, isIgnored, dirCount);
            }

            const durationMs = Date.now() - startedAt;
            span.setAttributes({
              'ok.ignore.pattern_count': counts.patternCount,
              'ok.ignore.nested_file_count': counts.nestedFileCount,
              'ok.ignore.bytes': counts.bytes,
            });
            log.info(
              {
                patternCount: counts.patternCount,
                nestedFileCount: counts.nestedFileCount,
                bytes: counts.bytes,
                durationMs,
              },
              'content-filter rebuild succeeded',
            );

            if (onAfterRebuild) {
              try {
                onAfterRebuild();
              } catch (err) {
                log.warn(
                  { err: err instanceof Error ? err : new Error(String(err)) },
                  'content-filter onAfterRebuild callback threw — derived views may be stale',
                );
              }
            }

            return {
              ok: true as const,
              patternCount: counts.patternCount,
              nestedFileCount: counts.nestedFileCount,
              bytes: counts.bytes,
              durationMs,
            };
          } catch (err) {
            ig = prevIg;
            okignoreIg = prevOkignoreIg;
            rootIgnorePatterns = prevRootPatterns;
            watcherIgnoreGlobs = prevWatcherGlobs;
            lastPatternCount = prevPatternCount;
            lastNestedFileCount = prevNestedFileCount;
            lastBytes = prevBytes;
            dirCount.clear();
            try {
              refreshDirCount();
            } catch (rollbackErr) {
              log.warn(
                {
                  err: rollbackErr instanceof Error ? rollbackErr : new Error(String(rollbackErr)),
                },
                'content-filter rollback dirCount re-walk failed — sibling-asset counts may be stale until next rebuild',
              );
            }

            const message = err instanceof Error ? err.message : String(err);
            log.warn(
              { err: err instanceof Error ? err : new Error(message) },
              'content-filter rebuild failed — rolled back to previous state',
            );
            return { ok: false as const, error: { message } };
          }
        });
      };
      if (rebuildInFlight !== null) {
        if (rebuildTrailing === null) {
          rebuildTrailing = rebuildInFlight
            .catch(() => null)
            .then(() => {
              rebuildTrailing = null;
              return startRun(runRebuild);
            });
        }
        return rebuildTrailing;
      }
      return startRun(runRebuild);
    },
  };
}

const YIELD_EVERY_DIRS = 50;
async function populateDirCountYielding(
  dir: string,
  isIgnored: (path: string) => boolean,
  dirCount: Map<string, number>,
): Promise<void> {
  const stack: Array<{ dir: string; relPath: string }> = [{ dir, relPath: '' }];
  let sinceYield = 0;
  while (stack.length > 0) {
    const { dir: cur, relPath } = stack.pop() as { dir: string; relPath: string };
    sinceYield += 1;
    if (sinceYield >= YIELD_EVERY_DIRS) {
      sinceYield = 0;
      await new Promise((resolve) => setImmediate(resolve));
    }
    let entries: import('node:fs').Dirent[];
    try {
      entries = readdirSync(cur, { withFileTypes: true });
    } catch (err) {
      log.warn({ dir: cur, err }, `Failed to read directory for dir-count: ${cur}`);
      continue;
    }
    for (const entry of entries) {
      const childRel = relPath ? `${relPath}/${entry.name}` : entry.name;
      if (entry.isDirectory()) {
        if (isBuiltinSkipDirName(entry.name)) continue;
        if (isIgnored(childRel) || isIgnored(`${childRel}/`)) continue;
        stack.push({ dir: join(cur, entry.name), relPath: childRel });
      } else if (entry.isFile() && isSupportedDocFile(entry.name) && !isIgnored(childRel)) {
        dirCount.set(relPath, (dirCount.get(relPath) ?? 0) + 1);
      }
    }
  }
}

function populateDirCount(
  dir: string,
  relPath: string,
  isIgnored: (path: string) => boolean,
  dirCount: Map<string, number>,
): void {
  let entries: import('node:fs').Dirent[];
  try {
    entries = readdirSync(dir, { withFileTypes: true });
  } catch (err) {
    log.warn({ dir, err }, `Failed to read directory for dir-count: ${dir}`);
    return;
  }
  for (const entry of entries) {
    const childRel = relPath ? `${relPath}/${entry.name}` : entry.name;
    if (entry.isDirectory()) {
      if (isBuiltinSkipDirName(entry.name)) continue;
      if (isIgnored(childRel) || isIgnored(`${childRel}/`)) continue;
      populateDirCount(join(dir, entry.name), childRel, isIgnored, dirCount);
    } else if (entry.isFile() && isSupportedDocFile(entry.name) && !isIgnored(childRel)) {
      dirCount.set(relPath, (dirCount.get(relPath) ?? 0) + 1);
    }
  }
}

function parseIgnorePatterns(content: string): string[] {
  return content
    .split('\n')
    .map((line) => line.trim())
    .filter((line) => line.length > 0 && !line.startsWith('#'));
}

/**
 * Re-anchors one nested ignore-file pattern into project-root-relative form while preserving
 * gitignore depth semantics: a naive prefix join injects an embedded slash, collapsing an
 * any-depth rule to one level and breaking the predicate symmetry precedent #55 guards.
 */
function prefixPattern(pattern: string, relPrefix: string): string {
  const negated = pattern.startsWith('!');
  const body = negated ? pattern.slice(1) : pattern;
  const core = body.startsWith('/') ? body.slice(1) : body;
  const withoutTrailingSlash = core.endsWith('/') ? core.slice(0, -1) : core;
  const anchored = body.startsWith('/') || withoutTrailingSlash.includes('/');
  const reanchored = anchored ? `${relPrefix}/${core}` : `${relPrefix}/**/${core}`;
  return negated ? `!${reanchored}` : reanchored;
}

function loadNestedIgnoreFiles(
  dir: string,
  projectDir: string,
  ig: Ignore,
  okignoreIg: Ignore,
  bytesAcc: { value: number },
): number {
  let entries: import('node:fs').Dirent[];
  try {
    entries = readdirSync(dir, { withFileTypes: true });
  } catch (err) {
    log.warn({ dir, err }, `Failed to read directory ${dir}`);
    return 0;
  }

  let count = 0;

  for (const entry of entries) {
    if (!entry.isDirectory()) continue;

    if (isBuiltinSkipDirName(entry.name)) continue;

    const dirPath = join(dir, entry.name);
    const relToProject = toPosix(relative(projectDir, dirPath));

    if (isOutsideIgnoreScope(relToProject)) continue;

    if (ig.ignores(relToProject) || ig.ignores(`${relToProject}/`)) continue;

    for (const name of IGNORE_FILE_NAMES) {
      const filePath = join(dirPath, name);
      if (!existsSync(filePath)) continue;
      try {
        const content = readFileSync(filePath, 'utf-8');
        bytesAcc.value += content.length;
        const patterns = parseIgnorePatterns(content);
        const prefixed = patterns.map((p) => prefixPattern(p, relToProject));
        ig.add(prefixed);
        if (name === '.okignore') okignoreIg.add(prefixed);
        count++;
      } catch (err) {
        log.warn({ path: filePath, err }, `Failed to read nested ${name} at ${filePath}`);
      }
    }

    count += loadNestedIgnoreFiles(dirPath, projectDir, ig, okignoreIg, bytesAcc);
  }

  return count;
}

async function initContentDirStateAsync(
  dir: string,
  relPath: string,
  projectDir: string,
  ig: Ignore,
  okignoreIg: Ignore,
  contentRelPrefix: string,
  contentOutsideProject: boolean,
  dirCount: Map<string, number>,
): Promise<void> {
  let entries: import('node:fs').Dirent[];
  try {
    entries = await readdir(dir, { withFileTypes: true });
  } catch (err) {
    log.warn({ dir, err }, `Failed to read directory ${dir}`);
    return;
  }

  for (const entry of entries) {
    const childRel = relPath ? `${relPath}/${entry.name}` : entry.name;

    if (entry.isDirectory()) {
      if (isBuiltinSkipDirName(entry.name)) continue;

      const dirPath = join(dir, entry.name);

      if (!contentOutsideProject) {
        const relToProject = toPosix(relative(projectDir, dirPath));
        if (isOutsideIgnoreScope(relToProject)) continue;
        if (ig.ignores(relToProject) || ig.ignores(`${relToProject}/`)) continue;

        for (const name of IGNORE_FILE_NAMES) {
          const filePath = join(dirPath, name);
          if (!existsSync(filePath)) continue;
          try {
            const patterns = parseIgnorePatterns(await readFileAsync(filePath, 'utf-8'));
            const prefixed = patterns.map((p) => prefixPattern(p, relToProject));
            ig.add(prefixed);
            if (name === '.okignore') okignoreIg.add(prefixed);
          } catch (err) {
            log.warn({ path: filePath, err }, `Failed to read nested ${name} at ${filePath}`);
          }
        }
      }

      await initContentDirStateAsync(
        dirPath,
        childRel,
        projectDir,
        ig,
        okignoreIg,
        contentRelPrefix,
        contentOutsideProject,
        dirCount,
      );
    } else if (entry.isFile() && isSupportedDocFile(entry.name)) {
      if (!contentOutsideProject) {
        const projectRelPath = contentRelPrefix ? `${contentRelPrefix}/${childRel}` : childRel;
        if (ig.ignores(projectRelPath)) continue;
      }
      dirCount.set(relPath, (dirCount.get(relPath) ?? 0) + 1);
    }
  }
}

export async function createContentFilterAsync(opts: ContentFilterOptions): Promise<ContentFilter> {
  const { projectDir, contentDir, onAfterRebuild, singleDocRelPath } = opts;
  let inPlaceSkillDirs: ReadonlySet<string> = opts.inPlaceSkillDirs ?? new Set();
  const skillRescan = createSkillRescanReporter();
  let configuredAttachmentFolder = attachmentFolderShape(
    opts.attachmentFolderPath ?? DEFAULT_ATTACHMENT_FOLDER_PATH,
  );
  const skillRootPaths: ReadonlySet<string> = opts.skillRootPaths ?? new Set();
  const descendantProjects = createDescendantProjectGate(
    projectDir,
    contentDir,
    singleDocRelPath,
    opts.isContentScopeExcluded,
  );

  const contentRelPrefix = toPosix(relative(projectDir, contentDir));
  const contentOutsideProject = isOutsideIgnoreScope(contentRelPrefix);

  let ig = ignore();
  let okignoreIg = ignore();
  let watcherIgnoreGlobs: string[] = [];
  let lastPatternCount = 0;

  const dirCount = new Map<string, number>();

  const refreshDirCount = (): void => {
    if (singleDocRelPath !== undefined) return;
    populateDirCount(contentDir, '', isIgnored, dirCount);
  };

  function isIgnored(
    relativePath: string,
    syncScope?: ContentFilterReadOpts['syncScope'],
  ): boolean {
    if (contentOutsideProject && syncScope?.pathBase !== 'project') return false;
    const projectRelPath =
      syncScope?.pathBase === 'project' || !contentRelPrefix
        ? relativePath
        : `${contentRelPrefix}/${relativePath}`;
    if (hasDotsOnlyLeadingSegment(projectRelPath)) return false;
    return ig.ignores(projectRelPath);
  }

  function syncProjectRelPath(
    relativePath: string,
    syncScope: NonNullable<ContentFilterReadOpts['syncScope']>,
  ): string {
    return syncScope.pathBase === 'project' || !contentRelPrefix
      ? relativePath
      : `${contentRelPrefix}/${relativePath}`;
  }

  function isOkIgnored(relativePath: string): boolean {
    if (contentOutsideProject) return false;
    const projectRelPath = contentRelPrefix ? `${contentRelPrefix}/${relativePath}` : relativePath;
    if (hasDotsOnlyLeadingSegment(projectRelPath)) return false;
    return okignoreIg.ignores(projectRelPath);
  }

  function isReservedDocName(relativePath: string): boolean {
    const docName = stripDocExtension(relativePath);
    return isReservedForUserTree(docName);
  }
  function isRejectedByConfigurableRules(relativePath: string): boolean {
    for (const segment of relativePath.split('/')) {
      if (isBuiltinSkipDirName(segment)) return true;
    }
    if (contentOutsideProject) return false;
    return isIgnored(relativePath);
  }

  async function buildAndSwapPatternState(): Promise<void> {
    const newIg = ignore();
    const newOkignoreIg = ignore();
    newIg.add('.git');
    const newRootPatterns: string[] = [];

    for (const name of IGNORE_FILE_NAMES) {
      const path = join(projectDir, name);
      if (!existsSync(path)) continue;
      try {
        const patterns = parseIgnorePatterns(await readFileAsync(path, 'utf-8'));
        newRootPatterns.push(...patterns);
        newIg.add(patterns);
        if (name === '.okignore') newOkignoreIg.add(patterns);
      } catch (err) {
        log.warn({ path, err }, `Failed to read ${name} at ${path}`);
      }
    }

    if (contentRelPrefix && !contentOutsideProject) {
      for (const name of IGNORE_FILE_NAMES) {
        const path = join(contentDir, name);
        if (!existsSync(path)) continue;
        try {
          const patterns = parseIgnorePatterns(await readFileAsync(path, 'utf-8'));
          const prefixed = patterns.map((p) => prefixPattern(p, contentRelPrefix));
          newIg.add(prefixed);
          if (name === '.okignore') newOkignoreIg.add(prefixed);
        } catch (err) {
          log.warn({ path, err }, `Failed to read ${name} at ${path}`);
        }
      }
    }

    const bytesAcc = { value: 0 };
    const gitExcludePatterns = await loadGitExcludeSourcesAsync(projectDir, bytesAcc);
    if (gitExcludePatterns.length > 0) {
      newRootPatterns.push(...gitExcludePatterns);
      newIg.add(gitExcludePatterns);
    }

    const newDirCount = new Map<string, number>();
    if (singleDocRelPath === undefined) {
      await initContentDirStateAsync(
        contentDir,
        '',
        projectDir,
        newIg,
        newOkignoreIg,
        contentRelPrefix,
        contentOutsideProject,
        newDirCount,
      );
    }

    ig = newIg;
    okignoreIg = newOkignoreIg;
    watcherIgnoreGlobs = buildWatcherIgnoreGlobs(newRootPatterns);
    lastPatternCount = newRootPatterns.length;
    dirCount.clear();
    for (const [k, v] of newDirCount) dirCount.set(k, v);
  }

  await buildAndSwapPatternState();

  let rebuildInFlight: Promise<RebuildResult> | null = null;
  let rebuildTrailing: Promise<RebuildResult> | null = null;

  return {
    isExcluded(relativePath: string, opts?: ContentFilterReadOpts): boolean {
      if (isReservedDocName(relativePath)) return true;
      if (isSecretBearingFile(relativePath)) return true;
      if (pathHasSecretBearingDirSegment(relativePath)) return true;
      if (descendantProjects.isInside(relativePath, opts?.syncScope)) return true;

      if (
        !opts?.bypassFilters &&
        isUnderSkillRoot(relativePath, skillRootPaths) &&
        !isInPlaceSkillFile(relativePath, inPlaceSkillDirs)
      ) {
        return true;
      }

      if (
        !opts?.bypassFilters &&
        (isSkillContentFile(relativePath) ||
          (isInPlaceSkillFile(relativePath, inPlaceSkillDirs) && !isIgnored(relativePath)))
      ) {
        if (singleDocRelPath !== undefined) return relativePath !== singleDocRelPath;
        if (isSupportedDocFile(relativePath)) return false;
        const skillExt = extname(relativePath).slice(1).toLowerCase();
        return !LINKABLE_ASSET_EXTENSIONS.has(skillExt);
      }
      if (!opts?.bypassFilters && isTemplateContentFile(relativePath)) {
        if (singleDocRelPath !== undefined) return relativePath !== singleDocRelPath;
        return false;
      }
      if (
        !opts?.bypassFilters &&
        opts?.syncScope !== undefined &&
        isShareableOkArtifact(syncProjectRelPath(relativePath, opts.syncScope)) &&
        !isIgnored(relativePath, opts.syncScope)
      ) {
        if (singleDocRelPath !== undefined) return relativePath !== singleDocRelPath;
        return false;
      }
      if (pathHasAlwaysSkipSegment(relativePath, opts?.showOk)) return true;
      if (isAlwaysSkipFile(relativePath)) return true;
      if (singleDocRelPath !== undefined) return relativePath !== singleDocRelPath;
      if (opts?.bypassFilters) {
        return opts.respectOkignore === true && isOkIgnored(relativePath);
      }
      if (isRejectedByConfigurableRules(relativePath)) return true;
      if (isSupportedDocFile(relativePath)) return false;
      if (
        isConfiguredAttachmentAsset(
          relativePath,
          configuredAttachmentFolder,
          (dir) => (dirCount.get(dir) ?? 0) > 0,
        )
      )
        return false;
      const ext = extname(relativePath).slice(1).toLowerCase();
      if (LINKABLE_ASSET_EXTENSIONS.has(ext)) {
        const dir = dirname(relativePath);
        const normalizedDir = dir === '.' ? '' : dir;
        if ((dirCount.get(normalizedDir) ?? 0) > 0) return false;
      }
      return true;
    },

    isDirExcluded(relativePath: string, opts?: ContentFilterReadOpts): boolean {
      if (pathHasSecretBearingDirSegment(relativePath)) return true;
      if (descendantProjects.isInside(relativePath, opts?.syncScope)) return true;
      if (
        !opts?.bypassFilters &&
        (isSkillContentAncestorDir(relativePath) ||
          isTemplateContentAncestorDir(relativePath) ||
          (opts?.syncScope !== undefined &&
            isShareableOkArtifactAncestorDir(syncProjectRelPath(relativePath, opts.syncScope))) ||
          isInPlaceSkillAncestorDir(relativePath, inPlaceSkillDirs))
      )
        return false;
      if (pathHasAlwaysSkipSegment(relativePath, opts?.showOk)) return true;
      if (singleDocRelPath !== undefined) {
        return !isSingleDocAncestorDir(relativePath, singleDocRelPath);
      }
      if (opts?.bypassFilters) {
        return (
          opts.respectOkignore === true &&
          (isOkIgnored(relativePath) || isOkIgnored(`${relativePath}/`))
        );
      }
      for (const segment of relativePath.split('/')) {
        if (isBuiltinSkipDirName(segment)) return true;
      }
      if (contentOutsideProject) return false;
      return (
        isIgnored(relativePath, opts?.syncScope) || isIgnored(`${relativePath}/`, opts?.syncScope)
      );
    },

    isPathIgnored(relativePath: string, opts?: ContentFilterPathReadOpts): boolean {
      if (isReservedDocName(relativePath)) return true;
      if (isSecretBearingFile(relativePath)) return true;
      if (pathHasSecretBearingDirSegment(relativePath)) return true;
      if (
        isSkillContentFile(relativePath) ||
        (isInPlaceSkillFile(relativePath, inPlaceSkillDirs) && !isIgnored(relativePath))
      )
        return false;
      if (isTemplateContentFile(relativePath)) return false;
      if (pathHasAlwaysSkipSegment(relativePath)) return true;
      if (isAlwaysSkipFile(relativePath)) return true;
      if (opts?.bypassFilters) return false;
      return isRejectedByConfigurableRules(relativePath);
    },

    isExcludedByIgnoreFiles(relativePath: string): boolean {
      if (relativePath.split('/').some(isBuiltinSkipDirName)) return false;
      if (contentOutsideProject) return false;
      return isIgnored(relativePath);
    },

    getWatcherIgnoreGlobs(): string[] {
      return watcherIgnoreGlobs;
    },

    incrementMdDir(dir: string): void {
      const normalizedDir = dir === '.' ? '' : dir;
      dirCount.set(normalizedDir, (dirCount.get(normalizedDir) ?? 0) + 1);
    },

    decrementMdDir(dir: string): void {
      const normalizedDir = dir === '.' ? '' : dir;
      const current = dirCount.get(normalizedDir) ?? 0;
      if (current <= 1) {
        dirCount.delete(normalizedDir);
      } else {
        dirCount.set(normalizedDir, current - 1);
      }
    },

    rebuildDirCount(): void {
      const prev = new Map(dirCount);
      dirCount.clear();
      try {
        refreshDirCount();
      } catch (err) {
        for (const [k, v] of prev) dirCount.set(k, v);
        log.warn(
          { err: err instanceof Error ? err : new Error(String(err)) },
          'content-filter rebuildDirCount walk failed — retaining previous counts',
        );
      }
    },

    setAttachmentFolderPath(value: string): void {
      configuredAttachmentFolder = attachmentFolderShape(value);
    },

    refreshInPlaceSkillDirs(): void {
      if (!opts.rescanInPlaceSkillDirs) return;
      try {
        inPlaceSkillDirs = opts.rescanInPlaceSkillDirs(inPlaceSkillDirs);
        skillRescan.succeeded();
      } catch (err) {
        skillRescan.failed(err);
      }
    },

    inPlaceSkillDirsFingerprint(): string {
      return [...inPlaceSkillDirs].sort().join('\n');
    },

    peekFreshInPlaceSkillDirsFingerprint(): string {
      if (!opts.rescanInPlaceSkillDirs) return [...inPlaceSkillDirs].sort().join('\n');
      try {
        return [...opts.rescanInPlaceSkillDirs(inPlaceSkillDirs)].sort().join('\n');
      } catch {
        return [...inPlaceSkillDirs].sort().join('\n');
      }
    },

    async rebuildIgnorePatterns(): Promise<RebuildResult> {
      const startRun = (runOnce: () => Promise<RebuildResult>): Promise<RebuildResult> => {
        rebuildInFlight = runOnce().finally(() => {
          rebuildInFlight = null;
        });
        return rebuildInFlight;
      };
      const runRebuild = async (): Promise<RebuildResult> => {
        descendantProjects.reset();
        if (opts.rescanInPlaceSkillDirs) {
          try {
            inPlaceSkillDirs = opts.rescanInPlaceSkillDirs(inPlaceSkillDirs);
            skillRescan.succeeded();
          } catch (err) {
            skillRescan.failed(err);
          }
        }
        const prevIg = ig;
        const prevOkignoreIg = okignoreIg;
        const prevWatcherGlobs = watcherIgnoreGlobs;
        const prevDirCount = new Map(dirCount);
        const startedAt = Date.now();

        return withSpan('config.ignore.rebuild', { attributes: {} }, async (span) => {
          try {
            await buildAndSwapPatternState();
            const durationMs = Date.now() - startedAt;
            span.setAttributes({
              'ok.ignore.pattern_count': lastPatternCount,
              'ok.ignore.nested_file_count': 0,
              'ok.ignore.bytes': 0,
            });
            log.info({ durationMs }, 'content-filter async rebuild succeeded');

            if (onAfterRebuild) {
              try {
                onAfterRebuild();
              } catch (err) {
                log.warn(
                  { err: err instanceof Error ? err : new Error(String(err)) },
                  'content-filter onAfterRebuild callback threw — derived views may be stale',
                );
              }
            }

            return {
              ok: true as const,
              patternCount: lastPatternCount,
              nestedFileCount: 0,
              bytes: 0,
              durationMs,
            };
          } catch (err) {
            ig = prevIg;
            okignoreIg = prevOkignoreIg;
            watcherIgnoreGlobs = prevWatcherGlobs;
            dirCount.clear();
            for (const [k, v] of prevDirCount) dirCount.set(k, v);
            const message = err instanceof Error ? err.message : String(err);
            log.warn(
              { err: err instanceof Error ? err : new Error(message) },
              'content-filter async rebuild failed — rolled back',
            );
            return { ok: false as const, error: { message } };
          }
        });
      };
      if (rebuildInFlight !== null) {
        if (rebuildTrailing === null) {
          rebuildTrailing = rebuildInFlight
            .catch(() => null)
            .then(() => {
              rebuildTrailing = null;
              return startRun(runRebuild);
            });
        }
        return rebuildTrailing;
      }
      return startRun(runRebuild);
    },
  };
}