ccdesk 0.2.2 → 0.2.3

package/dist/{server → core}/scan/index.js

@@ -4,20 +4,19 @@ import { storeDirName } from "../../shared/memory.js";
 import {} from "../../shared/types.js";
 import { buildContext } from "./context.js";
 import { isConfigHome } from "./env.js";
-import { gitRoot, isDir, isFile, isRecord, mainWorktreeRoot, readJsonObject, stringsIn, visibilityOf, } from "./files.js";
+import { isDir, isFile, readJsonObject, stringsIn } from "./files.js";
+import { isRecord } from "./data.js";
+import { gitRoot, mainWorktreeRoot, trustKey, visibilityOf } from "./git.js";
 import { AGENTS_MD_MODES, resolveInstructions } from "./instructions.js";
 import { readInventory } from "./inventory.js";
 import { readMemoryStore } from "./memory.js";
 import { permissionsOf, trustWaits } from "./permissions.js";
 import { listProjects } from "./projects.js";
-import { effectiveSettings, readSettingsLayers } from "./settings.js";
+import { effectiveSettings, readManagedSettings, readSettingsLayers } from "./settings.js";
 import { builtinTools } from "./tools.js";
-async function readClaudeJson(env) {
-    const result = await readJsonObject(env, env.claudeJson);
-    return result.ok ? result.data : null;
-}
 export async function scanOverview(env, launchDir) {
-    const claudeJson = await readClaudeJson(env);
+    const result = await readJsonObject(env, env.claudeJson);
+    const claudeJson = result.ok ? result.data : null;
     const projects = await listProjects(env, claudeJson, launchDir);
     const hashesByName = new Map();
     const memoryCatalog = [];
@@ -53,26 +52,30 @@ export async function scanOverview(env, launchDir) {
 export async function scanDirectory(env, dir, profile = "interactive") {
     const path = resolve(dir);
     const exists = await isDir(path);
-    const claudeJson = await readClaudeJson(env);
+    const problems = [];
+    const claudeJson = await readClaudeJson(env, problems);
     const root = exists ? await gitRoot(path) : null;
-    const settings = await readSettingsLayers(env, path);
+    const managed = await readManagedSettings(env);
+    const settings = await readSettingsLayers(env, path, managed);
+    for (const l of settings)
+        if (l.error)
+            problems.push({
+                path: l.path,
+                error: l.error,
+                ...(l.blocksStart ? { blocksStart: true } : {}),
+            });
     const effective = effectiveSettings(settings);
     const mode = agentsMdMode(settings);
     const excludes = effective.find((s) => s.key === "claudeMdExcludes")?.value;
     const mainRoot = exists ? await mainWorktreeRoot(path) : null;
-    const trust = trustOf(env, claudeJson, path, mainRoot ?? root);
-    const managedLayer = settings.find((l) => l.scope === "managed");
-    const managedClaudeMd = managedLayer?.data?.claudeMd;
-    const problems = [];
+    const trust = trustOf(env, claudeJson, path, mainRoot, root);
     const instructions = await resolveInstructions({
         env,
         cwd: path,
         mode,
         excludes: stringsIn(excludes),
         externalImports: trust.externalImports,
-        managedClaudeMd: managedLayer && typeof managedClaudeMd === "string"
-            ? { path: `${managedLayer.path}#claudeMd`, text: managedClaudeMd }
-            : null,
+        managedClaudeMd: managedClaudeMd(settings),
         problems,
     });
     const inventory = await readInventory({
@@ -80,67 +83,23 @@ export async function scanDirectory(env, dir, profile = "interactive") {
         projectDir: path,
         gitRoot: root,
         layers: settings,
+        effective,
+        managed: managed.data,
         claudeJson,
         trust,
         profile,
+        problems,
     });
-    // Every project file that shapes Claude here, so the UI can say who sees each one.
-    const mcpJson = join(path, ".mcp.json");
-    const projectFiles = [
-        ...instructions.filter((i) => i.scope === "project" || i.scope === "local").map((i) => i.path),
-        ...settings
-            .filter((s) => s.exists && (s.scope === "project" || s.scope === "local"))
-            .map((s) => s.path),
-        ...((await isFile(mcpJson)) ? [mcpJson] : []),
-        ...[...inventory.agents, ...inventory.skills, ...inventory.commands, ...inventory.outputStyles]
-            .filter((e) => e.scope === "project" || e.scope === "local")
-            .map((e) => e.path),
-    ];
-    const visibility = await visibilityOf(root, projectFiles);
-    for (const item of [...instructions, ...settings]) {
-        const v = visibility.get(item.path);
-        if (v)
-            item.visibility = v;
-    }
-    let sharing = null;
-    if (root) {
-        sharing = { tracked: [], untracked: [], ignored: [] };
-        for (const file of new Set(projectFiles)) {
-            const v = visibility.get(file);
-            // Shown as repository paths, with forward slashes on every platform.
-            const rel = relative(root, file).replaceAll("\\", "/");
-            if (v === "tracked")
-                sharing.tracked.push(rel);
-            else if (v === "untracked")
-                sharing.untracked.push(rel);
-            else if (v === "ignored")
-                sharing.ignored.push(rel);
-        }
-    }
-    // A local file tracked in git, or in a .claude that is a link, counts as the repository's
-    // (docs: permissions#when-your-local-settings-file-needs-trust).
-    const localFromRepository = (await Promise.all(settings
-        .filter((l) => l.scope === "local" && l.exists)
-        .map(async (l) => l.visibility === "tracked" ||
-        ((await lstat(dirname(l.path)).catch(() => null))?.isSymbolicLink() ?? false)))).some(Boolean);
+    const sharing = await shareProjectFiles(path, root, instructions, settings, inventory);
     const trustOptions = {
         trust,
         inConfigHome: isConfigHome(env, path),
-        localFromRepository,
+        // Reads the visibility shareProjectFiles gave each layer.
+        localFromRepository: await localFromRepository(settings),
         profile,
     };
-    const memory = await readMemory(env, mainRoot, path, effective, trustOptions);
+    const memory = await readMemory(env, mainRoot, path, effective, trustOptions, problems);
     const permissions = permissionsOf(settings, trustOptions);
-    for (const l of settings)
-        if (l.error)
-            problems.push({
-                path: l.path,
-                error: l.error,
-                ...(l.blocksStart ? { blocksStart: true } : {}),
-            });
-    const mcp = await readJsonObject(env, mcpJson);
-    if (!mcp.ok && !mcp.missing)
-        problems.push({ path: mcpJson, error: mcp.error });
     return {
         path,
         profile,
@@ -163,32 +122,95 @@ export async function scanDirectory(env, dir, profile = "interactive") {
         permissions,
         tools: builtinTools(permissions, inventory.hooks),
         trust,
-        problems,
+        // One line per file: a file read twice, such as a rule that a CLAUDE.md also imports, is one problem.
+        problems: problems.filter((p, i) => problems.findIndex((q) => q.path === p.path) === i),
         sharing,
     };
 }
+/** ~/.claude.json, or null when it is missing or broken; a broken one is a problem. */
+async function readClaudeJson(env, problems) {
+    const file = await readJsonObject(env, env.claudeJson);
+    if (file.ok)
+        return file.data;
+    // Without it the folder looks untrusted and your servers missing, so the problem says why.
+    if (!file.missing)
+        problems.push({
+            path: env.claudeJson,
+            error: `${file.error}, so ccdesk cannot show your trust answers or your user and local MCP servers`,
+        });
+    return null;
+}
+/** The CLAUDE.md text managed settings give in their claudeMd key. */
+function managedClaudeMd(settings) {
+    const managed = settings.find((l) => l.scope === "managed");
+    const text = managed?.data?.claudeMd;
+    return managed && typeof text === "string" ? { path: `${managed.path}#claudeMd`, text } : null;
+}
+/**
+ * Says who sees each project file that shapes Claude here: marks the instructions and settings
+ * with their git visibility, and returns the repository's files by visibility, or null outside one.
+ */
+async function shareProjectFiles(path, root, instructions, settings, inventory) {
+    const inProject = (scope) => scope === "project" || scope === "local";
+    const mcpJson = join(path, ".mcp.json");
+    const projectFiles = [
+        ...instructions.filter((i) => inProject(i.scope)).map((i) => i.path),
+        ...settings.filter((s) => s.exists && inProject(s.scope)).map((s) => s.path),
+        ...((await isFile(mcpJson)) ? [mcpJson] : []),
+        ...[...inventory.agents, ...inventory.skills, ...inventory.commands, ...inventory.outputStyles]
+            .filter((e) => inProject(e.scope))
+            .map((e) => e.path),
+    ];
+    const visibility = await visibilityOf(root, projectFiles);
+    for (const item of [...instructions, ...settings]) {
+        const v = visibility.get(item.path);
+        if (v)
+            item.visibility = v;
+    }
+    if (!root)
+        return null;
+    const sharing = { tracked: [], untracked: [], ignored: [] };
+    for (const file of new Set(projectFiles)) {
+        const v = visibility.get(file);
+        // Shown as repository paths, with forward slashes on every platform.
+        const rel = relative(root, file).replaceAll("\\", "/");
+        if (v === "tracked")
+            sharing.tracked.push(rel);
+        else if (v === "untracked")
+            sharing.untracked.push(rel);
+        else if (v === "ignored")
+            sharing.ignored.push(rel);
+    }
+    return sharing;
+}
+/**
+ * Whether the local settings file counts as the repository's: tracked in git, or in a .claude
+ * that is a link (docs: permissions#when-your-local-settings-file-needs-trust).
+ */
+async function localFromRepository(settings) {
+    const fromRepository = await Promise.all(settings
+        .filter((l) => l.scope === "local" && l.exists)
+        .map(async (l) => l.visibility === "tracked" ||
+        ((await lstat(dirname(l.path)).catch(() => null))?.isSymbolicLink() ?? false)));
+    return fromRepository.some(Boolean);
+}
 /**
  * Your answers to Claude Code's trust dialogs, from ~/.claude.json (docs: permissions#project-allow-rules-and-workspace-trust).
  * In a repository the key is the main checkout's root; outside one it is the folder, and a trusted
  * parent folder covers it. In your home directory trust lasts one session and is never saved.
  */
-function trustOf(env, claudeJson, path, repositoryRoot) {
+function trustOf(env, claudeJson, path, mainRoot, repoRoot) {
     const projects = isRecord(claudeJson?.projects) ? claudeJson.projects : {};
     const entry = (key) => (isRecord(projects[key]) ? projects[key] : {});
-    const root = repositoryRoot ?? path;
+    const root = trustKey(path, mainRoot, repoRoot);
     const own = entry(root);
     const trust = {
         root,
         trusted: own.hasTrustDialogAccepted === true,
         sessionOnly: path === env.home,
-        // These two keys are not documented; they are what Claude Code writes for the import dialog.
-        externalImports: own.hasClaudeMdExternalIncludesApproved === true
-            ? "approved"
-            : own.hasClaudeMdExternalIncludesWarningShown === true
-                ? "declined"
-                : "not-asked",
+        externalImports: importAnswer(own),
     };
-    if (!trust.trusted && !repositoryRoot)
+    if (!trust.trusted && !mainRoot && !repoRoot)
         for (let d = dirname(path); d !== dirname(d); d = dirname(d))
             if (entry(d).hasTrustDialogAccepted === true) {
                 trust.inheritedFrom = d;
@@ -196,12 +218,23 @@ function trustOf(env, claudeJson, path, repositoryRoot) {
             }
     return trust;
 }
+/**
+ * Your answer to the dialog about imports from outside the project. These two keys are not
+ * documented; they are what Claude Code writes for that dialog.
+ */
+function importAnswer(project) {
+    if (project.hasClaudeMdExternalIncludesApproved === true)
+        return "approved";
+    if (project.hasClaudeMdExternalIncludesWarningShown === true)
+        return "declined";
+    return "not-asked";
+}
 /**
  * The auto memory Claude Code uses here (docs: memory#storage-location, settings-reference#automemoryenabled).
  * Worktrees and subdirectories of one repository share one store. The store is returned even
  * when its folder does not exist yet, so a note about memory being off still shows.
  */
-async function readMemory(env, mainRoot, path, effective, trustOptions) {
+async function readMemory(env, mainRoot, path, effective, trustOptions, problems) {
     const key = mainRoot ?? path;
     const setting = effective.find((s) => s.key === "autoMemoryDirectory");
     // A value from a repository file counts once the folder is trusted, like hooks (docs:
@@ -216,7 +249,7 @@ async function readMemory(env, mainRoot, path, effective, trustOptions) {
     const customDir = typeof custom?.value === "string" ? expandHome(env, custom.value) : null;
     const storeName = env.projectDirName ?? storeDirName(key);
     const dir = customDir ?? join(env.claudeDir, "projects", storeName, "memory");
-    const store = (await readMemoryStore(env, dir, key)) ?? {
+    const store = (await readMemoryStore(env, dir, key, problems)) ?? {
         dir,
         loaded: true,
         projectPath: key,
@@ -272,8 +305,9 @@ function agentsMdMode(layers) {
         for (const id of ["cc-plugin-agents-md@builtin", "agents-md@builtin"]) {
             const entry = configs[id];
             const value = isRecord(entry) && isRecord(entry.options) ? entry.options.instructionFiles : undefined;
-            if (typeof value === "string" && AGENTS_MD_MODES.includes(value))
-                return value;
+            const mode = AGENTS_MD_MODES.find((m) => m === value);
+            if (mode)
+                return mode;
         }
     }
     return "claude-md-or-agents-md";

package/dist/core/scan/instructions.d.ts

@@ -0,0 +1,54 @@
+import { type AgentsMdMode, type Instruction, type Problem, type TextFile, type Trust } from "../../shared/types.ts";
+import { type ScanEnv } from "./env.ts";
+export declare const AGENTS_MD_MODES: AgentsMdMode[];
+/** The CLAUDE.md and AGENTS.md files each folder can hold, in the order Claude Code reads them. */
+export declare const CLAUDE_MD_NAMES: string[];
+export declare const AGENTS_MD_NAMES: string[];
+/**
+ * Whether AGENTS.md loads, given the instruction mode and whether a CLAUDE.md or CLAUDE.local.md
+ * is there (docs: memory#choose-which-instruction-files-load).
+ */
+export declare function agentsMdLoads(mode: AgentsMdMode, hasClaudeMd: boolean): boolean;
+/**
+ * Whether a claudeMdExcludes glob matches a file by its own path or, for a link, its target's
+ * (docs: memory#exclude-specific-claude-md-files).
+ */
+export declare function isExcluded(excludes: string[], path: string, realPath?: string): boolean;
+/**
+ * Where a rule in `dir` really is when that is outside both the project and `dir`: a link's
+ * target, or the file a linked folder leads to. Undefined for a rule that stays inside.
+ */
+export declare function ruleTarget(file: TextFile, dir: string, realCwd: string): Promise<string | undefined>;
+/**
+ * Why a project rule linked from outside the project does not load, or null when it does: it waits
+ * for your approval of outside imports, and once approved loads only without a paths field
+ * (docs: memory#share-rules-across-projects-with-symlinks).
+ */
+export declare function linkedRuleBlock(target: string | undefined, realCwd: string, approved: boolean, hasPaths: boolean): "needs-approval" | "has-paths" | null;
+/** Directories from the filesystem root down to `cwd`, the order Claude Code concatenates them in. */
+export declare function ancestorsRootFirst(cwd: string): string[];
+interface ResolveOptions {
+    env: ScanEnv;
+    cwd: string;
+    mode: AgentsMdMode;
+    /** Merged `claudeMdExcludes` globs from every settings layer. */
+    excludes: string[];
+    /** Your answer to Claude Code's dialog about imports from outside the project. */
+    externalImports: Trust["externalImports"];
+    /** The managed settings' `claudeMd` text, which loads like a managed CLAUDE.md. */
+    managedClaudeMd: {
+        path: string;
+        text: string;
+    } | null;
+    /** Receives instruction files and imports that exist but cannot be read. */
+    problems: Problem[];
+}
+/**
+ * The instruction files Claude Code reads in `cwd`, in load order, each with whether it loads at
+ * session start, when Claude works with matching files, or not at all, and why.
+ * Follows code.claude.com/docs/en/memory.
+ */
+export declare function resolveInstructions(options: ResolveOptions): Promise<Instruction[]>;
+/** An invalid pattern matches nothing. */
+export declare function safeMatch(path: string, glob: string): boolean;
+export {};

package/dist/{server → core}/scan/instructions.js

@@ -1,9 +1,8 @@
-import { constants } from "node:fs";
-import { access, stat } from "node:fs/promises";
 import { dirname, isAbsolute, join, matchesGlob, parse, resolve } from "node:path";
 import {} from "../../shared/types.js";
 import {} from "./env.js";
-import { isFile, isNetworkPath, isWithin, MAX_TEXT_BYTES, parseFrontmatter, readTextFile, resolvedPath, toStringList, walkMarkdown, } from "./files.js";
+import { isFile, isNetworkPath, isWithin, MAX_TEXT_BYTES, readTextFile, resolvedPath, toStringList, walkMarkdown, } from "./files.js";
+import { parseFrontmatter } from "./data.js";
 const MAX_IMPORT_HOPS = 4;
 export const AGENTS_MD_MODES = [
     "claude-md-or-agents-md",
@@ -11,6 +10,45 @@ export const AGENTS_MD_MODES = [
     "claude-md",
     "managed-only",
 ];
+/** The CLAUDE.md and AGENTS.md files each folder can hold, in the order Claude Code reads them. */
+export const CLAUDE_MD_NAMES = ["CLAUDE.md", ".claude/CLAUDE.md"];
+export const AGENTS_MD_NAMES = ["AGENTS.md", ".claude/AGENTS.md"];
+/**
+ * Whether AGENTS.md loads, given the instruction mode and whether a CLAUDE.md or CLAUDE.local.md
+ * is there (docs: memory#choose-which-instruction-files-load).
+ */
+export function agentsMdLoads(mode, hasClaudeMd) {
+    return mode === "claude-md-and-agents-md" || (mode === "claude-md-or-agents-md" && !hasClaudeMd);
+}
+/**
+ * Whether a claudeMdExcludes glob matches a file by its own path or, for a link, its target's
+ * (docs: memory#exclude-specific-claude-md-files).
+ */
+export function isExcluded(excludes, path, realPath) {
+    return excludes.some((glob) => [path, realPath].some((p) => p !== undefined && safeMatch(p, glob)));
+}
+/**
+ * Where a rule in `dir` really is when that is outside both the project and `dir`: a link's
+ * target, or the file a linked folder leads to. Undefined for a rule that stays inside.
+ */
+export async function ruleTarget(file, dir, realCwd) {
+    if (file.realPath)
+        return file.realPath;
+    const real = await resolvedPath(file.path);
+    return isWithin(realCwd, real) || isWithin(await resolvedPath(dir), real) ? undefined : real;
+}
+/**
+ * Why a project rule linked from outside the project does not load, or null when it does: it waits
+ * for your approval of outside imports, and once approved loads only without a paths field
+ * (docs: memory#share-rules-across-projects-with-symlinks).
+ */
+export function linkedRuleBlock(target, realCwd, approved, hasPaths) {
+    if (target === undefined || isWithin(realCwd, target))
+        return null;
+    if (!approved)
+        return "needs-approval";
+    return hasPaths ? "has-paths" : null;
+}
 /** Directories from the filesystem root down to `cwd`, the order Claude Code concatenates them in. */
 export function ancestorsRootFirst(cwd) {
     const dirs = [];
@@ -31,25 +69,31 @@ export function ancestorsRootFirst(cwd) {
  */
 export async function resolveInstructions(options) {
     const { env, cwd, mode, excludes, externalImports, managedClaudeMd, problems } = options;
-    /** A file that exists but cannot be read is reported, not taken for a missing one. */
-    const readInstruction = async (path) => {
-        const file = await readTextFile(env, path);
-        if (file || !(await stat(path).catch(() => null))?.isFile())
-            return file;
-        const denied = await access(path, constants.R_OK).then(() => null, (error) => error.code ?? String(error));
-        if (denied)
-            problems.push({ path, error: `cannot be read (${denied})` });
-        return null;
-    };
     const ctx = {
         realCwd: await resolvedPath(resolve(cwd)),
         env,
         approved: externalImports === "approved",
+        problems,
     };
-    const managedOnly = mode === "managed-only";
-    const skippedByMode = `Skipped: instruction mode is ${mode}`;
+    const out = await readOwnFiles(ctx, managedClaudeMd);
+    const { claudeFiles, agentsFiles } = await readDirectoryFiles(ctx, cwd);
+    explainClaudeFiles(claudeFiles, cwd);
+    explainAgentsFiles(agentsFiles, claudeFiles, mode);
+    for (const dir of ancestorsRootFirst(cwd))
+        out.push(...claudeFiles.filter((f) => f.dir === dir), ...agentsFiles.filter((f) => f.dir === dir));
+    applyLoadRules(out, ctx, mode, excludes, externalImports);
+    addChecks(out);
+    return out;
+}
+/** A file that exists but cannot be read is reported, not taken for a missing one. */
+function readInstruction(ctx, path) {
+    return readTextFile(ctx.env, path, ctx.problems);
+}
+/** The managed and user files, which come first and do not depend on the folder. */
+async function readOwnFiles(ctx, managedClaudeMd) {
+    const { env } = ctx;
     const out = [];
-    const managed = await readInstruction(join(env.managedDir, "CLAUDE.md"));
+    const managed = await readInstruction(ctx, join(env.managedDir, "CLAUDE.md"));
     if (managed)
         out.push(await instruction(managed, "claude-md", "managed", env.managedDir, ctx, "Organisation policy, always loaded"));
     if (managedClaudeMd) {
@@ -65,69 +109,94 @@ export async function resolveInstructions(options) {
         entry.imports = [];
         out.push(entry);
     }
-    const user = await readInstruction(join(env.claudeDir, "CLAUDE.md"));
+    const user = await readInstruction(ctx, join(env.claudeDir, "CLAUDE.md"));
     if (user)
         out.push(await instruction(user, "claude-md", "user", env.claudeDir, ctx, "Your instructions for every project"));
     for (const path of await walkMarkdown(join(env.claudeDir, "rules"))) {
-        const file = await readInstruction(path);
+        const file = await readInstruction(ctx, path);
         if (file)
             out.push(await rule(file, "user", env.claudeDir, ctx));
     }
-    // Per directory, root first: CLAUDE.md, .claude/CLAUDE.md, rules, then CLAUDE.local.md last
-    // ("your personal notes are the last thing Claude reads at that level"), then AGENTS.md.
+    return out;
+}
+/**
+ * The project and local files of `cwd` and every folder above it. Per directory, root first:
+ * CLAUDE.md, .claude/CLAUDE.md, rules, then CLAUDE.local.md last ("your personal notes are the last
+ * thing Claude reads at that level"), then AGENTS.md.
+ */
+async function readDirectoryFiles(ctx, cwd) {
     const claudeFiles = [];
     const agentsFiles = [];
     for (const dir of ancestorsRootFirst(cwd)) {
-        // ~/.claude/CLAUDE.md and ~/.claude/rules are the user files above, not the home's project files.
-        const isConfigHome = join(dir, ".claude") === env.claudeDir;
-        for (const name of ["CLAUDE.md", ".claude/CLAUDE.md"]) {
-            if (isConfigHome && name === ".claude/CLAUDE.md")
-                continue;
-            const file = await readInstruction(join(dir, name));
-            if (file)
-                claudeFiles.push(await instruction(file, "claude-md", "project", dir, ctx, ""));
-        }
-        if (!isConfigHome && dir !== env.claudeDir)
-            for (const path of await walkMarkdown(join(dir, ".claude", "rules"))) {
-                const file = await readInstruction(path);
-                if (file)
-                    claudeFiles.push(await rule(file, "project", dir, ctx));
-            }
-        const local = await readInstruction(join(dir, "CLAUDE.local.md"));
-        if (local)
-            claudeFiles.push(await instruction(local, "claude-local-md", "local", dir, ctx, ""));
-        for (const name of ["AGENTS.md", ".claude/AGENTS.md"]) {
-            const file = await readInstruction(join(dir, name));
+        claudeFiles.push(...(await readClaudeFiles(ctx, dir)));
+        for (const name of AGENTS_MD_NAMES) {
+            const file = await readInstruction(ctx, join(dir, name));
             if (file)
                 agentsFiles.push(await instruction(file, "agents-md", "project", dir, ctx, ""));
         }
     }
-    const hasClaudeMd = claudeFiles.some((f) => f.kind !== "rule");
+    return { claudeFiles, agentsFiles };
+}
+/** One folder's CLAUDE.md files, rules and CLAUDE.local.md, in the order Claude Code reads them. */
+async function readClaudeFiles(ctx, dir) {
+    const { env } = ctx;
+    const out = [];
+    // ~/.claude/CLAUDE.md and ~/.claude/rules are the user files above, not the home's project files.
+    const holdsClaudeDir = join(dir, ".claude") === env.claudeDir;
+    for (const name of CLAUDE_MD_NAMES) {
+        if (holdsClaudeDir && name === ".claude/CLAUDE.md")
+            continue;
+        const file = await readInstruction(ctx, join(dir, name));
+        if (file)
+            out.push(await instruction(file, "claude-md", "project", dir, ctx, ""));
+    }
+    if (!holdsClaudeDir && dir !== env.claudeDir)
+        for (const path of await walkMarkdown(join(dir, ".claude", "rules"))) {
+            const file = await readInstruction(ctx, path);
+            if (file)
+                out.push(await rule(file, "project", dir, ctx));
+        }
+    const local = await readInstruction(ctx, join(dir, "CLAUDE.local.md"));
+    if (local)
+        out.push(await instruction(local, "claude-local-md", "local", dir, ctx, ""));
+    return out;
+}
+/** Why each CLAUDE.md and CLAUDE.local.md loads; rules have their reason already. */
+function explainClaudeFiles(claudeFiles, cwd) {
     for (const file of claudeFiles) {
         if (file.kind === "rule")
             continue;
-        file.reason =
-            file.kind === "claude-local-md"
-                ? "Your private notes for this directory"
-                : file.dir === resolve(cwd)
-                    ? "Instructions for this directory"
-                    : "Inherited from a parent directory";
+        if (file.kind === "claude-local-md")
+            file.reason = "Your private notes for this directory";
+        else if (file.dir === resolve(cwd))
+            file.reason = "Instructions for this directory";
+        else
+            file.reason = "Inherited from a parent directory";
     }
+}
+/** Whether each AGENTS.md loads next to the CLAUDE.md files found, and why. */
+function explainAgentsFiles(agentsFiles, claudeFiles, mode) {
+    const hasClaudeMd = claudeFiles.some((f) => f.kind !== "rule");
     const includedElsewhere = new Set(claudeFiles.flatMap((f) => [f.realPath ?? f.path, ...f.imports.map((i) => i.resolved)]));
     for (const file of agentsFiles) {
-        if (mode === "managed-only" || mode === "claude-md")
-            skip(file, skippedByMode);
+        if (!agentsMdLoads(mode, false))
+            skip(file, skippedByMode(mode));
         else if (includedElsewhere.has(file.realPath ?? file.path))
             skip(file, "Already included through a CLAUDE.md import or symlink");
+        else if (!agentsMdLoads(mode, hasClaudeMd))
+            skip(file, "Ignored: a CLAUDE.md or CLAUDE.local.md exists here or above, so Claude Code reads that instead");
         else if (mode === "claude-md-and-agents-md")
             file.reason = "Loaded alongside CLAUDE.md (instruction mode claude-md-and-agents-md)";
-        else if (hasClaudeMd)
-            skip(file, "Ignored: a CLAUDE.md or CLAUDE.local.md exists here or above, so Claude Code reads that instead");
         else
             file.reason = "Loaded because there is no CLAUDE.md here or above";
     }
-    for (const dir of ancestorsRootFirst(cwd))
-        out.push(...claudeFiles.filter((f) => f.dir === dir), ...agentsFiles.filter((f) => f.dir === dir));
+}
+/**
+ * Skips what Claude Code leaves out of every file but managed ones: all of them in managed-only
+ * mode, ones matched by claudeMdExcludes, ones over 4 MiB, and project rules linked from outside
+ * the project that do not qualify.
+ */
+function applyLoadRules(out, ctx, mode, excludes, externalImports) {
     const waiting = externalImports === "declined"
         ? "You declined imports from outside this project"
         : "Waits for you to approve imports from outside this project";
@@ -135,28 +204,27 @@ export async function resolveInstructions(options) {
         if (file.scope === "managed")
             continue;
         // Path-scoped rules still load on demand in managed-only mode (docs: memory#choose-which-instruction-files-load).
-        if (managedOnly && file.status === "loaded")
-            skip(file, skippedByMode);
-        // Managed files cannot be excluded; a linked file is excluded by its own path or its target's
-        // (docs: memory#exclude-specific-claude-md-files).
-        const excluded = excludes.some((glob) => [file.path, file.realPath].some((p) => p !== undefined && safeMatch(p, glob)));
-        if (excluded)
+        if (mode === "managed-only" && file.status === "loaded")
+            skip(file, skippedByMode(mode));
+        // Managed files cannot be excluded.
+        if (isExcluded(excludes, file.path, file.realPath))
             skip(file, "Skipped by claudeMdExcludes");
         if (file.status !== "skipped" && file.bytes > MAX_TEXT_BYTES)
             skip(file, "Skipped: Claude Code does not load an instruction file over 4 MiB");
         // A project's links outside it need your approval, like its imports; your own files do not.
         if (file.scope !== "project" && file.scope !== "local")
             continue;
-        if (file.kind === "rule" && file.realPath && !isWithin(ctx.realCwd, file.realPath)) {
-            if (!ctx.approved)
-                skip(file, `${waiting}; this rule links outside it`);
-            // docs: memory#share-rules-across-projects-with-symlinks
-            else if (file.paths)
-                skip(file, "Links outside this project, and such a rule loads only without a paths field");
-        }
+        if (file.kind !== "rule")
+            continue;
+        const block = linkedRuleBlock(file.realPath, ctx.realCwd, ctx.approved, file.paths !== undefined);
+        if (block === "needs-approval")
+            skip(file, `${waiting}; this rule links outside it`);
+        else if (block === "has-paths")
+            skip(file, "Links outside this project, and such a rule loads only without a paths field");
     }
-    addChecks(out);
-    return out;
+}
+function skippedByMode(mode) {
+    return `Skipped: instruction mode is ${mode}`;
 }
 function skip(file, reason) {
     if (file.status === "skipped")
@@ -165,7 +233,7 @@ function skip(file, reason) {
     file.reason = reason;
 }
 /** An invalid pattern matches nothing. */
-function safeMatch(path, glob) {
+export function safeMatch(path, glob) {
     try {
         return matchesGlob(path, glob);
     }
@@ -213,9 +281,9 @@ async function rule(file, scope, dir, ctx) {
         entry.status = "on-match";
     }
     // A rule reached through a linked folder is not a link itself, but its target can be outside.
-    const real = await resolvedPath(file.path);
-    if (!entry.realPath && !isWithin(ctx.realCwd, real) && !isWithin(await resolvedPath(dir), real))
-        entry.realPath = real;
+    const target = await ruleTarget(file, dir, ctx.realCwd);
+    if (target)
+        entry.realPath = target;
     return entry;
 }
 async function instruction(file, kind, scope, dir, ctx, reason) {
@@ -248,7 +316,7 @@ async function collectImports(file, ctx, readExternal) {
                 continue;
             seen.add(real);
             const external = !isWithin(ctx.realCwd, real);
-            const imported = !external || readExternal ? await readTextFile(ctx.env, target) : null;
+            const imported = !external || readExternal ? await readTextFile(ctx.env, target, ctx.problems) : null;
             const ref = {
                 raw,
                 resolved: real,