clank-cli 0.1.62 → 0.1.66

package/README.md

@@ -84,6 +84,9 @@ clank link ~/my-project # Link to specific project
 
 Move a file to the overlay and replace it with a symlink. If the file doesn't exist, an empty file is created. Accepts [scope options](#scope-options).
 
+**Options:**
+- `-i, --interactive` - Interactively add all unadded files, prompting for scope on each
+
 **Examples:**
 ```bash
 clank add style.md                            # Project scope (default)
@@ -92,6 +95,24 @@ clank add notes.md --worktree                 # Worktree scope
 clank add .claude/commands/review.md --global # Global command
 clank add .claude/commands/build.md           # Project command (default)
 clank add CLAUDE.md                           # Creates agents.md + agent symlinks
+clank add -i                                  # Interactive mode for all unadded files
+```
+
+**Interactive mode:**
+
+Running `clank add --interactive` finds all unadded files and prompts for each:
+
+```
+Found 3 unadded file(s):
+
+[1/3] clank/notes.md
+      (P)roject  (W)orktree  (G)lobal  (S)kip  (Q)uit  [P]:
+```
+
+Press a single key to select the scope (default: Project). The summary shows what was added:
+
+```
+Added 2 to project, 1 skipped
 ```
 
 ### `clank unlink [target]`
@@ -173,10 +194,13 @@ clank rm style.md --global         # Remove global style guide
 
 ### `clank mv <files...>` (alias: `move`)
 
