clank-cli 0.1.72 → 0.1.74

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clank-cli",
   "description": "Keep AI files in a separate overlay repository",
-  "version": "0.1.72",
+  "version": "0.1.74",
   "author": "",
   "type": "module",
   "bin": {

package/src/AgentFiles.ts

@@ -1,7 +1,7 @@
 import { join } from "node:path";
 
 /** Base agent directory names (without leading dot) */
-export const agentDirNames = ["claude", "gemini"];
+export const agentDirNames = ["claude", "gemini", "codex"];
 
 /** Agent directories as they appear in target (with leading dot) */
 export const managedAgentDirs = agentDirNames.map((d) => `.${d}`);

package/src/Cli.ts

@@ -36,6 +36,8 @@ Clank Overlay Directory Structure
         │   ├── settings.json    # -> .claude/settings.json
         │   ├── commands/        # -> .claude/commands/
         │   └── agents/          # -> .claude/agents/
+        ├── codex/               # Codex specific
+        │   └── config.toml      # -> .codex/config.toml
         ├── <subdir>/clank/      # Subdirectory files (monorepo support)
         │   └── notes.md         # -> <subdir>/clank/notes.md
         └── worktrees/
@@ -51,6 +53,7 @@ Mapping Rules
   global/claude/commands/<file>       -> .claude/commands/<file>
   targets/<proj>/clank/<file>         -> clank/<file>
   targets/<proj>/claude/commands/     -> .claude/commands/
+  targets/<proj>/codex/config.toml    -> .codex/config.toml
   targets/<proj>/agents.md            -> CLAUDE.md, AGENTS.md, GEMINI.md
   targets/<proj>/<sub>/clank/<file>   -> <sub>/clank/<file>
   targets/<proj>/worktrees/<br>/clank -> clank/
@@ -84,31 +87,9 @@ export async function runCLI(): Promise<void> {
 }
 
 function registerCommands(program: Command): void {
-  registerCoreCommands(program);
-  registerHelpCommands(program);
-}
-
-function registerCoreCommands(program: Command): void {
   registerOverlayCommands(program);
   registerUtilityCommands(program);
-}
-
-function registerHelpCommands(program: Command): void {
-  const help = program
-    .command("help")
-    .description("Show help information")
-    .argument("[command]", "Command to show help for")
-    .action((commandName?: string) => {
-      if (!commandName) return program.help();
-      const subcommand = program.commands.find((c) => c.name() === commandName);
-      if (subcommand) return subcommand.help();
-      console.error(`Unknown command: ${commandName}`);
-      process.exit(1);
-    });
-  help
-    .command("structure")
-    .description("Show overlay directory structure")
-    .action(() => console.log(structureHelp));
+  registerHelpCommands(program);
 }
 
 function registerOverlayCommands(program: Command): void {
@@ -163,6 +144,7 @@ function registerUtilityCommands(program: Command): void {
     .command("check")
     .alias("status")
     .description("Show overlay status and check for issues")
+    .option("--prompt", "Print the agent fix prompt for orphaned paths")
     .action(withErrorHandling(checkCommand));
 
   registerFilesCommand(program);
@@ -175,6 +157,24 @@ function registerUtilityCommands(program: Command): void {
     .action(withErrorHandling(vscodeCommand));
 }
 
+function registerHelpCommands(program: Command): void {
+  const help = program
+    .command("help")
+    .description("Show help information")
+    .argument("[command]", "Command to show help for")
+    .action((commandName?: string) => {
+      if (!commandName) return program.help();
+      const subcommand = program.commands.find((c) => c.name() === commandName);
+      if (subcommand) return subcommand.help();
+      console.error(`Unknown command: ${commandName}`);
+      process.exit(1);
+    });
+  help
+    .command("structure")
+    .description("Show overlay directory structure")
+    .action(() => console.log(structureHelp));
+}
+
 function withErrorHandling<T extends unknown[]>(
   fn: (...args: T) => Promise<void>,
 ): (...args: T) => Promise<void> {

package/src/FsUtil.ts

@@ -178,6 +178,16 @@ export async function isSymlink(filePath: string): Promise<boolean> {
   }
 }
 
+/** Check if a path is a real (non-symlink) file tracked by git */
+export async function isTrackedRealFile(
+  filePath: string,
+  repoRoot: string,
+): Promise<boolean> {
+  if (!(await fileExists(filePath))) return false;
+  if (await isSymlink(filePath)) return false;
+  return isTrackedByGit(filePath, repoRoot);
+}
+
 /** Get path relative to cwd, or "." if same directory */
 export function relativePath(cwd: string, path: string): string {
   return relative(cwd, path) || ".";

package/src/Mapper.ts

@@ -292,14 +292,14 @@ function encodeTargetPath(relPath: string, overlayBase: string): string {
   if (basename(relPath) === "agents.md") {
     return join(overlayBase, relPath);
   }
-  // .claude/prompts/ and .gemini/prompts/ → prompts/ in overlay (agent-agnostic)
+  // <agentDir>/prompts/ (.claude/, .gemini/, .codex/) → prompts/ in overlay (agent-agnostic)
   for (const agentDir of managedAgentDirs) {
     const prefix = `${agentDir}/prompts/`;
     if (relPath.startsWith(prefix)) {
       return join(overlayBase, "prompts", relPath.slice(prefix.length));
     }
   }
-  // .claude/* and .gemini/* → claude/*, gemini/* in overlay (agent-specific)
+  // .claude/*, .gemini/*, .codex/* → claude/*, gemini/*, codex/* in overlay (agent-specific)
   for (const agentDir of managedAgentDirs) {
     if (relPath.startsWith(`${agentDir}/`)) {
       const subPath = relPath.slice(agentDir.length + 1);
@@ -314,12 +314,12 @@ function encodeTargetPath(relPath: string, overlayBase: string): string {
   return join(overlayBase, "clank", relPath);
 }
 
-/** Check if path starts with a managed agent dir (.claude/, .gemini/) */
+/** Check if path starts with a managed agent dir (.claude/, .gemini/, .codex/) */
 function startsWithAgentDir(path: string): boolean {
   return managedAgentDirs.some((dir) => path.startsWith(`${dir}/`));
 }
 
-/** Check if path is inside a managed agent dir (.claude/, .gemini/) */
+/** Check if path is inside a managed agent dir (.claude/, .gemini/, .codex/) */
 function isInsideAgentDir(relPath: string): boolean {
   return managedAgentDirs.some(
     (dir) => relPath.startsWith(`${dir}/`) || relPath === dir,
@@ -346,7 +346,7 @@ function decodeOverlayPath(
     };
   }
 
-  // claude/, gemini/ files → map to .claude/, .gemini/ in target
+  // claude/, gemini/, codex/ files → map to .claude/, .gemini/, .codex/ in target
   for (const agentDir of managedAgentDirs) {
     const overlayDir = agentDir.slice(1); // "claude" or "gemini"
     if (relPath.startsWith(`${overlayDir}/`)) {

package/src/OverlayLinks.ts

@@ -59,7 +59,7 @@ export async function verifyManaged(
       };
     }
 
-    // Prompt files are fanned out to all agent directories (.claude/prompts/, .gemini/prompts/)
+    // Prompt files are fanned out to all agent directories (.claude/prompts/, .gemini/prompts/, .codex/prompts/)
     // Accept any agent's prompts dir as valid if the filename matches
     if (mapping.targetPath !== linkPath) {
       if (!isMatchingPromptPath(mapping.targetPath, linkPath)) {

package/src/commands/Add.ts

@@ -17,7 +17,7 @@ import {
   getCwd,
   getLinkTarget,
   isSymlink,
-  isTrackedByGit,
+  isTrackedRealFile,
   walkDirectory,
 } from "../FsUtil.ts";
 import { type GitContext, getGitContext } from "../Git.ts";
@@ -48,7 +48,6 @@ interface AddContext {
   overlayRoot: string;
 }
 
-/** Create agent symlinks (CLAUDE.md, GEMINI.md, AGENTS.md → agents.md) */
 interface AgentLinkParams {
   overlayPath: string;
   symlinkDir: string;
@@ -72,6 +71,17 @@ type ScopeCounts = {
   skip: number;
 };
 
+interface CreateSymlinksParams {
+  filePath: string;
+  normalizedPath: string;
+  overlayPath: string;
+  config: { agents: string[] };
+  gitRoot: string;
+  overlayRoot: string;
+  cwd: string;
+  quiet?: boolean;
+}
+
 const scopeLabels: Record<Scope, string> = {
   global: "global",
   project: "project",
@@ -92,17 +102,11 @@ export async function addCommand(
 
   const ctx = { cwd, gitContext, config, overlayRoot };
 
-  if (options.interactive) {
+  if (options.interactive || filePaths.length === 0) {
     await addAllInteractive(ctx);
     return;
   }
 
-  if (filePaths.length === 0) {
-    throw new Error(
-      "No files specified. Use --interactive for interactive mode.",
-    );
-  }
-
   for (const filePath of filePaths) {
     const inputPath = join(cwd, filePath);
 
@@ -137,18 +141,15 @@ async function validateAddOptions(
 /** Interactive mode: add all unadded files with per-file scope selection */
 async function addAllInteractive(ctx: AddContext): Promise<void> {
   const { cwd, gitContext, overlayRoot } = ctx;
-  const context: MapperContext = {
-    overlayRoot,
-    targetRoot: gitContext.gitRoot,
-    gitContext,
-  };
+  const { gitRoot: targetRoot } = gitContext;
+  const context: MapperContext = { overlayRoot, targetRoot, gitContext };
 
   const unadded = await findUnaddedFiles(context);
   const regularFiles = unadded.filter((f) => f.kind === "unadded");
 
   // Also find untracked agent files outside managed dirs (e.g. packages/foo/CLAUDE.md)
   const agentClassification = await classifyAgentFiles(
-    gitContext.gitRoot,
+    targetRoot,
     overlayRoot,
     gitContext,
   );
@@ -200,7 +201,6 @@ async function addSingleFile(
   const { quiet } = options;
 
   const scope = resolveScopeFromOptions(options);
-  /** Absolute path where symlink will be created in target repo */
   const normalizedPath = normalizeAddPath(filePath, cwd, gitRoot);
   const context: MapperContext = {
     overlayRoot,
@@ -216,7 +216,6 @@ async function addSingleFile(
   // Only check barePath for symlink - we want the user's input file, not clank/foo.md
   const barePath = join(cwd, filePath);
 
-  // Check if already in overlay at a different scope
   await checkScopeConflict(barePath, scope, context, cwd);
 
   if (await fileExists(overlayPath)) {
@@ -246,53 +245,6 @@ async function addSingleFile(
   });
 }
 
-interface CreateSymlinksParams {
-  filePath: string;
-  normalizedPath: string;
-  overlayPath: string;
-  config: { agents: string[] };
-  gitRoot: string;
-  overlayRoot: string;
-  cwd: string;
-  quiet?: boolean;
-}
-
-/** Create symlinks based on file type (agent, prompt, or regular) */
-async function createSymlinksForFile(params: CreateSymlinksParams) {
-  const {
-    filePath,
-    normalizedPath,
-    overlayPath,
-    config,
-    gitRoot,
-    overlayRoot,
-    cwd,
-    quiet,
-  } = params;
-
-  if (isAgentFile(filePath)) {
-    const symlinkDir = dirname(normalizedPath);
-    await createAgentLinks({
-      overlayPath,
-      symlinkDir,
-      gitRoot,
-      overlayRoot,
-      agents: config.agents,
-      quiet,
-    });
-  } else if (isPromptFile(normalizedPath)) {
-    await handlePromptFile(normalizedPath, overlayPath, gitRoot, cwd, quiet);
-  } else {
-    await handleRegularFile(
-      normalizedPath,
-      overlayPath,
-      overlayRoot,
-      cwd,
-      quiet,
-    );
-  }
-}
-
 /** Prompt for scope and add a single file. Returns the choice or "error". */
 async function promptAndAddFile(
   relPath: string,
@@ -332,7 +284,7 @@ async function promptAndAddFile(
 }
 
 /** Print summary of interactive add results */
-function printSummary(counts: Record<string, number>): void {
+function printSummary(counts: ScopeCounts): void {
   const parts: string[] = [];
   if (counts.project > 0) parts.push(`${counts.project} to project`);
   if (counts.worktree > 0) parts.push(`${counts.worktree} to worktree`);
@@ -398,6 +350,87 @@ async function addFileToOverlay(
   }
 }
 
+/** Create symlinks based on file type (agent, prompt, or regular) */
+async function createSymlinksForFile(params: CreateSymlinksParams) {
+  const { filePath, normalizedPath, overlayPath, config } = params;
+  const { gitRoot, overlayRoot, cwd, quiet } = params;
+
+  if (isAgentFile(filePath)) {
+    const symlinkDir = dirname(normalizedPath);
+    await createAgentLinks({
+      overlayPath,
+      symlinkDir,
+      gitRoot,
+      overlayRoot,
+      agents: config.agents,
+      quiet,
+    });
+  } else if (isPromptFile(normalizedPath)) {
+    await handlePromptFile(normalizedPath, overlayPath, gitRoot, cwd, quiet);
+  } else {
+    await handleRegularFile(
+      normalizedPath,
+      overlayPath,
+      overlayRoot,
+      cwd,
+      quiet,
+    );
+  }
+}
+
+/** Read a single keypress for scope selection */
+async function readScopeChoice(
+  isWorktree: boolean,
+): Promise<InteractiveChoice> {
+  const key = await readSingleKey();
+
+  switch (key.toLowerCase()) {
+    case "p":
+    case "\r":
+    case "\n":
+      console.log("project");
+      return "project";
+    case "w":
+      if (!isWorktree) {
+        console.log("(not in worktree, using project)");
+        return "project";
+      }
+      console.log("worktree");
+      return "worktree";
+    case "g":
+      console.log("global");
+      return "global";
+    case "s":
+      console.log("skip");
+      return "skip";
+    case "q":
+    case "\x03": // Ctrl+C
+      return "quit";
+    default:
+      console.log("project");
+      return "project";
+  }
+}
+
+/** Find content from normalized path or bare input path */
+async function findSourceContent(
+  normalizedPath: string,
+  barePath: string,
+): Promise<string> {
+  // Try normalized path first (e.g., cwd/clank/foo.md)
+  if (
+    (await fileExists(normalizedPath)) &&
+    !(await isSymlink(normalizedPath))
+  ) {
+    return await readFile(normalizedPath, "utf-8");
+  }
+  // Fall back to bare input path (e.g., cwd/foo.md)
+  if ((await fileExists(barePath)) && !(await isSymlink(barePath))) {
+    return await readFile(barePath, "utf-8");
+  }
+  return "";
+}
+
 async function createAgentLinks(p: AgentLinkParams): Promise<void> {
   const { overlayPath, quiet, ...classifyParams } = p;
   const { toCreate, existing, skipped } =
@@ -441,9 +474,8 @@ async function handlePromptFile(
       gitRoot,
     );
     if (!quiet && created.length) {
-      console.log(
-        `Created symlinks: ${created.map((p) => relative(cwd, p)).join(", ")}`,
-      );
+      const names = created.map((p) => relative(cwd, p)).join(", ");
+      console.log(`Created symlinks: ${names}`);
     }
   }
 }
@@ -467,57 +499,27 @@ async function handleRegularFile(
   }
 }
 
-/** Read a single keypress for scope selection */
-async function readScopeChoice(
-  isWorktree: boolean,
-): Promise<InteractiveChoice> {
-  const key = await readSingleKey();
+/** Read a single keypress from stdin (raw mode) */
+function readSingleKey(): Promise<string> {
+  return new Promise((resolve) => {
+    const wasRaw = process.stdin.isRaw;
+    if (process.stdin.isTTY) {
+      readline.emitKeypressEvents(process.stdin);
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
 
-  switch (key.toLowerCase()) {
-    case "p":
-    case "\r":
-    case "\n":
-      console.log("project");
-      return "project";
-    case "w":
-      if (!isWorktree) {
-        console.log("(not in worktree, using project)");
-        return "project";
+    const onKeypress = (data: Buffer): void => {
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(wasRaw ?? false);
       }
-      console.log("worktree");
-      return "worktree";
-    case "g":
-      console.log("global");
-      return "global";
-    case "s":
-      console.log("skip");
-      return "skip";
-    case "q":
-    case "\x03": // Ctrl+C
-      return "quit";
-    default:
-      console.log("project");
-      return "project";
-  }
-}
+      process.stdin.pause();
+      process.stdin.removeListener("data", onKeypress);
+      resolve(data.toString());
+    };
 
-/** Find content from normalized path or bare input path */
-async function findSourceContent(
-  normalizedPath: string,
-  barePath: string,
-): Promise<string> {
-  // Try normalized path first (e.g., cwd/clank/foo.md)
-  if (
-    (await fileExists(normalizedPath)) &&
-    !(await isSymlink(normalizedPath))
-  ) {
-    return await readFile(normalizedPath, "utf-8");
-  }
-  // Fall back to bare input path (e.g., cwd/foo.md)
-  if ((await fileExists(barePath)) && !(await isSymlink(barePath))) {
-    return await readFile(barePath, "utf-8");
-  }
-  return "";
+    process.stdin.once("data", onKeypress);
+  });
 }
 
 /** Classify which agent symlinks to create vs skip */
@@ -530,18 +532,12 @@ async function classifyAgentLinks(
   const toCreate: { targetPath: string; name: string }[] = [];
 
   await forEachAgentPath(symlinkDir, agents, async (targetPath) => {
-    // Check if symlink already points to overlay
     if (await isSymlinkToOverlay(targetPath, overlayRoot)) {
       existing.push(basename(targetPath));
       return;
     }
 
-    const isTrackedFile =
-      (await fileExists(targetPath)) &&
-      !(await isSymlink(targetPath)) &&
-      (await isTrackedByGit(targetPath, gitRoot));
-
-    if (isTrackedFile) {
+    if (await isTrackedRealFile(targetPath, gitRoot)) {
       skipped.push(basename(targetPath));
     } else {
       toCreate.push({ targetPath, name: basename(targetPath) });
@@ -550,26 +546,3 @@ async function classifyAgentLinks(
 
   return { toCreate, existing, skipped };
 }
-
-/** Read a single keypress from stdin (raw mode) */
-function readSingleKey(): Promise<string> {
-  return new Promise((resolve) => {
-    const wasRaw = process.stdin.isRaw;
-    if (process.stdin.isTTY) {
-      readline.emitKeypressEvents(process.stdin);
-      process.stdin.setRawMode(true);
-    }
-    process.stdin.resume();
-
-    const onKeypress = (data: Buffer): void => {
-      if (process.stdin.isTTY) {
-        process.stdin.setRawMode(wasRaw ?? false);
-      }
-      process.stdin.pause();
-      process.stdin.removeListener("data", onKeypress);
-      resolve(data.toString());
-    };
-
-    process.stdin.once("data", onKeypress);
-  });
-}

package/src/commands/Check.ts

@@ -35,11 +35,18 @@ export type UnaddedFile = ManagedFileState & {
   relativePath: string;
 };
 
+export interface CheckOptions {
+  prompt?: boolean;
+}
+
 /** Files that should remain local and not be tracked by clank */
 const localOnlyFiles = ["settings.local.json"];
 
+/** Switch to a one-line summary when a category has at least this many files */
+const compactThreshold = 5;
+
 /** Check for orphaned overlay paths that don't match target structure */
-export async function checkCommand(): Promise<void> {
+export async function checkCommand(options: CheckOptions = {}): Promise<void> {
   const cwd = await getCwd();
   const gitContext = await getGitContext(cwd);
   const config = await loadConfig();
@@ -50,7 +57,7 @@ export async function checkCommand(): Promise<void> {
 
   await showOverlayStatus(overlayRoot, ignorePatterns);
 
-  const problems = await checkAllProblems(ctx, cwd, ignorePatterns);
+  const problems = await checkAllProblems(ctx, cwd, ignorePatterns, options);
   if (!problems) {
     console.log("No issues found. Overlay matches target structure.");
   }
@@ -98,13 +105,8 @@ export async function findOrphans(
   const isIgnored =
     ignorePatterns.length > 0 ? picomatch(ignorePatterns) : null;
 
-  const skip = (relPath: string): boolean => {
-    if (isIgnored) {
-      const pathBasename = basename(relPath);
-      if (isIgnored(relPath) || isIgnored(pathBasename)) return true;
-    }
-    return false;
-  };
+  const skip = (relPath: string): boolean =>
+    !!isIgnored && (isIgnored(relPath) || isIgnored(basename(relPath)));
 
   for await (const { path, isDirectory } of walkDirectory(projectDir, {
     skipDirs: [".git", "node_modules", "worktrees"],
@@ -122,7 +124,6 @@ export async function findOrphans(
       continue;
     }
 
-    // This is a subdirectory file - check if target dir exists
     // e.g., tools/packages/wesl/clank/notes.md -> check tools/packages/wesl/
     const targetSubdir = extractTargetSubdir(relPath);
     if (!targetSubdir) continue;
@@ -173,6 +174,7 @@ async function checkAllProblems(
   ctx: MapperContext,
   cwd: string,
   ignorePatterns: string[] = [],
+  options: CheckOptions = {},
 ): Promise<boolean> {
   const { overlayRoot, targetRoot, gitContext } = ctx;
   let hasProblems = false;
@@ -202,7 +204,7 @@ async function checkAllProblems(
   );
   if (orphans.length > 0) {
     hasProblems = true;
-    showOrphanedPaths(orphans, targetRoot, overlayRoot);
+    showOrphanedPaths(orphans, targetRoot, overlayRoot, options);
   }
 
   return hasProblems;
@@ -227,12 +229,10 @@ function isLocalOnlyFile(relPath: string): boolean {
  * @example "tools/packages/wesl/agents.md" -> "tools/packages/wesl"
  */
 function extractTargetSubdir(relPath: string): string | null {
-  // Check for /clank/ or /claude/ in path
   for (const dir of managedDirs) {
     const idx = relPath.indexOf(`/${dir}/`);
     if (idx !== -1) return relPath.slice(0, idx);
   }
-  // Check for agents.md in a subdirectory
   if (relPath.endsWith("/agents.md")) {
     return relPath.slice(0, -"/agents.md".length);
   }
@@ -250,49 +250,27 @@ function showUnaddedFiles(
     ? `${projectName}/${worktreeName}`
     : projectName;
 
-  const outsideOverlay = unadded.filter((f) => f.kind === "outside-overlay");
-  const wrongMapping = unadded.filter((f) => f.kind === "wrong-mapping");
+  const outsideOverlay = unadded.filter(
+    (
+      f,
+    ): f is UnaddedFile & { kind: "outside-overlay"; currentTarget: string } =>
+      f.kind === "outside-overlay",
+  );
+  const wrongMapping = unadded.filter(
+    (
+      f,
+    ): f is UnaddedFile & {
+      kind: "wrong-mapping";
+      currentTarget: string;
+      expectedTarget: string;
+    } => f.kind === "wrong-mapping",
+  );
   const regularFiles = unadded.filter((f) => f.kind === "unadded");
 
-  if (outsideOverlay.length > 0) {
-    console.log(
-      `Found ${outsideOverlay.length} stale symlink(s) in ${targetName}:\n`,
-    );
-    console.log("These symlinks point outside the clank overlay.");
-    console.log("Remove them manually, then run `clank link` to recreate:\n");
-    for (const file of outsideOverlay) {
-      console.log(`  rm ${relativePath(cwd, file.targetPath)}`);
-    }
-    console.log();
-  }
-
-  if (wrongMapping.length > 0) {
-    console.log(
-      `Found ${wrongMapping.length} mislinked symlink(s) in ${targetName}:\n`,
-    );
-    console.log("These symlinks point to the wrong overlay location.");
-    console.log("Run `clank link` to fix them.\n");
-    for (const file of wrongMapping) {
-      console.log(`  ${relativePath(cwd, file.targetPath)}`);
-      if (file.currentTarget) {
-        console.log(`    points to: ${file.currentTarget}`);
-      }
-    }
-    console.log();
-  }
-
-  if (regularFiles.length > 0) {
-    console.log(
-      `Found ${regularFiles.length} unadded file(s) in ${targetName}:\n`,
-    );
-    for (const file of regularFiles) {
-      console.log(`  ${relativePath(cwd, file.targetPath)}`);
-    }
-    console.log();
-    console.log("  clank add -i                  # add interactively");
-    console.log("  clank add <file> [<file>...]  # add specific files");
-    console.log();
-  }
+  if (outsideOverlay.length > 0)
+    showOutsideOverlay(outsideOverlay, cwd, targetName);
+  if (wrongMapping.length > 0) showWrongMapping(wrongMapping, cwd, targetName);
+  if (regularFiles.length > 0) showUnadded(regularFiles, cwd, targetName);
 }
 
 /** Display orphaned paths and remediation prompt */
@@ -300,12 +278,26 @@ function showOrphanedPaths(
   orphans: OrphanedPath[],
   targetRoot: string,
   overlayRoot: string,
+  options: CheckOptions = {},
 ): void {
-  console.log(`Found ${orphans.length} orphaned overlay path(s):\n`);
-  for (const orphan of orphans) {
-    console.log(`  ${orphan.fileName} (${orphan.scope})`);
-    console.log(`    Overlay: ${orphan.overlayPath}`);
-    console.log(`    Expected dir: ${orphan.expectedTargetDir}\n`);
+  const compact = orphans.length >= compactThreshold;
+
+  if (compact) {
+    const names = orphans.map((o) => `${o.expectedTargetDir}/${o.fileName}`);
+    console.log(`Found ${orphans.length} orphaned overlay path(s):`);
+    console.log(`  ${formatInlineList(names)}\n`);
+  } else {
+    console.log(`Found ${orphans.length} orphaned overlay path(s):\n`);
+    for (const orphan of orphans) {
+      console.log(`  ${orphan.fileName} (${orphan.scope})`);
+      console.log(`    Overlay: ${orphan.overlayPath}`);
+      console.log(`    Expected dir: ${orphan.expectedTargetDir}\n`);
+    }
+  }
+
+  if (compact && !options.prompt) {
+    console.log("Run `clank status --prompt` for an agent fix prompt.");
+    return;
   }
 
   console.log("Target project:", targetRoot);
@@ -316,6 +308,85 @@ function showOrphanedPaths(
   console.log("─".repeat(50));
 }
 
+function showOutsideOverlay(
+  items: (UnaddedFile & { currentTarget: string })[],
+  cwd: string,
+  targetName: string,
+): void {
+  console.log(`Found ${items.length} stale symlink(s) in ${targetName}:\n`);
+  console.log("These symlinks point outside the clank overlay.");
+  console.log("Remove them manually, then run `clank link` to recreate:\n");
+  for (const file of items) {
+    console.log(`  rm ${relativePath(cwd, file.targetPath)}`);
+  }
+  console.log();
+}
+
+function showWrongMapping(
+  items: (UnaddedFile & { currentTarget: string })[],
+  cwd: string,
+  targetName: string,
+): void {
+  if (items.length >= compactThreshold) {
+    const names = items.map((f) => relativePath(cwd, f.targetPath));
+    console.log(
+      `Found ${items.length} mislinked symlink(s) in ${targetName} — run \`clank link\` to fix:`,
+    );
+    console.log(`  ${formatInlineList(names)}\n`);
+    return;
+  }
+  console.log(`Found ${items.length} mislinked symlink(s) in ${targetName}:\n`);
+  console.log("These symlinks point to the wrong overlay location.");
+  console.log("Run `clank link` to fix them.\n");
+  for (const file of items) {
+    console.log(`  ${relativePath(cwd, file.targetPath)}`);
+    if (file.currentTarget) {
+      console.log(`    points to: ${file.currentTarget}`);
+    }
+  }
+  console.log();
+}
+
+function showUnadded(
+  items: UnaddedFile[],
+  cwd: string,
+  targetName: string,
+): void {
+  if (items.length >= compactThreshold) {
+    const names = items.map((f) => relativePath(cwd, f.targetPath));
+    console.log(
+      `Found ${items.length} unadded file(s) in ${targetName} — run \`clank add\` to add:`,
+    );
+    console.log(`  ${formatInlineList(names)}\n`);
+    return;
+  }
+  console.log(`Found ${items.length} unadded file(s) in ${targetName}:\n`);
+  for (const file of items) {
+    console.log(`  ${relativePath(cwd, file.targetPath)}`);
+  }
+  console.log();
+  console.log("  clank add                     # add interactively");
+  console.log("  clank add <file> [<file>...]  # add specific files");
+  console.log();
+}
+
+/** Join names with spaces up to maxChars, then append "(+N more)" if truncated */
+function formatInlineList(names: string[], maxChars = 80): string {
+  const parts: string[] = [];
+  let used = 0;
+  for (let i = 0; i < names.length; i++) {
+    const next = names[i];
+    const sep = parts.length === 0 ? 0 : 1;
+    if (parts.length > 0 && used + sep + next.length > maxChars) {
+      parts.push(`(+${names.length - i} more)`);
+      break;
+    }
+    parts.push(next);
+    used += sep + next.length;
+  }
+  return parts.join(" ");
+}
+
 /** Generate agent prompt for fixing orphaned paths */
 function generateAgentPrompt(
   orphans: OrphanedPath[],

package/src/commands/Link.ts

@@ -21,7 +21,7 @@ import {
   getCwd,
   getLinkTarget,
   isSymlink,
-  isTrackedByGit,
+  isTrackedRealFile,
   toSlash,
 } from "../FsUtil.ts";
 import { type GitContext, getGitContext } from "../Git.ts";
@@ -134,27 +134,6 @@ async function cleanStaleAndCheck(
   }
 }
 
-/** Consolidate rules into generated AGENTS.md/GEMINI.md if rules exist */
-async function maybeConsolidateRules(
-  overlayRoot: string,
-  targetRoot: string,
-  gitContext: GitContext,
-  config: ClankConfig,
-): Promise<void> {
-  const consolidated = await consolidateRulesIntoAgentFiles({
-    overlayRoot,
-    targetRoot,
-    gitContext,
-    agents: config.agents,
-  });
-  if (consolidated.length > 0) {
-    console.log(`\nGenerated consolidated agent files:`);
-    for (const name of consolidated) {
-      console.log(`  ${name}`);
-    }
-  }
-}
-
 async function maybeInitWorktree(
   overlayRoot: string,
   gitContext: GitContext,
@@ -258,7 +237,7 @@ async function createAgentLinks(
   }
 }
 
-/** Create prompt symlinks in all agent directories (.claude/prompts/, .gemini/prompts/) */
+/** Create prompt symlinks in all agent directories (.claude/prompts/, .gemini/prompts/, .codex/prompts/) */
 async function createPromptLinks(
   promptsMappings: FileMapping[],
   targetRoot: string,
@@ -278,6 +257,27 @@ async function createPromptLinks(
   }
 }
 
+/** Consolidate rules into generated AGENTS.md/GEMINI.md if rules exist */
+async function maybeConsolidateRules(
+  overlayRoot: string,
+  targetRoot: string,
+  gitContext: GitContext,
+  config: ClankConfig,
+): Promise<void> {
+  const consolidated = await consolidateRulesIntoAgentFiles({
+    overlayRoot,
+    targetRoot,
+    gitContext,
+    agents: config.agents,
+  });
+  if (consolidated.length > 0) {
+    console.log(`\nGenerated consolidated agent files:`);
+    for (const name of consolidated) {
+      console.log(`  ${name}`);
+    }
+  }
+}
+
 /** Setup project settings.json - adopt existing or create new */
 async function setupProjectSettings(
   overlayRoot: string,
@@ -432,7 +432,7 @@ async function processAgentMapping(
   const skipped: string[] = [];
 
   await forEachAgentPath(targetDir, agents, async (agentPath) => {
-    if (await isTrackedFile(agentPath, targetRoot)) {
+    if (await isTrackedRealFile(agentPath, targetRoot)) {
       skipped.push(relative(targetRoot, agentPath));
     } else {
       const linkTarget = getLinkTarget(agentPath, overlayPath);
@@ -495,10 +495,3 @@ async function checkMappingParentExists(
   }
   return m;
 }
-
-/** Check if a file is tracked in git (exists as real file, not symlink, and tracked) */
-async function isTrackedFile(path: string, gitRoot: string): Promise<boolean> {
-  if (!(await fileExists(path))) return false;
-  if (await isSymlink(path)) return false;
-  return isTrackedByGit(path, gitRoot);
-}

package/src/commands/files/Scan.ts

@@ -1,4 +1,5 @@
 import { join, relative } from "node:path";
+import { managedAgentDirs } from "../../AgentFiles.ts";
 import { expandPath, loadConfig } from "../../Config.ts";
 import {
   getCwd,
@@ -244,7 +245,7 @@ function passesLinkFilter(
 }
 
 function isInDotAgentDir(relPath: string): boolean {
-  return isInDirectory(relPath, ".claude") || isInDirectory(relPath, ".gemini");
+  return managedAgentDirs.some((dir) => isInDirectory(relPath, dir));
 }
 
 /** Enforce a max segment count beneath the nearest `clank/` path component. */