-Move file(s) between overlay scopes. Requires one [scope option](#scope-options) to specify the destination.
+Move or rename file(s) in the overlay. With a [scope option](#scope-options), moves files to that scope. With two arguments and no scope, renames within the current scope.
 
-**Example:**
+**Examples:**
 ```bash
+# Rename a file (keeps same scope)
+clank mv batch-dry-check.md batch-dry.md
+
 # Promote a worktree note to project scope
 clank mv clank/notes.md --project
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clank-cli",
   "description": "Keep AI files in a separate overlay repository",
-  "version": "0.1.62",
+  "version": "0.1.66",
   "author": "",
   "type": "module",
   "bin": {
@@ -46,10 +46,11 @@
   },
   "scripts": {
     "bump": "monobump",
-    "fix": "biome check --fix --unsafe",
+    "fix": "biome check --fix --unsafe --error-on-warnings",
     "fix:pkgJsonFormat": "syncpack format",
     "global": "pnpm link --global",
     "lint": "biome check --error-on-warnings",
+    "prepush": "run-s fix typecheck fix:pkgJsonFormat test:once",
     "test": "vitest",
     "test:once": "vitest run",
     "test:ui": "vitest --ui",

package/src/AgentFiles.ts

@@ -32,8 +32,7 @@ export async function forEachAgentPath(
 ): Promise<void> {
   const agentPaths = getAgentFilePaths(dir);
   for (const agent of agents) {
-    const key = agent.toLowerCase();
-    const agentPath = agentPaths[key];
+    const agentPath = agentPaths[agent.toLowerCase()];
     if (!agentPath) continue;
     await fn(agentPath, agent);
   }

package/src/ClassifyFiles.ts

@@ -61,14 +61,10 @@ export async function classifyAgentFiles(
 }
 
 /** @return true if classification has any problems */
-export function agentFileProblems(
-  classification: AgentFileClassification,
-): boolean {
-  return (
-    classification.tracked.length > 0 ||
-    classification.untracked.length > 0 ||
-    classification.staleSymlinks.length > 0 ||
-    classification.outdatedSymlinks.length > 0
+export function agentFileProblems(c: AgentFileClassification): boolean {
+  const { tracked, untracked, staleSymlinks, outdatedSymlinks } = c;
+  return [tracked, untracked, staleSymlinks, outdatedSymlinks].some(
+    (a) => a.length > 0,
   );
 }
 
@@ -110,10 +106,12 @@ ${commands.join("\n")}`);
   }
 
   if (classified.outdatedSymlinks.length > 0) {
-    const details = classified.outdatedSymlinks.map((s) => {
-      const symlinkRel = rel(s.symlinkPath);
-      return `  ${symlinkRel}\n    points to: ${s.currentTarget}\n    expected:  ${s.expectedTarget}`;
-    });
+    const details = classified.outdatedSymlinks.map(
+      (s) =>
+        `  ${rel(s.symlinkPath)}\n` +
+        `    points to: ${s.currentTarget}\n` +
+        `    expected:  ${s.expectedTarget}`,
+    );
     sections.push(`Found outdated agent symlinks (pointing to wrong overlay path).
 
 This typically happens after a directory rename. Remove symlinks and run \`clank link\`:
@@ -192,15 +190,12 @@ async function classifyAgentSymlink(
     const agentsMdPath = join(dirname(filePath), "agents.md");
     const expectedTarget = targetToOverlay(agentsMdPath, "project", mapperCtx);
     if (absoluteTarget !== expectedTarget) {
-      return {
-        outdatedSymlinks: [
-          {
-            symlinkPath: filePath,
-            currentTarget: absoluteTarget,
-            expectedTarget,
-          },
-        ],
+      const symlink = {
+        symlinkPath: filePath,
+        currentTarget: absoluteTarget,
+        expectedTarget,
       };
+      return { outdatedSymlinks: [symlink] };
     }
   }
 

package/src/Cli.ts

@@ -133,9 +133,10 @@ function registerOverlayCommands(program: Command): void {
     .command("add")
     .description("Add file(s) to overlay and create symlinks")
     .argument(
-      "<files...>",
+      "[files...]",
       "File path(s) (e.g., style.md, .claude/commands/review.md)",
     )
+    .option("-i, --interactive", "Interactively add all unadded files")
     .option("-g, --global", "Add to global location (all projects)")
     .option("-p, --project", "Add to project location (default)")
     .option("-w, --worktree", "Add to worktree location (this branch only)")
@@ -170,6 +171,7 @@ function registerUtilityCommands(program: Command): void {
     .command("vscode")
     .description("Generate VS Code settings to show clank files")
     .option("--remove", "Remove clank-generated VS Code settings")
+    .option("--force", "Generate even if settings.json is tracked by git")
     .action(withErrorHandling(vscodeCommand));
 }
 
@@ -202,7 +204,7 @@ function registerMvCommand(program: Command): void {
   const cmd = program
     .command("mv")
     .alias("move")
-    .description("Move file(s) between overlay scopes")
+    .description("Move or rename file(s) in overlay")
     .argument("<files...>", "File(s) to move");
 
   cmd.addOption(

package/src/Gitignore.ts

@@ -99,24 +99,16 @@ export function isClankPattern(glob: string): boolean {
   const normalized = glob.replace(/^\*\*\//, "").replace(/\/$/, "");
 
   // Check against managed directories
-  for (const dir of targetManagedDirs) {
-    if (
-      normalized === dir ||
-      normalized.startsWith(`${dir}/`) ||
-      normalized.endsWith(`/${dir}`)
-    ) {
-      return true;
-    }
-  }
+  const matchesDir = (dir: string) =>
+    normalized === dir ||
+    normalized.startsWith(`${dir}/`) ||
+    normalized.endsWith(`/${dir}`);
+  if (targetManagedDirs.some(matchesDir)) return true;
 
   // Check against agent files
-  for (const agentFile of agentFiles) {
-    if (normalized === agentFile || normalized.endsWith(`/${agentFile}`)) {
-      return true;
-    }
-  }
-
-  return false;
+  const matchesAgent = (f: string) =>
+    normalized === f || normalized.endsWith(`/${f}`);
+  return agentFiles.some(matchesAgent);
 }
 
 /** Convert collected patterns to VS Code exclude globs, filtering clank patterns */
@@ -143,14 +135,11 @@ export function deduplicateGlobs(globs: string[]): string[] {
   const coveredSuffixes = new Set(universal.map((g) => g.slice(3)));
 
   // Keep specific patterns not covered by a universal pattern
-  const uncovered = specific.filter((glob) => {
-    for (const suffix of coveredSuffixes) {
-      if (glob.endsWith(`/**/${suffix}`) || glob.endsWith(`/${suffix}`)) {
-        return false;
-      }
-    }
-    return true;
-  });
+  const isCovered = (glob: string) =>
+    [...coveredSuffixes].some(
+      (s) => glob.endsWith(`/**/${s}`) || glob.endsWith(`/${s}`),
+    );
+  const uncovered = specific.filter((glob) => !isCovered(glob));
 
   return [...universal, ...uncovered];
 }

package/src/OverlayGit.ts

@@ -54,11 +54,7 @@ function filterIgnoredLines(
     if (isIgnored(filePath) || isIgnored(pathBasename)) return false;
 
     // Check each directory segment (for patterns like ".obsidian")
-    for (const segment of segments) {
-      if (isIgnored(segment)) return false;
-    }
-
-    return true;
+    return !segments.some((segment) => isIgnored(segment));
   });
 }
 
@@ -81,10 +77,8 @@ function parseScopedPath(filePath: string): {
         Math.max(0, afterWorktrees.length - 1),
       );
       const branch = afterWorktrees.slice(0, branchSegments).join("/");
-      return {
-        scope: `${project}/${branch}`,
-        pathParts: afterWorktrees.slice(branchSegments),
-      };
+      const scope = `${project}/${branch}`;
+      return { scope, pathParts: afterWorktrees.slice(branchSegments) };
     }
     return { scope: project || "unknown", pathParts: segments.slice(2) };
   }

package/src/OverlayLinks.ts

@@ -101,14 +101,10 @@ export async function* walkOverlayFiles(
     ignorePatterns.length > 0 ? picomatch(ignorePatterns) : null;
 
   const skip = (relPath: string): boolean => {
-    // Skip templates
-    if (relPath.startsWith("clank/init/")) return true;
-    // Check ignore patterns against relative path and basename
-    if (isIgnored) {
-      const basename = relPath.split("/").at(-1) ?? "";
-      if (isIgnored(relPath) || isIgnored(basename)) return true;
-    }
-    return false;
+    if (relPath.startsWith("clank/init/")) return true; // Skip templates
+    if (!isIgnored) return false;
+    const basename = relPath.split("/").at(-1) ?? "";
+    return isIgnored(relPath) || isIgnored(basename);
   };
 
   const genEntries = walkDirectory(overlayRoot, { skip });
@@ -140,7 +136,6 @@ function isMatchingPromptPath(
   canonicalPath: string,
   actualPath: string,
 ): boolean {
-  const canonicalPrompt = getPromptRelPath(canonicalPath);
-  const actualPrompt = getPromptRelPath(actualPath);
-  return canonicalPrompt !== null && canonicalPrompt === actualPrompt;
+  const canonical = getPromptRelPath(canonicalPath);
+  return canonical !== null && canonical === getPromptRelPath(actualPath);
 }

package/src/commands/Add.ts

@@ -6,6 +6,7 @@ import {
   writeFile,
 } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
+import * as readline from "node:readline";
 import { forEachAgentPath } from "../AgentFiles.ts";
 import { expandPath, loadConfig, validateOverlayExists } from "../Config.ts";
 import {
@@ -31,8 +32,12 @@ import {
 } from "../Mapper.ts";
 import { createPromptLinks, isSymlinkToOverlay } from "../OverlayLinks.ts";
 import { scopeFromSymlink } from "../ScopeFromSymlink.ts";
+import { findUnaddedFiles } from "./Check.ts";
 
-export type AddOptions = ScopeOptions;
+export type AddOptions = ScopeOptions & {
+  interactive?: boolean;
+  quiet?: boolean;
+};
 
 interface AddContext {
   cwd: string;
@@ -48,6 +53,7 @@ interface AgentLinkParams {
   gitRoot: string;
   overlayRoot: string;
   agents: string[];
+  quiet?: boolean;
 }
 
 interface AgentLinkClassification {
@@ -56,6 +62,14 @@ interface AgentLinkClassification {
   skipped: string[];
 }
 
+type InteractiveChoice = "project" | "worktree" | "global" | "skip" | "quit";
+type ScopeCounts = {
+  project: number;
+  worktree: number;
+  global: number;
+  skip: number;
+};
+
 const scopeLabels: Record<Scope, string> = {
   global: "global",
   project: "project",
@@ -76,6 +90,17 @@ export async function addCommand(
 
   const ctx = { cwd, gitContext, config, overlayRoot };
 
+  if (options.interactive) {
+    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);
 
@@ -107,6 +132,38 @@ 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 unadded = await findUnaddedFiles(context);
+  const regularFiles = unadded.filter((f) => f.kind === "unadded");
+
+  if (regularFiles.length === 0) {
+    console.log("No unadded files found.");
+    return;
+  }
+
+  console.log(`Found ${regularFiles.length} unadded file(s):\n`);
+
+  const counts: ScopeCounts = { project: 0, worktree: 0, global: 0, skip: 0 };
+
+  for (let i = 0; i < regularFiles.length; i++) {
+    const file = regularFiles[i];
+    const relPath = relative(cwd, file.targetPath);
+    const result = await promptAndAddFile(relPath, i, regularFiles.length, ctx);
+    if (result === "quit") break;
+    if (result !== "error") counts[result]++;
+  }
+
+  printSummary(counts);
+}
+
 async function isDirectory(path: string): Promise<boolean> {
   try {
     return (await lstat(path)).isDirectory();
@@ -123,6 +180,7 @@ async function addSingleFile(
 ): Promise<void> {
   const { cwd, gitContext, config, overlayRoot } = ctx;
   const { gitRoot } = gitContext;
+  const { quiet } = options;
 
   const scope = resolveScopeFromOptions(options);
   /** Absolute path where symlink will be created in target repo */
@@ -145,23 +203,127 @@ async function addSingleFile(
   await checkScopeConflict(barePath, scope, context, cwd);
 
   if (await fileExists(overlayPath)) {
-    console.log(`${fileName} already exists in ${scopeLabel} overlay`);
+    if (!quiet)
+      console.log(`${fileName} already exists in ${scopeLabel} overlay`);
   } else if (await isSymlink(barePath)) {
-    await addSymlinkToOverlay(barePath, overlayPath, scopeLabel);
+    await addSymlinkToOverlay(barePath, overlayPath, scopeLabel, quiet);
   } else {
-    await addFileToOverlay(normalizedPath, barePath, overlayPath, scopeLabel);
+    await addFileToOverlay(
+      normalizedPath,
+      barePath,
+      overlayPath,
+      scopeLabel,
+      quiet,
+    );
   }
 
-  // Check if this is an agent file (CLAUDE.md, AGENTS.md, GEMINI.md)
+  await createSymlinksForFile({
+    filePath,
+    normalizedPath,
+    overlayPath,
+    config,
+    gitRoot,
+    overlayRoot,
+    cwd,
+    quiet,
+  });
+}
+
+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);
-    const { agents } = config;
-    const params = { overlayPath, symlinkDir, gitRoot, overlayRoot, agents };
-    await createAgentLinks(params);
+    await createAgentLinks({
+      overlayPath,
+      symlinkDir,
+      gitRoot,
+      overlayRoot,
+      agents: config.agents,
+      quiet,
+    });
   } else if (isPromptFile(normalizedPath)) {
-    await handlePromptFile(normalizedPath, overlayPath, gitRoot, cwd);
+    await handlePromptFile(normalizedPath, overlayPath, gitRoot, cwd, quiet);
   } else {
-    await handleRegularFile(normalizedPath, overlayPath, overlayRoot, cwd);
+    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,
+  index: number,
+  total: number,
+  ctx: AddContext,
+): Promise<InteractiveChoice | "error"> {
+  process.stdout.write(`\x1b[1m${relPath}\x1b[0m  [${index + 1}/${total}]\n`);
+  process.stdout.write(
+    "      (P)roject  (W)orktree  (G)lobal  (S)kip  (Q)uit  [P]: ",
+  );
+
+  const choice = await readScopeChoice(ctx.gitContext.isWorktree);
+
+  if (choice === "quit" || choice === "skip") {
+    if (choice === "quit") console.log("\nAborted.");
+    else console.log();
+    return choice;
+  }
+
+  const scopeOptions: AddOptions = {
+    project: choice === "project",
+    worktree: choice === "worktree",
+    global: choice === "global",
+    quiet: true,
+  };
+
+  try {
+    await addSingleFile(relPath, scopeOptions, ctx);
+    console.log();
+    return choice;
+  } catch (error) {
+    console.error(`  Error: ${error instanceof Error ? error.message : error}`);
+    console.log();
+    return "error";
+  }
+}
+
+/** Print summary of interactive add results */
+function printSummary(counts: Record<string, number>): void {
+  const parts: string[] = [];
+  if (counts.project > 0) parts.push(`${counts.project} to project`);
+  if (counts.worktree > 0) parts.push(`${counts.worktree} to worktree`);
+  if (counts.global > 0) parts.push(`${counts.global} to global`);
+  if (counts.skip > 0) parts.push(`${counts.skip} skipped`);
+
+  if (parts.length > 0) {
+    console.log(`Added ${parts.join(", ")}`);
   }
 }
 
@@ -187,11 +349,15 @@ async function addSymlinkToOverlay(
   inputPath: string,
   overlayPath: string,
   scopeLabel: string,
+  quiet?: boolean,
 ): Promise<void> {
   const target = await readlink(inputPath);
   await ensureDir(dirname(overlayPath));
   await symlink(target, overlayPath);
-  console.log(`Copied symlink ${basename(inputPath)} to ${scopeLabel} overlay`);
+  if (!quiet)
+    console.log(
+      `Copied symlink ${basename(inputPath)} to ${scopeLabel} overlay`,
+    );
 }
 
 /** Copy file content to overlay */
@@ -200,20 +366,23 @@ async function addFileToOverlay(
   barePath: string,
   overlayPath: string,
   scopeLabel: string,
+  quiet?: boolean,
 ): Promise<void> {
   await ensureDir(dirname(overlayPath));
   const content = await findSourceContent(normalizedPath, barePath);
   await writeFile(overlayPath, content, "utf-8");
-  const fileName = basename(overlayPath);
-  if (content) {
-    console.log(`Copied ${fileName} to ${scopeLabel} overlay`);
-  } else {
-    console.log(`Created empty ${fileName} in ${scopeLabel} overlay`);
+  if (!quiet) {
+    const fileName = basename(overlayPath);
+    if (content) {
+      console.log(`Copied ${fileName} to ${scopeLabel} overlay`);
+    } else {
+      console.log(`Created empty ${fileName} in ${scopeLabel} overlay`);
+    }
   }
 }
 
 async function createAgentLinks(p: AgentLinkParams): Promise<void> {
-  const { overlayPath, ...classifyParams } = p;
+  const { overlayPath, quiet, ...classifyParams } = p;
   const { toCreate, existing, skipped } =
     await classifyAgentLinks(classifyParams);
 
@@ -223,17 +392,19 @@ async function createAgentLinks(p: AgentLinkParams): Promise<void> {
   });
   await Promise.all(promisedLinks);
 
-  if (toCreate.length) {
-    const created = toCreate.map(({ name }) => name);
-    console.log(`Created symlinks: ${created.join(", ")}`);
-  }
+  if (!quiet) {
+    if (toCreate.length) {
+      const created = toCreate.map(({ name }) => name);
+      console.log(`Created symlinks: ${created.join(", ")}`);
+    }
 
-  if (existing.length) {
-    console.log(`Symlinks already exist: ${existing.join(", ")}`);
-  }
+    if (existing.length) {
+      console.log(`Symlinks already exist: ${existing.join(", ")}`);
+    }
 
-  if (skipped.length) {
-    console.log(`Skipped (already tracked in git): ${skipped.join(", ")}`);
+    if (skipped.length) {
+      console.log(`Skipped (already tracked in git): ${skipped.join(", ")}`);
+    }
   }
 }
 
@@ -243,6 +414,7 @@ async function handlePromptFile(
   overlayPath: string,
   gitRoot: string,
   cwd: string,
+  quiet?: boolean,
 ): Promise<void> {
   const promptRelPath = getPromptRelPath(normalizedPath);
   if (promptRelPath) {
@@ -251,7 +423,7 @@ async function handlePromptFile(
       promptRelPath,
       gitRoot,
     );
-    if (created.length) {
+    if (!quiet && created.length) {
       console.log(
         `Created symlinks: ${created.map((p) => relative(cwd, p)).join(", ")}`,
       );
@@ -265,13 +437,50 @@ async function handleRegularFile(
   overlayPath: string,
   overlayRoot: string,
   cwd: string,
+  quiet?: boolean,
 ): Promise<void> {
   if (await isSymlinkToOverlay(normalizedPath, overlayRoot)) {
-    console.log(`Symlink already exists: ${relative(cwd, normalizedPath)}`);
+    if (!quiet)
+      console.log(`Symlink already exists: ${relative(cwd, normalizedPath)}`);
   } else {
     const linkTarget = getLinkTarget(normalizedPath, overlayPath);
     await createSymlink(linkTarget, normalizedPath);
-    console.log(`Created symlink: ${relative(cwd, normalizedPath)}`);
+    if (!quiet)
+      console.log(`Created symlink: ${relative(cwd, normalizedPath)}`);
+  }
+}
+
+/** 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";
   }
 }
 
@@ -324,3 +533,26 @@ 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/Link.ts

@@ -40,7 +40,11 @@ import {
   isWorktreeInitialized,
 } from "../Templates.ts";
 import { findOrphans } from "./Check.ts";
-import { generateVscodeSettings, isVscodeProject } from "./VsCode.ts";
+import {
+  checkVscodeTracking,
+  generateVscodeSettings,
+  isVscodeProject,
+} from "./VsCode.ts";
 
 interface FileMapping extends TargetMapping {
   overlayPath: string;
@@ -291,6 +295,7 @@ async function maybeGenerateVscodeSettings(
 ): Promise<void> {
   const setting = config.vscodeSettings ?? "auto";
 
+  // User opted out - skip silently
   if (setting === "never") return;
 
   if (setting === "auto") {
@@ -298,7 +303,14 @@ async function maybeGenerateVscodeSettings(
     if (!isVscode) return;
   }
 
-  // setting === "always" or (setting === "auto" && isVscodeProject)
+  // Check if settings.json is tracked and show appropriate warning
+  const check = await checkVscodeTracking(targetRoot);
+  if (!check.canGenerate) {
+    console.log(`\n${check.warning}`);
+    return;
+  }
+
+  // Generate: "always" mode, or "auto" with untracked/layered settings
   console.log("");
   await generateVscodeSettings(targetRoot);
 }

package/src/commands/Move.ts

@@ -2,7 +2,12 @@ import { rename, unlink } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { forEachAgentPath, managedAgentDirs } from "../AgentFiles.ts";
 import { expandPath, loadConfig, validateOverlayExists } from "../Config.ts";
-import { createSymlink, ensureDir, getLinkTarget } from "../FsUtil.ts";
+import {
+  createSymlink,
+  ensureDir,
+  fileExists,
+  getLinkTarget,
+} from "../FsUtil.ts";
 import { getGitContext } from "../Git.ts";
 import {
   getPromptRelPath,
@@ -26,12 +31,12 @@ interface MoveContext {
   agents: string[];
 }
 
-/** Move file(s) between overlay scopes */
+/** Move or rename file(s) in overlay */
 export async function moveCommand(
   filePaths: string[],
   options: MoveOptions,
 ): Promise<void> {
-  const targetScope = resolveScopeFromOptions(options, "require");
+  const hasScope = options.global || options.project || options.worktree;
   const cwd = process.cwd();
   const gitContext = await getGitContext(cwd);
   const config = await loadConfig();
@@ -42,8 +47,23 @@ export async function moveCommand(
   const { gitRoot: targetRoot } = gitContext;
   const context: MapperContext = { overlayRoot, targetRoot, gitContext };
 
-  for (const filePath of filePaths) {
-    await moveSingleFile(filePath, targetScope, context, cwd, config);
+  if (hasScope) {
+    // Scope-move mode (existing behavior)
+    const targetScope = resolveScopeFromOptions(options, "require");
+    for (const filePath of filePaths) {
+      await moveSingleFile(filePath, targetScope, context, cwd, config);
+    }
+  } else if (filePaths.length === 2) {
+    // Rename mode
+    await renameFile(filePaths[0], filePaths[1], context, cwd, config);
+  } else if (filePaths.length === 1) {
+    throw new Error(
+      "Must specify destination or scope flag (--global, --project, --worktree)",
+    );
+  } else {
+    throw new Error(
+      "Too many arguments without scope flag. Use --global, --project, or --worktree",
+    );
   }
 }
 
@@ -101,6 +121,64 @@ async function moveSingleFile(
   );
 }
 
+/** Rename a file within its current scope */
+async function renameFile(
+  sourcePath: string,
+  destName: string,
+  context: MapperContext,
+  cwd: string,
+  config: { agents: string[] },
+): Promise<void> {
+  const { overlayRoot, targetRoot: gitRoot } = context;
+  const sourceBarePath = join(cwd, sourcePath);
+
+  // Verify source is managed by clank
+  const currentScope = await scopeFromSymlink(sourceBarePath, context);
+  if (!currentScope) {
+    throw new Error(`${sourcePath} is not managed by clank`);
+  }
+  if (isAgentFile(sourcePath)) {
+    throw new Error(
+      "Cannot rename agent files (CLAUDE.md, AGENTS.md, GEMINI.md)",
+    );
+  }
+
+  // Build dest path (same directory as source)
+  const sourceDir = dirname(sourcePath);
+  const destPath = sourceDir === "." ? destName : join(sourceDir, destName);
+
+  // Calculate overlay paths
+  const normalizedSource = normalizeAddPath(sourcePath, cwd, gitRoot);
+  const normalizedDest = normalizeAddPath(destPath, cwd, gitRoot);
+  const sourceOverlay = targetToOverlay(
+    normalizedSource,
+    currentScope,
+    context,
+  );
+  const destOverlay = targetToOverlay(normalizedDest, currentScope, context);
+
+  if (await fileExists(destOverlay)) {
+    throw new Error(`Destination already exists: ${destName}`);
+  }
+
+  // Rename in overlay and update symlinks
+  await ensureDir(dirname(destOverlay));
+  await rename(sourceOverlay, destOverlay);
+  const moveCtx: MoveContext = { overlayRoot, gitRoot, agents: config.agents };
+  if (isPromptFile(normalizedSource)) {
+    await renamePromptLinks(
+      normalizedSource,
+      normalizedDest,
+      destOverlay,
+      moveCtx,
+    );
+  } else {
+    await renameSymlink(normalizedSource, normalizedDest, destOverlay, moveCtx);
+  }
+
+  console.log(`Renamed ${sourcePath} → ${destName} (${currentScope} scope)`);
+}
+
 /** Recreate agent symlinks (CLAUDE.md, GEMINI.md, AGENTS.md) after moving */
 async function recreateAgentLinks(
   normalizedPath: string,
@@ -172,3 +250,55 @@ async function recreateSymlink(
   const linkTarget = getLinkTarget(targetPath, overlayPath);
   await createSymlink(linkTarget, targetPath);
 }
+
+/** Rename prompt symlinks in all agent directories */
+async function renamePromptLinks(
+  oldNormPath: string,
+  newNormPath: string,
+  newOverlayPath: string,
+  ctx: MoveContext,
+): Promise<void> {
+  const { overlayRoot, gitRoot } = ctx;
+  const oldPromptRel = getPromptRelPath(oldNormPath);
+  const newPromptRel = getPromptRelPath(newNormPath);
+  if (!oldPromptRel || !newPromptRel) return;
+
+  // Remove old symlinks
+  for (const agentDir of managedAgentDirs) {
+    const oldTarget = join(gitRoot, agentDir, "prompts", oldPromptRel);
+    if (await isSymlinkToOverlay(oldTarget, overlayRoot)) {
+      await unlink(oldTarget);
+    }
+  }
+
+  // Create new symlinks
+  const created = await createPromptLinks(
+    newOverlayPath,
+    newPromptRel,
+    gitRoot,
+  );
+
+  if (created.length > 0) {
+    console.log(
+      `Updated symlinks: ${created.map((p) => relative(gitRoot, p)).join(", ")}`,
+    );
+  }
+}
+
+/** Rename a regular symlink */
+async function renameSymlink(
+  oldTargetPath: string,
+  newTargetPath: string,
+  newOverlayPath: string,
+  ctx: MoveContext,
+): Promise<void> {
+  // Remove old symlink
+  if (await isSymlinkToOverlay(oldTargetPath, ctx.overlayRoot)) {
+    await unlink(oldTargetPath);
+  }
+
+  // Create new symlink
+  await ensureDir(dirname(newTargetPath));
+  const linkTarget = getLinkTarget(newTargetPath, newOverlayPath);
+  await createSymlink(linkTarget, newTargetPath);
+}

package/src/commands/Rm.ts

@@ -41,14 +41,18 @@ export async function rmCommand(
   for (const filePath of filePaths) {
     const normalizedPath = normalizeAddPath(filePath, cwd, gitRoot);
 
+    // Try to find overlay path (may not exist for unmanaged files)
     const scope = await resolveScope(normalizedPath, options, context);
-    const overlayPath = targetToOverlay(normalizedPath, scope, context);
-
-    if (!(await fileExists(overlayPath))) {
-      throw new Error(`Not found in overlay: ${relative(cwd, normalizedPath)}`);
-    }
+    const overlayPath = scope
+      ? targetToOverlay(normalizedPath, scope, context)
+      : null;
 
     if (isAgentFile(filePath)) {
+      if (!overlayPath || !(await fileExists(overlayPath))) {
+        throw new Error(
+          `Not found in overlay: ${relative(cwd, normalizedPath)}`,
+        );
+      }
       await removeAgentFiles(normalizedPath, overlayPath, overlayRoot, config);
     } else {
       await removeFile(normalizedPath, overlayPath, overlayRoot, cwd);
@@ -56,12 +60,12 @@ export async function rmCommand(
   }
 }
 
-/** Resolve which scope to remove from */
+/** Resolve which scope to remove from, or null if not in overlay */
 async function resolveScope(
   targetPath: string,
   options: RmOptions,
   context: MapperContext,
-): Promise<Scope> {
+): Promise<Scope | null> {
   // Explicit scope takes priority
   if (options.global || options.project || options.worktree) {
     return resolveScopeFromOptions(options);
@@ -73,10 +77,8 @@ async function resolveScope(
   const found = await findInScopes(targetPath, context);
 
   if (found.length === 0) {
-    throw new Error(
-      `Not found in overlay: ${basename(targetPath)}\n` +
-        `File does not exist in any scope (global, project, worktree)`,
-    );
+    // Not in overlay - might be an unmanaged local file
+    return null;
   }
 
   if (found.length > 1) {
@@ -119,28 +121,36 @@ async function removeAgentFiles(
 /** Remove a regular file */
 async function removeFile(
   targetPath: string,
-  overlayPath: string,
+  overlayPath: string | null,
   overlayRoot: string,
   cwd: string,
 ): Promise<void> {
   const fileName = relative(cwd, targetPath);
+  const targetExists = await fileExists(targetPath);
+  const overlayExists = overlayPath ? await fileExists(overlayPath) : false;
 
-  // Check if local file exists and handle it
-  if (await fileExists(targetPath)) {
+  // Nothing to remove
+  if (!targetExists && !overlayExists) {
+    throw new Error(`File not found: ${fileName}`);
+  }
+
+  // Handle target file
+  if (targetExists) {
     if (await isSymlinkToOverlay(targetPath, overlayRoot)) {
       await unlink(targetPath);
       console.log(`Removed symlink: ${fileName}`);
     } else {
-      throw new Error(
-        `File exists but is not managed by clank: ${fileName}\n` +
-          `Cannot remove a file that is not a symlink to the overlay`,
-      );
+      // Unmanaged file in clank/ directory - just remove it
+      await rm(targetPath);
+      console.log(`Removed: ${fileName}`);
     }
   }
 
-  // Remove from overlay
-  await rm(overlayPath);
-  console.log(`Removed from overlay: ${basename(overlayPath)}`);
+  // Remove from overlay if it exists
+  if (overlayPath && overlayExists) {
+    await rm(overlayPath);
+    console.log(`Removed from overlay: ${basename(overlayPath)}`);
+  }
 }
 
 /** Search all scopes to find where the file exists */

package/src/commands/VsCode.ts

@@ -16,6 +16,95 @@ import {
 
 export interface VscodeOptions {
   remove?: boolean;
+  force?: boolean;
+}
+
+/** Result of checking if VS Code settings can be generated */
+export interface VscodeTrackingCheck {
+  canGenerate: boolean;
+  warning?: string;
+  hasBase: boolean;
+}
+
+/** Check if settings.base.json exists */
+export async function hasBaseSettings(targetRoot: string): Promise<boolean> {
+  return fileExists(join(targetRoot, ".vscode/settings.base.json"));
+}
+
+/** Read layered settings (base + local) if base exists */
+async function readLayeredSettings(
+  targetRoot: string,
+): Promise<Record<string, unknown> | null> {
+  const basePath = join(targetRoot, ".vscode/settings.base.json");
+  const localPath = join(targetRoot, ".vscode/settings.local.json");
+
+  if (!(await fileExists(basePath))) return null;
+
+  let base: Record<string, unknown> = {};
+  const baseContent = await readFile(basePath, "utf-8");
+  try {
+    base = JSON.parse(baseContent);
+  } catch {
+    console.warn("Warning: Could not parse settings.base.json, ignoring");
+    return null;
+  }
+
+  let local: Record<string, unknown> = {};
+  if (await fileExists(localPath)) {
+    const localContent = await readFile(localPath, "utf-8");
+    try {
+      local = JSON.parse(localContent);
+    } catch {
+      console.warn("Warning: Could not parse settings.local.json, ignoring");
+    }
+  }
+
+  // Merge exclude patterns specially (combine, don't replace)
+  const baseSearch = (base["search.exclude"] as Record<string, boolean>) || {};
+  const localSearch =
+    (local["search.exclude"] as Record<string, boolean>) || {};
+  const baseFiles = (base["files.exclude"] as Record<string, boolean>) || {};
+  const localFiles = (local["files.exclude"] as Record<string, boolean>) || {};
+
+  return {
+    ...base,
+    ...local,
+    "search.exclude": { ...baseSearch, ...localSearch },
+    "files.exclude": { ...baseFiles, ...localFiles },
+  };
+}
+
+/** Check if settings.json is tracked and return appropriate warning */
+export async function checkVscodeTracking(
+  targetRoot: string,
+): Promise<VscodeTrackingCheck> {
+  const settingsPath = join(targetRoot, ".vscode/settings.json");
+  const hasBase = await hasBaseSettings(targetRoot);
+  const isTracked = await isTrackedByGit(settingsPath, targetRoot);
+
+  if (!isTracked) {
+    return { canGenerate: true, hasBase };
+  }
+
+  // settings.json is tracked
+  if (hasBase) {
+    return {
+      canGenerate: false,
+      hasBase,
+      warning:
+        "settings.base.json found but settings.json is still tracked.\n" +
+        "Complete migration: git rm --cached .vscode/settings.json",
+    };
+  }
+
+  return {
+    canGenerate: false,
+    hasBase,
+    warning:
+      "Skipping: .vscode/settings.json is tracked.\n" +
+      "Use `clank vscode --force` to override, or migrate:\n" +
+      "  mv .vscode/settings.json .vscode/settings.base.json && git rm --cached .vscode/settings.json",
+  };
 }
 
 /** Generate VS Code settings to show clank files in search and explorer */
@@ -27,6 +116,19 @@ export async function vscodeCommand(options?: VscodeOptions): Promise<void> {
     return;
   }
 
+  // Check if we can generate (tracking check)
+  const check = await checkVscodeTracking(targetRoot);
+  if (!check.canGenerate && !options?.force) {
+    console.log(check.warning);
+    return;
+  }
+
+  if (options?.force && !check.canGenerate) {
+    console.log(
+      "Note: settings.json is tracked, this will create uncommitted changes.\n",
+    );
+  }
+
   await generateVscodeSettings(targetRoot);
 }
 
@@ -70,10 +172,38 @@ export async function generateVscodeSettings(
   );
 }
 
+/** Regenerate settings.json from base+local only (remove clank additions) */
+async function removeLayeredSettings(
+  settingsPath: string,
+  layered: Record<string, unknown>,
+): Promise<void> {
+  delete layered["search.useIgnoreFiles"];
+
+  if (Object.keys(layered).length === 0) {
+    if (await fileExists(settingsPath)) {
+      await unlink(settingsPath);
+      console.log("Removed .vscode/settings.json (base+local were empty)");
+    }
+  } else {
+    await writeJsonFile(settingsPath, layered);
+    console.log(
+      "Regenerated .vscode/settings.json from base+local (removed clank patterns)",
+    );
+  }
+}
+
 /** Remove clank-generated VS Code settings */
 export async function removeVscodeSettings(targetRoot: string): Promise<void> {
   const settingsPath = join(targetRoot, ".vscode/settings.json");
 
+  // If layered settings exist, regenerate from base+local only
+  const layered = await readLayeredSettings(targetRoot);
+  if (layered) {
+    await removeLayeredSettings(settingsPath, layered);
+    return;
+  }
+
+  // Legacy mode: selectively remove clank patterns
   if (!(await fileExists(settingsPath))) {
     return;
   }
@@ -123,11 +253,30 @@ export async function isVscodeProject(targetRoot: string): Promise<boolean> {
   }
 }
 
-/** Merge clank exclude patterns with existing .vscode/settings.json */
+/** Merge clank exclude patterns with layered or existing settings */
 async function mergeVscodeSettings(
   targetRoot: string,
   excludePatterns: Record<string, boolean>,
 ): Promise<Record<string, unknown>> {
+  // Try layered settings first (base + local)
+  const layered = await readLayeredSettings(targetRoot);
+
+  if (layered) {
+    // Layered mode: base + local + clank
+    const layeredSearch =
+      (layered["search.exclude"] as Record<string, boolean>) || {};
+    const layeredFiles =
+      (layered["files.exclude"] as Record<string, boolean>) || {};
+
+    return {
+      ...layered,
+      "search.useIgnoreFiles": false,
+      "search.exclude": { ...layeredSearch, ...excludePatterns },
+      "files.exclude": { ...layeredFiles, ...excludePatterns },
+    };
+  }
+
+  // Legacy mode: read existing settings.json
   const settingsPath = join(targetRoot, ".vscode/settings.json");
 
   let existingSettings: Record<string, unknown> = {};
@@ -170,11 +319,17 @@ async function writeVscodeSettings(
   console.log(`Wrote ${settingsPath}`);
 }
 
-/** Add .vscode/settings.json to .git/info/exclude */
+/** Add .vscode/settings.json and settings.local.json to .git/info/exclude */
 async function addVscodeToGitExclude(targetRoot: string): Promise<void> {
   const settingsPath = join(targetRoot, ".vscode/settings.json");
-  if (await isTrackedByGit(settingsPath, targetRoot)) return;
-  await addToGitExclude(targetRoot, ".vscode/settings.json");
+  const localPath = join(targetRoot, ".vscode/settings.local.json");
+
+  if (!(await isTrackedByGit(settingsPath, targetRoot))) {
+    await addToGitExclude(targetRoot, ".vscode/settings.json");
+  }
+  if (!(await isTrackedByGit(localPath, targetRoot))) {
+    await addToGitExclude(targetRoot, ".vscode/settings.local.json");
+  }
 }
 
 /** Remove patterns from an exclude object, deleting the key if empty */