@danieldeusing/seedr 0.1.87 → 0.1.88

package/dist/cli.js

@@ -2,44 +2,61 @@
 import {
   ALL_AGENTS,
   CODING_AGENTS,
+  MAX_SLUG_LENGTH,
+  SLUG_PATTERN,
+  assertDirectoryWithin,
   assertOverwritable,
+  assertSafePathSegment,
+  assertValidSlug,
   brand,
-  cancelled,
+  canonicalAgent,
+  canonicalAgents,
   confirm,
+  copyDirectory,
   ensureDir,
   error,
   exists,
+  fetchItemFile,
   fetchItemToDestination,
   getAgentPath,
   getAgentsPath,
   getContentPath,
-  getInstalledSkills,
+  getEffectiveSourceRevision,
   getItem,
   getItemContent,
   getItemSourcePath,
-  getMcpPath,
+  getItemsBySlug,
+  getMcpConfigPath,
   getSettingsPath,
   info,
-  installDirectory,
   installFile,
   intro,
+  isInteractive,
+  isLegacyAgent,
+  isValidSlug,
   listItems,
+  moveDirectory,
   outro,
   p,
-  parseAgentsArg,
+  parseAgentsArgStrict,
+  parseGitHubRepo,
   printLogo,
-  removeFile,
+  removePathEntry,
+  resolveContained,
+  restoreFile,
   searchItems,
   selectAgents,
   selectMethod,
   selectScope,
   selectSkill,
   skillHandler,
+  snapshotFile,
   step,
   success,
   warn,
+  writeFileAtomic,
   writeTextFile
-} from "./chunk-77M7PGDO.js";
+} from "./chunk-WJEBBHTL.js";
 
 // src/cli.ts
 import { Command as Command5 } from "commander";
@@ -56,13 +73,30 @@ function registerHandler(handler) {
 function getHandler(type) {
   return handlers.get(type);
 }
+function getRegisteredTypes() {
+  return Array.from(handlers.keys());
+}
 
 // src/utils/errors.ts
 import chalk from "chalk";
+function describe(error2) {
+  if (!(error2 instanceof Error)) return [typeof error2 === "string" ? error2 : "Unknown error"];
+  const lines = [error2.message];
+  let cause = error2.cause;
+  while (cause instanceof Error) {
+    lines.push(cause.message);
+    cause = cause.cause;
+  }
+  if (cause !== void 0 && typeof cause === "string") lines.push(cause);
+  return lines;
+}
 function handleCommandError(error2) {
-  console.error(
-    chalk.red(`Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`)
-  );
+  const [message, ...causes] = describe(error2);
+  console.error(chalk.red(`Error: ${message}`));
+  for (const cause of causes) console.error(chalk.gray(`  caused by: ${cause}`));
+  if (process.env.SEEDR_DEBUG && error2 instanceof Error && error2.stack) {
+    console.error(chalk.gray(error2.stack));
+  }
   process.exit(1);
 }
 
@@ -102,71 +136,94 @@ function validateType(value) {
 
 // src/utils/analytics.ts
 var ANALYTICS_URL = "https://seedr.danieldeusing.de/api/installs";
-function trackInstalls(slug, type, results, scope) {
-  if (process.env.SEEDR_NO_TELEMETRY) return;
-  const version = true ? "0.1.87" : "dev";
-  for (const result of results) {
-    if (!result.success) continue;
-    fetch(ANALYTICS_URL, {
+var TELEMETRY_OPT_OUT_VARIABLE = "SEEDR_NO_TELEMETRY";
+var REQUEST_TIMEOUT_MS = 4e3;
+var TELEMETRY_HELP_TEXT = `Sends one anonymous install event per successful agent target to ${ANALYTICS_URL}; set ${TELEMETRY_OPT_OUT_VARIABLE}=1 to disable`;
+function isTelemetryDisabled(env = process.env) {
+  return env[TELEMETRY_OPT_OUT_VARIABLE] !== void 0;
+}
+function cliVersion() {
+  return true ? "0.1.88" : "dev";
+}
+async function sendEvent(event) {
+  try {
+    await fetch(ANALYTICS_URL, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        slug,
-        type,
-        tool: result.agent,
-        scope,
-        version
-      }),
-      signal: AbortSignal.timeout(4e3)
-    }).catch(() => {
+      body: JSON.stringify(event),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
     });
+  } catch {
   }
 }
+function trackInstalls(slug, type, results, scope) {
+  if (isTelemetryDisabled()) return Promise.resolve();
+  const version = cliVersion();
+  const sends = results.filter((result) => result.success).map((result) => sendEvent({ slug, type, tool: result.agent, scope, version }));
+  return Promise.all(sends).then(() => void 0);
+}
 
 // src/config/compatibility.ts
 var AGENT_COMPATIBILITY = {
-  skill: ["claude", "copilot", "gemini", "codex", "opencode"],
+  skill: ["claude", "copilot", "antigravity", "codex", "opencode"],
   command: ["claude"],
   agent: ["claude"],
   hook: ["claude"],
   plugin: ["claude"],
   settings: ["claude"],
-  mcp: ["claude", "copilot", "gemini", "codex", "opencode"]
+  mcp: ["claude", "codex", "opencode"]
 };
+function isTypeSupported(type, agent) {
+  const canonical = canonicalAgent(agent);
+  return canonical !== null && AGENT_COMPATIBILITY[type].includes(canonical);
+}
 function filterCompatibleAgents(type, agents) {
   const compatible = AGENT_COMPATIBILITY[type];
-  return agents.filter((a) => compatible.includes(a));
+  return canonicalAgents(agents).filter((a) => compatible.includes(a));
+}
+var MCP_UNSUPPORTED_REASONS = {
+  copilot: "GitHub Copilot's MCP configuration format could not be verified against primary documentation, so seedr does not write it",
+  antigravity: "Google Antigravity's MCP configuration format could not be verified against primary documentation, so seedr does not write it"
+};
+function describeIncompatibility(type, agent) {
+  const canonical = canonicalAgent(agent);
+  if (type === "mcp" && canonical !== null && MCP_UNSUPPORTED_REASONS[canonical]) {
+    return MCP_UNSUPPORTED_REASONS[canonical];
+  }
+  return `${canonical ?? agent} does not support ${type} content`;
 }
 
 // src/handlers/agent.ts
-import { join } from "path";
-import { readdir } from "fs/promises";
+import { join, relative } from "path";
+import { homedir } from "os";
+import { lstat, readdir, unlink } from "fs/promises";
 import chalk2 from "chalk";
 import ora from "ora";
+var SLUG_LABEL = "agent slug";
+async function resolveAgentFilePath(agent, slug, scope, cwd) {
+  const destDir = getContentPath(agent, "agent", scope, cwd);
+  if (!destDir) return null;
+  const scopeRoot = scope === "user" ? homedir() : cwd;
+  return resolveContained(scopeRoot, relative(scopeRoot, destDir), `${slug}.md`);
+}
 async function installAgentForCodingAgent(item, agent, scope, method, force, cwd) {
   const spinner = ora(
     `Installing ${item.name} for ${CODING_AGENTS[agent].name}...`
   ).start();
   try {
-    const destDir = getContentPath(agent, "agent", scope, cwd);
-    if (!destDir) {
+    assertValidSlug(item.slug, SLUG_LABEL);
+    const destPath = await resolveAgentFilePath(agent, item.slug, scope, cwd);
+    if (!destPath) {
       throw new Error(`${CODING_AGENTS[agent].name} does not support agents`);
     }
-    const destPath = join(destDir, `${item.slug}.md`);
     await assertOverwritable(destPath, force);
     const sourcePath = getItemSourcePath(item);
-    if (sourcePath && method === "symlink") {
-      const sourceFile = join(sourcePath, "AGENT.md");
-      if (await exists(sourceFile)) {
-        await installFile(sourceFile, destPath, "symlink");
-      } else {
-        const content = await getItemContent(item);
-        await ensureDir(destDir);
-        await writeTextFile(destPath, content);
-      }
+    const sourceFile = sourcePath ? join(sourcePath, "AGENT.md") : null;
+    if (method === "symlink" && sourceFile && await exists(sourceFile)) {
+      await installFile(sourceFile, destPath, "symlink");
     } else {
       const content = await getItemContent(item);
-      await ensureDir(destDir);
+      await ensureDir(getContentPath(agent, "agent", scope, cwd));
       await writeTextFile(destPath, content);
     }
     spinner.succeed(
@@ -190,13 +247,21 @@ async function installAgent(item, agents, scope, method, force, cwd = process.cw
   return results;
 }
 async function uninstallAgent(slug, agent, scope, cwd = process.cwd()) {
-  const destDir = getContentPath(agent, "agent", scope, cwd);
-  if (!destDir) return false;
-  const destPath = join(destDir, `${slug}.md`);
-  if (!await exists(destPath)) {
-    return false;
+  assertValidSlug(slug, SLUG_LABEL);
+  const destPath = await resolveAgentFilePath(agent, slug, scope, cwd);
+  if (!destPath) return false;
+  let stats;
+  try {
+    stats = await lstat(destPath);
+  } catch (error2) {
+    if (error2.code === "ENOENT") return false;
+    throw error2;
   }
-  return removeFile(destPath);
+  if (stats.isDirectory()) {
+    throw new Error(`${destPath} is a directory; refusing to remove it`);
+  }
+  await unlink(destPath);
+  return true;
 }
 async function getInstalledAgents(agent, scope, cwd = process.cwd()) {
   const destDir = getContentPath(agent, "agent", scope, cwd);
@@ -206,6 +271,23 @@ async function getInstalledAgents(agent, scope, cwd = process.cwd()) {
   const files = await readdir(destDir);
   return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
 }
+async function planAgent(item, agents, scope, method, cwd) {
+  assertValidSlug(item.slug, SLUG_LABEL);
+  const changes = [];
+  for (const agent of agents) {
+    const destPath = await resolveAgentFilePath(agent, item.slug, scope, cwd);
+    if (!destPath) throw new Error(`${CODING_AGENTS[agent].name} does not support agents`);
+    const sourcePath = getItemSourcePath(item);
+    const linked = method === "symlink" && sourcePath !== null && await exists(join(sourcePath, "AGENT.md"));
+    changes.push({
+      agent,
+      kind: await exists(destPath) ? "modify" : "create",
+      path: destPath,
+      detail: linked ? `symlink \u2192 ${join(sourcePath, "AGENT.md")}` : "agent definition file"
+    });
+  }
+  return changes;
+}
 var agentHandler = {
   type: "agent",
   async install(item, agents, scope, method, force, cwd) {
@@ -216,18 +298,19 @@ var agentHandler = {
   },
   async listInstalled(agent, scope, cwd) {
     return getInstalledAgents(agent, scope, cwd);
-  }
+  },
+  plan: planAgent
 };
 
 // src/handlers/hook.ts
-import { join as join2, basename } from "path";
-import { homedir } from "os";
-import { mkdir, copyFile, chmod, rm } from "fs/promises";
+import { join as join2, basename, dirname as dirname2 } from "path";
+import { homedir as homedir2 } from "os";
+import { lstat as lstat2, mkdir, mkdtemp, readFile as readFile2, realpath, rm, unlink as unlink2 } from "fs/promises";
 import chalk3 from "chalk";
 import ora2 from "ora";
 
 // src/utils/json.ts
-import { readFile, writeFile } from "fs/promises";
+import { readFile, stat } from "fs/promises";
 import { dirname } from "path";
 async function readJson(path) {
   try {
@@ -237,12 +320,24 @@ async function readJson(path) {
     if (error2.code === "ENOENT") {
       return {};
     }
+    if (error2 instanceof SyntaxError) {
+      throw new Error(`${path} is not valid JSON: ${error2.message}`, { cause: error2 });
+    }
+    throw error2;
+  }
+}
+async function existingFileMode(path) {
+  try {
+    return (await stat(path)).mode & 511;
+  } catch (error2) {
+    if (error2.code === "ENOENT") return void 0;
     throw error2;
   }
 }
 async function writeJson(path, data) {
   await ensureDir(dirname(path));
-  await writeFile(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+  const mode = await existingFileMode(path);
+  await writeFileAtomic(path, JSON.stringify(data, null, 2) + "\n", { mode });
 }
 function deepMerge(target, source) {
   const result = { ...target };
@@ -262,14 +357,14 @@ function deepMerge(target, source) {
 }
 
 // src/handlers/hook.ts
+var CLAUDE_ONLY_ERROR = "Hooks are only supported for Claude Code";
+var SCRIPT_NAME_LABEL = "hook script name";
+var SCRIPT_MODE = 493;
+function getScopeRoot(scope, cwd) {
+  return scope === "user" ? homedir2() : cwd;
+}
 function getHooksDir(scope, cwd) {
-  switch (scope) {
-    case "user":
-      return join2(homedir(), ".claude", "hooks");
-    case "project":
-    case "local":
-      return join2(cwd, ".claude", "hooks");
-  }
+  return join2(getScopeRoot(scope, cwd), ".claude", "hooks");
 }
 function getScriptPath(scope, scriptName) {
   switch (scope) {
@@ -290,13 +385,65 @@ function findScriptFile(item) {
   }
   return null;
 }
+async function prepareHooksDir(scope, cwd) {
+  const scopeRoot = getScopeRoot(scope, cwd);
+  const hooksDir = await resolveContained(scopeRoot, ".claude", "hooks");
+  await mkdir(hooksDir, { recursive: true });
+  await assertDirectoryWithin(hooksDir, scopeRoot, "hooks directory");
+  return realpath(hooksDir);
+}
+async function assertRegularFileOrMissing(path) {
+  let stats;
+  try {
+    stats = await lstat2(path);
+  } catch (error2) {
+    if (error2.code === "ENOENT") return;
+    throw error2;
+  }
+  if (stats.isSymbolicLink()) {
+    throw new Error(`${path} is a symbolic link; refusing to write through it \u2014 remove it first`);
+  }
+  if (!stats.isFile()) {
+    throw new Error(`${path} exists and is not a regular file; refusing to replace it`);
+  }
+}
+async function loadScriptBytes(item, scriptFile, hooksDir) {
+  const sourcePath = getItemSourcePath(item);
+  if (sourcePath && await exists(sourcePath)) {
+    return readFile2(join2(sourcePath, scriptFile));
+  }
+  const fetchDir = await mkdtemp(join2(dirname2(hooksDir), ".seedr-hook-"));
+  try {
+    const contentDir = join2(fetchDir, "content");
+    await fetchItemToDestination(item, contentDir);
+    return await readFile2(join2(contentDir, scriptFile));
+  } finally {
+    await rm(fetchDir, { recursive: true, force: true });
+  }
+}
+function mergeTriggers(hooks, triggers, command) {
+  for (const trigger of triggers) {
+    const entries = hooks[trigger.event] ??= [];
+    const existingEntry = entries.find((entry) => entry.matcher === trigger.matcher);
+    const hookCommand = { type: "command", command };
+    if (existingEntry) {
+      if (!existingEntry.hooks.some((hook) => hook.command === command)) {
+        existingEntry.hooks.push(hookCommand);
+      }
+      continue;
+    }
+    const newEntry = { hooks: [hookCommand] };
+    if (trigger.matcher) newEntry.matcher = trigger.matcher;
+    entries.push(newEntry);
+  }
+}
 async function installHookForAgent(item, agent, scope, _method, force, cwd) {
   const spinner = ora2(
     `Installing ${item.name} for ${CODING_AGENTS[agent].name}...`
   ).start();
   try {
     if (agent !== "claude") {
-      throw new Error("Hooks are only supported for Claude Code");
+      throw new Error(CLAUDE_ONLY_ERROR);
     }
     const triggers = item.contents?.triggers;
     if (!triggers || triggers.length === 0) {
@@ -306,53 +453,24 @@ async function installHookForAgent(item, agent, scope, _method, force, cwd) {
     if (!scriptFile) {
       throw new Error("No script file found in hook");
     }
-    const hooksDir = getHooksDir(scope, cwd);
-    await mkdir(hooksDir, { recursive: true });
-    const sourcePath = getItemSourcePath(item);
-    const destScriptPath = join2(hooksDir, scriptFile);
+    assertSafePathSegment(scriptFile, SCRIPT_NAME_LABEL);
+    const hooksDir = await prepareHooksDir(scope, cwd);
+    const destScriptPath = await resolveContained(hooksDir, scriptFile);
+    await assertRegularFileOrMissing(destScriptPath);
     await assertOverwritable(destScriptPath, force);
-    if (sourcePath && await exists(sourcePath)) {
-      const sourceScriptPath = join2(sourcePath, scriptFile);
-      await copyFile(sourceScriptPath, destScriptPath);
-    } else {
-      const tempDir = join2(cwd, ".claude", ".tmp", item.slug);
-      await fetchItemToDestination(item, tempDir);
-      await copyFile(join2(tempDir, scriptFile), destScriptPath);
-      await rm(tempDir, { recursive: true, force: true });
-    }
-    await chmod(destScriptPath, 493);
-    const settingsPath = getSettingsPath(scope, cwd);
-    const settings = await readJson(settingsPath);
-    settings.hooks = settings.hooks || {};
-    const scriptPath = getScriptPath(scope, scriptFile);
-    for (const trigger of triggers) {
-      const event = trigger.event;
-      const matcher = trigger.matcher;
-      if (!settings.hooks[event]) {
-        settings.hooks[event] = [];
-      }
-      const existingEntry = settings.hooks[event].find(
-        (e) => e.matcher === matcher
-      );
-      const hookCommand = { type: "command", command: scriptPath };
-      if (existingEntry) {
-        const alreadyExists = existingEntry.hooks.some(
-          (h) => h.command === scriptPath
-        );
-        if (!alreadyExists) {
-          existingEntry.hooks.push(hookCommand);
-        }
-      } else {
-        const newEntry = {
-          hooks: [hookCommand]
-        };
-        if (matcher) {
-          newEntry.matcher = matcher;
-        }
-        settings.hooks[event].push(newEntry);
-      }
+    const scriptBytes = await loadScriptBytes(item, scriptFile, hooksDir);
+    const previousScript = await snapshotFile(destScriptPath);
+    await writeFileAtomic(destScriptPath, scriptBytes, { mode: SCRIPT_MODE });
+    try {
+      const settingsPath = getSettingsPath(scope, cwd);
+      const settings = await readJson(settingsPath);
+      settings.hooks = settings.hooks || {};
+      mergeTriggers(settings.hooks, triggers, getScriptPath(scope, scriptFile));
+      await writeJson(settingsPath, settings);
+    } catch (error2) {
+      await restoreFile(destScriptPath, previousScript);
+      throw error2;
     }
-    await writeJson(settingsPath, settings);
     spinner.succeed(
       brand(`Installed ${item.name} for ${CODING_AGENTS[agent].name}`)
     );
@@ -373,7 +491,47 @@ async function installHook(item, agents, scope, method, force, cwd = process.cwd
   }
   return results;
 }
+function removeHookCommands(hooks, slug, expectedPath) {
+  let removed = false;
+  const belongsToHook = (hook) => expectedPath !== null && hook.command === expectedPath || basename(hook.command, ".sh") === slug;
+  for (const event of Object.keys(hooks)) {
+    const entries = hooks[event] ?? [];
+    const keptEntries = [];
+    for (const entry of entries) {
+      const keptHooks = entry.hooks.filter((hook) => !belongsToHook(hook));
+      if (keptHooks.length < entry.hooks.length) removed = true;
+      if (keptHooks.length > 0) keptEntries.push({ ...entry, hooks: keptHooks });
+    }
+    if (keptEntries.length === 0) {
+      delete hooks[event];
+    } else {
+      hooks[event] = keptEntries;
+    }
+  }
+  return removed;
+}
+async function removeScriptFile(scope, cwd, scriptFileName) {
+  const scopeRoot = getScopeRoot(scope, cwd);
+  const hooksDir = getHooksDir(scope, cwd);
+  if (!await exists(hooksDir)) return false;
+  await assertDirectoryWithin(hooksDir, scopeRoot, "hooks directory");
+  assertSafePathSegment(scriptFileName, SCRIPT_NAME_LABEL);
+  const scriptFilePath = await resolveContained(hooksDir, scriptFileName);
+  let stats;
+  try {
+    stats = await lstat2(scriptFilePath);
+  } catch (error2) {
+    if (error2.code === "ENOENT") return false;
+    throw error2;
+  }
+  if (stats.isDirectory()) {
+    throw new Error(`${scriptFilePath} is a directory; refusing to remove it`);
+  }
+  await unlink2(scriptFilePath);
+  return true;
+}
 async function uninstallHook(slug, agent, scope, cwd = process.cwd()) {
+  assertValidSlug(slug, "hook slug");
   if (agent !== "claude") return false;
   const settingsPath = getSettingsPath(scope, cwd);
   if (!await exists(settingsPath)) return false;
@@ -382,43 +540,15 @@ async function uninstallHook(slug, agent, scope, cwd = process.cwd()) {
   const expectedPath = scriptFile ? getScriptPath(scope, scriptFile) : null;
   const settings = await readJson(settingsPath);
   if (!settings.hooks) return false;
-  let removed = false;
-  for (const event of Object.keys(settings.hooks)) {
-    const entries = settings.hooks[event];
-    if (!entries) continue;
-    for (let i = entries.length - 1; i >= 0; i--) {
-      const entry = entries[i];
-      const originalLength = entry.hooks.length;
-      entry.hooks = entry.hooks.filter((h) => {
-        if (expectedPath && h.command === expectedPath) return false;
-        const cmdBasename = basename(h.command, ".sh");
-        return cmdBasename !== slug;
-      });
-      if (entry.hooks.length < originalLength) {
-        removed = true;
-      }
-      if (entry.hooks.length === 0) {
-        entries.splice(i, 1);
-      }
-    }
-    if (entries.length === 0) {
-      delete settings.hooks[event];
-    }
-  }
+  let removed = removeHookCommands(settings.hooks, slug, expectedPath);
   if (Object.keys(settings.hooks).length === 0) {
     delete settings.hooks;
   }
   if (removed) {
     await writeJson(settingsPath, settings);
   }
-  const hooksDir = getHooksDir(scope, cwd);
-  const scriptFileName = scriptFile || `${slug}.sh`;
-  const scriptFilePath = join2(hooksDir, scriptFileName);
-  try {
-    await rm(scriptFilePath);
+  if (await removeScriptFile(scope, cwd, scriptFile || `${slug}.sh`)) {
     removed = true;
-  } catch (e) {
-    if (e.code !== "ENOENT") throw e;
   }
   return removed;
 }
@@ -432,13 +562,35 @@ async function getInstalledHooks(agent, scope, cwd = process.cwd()) {
   for (const entries of Object.values(settings.hooks)) {
     for (const entry of entries) {
       for (const hook of entry.hooks) {
-        const slug = basename(hook.command, ".sh");
-        slugs.add(slug);
+        slugs.add(basename(hook.command, ".sh"));
       }
     }
   }
   return Array.from(slugs);
 }
+async function planHook(item, agents, scope, _method, cwd) {
+  const changes = [];
+  for (const agent of agents) {
+    if (agent !== "claude") throw new Error(CLAUDE_ONLY_ERROR);
+    const scriptFile = findScriptFile(item);
+    if (!scriptFile) throw new Error("No script file found in hook");
+    assertSafePathSegment(scriptFile, SCRIPT_NAME_LABEL);
+    const scopeRoot = getScopeRoot(scope, cwd);
+    const scriptPath = await resolveContained(scopeRoot, ".claude", "hooks", scriptFile);
+    const settingsPath = getSettingsPath(scope, cwd);
+    const events = (item.contents?.triggers ?? []).map((trigger) => trigger.matcher ? `${trigger.event}[${trigger.matcher}]` : trigger.event).join(", ");
+    changes.push(
+      { agent, kind: await exists(scriptPath) ? "modify" : "create", path: scriptPath, detail: "executable hook script" },
+      {
+        agent,
+        kind: await exists(settingsPath) ? "modify" : "create",
+        path: settingsPath,
+        detail: `hooks: ${events || "(no triggers)"} \u2192 ${getScriptPath(scope, scriptFile)}`
+      }
+    );
+  }
+  return changes;
+}
 var hookHandler = {
   type: "hook",
   async install(item, agents, scope, method, force, cwd) {
@@ -449,36 +601,362 @@ var hookHandler = {
   },
   async listInstalled(agent, scope, cwd) {
     return getInstalledHooks(agent, scope, cwd);
-  }
+  },
+  plan: planHook
 };
 
 // src/handlers/mcp.ts
+import { readFile as readFile3 } from "fs/promises";
+import { dirname as dirname3 } from "path";
 import chalk4 from "chalk";
 import ora3 from "ora";
+
+// src/utils/toml.ts
+var BARE_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
+function parseTomlHeader(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("[")) return null;
+  const isArrayTable = trimmed.startsWith("[[");
+  const open = isArrayTable ? "[[" : "[";
+  const close = isArrayTable ? "]]" : "]";
+  const closeIndex = findHeaderClose(trimmed, open.length, close);
+  if (closeIndex === -1) return null;
+  const inner = trimmed.slice(open.length, closeIndex);
+  return splitKeyPath(inner);
+}
+function findHeaderClose(line, start, close) {
+  let quote = null;
+  for (let i = start; i < line.length; i++) {
+    const ch = line[i];
+    if (quote) {
+      if (ch === "\\" && quote === '"') {
+        i++;
+      } else if (ch === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+    } else if (line.startsWith(close, i)) {
+      return i;
+    }
+  }
+  return -1;
+}
+function readQuotedKey(inner, start) {
+  const quote = inner[start];
+  let text = "";
+  for (let i = start + 1; i < inner.length; i++) {
+    const ch = inner[i];
+    if (ch === quote) return { text, end: i + 1 };
+    if (ch === "\\" && quote === '"') {
+      const next = inner[i + 1];
+      if (next === void 0) return null;
+      text += unescapeBasic(next);
+      i++;
+    } else {
+      text += ch;
+    }
+  }
+  return null;
+}
+function readKeyPart(inner, start) {
+  let text = "";
+  let sawQuoted = false;
+  let i = start;
+  while (i < inner.length && inner[i] !== ".") {
+    const ch = inner[i];
+    if (ch === '"' || ch === "'") {
+      const quoted = readQuotedKey(inner, i);
+      if (!quoted) return null;
+      text += quoted.text;
+      sawQuoted = true;
+      i = quoted.end;
+      continue;
+    }
+    if (ch !== " " && ch !== "	") text += ch;
+    i++;
+  }
+  if (text === "" && !sawQuoted) return null;
+  return { text, end: i };
+}
+function splitKeyPath(inner) {
+  const parts = [];
+  let i = 0;
+  for (; ; ) {
+    const part = readKeyPart(inner, i);
+    if (!part) return null;
+    parts.push(part.text);
+    if (part.end >= inner.length) return parts;
+    i = part.end + 1;
+  }
+}
+function unescapeBasic(ch) {
+  switch (ch) {
+    case "n":
+      return "\n";
+    case "t":
+      return "	";
+    case "r":
+      return "\r";
+    case "b":
+      return "\b";
+    case "f":
+      return "\f";
+    default:
+      return ch;
+  }
+}
+function parseTomlSections(text) {
+  const lines = text.split(/\r?\n/);
+  const sections = [{ keyPath: [], lines: [] }];
+  for (const line of lines) {
+    const keyPath = parseTomlHeader(line);
+    if (keyPath) {
+      sections.push({ keyPath, lines: [line] });
+    } else {
+      sections[sections.length - 1].lines.push(line);
+    }
+  }
+  return sections;
+}
+function keyPathStartsWith(keyPath, prefix) {
+  return prefix.length <= keyPath.length && prefix.every((part, i) => keyPath[i] === part);
+}
+function trimBlankEdges(lines) {
+  let start = 0;
+  let end = lines.length;
+  while (start < end && lines[start].trim() === "") start++;
+  while (end > start && lines[end - 1].trim() === "") end--;
+  return lines.slice(start, end);
+}
+function joinSections(sections) {
+  const blocks = sections.map((section) => trimBlankEdges(section.lines)).filter((lines) => lines.length > 0).map((lines) => lines.join("\n"));
+  return blocks.length === 0 ? "" : blocks.join("\n\n") + "\n";
+}
+function formatTomlKey(key) {
+  return BARE_KEY_PATTERN.test(key) ? key : formatTomlString(key);
+}
+function formatTomlString(value) {
+  let out = '"';
+  for (const ch of value) {
+    const code = ch.codePointAt(0);
+    if (ch === '"') out += '\\"';
+    else if (ch === "\\") out += "\\\\";
+    else if (ch === "\n") out += "\\n";
+    else if (ch === "	") out += "\\t";
+    else if (ch === "\r") out += "\\r";
+    else if (code < 32 || code === 127) out += `\\u${code.toString(16).padStart(4, "0")}`;
+    else out += ch;
+  }
+  return out + '"';
+}
+function formatTomlValue(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => formatTomlValue(v)).join(", ")}]`;
+  }
+  if (typeof value === "string") return formatTomlString(value);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(`Cannot encode ${value} as TOML`);
+    return String(value);
+  }
+  return value ? "true" : "false";
+}
+function renderTable(table) {
+  const header = `[${table.keyPath.map(formatTomlKey).join(".")}]`;
+  const lines = [header];
+  for (const [key, value] of Object.entries(table.entries)) {
+    lines.push(`${formatTomlKey(key)} = ${formatTomlValue(value)}`);
+  }
+  return { keyPath: table.keyPath, lines };
+}
+function upsertTomlTables(text, prefix, tables) {
+  const kept = parseTomlSections(text).filter((section) => !keyPathStartsWith(section.keyPath, prefix));
+  return joinSections([...kept, ...tables.map(renderTable)]);
+}
+function removeTomlTables(text, prefix) {
+  const sections = parseTomlSections(text);
+  const kept = sections.filter((section) => !keyPathStartsWith(section.keyPath, prefix));
+  if (kept.length === sections.length) return { text, removed: false };
+  return { text: joinSections(kept), removed: true };
+}
+function hasTomlTable(text, keyPath) {
+  return parseTomlSections(text).some(
+    (section) => section.keyPath.length === keyPath.length && keyPathStartsWith(section.keyPath, keyPath)
+  );
+}
+function listTomlChildTables(text, parent) {
+  const names = /* @__PURE__ */ new Set();
+  for (const section of parseTomlSections(text)) {
+    if (section.keyPath.length === parent.length + 1 && keyPathStartsWith(section.keyPath, parent)) {
+      names.add(section.keyPath[parent.length]);
+    }
+  }
+  return Array.from(names);
+}
+
+// src/handlers/mcp.ts
+var MCP_SERVERS_KEY = "mcpServers";
+var CODEX_TABLE = "mcp_servers";
+var NO_COMMAND_ERROR = "MCP definition has no command for a stdio server";
+var NO_URL_ERROR = "MCP definition has no url for a remote server";
 function parseMcpDefinition(content) {
+  let parsed;
   try {
-    return JSON.parse(content);
+    parsed = JSON.parse(content);
   } catch {
     throw new Error("Invalid MCP definition: must be valid JSON");
   }
+  const definition = parsed;
+  if (!definition || typeof definition.name !== "string" || definition.name === "" || typeof definition.config !== "object" || definition.config === null) {
+    throw new Error('Invalid MCP definition: expected { "name": string, "config": object }');
+  }
+  return definition;
+}
+function transportOf(config) {
+  if (config.type === "http" || config.type === "sse") return config.type;
+  if (config.type === void 0 && config.url && !config.command) return "http";
+  return "stdio";
+}
+function definedEntries(object) {
+  return Object.fromEntries(Object.entries(object).filter(([, value]) => value !== void 0));
+}
+function toOpenCodeServer(config) {
+  if (transportOf(config) === "stdio") {
+    if (!config.command) throw new Error(NO_COMMAND_ERROR);
+    return definedEntries({
+      type: "local",
+      command: [config.command, ...config.args ?? []],
+      environment: config.env,
+      enabled: true
+    });
+  }
+  if (!config.url) throw new Error(NO_URL_ERROR);
+  return definedEntries({ type: "remote", url: config.url, headers: config.headers, enabled: true });
+}
+function codexMainEntries(config) {
+  if (transportOf(config) === "stdio") {
+    if (!config.command) throw new Error(NO_COMMAND_ERROR);
+    return definedEntries({
+      command: config.command,
+      args: config.args && config.args.length > 0 ? config.args : void 0,
+      cwd: config.cwd || void 0
+    });
+  }
+  if (!config.url) throw new Error(NO_URL_ERROR);
+  return definedEntries({
+    url: config.url,
+    bearer_token_env_var: config.bearer_token_env_var || void 0
+  });
+}
+function hasEntries(record) {
+  return record !== void 0 && Object.keys(record).length > 0;
+}
+function toCodexTables(name, config) {
+  const base = [CODEX_TABLE, name];
+  const tables = [{ keyPath: base, entries: codexMainEntries(config) }];
+  if (hasEntries(config.env)) {
+    tables.push({ keyPath: [...base, "env"], entries: { ...config.env } });
+  }
+  if (hasEntries(config.headers)) {
+    tables.push({ keyPath: [...base, "http_headers"], entries: { ...config.headers } });
+  }
+  return tables;
+}
+function serverMapOf(doc, key) {
+  const servers = doc[key];
+  return servers !== null && typeof servers === "object" && !Array.isArray(servers) ? servers : {};
+}
+async function readDocument(path) {
+  return await exists(path) ? readJson(path) : null;
+}
+function jsonAdapter(agent, key, translate, defaults = {}) {
+  return {
+    configPath: (scope, cwd) => getMcpConfigPath(agent, scope, cwd),
+    describeEntry: (name) => `${key}.${name}`,
+    async has(path, name) {
+      const doc = await readDocument(path);
+      return doc !== null && name in serverMapOf(doc, key);
+    },
+    async write(path, name, config) {
+      const doc = await readDocument(path) ?? { ...defaults };
+      const servers = serverMapOf(doc, key);
+      servers[name] = translate(config);
+      doc[key] = servers;
+      await writeJson(path, doc);
+    },
+    async remove(path, name) {
+      const doc = await readDocument(path);
+      if (doc === null) return false;
+      const servers = serverMapOf(doc, key);
+      if (!(name in servers)) return false;
+      delete servers[name];
+      doc[key] = servers;
+      await writeJson(path, doc);
+      return true;
+    },
+    async list(path) {
+      const doc = await readDocument(path);
+      return doc === null ? [] : Object.keys(serverMapOf(doc, key));
+    }
+  };
+}
+async function readTextOrEmpty(path) {
+  try {
+    return await readFile3(path, "utf-8");
+  } catch (error2) {
+    if (error2.code === "ENOENT") return "";
+    throw error2;
+  }
+}
+var codexAdapter = {
+  configPath: (scope, cwd) => getMcpConfigPath("codex", scope, cwd),
+  describeEntry: (name) => `[${CODEX_TABLE}.${name}]`,
+  async has(path, name) {
+    return hasTomlTable(await readTextOrEmpty(path), [CODEX_TABLE, name]);
+  },
+  async write(path, name, config) {
+    const text = await readTextOrEmpty(path);
+    await ensureDir(dirname3(path));
+    await writeFileAtomic(path, upsertTomlTables(text, [CODEX_TABLE, name], toCodexTables(name, config)));
+  },
+  async remove(path, name) {
+    if (!await exists(path)) return false;
+    const { text, removed } = removeTomlTables(await readTextOrEmpty(path), [CODEX_TABLE, name]);
+    if (removed) await writeFileAtomic(path, text);
+    return removed;
+  },
+  async list(path) {
+    return listTomlChildTables(await readTextOrEmpty(path), [CODEX_TABLE]);
+  }
+};
+var ADAPTERS = {
+  claude: jsonAdapter("claude", MCP_SERVERS_KEY, (config) => ({ ...config })),
+  opencode: jsonAdapter("opencode", "mcp", toOpenCodeServer, { $schema: "https://opencode.ai/config.json" }),
+  codex: codexAdapter
+};
+function adapterFor(agent) {
+  const adapter = ADAPTERS[agent];
+  if (!adapter || !isTypeSupported("mcp", agent)) {
+    throw new Error(`MCP servers are not supported for ${CODING_AGENTS[agent].name}`);
+  }
+  return adapter;
 }
 async function installMcpForAgent(item, agent, scope, _method, force, cwd) {
   const spinner = ora3(
     `Installing ${item.name} for ${CODING_AGENTS[agent].name}...`
   ).start();
   try {
-    const content = await getItemContent(item);
-    const mcpDef = parseMcpDefinition(content);
-    const configPath = getMcpPath(scope, cwd);
-    const config = await readJson(configPath);
-    config.mcpServers = config.mcpServers || {};
-    if (!force && mcpDef.name in config.mcpServers) {
+    const adapter = adapterFor(agent);
+    const mcpDef = parseMcpDefinition(await getItemContent(item));
+    const configPath = adapter.configPath(scope, cwd);
+    if (!force && await adapter.has(configPath, mcpDef.name)) {
       throw new Error(
         `MCP server "${mcpDef.name}" already exists in ${configPath}; pass --force to overwrite`
       );
     }
-    config.mcpServers[mcpDef.name] = mcpDef.config;
-    await writeJson(configPath, config);
+    await adapter.write(configPath, mcpDef.name, mcpDef.config);
     spinner.succeed(
       brand(`Installed ${item.name} for ${CODING_AGENTS[agent].name}`)
     );
@@ -499,22 +977,45 @@ async function installMcp(item, agents, scope, method, force, cwd = process.cwd(
   }
   return results;
 }
-async function uninstallMcp(slug, _agent, scope, cwd = process.cwd()) {
-  const configPath = getMcpPath(scope, cwd);
-  if (!await exists(configPath)) return false;
-  const config = await readJson(configPath);
-  if (!config.mcpServers || !(slug in config.mcpServers)) {
-    return false;
+async function resolveServerName(slug) {
+  try {
+    const item = await getItem(slug, "mcp");
+    if (!item) return slug;
+    return parseMcpDefinition(await getItemContent(item)).name;
+  } catch {
+    return slug;
   }
-  delete config.mcpServers[slug];
-  await writeJson(configPath, config);
-  return true;
 }
-async function getInstalledMcpServers(_agent, scope, cwd = process.cwd()) {
-  const configPath = getMcpPath(scope, cwd);
-  if (!await exists(configPath)) return [];
-  const config = await readJson(configPath);
-  return Object.keys(config.mcpServers || {});
+async function uninstallMcp(slug, agent, scope, cwd = process.cwd()) {
+  assertValidSlug(slug);
+  if (!isTypeSupported("mcp", agent)) return false;
+  const adapter = adapterFor(agent);
+  const configPath = adapter.configPath(scope, cwd);
+  if (!await exists(configPath)) return false;
+  const name = await resolveServerName(slug);
+  return adapter.remove(configPath, name);
+}
+async function getInstalledMcpServers(agent, scope, cwd = process.cwd()) {
+  if (!isTypeSupported("mcp", agent)) return [];
+  const adapter = adapterFor(agent);
+  return adapter.list(adapter.configPath(scope, cwd));
+}
+async function planMcp(item, agents, scope, _method, cwd) {
+  const mcpDef = parseMcpDefinition(await getItemContent(item));
+  const changes = [];
+  for (const agent of agents) {
+    const adapter = adapterFor(agent);
+    const path = adapter.configPath(scope, cwd);
+    const fileExists = await exists(path);
+    const replaces = fileExists && await adapter.has(path, mcpDef.name);
+    changes.push({
+      agent,
+      kind: fileExists ? "modify" : "create",
+      path,
+      detail: `${adapter.describeEntry(mcpDef.name)}${replaces ? " (replaces existing entry)" : ""}`
+    });
+  }
+  return changes;
 }
 var mcpHandler = {
   type: "mcp",
@@ -526,12 +1027,15 @@ var mcpHandler = {
   },
   async listInstalled(agent, scope, cwd) {
     return getInstalledMcpServers(agent, scope, cwd);
-  }
+  },
+  plan: planMcp
 };
 
 // src/handlers/settings.ts
 import chalk5 from "chalk";
 import ora4 from "ora";
+var SETTINGS_NOT_DISCOVERABLE = "settings items cannot be discovered (they are merged into settings.json)";
+var CLAUDE_ONLY_ERROR2 = "Settings are only supported for Claude Code";
 function parseSettings(content) {
   try {
     return JSON.parse(content);
@@ -545,7 +1049,7 @@ async function installSettingsForAgent(item, agent, scope, _method, _force, cwd)
   ).start();
   try {
     if (agent !== "claude") {
-      throw new Error("Settings are only supported for Claude Code");
+      throw new Error(CLAUDE_ONLY_ERROR2);
     }
     const content = await getItemContent(item);
     const newSettings = parseSettings(content);
@@ -601,6 +1105,7 @@ function deepUnmerge(target, source) {
   return { result, changed };
 }
 async function uninstallSettings(slug, agent, scope, cwd = process.cwd()) {
+  assertValidSlug(slug, "settings slug");
   if (agent !== "claude") return false;
   const item = await getItem(slug, "settings");
   if (!item) return false;
@@ -620,12 +1125,24 @@ async function uninstallSettings(slug, agent, scope, cwd = process.cwd()) {
   }
   return changed;
 }
-async function getInstalledSettings(agent, scope, cwd = process.cwd()) {
-  if (agent !== "claude") return [];
-  const settingsPath = getSettingsPath(scope, cwd);
-  if (!await exists(settingsPath)) return [];
+async function getInstalledSettings(_agent, _scope, _cwd = process.cwd()) {
   return [];
 }
+async function planSettings(item, agents, scope, _method, cwd) {
+  const changes = [];
+  for (const agent of agents) {
+    if (agent !== "claude") throw new Error(CLAUDE_ONLY_ERROR2);
+    const keys = Object.keys(parseSettings(await getItemContent(item)));
+    const settingsPath = getSettingsPath(scope, cwd);
+    changes.push({
+      agent,
+      kind: await exists(settingsPath) ? "modify" : "create",
+      path: settingsPath,
+      detail: `deep-merge keys: ${keys.join(", ") || "(none)"}`
+    });
+  }
+  return changes;
+}
 var settingsHandler = {
   type: "settings",
   async install(item, agents, scope, method, force, cwd) {
@@ -636,49 +1153,78 @@ var settingsHandler = {
   },
   async listInstalled(agent, scope, cwd) {
     return getInstalledSettings(agent, scope, cwd);
-  }
+  },
+  plan: planSettings
 };
 
 // src/handlers/plugin.ts
-import { homedir as homedir2 } from "os";
-import { join as join3 } from "path";
-import { mkdir as mkdir2, rm as rm2 } from "fs/promises";
+import { homedir as homedir3 } from "os";
+import { join as join3, relative as relative2 } from "path";
+import { mkdir as mkdir2, mkdtemp as mkdtemp2, rm as rm2 } from "fs/promises";
 import { execFile } from "child_process";
 import { promisify } from "util";
 import chalk6 from "chalk";
 import ora5 from "ora";
-var home = homedir2();
-var PLUGINS_CACHE_DIR = join3(home, ".claude/plugins/cache");
-var INSTALLED_PLUGINS_PATH = join3(home, ".claude/plugins/installed_plugins.json");
-var KNOWN_MARKETPLACES_PATH = join3(home, ".claude/plugins/known_marketplaces.json");
-var MARKETPLACES_DIR = join3(home, ".claude/plugins/marketplaces");
-function getPluginCachePath(marketplace, name, version) {
-  return join3(PLUGINS_CACHE_DIR, marketplace, name, version);
-}
+var home = homedir3();
+var PLUGINS_DIR = join3(home, ".claude", "plugins");
+var PLUGINS_CACHE_DIR = join3(PLUGINS_DIR, "cache");
+var INSTALLED_PLUGINS_PATH = join3(PLUGINS_DIR, "installed_plugins.json");
+var KNOWN_MARKETPLACES_PATH = join3(PLUGINS_DIR, "known_marketplaces.json");
+var MARKETPLACES_DIR = join3(PLUGINS_DIR, "marketplaces");
+var PLUGIN_JSON_PATH = ".claude-plugin/plugin.json";
+var CLAUDE_ONLY_ERROR3 = "Plugins are only supported for Claude Code";
+var SLUG_LABEL2 = "plugin slug";
+var GITHUB_REPO_SLUG_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 function getPluginId(name, marketplace) {
   return `${name}@${marketplace}`;
 }
+function splitPluginId(pluginId) {
+  const at = pluginId.indexOf("@");
+  if (at <= 0 || at === pluginId.length - 1) return null;
+  return { name: pluginId.slice(0, at), marketplace: pluginId.slice(at + 1) };
+}
+function resolveMarketplaceName(item) {
+  const marketplace = item.marketplace || item.author?.name || "seedr";
+  assertSafePathSegment(marketplace, "plugin marketplace");
+  return marketplace;
+}
+function resolvePluginIdentity(item, pluginJson) {
+  const name = pluginJson.name || item.slug;
+  const version = pluginJson.version || "1.0.0";
+  assertSafePathSegment(name, "plugin name");
+  assertSafePathSegment(version, "plugin version");
+  return { name, version };
+}
 function extractGitHubRepo(url) {
-  const match = url.match(/github\.com\/([^/]+\/[^/]+)/);
-  return match?.[1]?.replace(/\.git$/, "") ?? null;
+  const parsed = parseGitHubRepo(url);
+  if (!parsed) return null;
+  const slug = `${parsed.owner}/${parsed.repo}`;
+  if (!GITHUB_REPO_SLUG_PATTERN.test(slug) || slug.includes("..")) return null;
+  return slug;
+}
+function marketplaceRepoUrl(item) {
+  return item.marketplaceRef?.url ?? item.externalUrl;
 }
 async function ensureMarketplaceRegistered(marketplace, item) {
   const known = await readJson(
     KNOWN_MARKETPLACES_PATH
   );
   if (known[marketplace]) return;
-  const repo = item.externalUrl ? extractGitHubRepo(item.externalUrl) : null;
+  const sourceUrl = marketplaceRepoUrl(item);
+  const repo = sourceUrl ? extractGitHubRepo(sourceUrl) : null;
   if (!repo) return;
-  const installLocation = join3(MARKETPLACES_DIR, marketplace);
-  const execFileAsync = promisify(execFile);
+  const installLocation = await resolveContained(MARKETPLACES_DIR, marketplace);
   await mkdir2(MARKETPLACES_DIR, { recursive: true });
-  await execFileAsync("git", [
-    "clone",
-    "--depth",
-    "1",
-    `https://github.com/${repo}.git`,
-    installLocation
-  ]);
+  if (!await exists(installLocation)) {
+    const execFileAsync = promisify(execFile);
+    await execFileAsync("git", [
+      "clone",
+      "--depth",
+      "1",
+      `https://github.com/${repo}.git`,
+      installLocation
+    ]);
+  }
   known[marketplace] = {
     source: { source: "github", repo },
     installLocation,
@@ -686,66 +1232,122 @@ async function ensureMarketplaceRegistered(marketplace, item) {
   };
   await writeJson(KNOWN_MARKETPLACES_PATH, known);
 }
-async function installPluginForAgent(item, agent, scope, method, force, cwd) {
+async function createStagingDir(slug) {
+  const tmpRoot = await resolveContained(PLUGINS_CACHE_DIR, ".tmp");
+  await mkdir2(tmpRoot, { recursive: true });
+  const staging = await mkdtemp2(join3(tmpRoot, `${slug}-`));
+  return resolveContained(PLUGINS_CACHE_DIR, relative2(PLUGINS_CACHE_DIR, staging));
+}
+async function stageContent(item, contentPath) {
+  const sourcePath = getItemSourcePath(item);
+  if (sourcePath) {
+    await copyDirectory(sourcePath, contentPath);
+    return null;
+  }
+  return fetchItemToDestination(item, contentPath);
+}
+function resolveGitCommitSha(item, fetched) {
+  const sha = fetched?.sourceRevision ?? getEffectiveSourceRevision(item);
+  if (!sha) {
+    throw new Error(
+      `Cannot record a source revision for "${item.slug}": the registry entry has neither sourceRevision nor pluginSource.sha`
+    );
+  }
+  return sha;
+}
+function isScopeEntry(entry, scope, cwd) {
+  return entry.scope === scope && (scope === "user" || entry.projectPath === cwd);
+}
+async function writeInstalledEntry(params) {
+  const { cachePath, pluginId, version, gitCommitSha, scope, cwd } = params;
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const registry = await readJson(INSTALLED_PLUGINS_PATH);
+  registry.version = registry.version || 2;
+  registry.plugins = registry.plugins || {};
+  const installInfo = {
+    scope,
+    ...scope !== "user" ? { projectPath: cwd } : {},
+    installPath: cachePath,
+    version,
+    installedAt: now,
+    lastUpdated: now,
+    gitCommitSha
+  };
+  const existingEntries = registry.plugins[pluginId] || [];
+  registry.plugins[pluginId] = [
+    ...existingEntries.filter((entry) => !isScopeEntry(entry, scope, cwd)),
+    installInfo
+  ];
+  await writeJson(INSTALLED_PLUGINS_PATH, registry);
+}
+async function enableInSettings(settingsPath, pluginId) {
+  const settings = await readJson(settingsPath);
+  settings.enabledPlugins = settings.enabledPlugins || {};
+  settings.enabledPlugins[pluginId] = true;
+  await writeJson(settingsPath, settings);
+}
+async function rollback(undo, error2) {
+  const failures = [];
+  for (const step2 of undo.reverse()) {
+    try {
+      await step2();
+    } catch (undoError) {
+      failures.push(undoError instanceof Error ? undoError.message : String(undoError));
+    }
+  }
+  if (failures.length > 0) {
+    const message = error2 instanceof Error ? error2.message : String(error2);
+    throw new Error(`${message} (rollback incomplete: ${failures.join("; ")})`, { cause: error2 });
+  }
+  throw error2;
+}
+async function commitInstall(params) {
+  const { contentPath, cachePath, pluginId, scope, cwd } = params;
+  const undo = [];
+  try {
+    await removePathEntry(cachePath);
+    await moveDirectory(contentPath, cachePath);
+    undo.push(() => removePathEntry(cachePath).then(() => void 0));
+    const registrySnapshot = await snapshotFile(INSTALLED_PLUGINS_PATH);
+    await writeInstalledEntry(params);
+    undo.push(() => restoreFile(INSTALLED_PLUGINS_PATH, registrySnapshot));
+    const settingsPath = getSettingsPath(scope, cwd);
+    const settingsSnapshot = await snapshotFile(settingsPath);
+    await enableInSettings(settingsPath, pluginId);
+    undo.push(() => restoreFile(settingsPath, settingsSnapshot));
+  } catch (error2) {
+    await rollback(undo, error2);
+  }
+}
+async function installPluginForAgent(item, agent, scope, _method, force, cwd) {
   const spinner = ora5(
     `Installing ${item.name} for ${CODING_AGENTS[agent].name}...`
   ).start();
   try {
     if (agent !== "claude") {
-      throw new Error("Plugins are only supported for Claude Code");
-    }
-    const tmpPath = join3(PLUGINS_CACHE_DIR, ".tmp", item.slug);
-    const sourcePath = getItemSourcePath(item);
-    if (sourcePath) {
-      await installDirectory(sourcePath, tmpPath, method);
-    } else {
-      await fetchItemToDestination(item, tmpPath);
+      throw new Error(CLAUDE_ONLY_ERROR3);
     }
-    const pluginJson = await readJson(
-      join3(tmpPath, ".claude-plugin", "plugin.json")
-    );
-    const marketplace = item.marketplace || item.author?.name || "seedr";
-    const pluginName = pluginJson.name || item.slug;
-    const version = pluginJson.version || "1.0.0";
-    const pluginId = getPluginId(pluginName, marketplace);
-    await ensureMarketplaceRegistered(marketplace, item);
-    const cachePath = getPluginCachePath(marketplace, pluginName, version);
+    assertValidSlug(item.slug, SLUG_LABEL2);
+    const marketplace = resolveMarketplaceName(item);
+    const staging = await createStagingDir(item.slug);
     try {
+      const contentPath = join3(staging, "content");
+      const fetched = await stageContent(item, contentPath);
+      const pluginJson = await readJson(join3(contentPath, ...PLUGIN_JSON_PATH.split("/")));
+      const { name, version } = resolvePluginIdentity(item, pluginJson);
+      const gitCommitSha = resolveGitCommitSha(item, fetched);
+      const pluginId = getPluginId(name, marketplace);
+      await ensureMarketplaceRegistered(marketplace, item);
+      const cachePath = await resolveContained(PLUGINS_CACHE_DIR, marketplace, name, version);
       await assertOverwritable(cachePath, force);
-    } catch (error2) {
-      await rm2(tmpPath, { recursive: true, force: true });
-      throw error2;
+      await commitInstall({ contentPath, cachePath, pluginId, version, gitCommitSha, scope, cwd });
+      spinner.succeed(
+        brand(`Installed ${item.name} for ${CODING_AGENTS[agent].name}`)
+      );
+      return { agent, success: true, path: cachePath };
+    } finally {
+      await rm2(staging, { recursive: true, force: true });
     }
-    await installDirectory(tmpPath, cachePath, "copy");
-    await rm2(tmpPath, { recursive: true, force: true });
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const registry = await readJson(INSTALLED_PLUGINS_PATH);
-    registry.version = registry.version || 2;
-    registry.plugins = registry.plugins || {};
-    const installInfo = {
-      scope,
-      ...scope !== "user" ? { projectPath: cwd } : {},
-      installPath: cachePath,
-      version,
-      installedAt: now,
-      lastUpdated: now,
-      gitCommitSha: ""
-    };
-    const existingEntries = registry.plugins[pluginId] || [];
-    const filteredEntries = existingEntries.filter(
-      (e) => !(e.scope === scope && (scope === "user" || e.projectPath === cwd))
-    );
-    registry.plugins[pluginId] = [...filteredEntries, installInfo];
-    await writeJson(INSTALLED_PLUGINS_PATH, registry);
-    const settingsPath = getSettingsPath(scope, cwd);
-    const settings = await readJson(settingsPath);
-    settings.enabledPlugins = settings.enabledPlugins || {};
-    settings.enabledPlugins[pluginId] = true;
-    await writeJson(settingsPath, settings);
-    spinner.succeed(
-      brand(`Installed ${item.name} for ${CODING_AGENTS[agent].name}`)
-    );
-    return { agent, success: true, path: cachePath };
   } catch (error2) {
     const errorMsg = error2 instanceof Error ? error2.message : "Unknown error";
     spinner.fail(
@@ -762,30 +1364,60 @@ async function installPlugin(item, agents, scope, method, force, cwd = process.c
   }
   return results;
 }
+async function findInstalledPluginId(registry, slug) {
+  let registryMarketplace = null;
+  try {
+    const item = await getItem(slug, "plugin");
+    if (item) registryMarketplace = resolveMarketplaceName(item);
+  } catch {
+    registryMarketplace = null;
+  }
+  if (registryMarketplace !== null) {
+    const exact = getPluginId(slug, registryMarketplace);
+    return exact in registry.plugins ? exact : null;
+  }
+  const candidates = Object.keys(registry.plugins).filter((id) => splitPluginId(id)?.name === slug);
+  return candidates.length === 1 ? candidates[0] : null;
+}
+async function removeOrphanedCache(installPath, registry) {
+  const stillReferenced = Object.values(registry.plugins).some(
+    (entries) => entries.some((entry) => entry.installPath === installPath)
+  );
+  if (stillReferenced) return;
+  let contained;
+  try {
+    contained = await resolveContained(PLUGINS_CACHE_DIR, installPath);
+  } catch {
+    return;
+  }
+  await removePathEntry(contained);
+}
 async function uninstallPlugin(slug, agent, scope, cwd = process.cwd()) {
+  assertValidSlug(slug, SLUG_LABEL2);
   if (agent !== "claude") return false;
   const registry = await readJson(INSTALLED_PLUGINS_PATH);
   if (!registry.plugins) return false;
-  const matchingKey = Object.keys(registry.plugins).find(
-    (key) => key.startsWith(`${slug}@`)
-  );
-  if (!matchingKey) return false;
-  const entries = registry.plugins[matchingKey] || [];
-  const filteredEntries = entries.filter(
-    (e) => !(e.scope === scope && (scope === "user" || e.projectPath === cwd))
-  );
-  if (filteredEntries.length === 0) {
-    delete registry.plugins[matchingKey];
+  const pluginId = await findInstalledPluginId(registry, slug);
+  if (!pluginId) return false;
+  const entries = registry.plugins[pluginId] || [];
+  const removedEntries = entries.filter((entry) => isScopeEntry(entry, scope, cwd));
+  if (removedEntries.length === 0) return false;
+  const remaining = entries.filter((entry) => !isScopeEntry(entry, scope, cwd));
+  if (remaining.length === 0) {
+    delete registry.plugins[pluginId];
   } else {
-    registry.plugins[matchingKey] = filteredEntries;
+    registry.plugins[pluginId] = remaining;
   }
   await writeJson(INSTALLED_PLUGINS_PATH, registry);
   const settingsPath = getSettingsPath(scope, cwd);
   const settings = await readJson(settingsPath);
-  if (settings.enabledPlugins && matchingKey in settings.enabledPlugins) {
-    delete settings.enabledPlugins[matchingKey];
+  if (settings.enabledPlugins && pluginId in settings.enabledPlugins) {
+    delete settings.enabledPlugins[pluginId];
     await writeJson(settingsPath, settings);
   }
+  for (const installPath of new Set(removedEntries.map((entry) => entry.installPath))) {
+    await removeOrphanedCache(installPath, registry);
+  }
   return true;
 }
 async function getInstalledPlugins(agent, scope, cwd = process.cwd()) {
@@ -794,16 +1426,57 @@ async function getInstalledPlugins(agent, scope, cwd = process.cwd()) {
   if (!registry.plugins) return [];
   const installed = [];
   for (const [pluginId, entries] of Object.entries(registry.plugins)) {
-    for (const entry of entries) {
-      if (entry.scope === scope && (scope === "user" || entry.projectPath === cwd)) {
-        const slug = pluginId.split("@")[0] || pluginId;
-        installed.push(slug);
-        break;
-      }
+    if (entries.some((entry) => isScopeEntry(entry, scope, cwd))) {
+      installed.push(splitPluginId(pluginId)?.name ?? pluginId);
     }
   }
   return installed;
 }
+async function readPluginJsonForPlan(item) {
+  const sourcePath = getItemSourcePath(item);
+  if (sourcePath) {
+    return readJson(join3(sourcePath, ...PLUGIN_JSON_PATH.split("/")));
+  }
+  return JSON.parse(await fetchItemFile(item, PLUGIN_JSON_PATH));
+}
+async function kindFor(path) {
+  return await exists(path) ? "modify" : "create";
+}
+async function planPlugin(item, agents, scope, _method, cwd) {
+  const changes = [];
+  for (const agent of agents) {
+    if (agent !== "claude") throw new Error(CLAUDE_ONLY_ERROR3);
+    assertValidSlug(item.slug, SLUG_LABEL2);
+    const marketplace = resolveMarketplaceName(item);
+    const { name, version } = resolvePluginIdentity(item, await readPluginJsonForPlan(item));
+    const pluginId = getPluginId(name, marketplace);
+    const cachePath = await resolveContained(PLUGINS_CACHE_DIR, marketplace, name, version);
+    const settingsPath = getSettingsPath(scope, cwd);
+    changes.push(
+      { agent, kind: await kindFor(cachePath), path: cachePath, detail: "plugin files (digest-verified download)" },
+      {
+        agent,
+        kind: await kindFor(INSTALLED_PLUGINS_PATH),
+        path: INSTALLED_PLUGINS_PATH,
+        detail: `plugins["${pluginId}"] entry for ${scope} scope`
+      }
+    );
+    const known = await readJson(KNOWN_MARKETPLACES_PATH);
+    if (!known[marketplace]) {
+      const sourceUrl = marketplaceRepoUrl(item);
+      const repo = sourceUrl ? extractGitHubRepo(sourceUrl) : null;
+      if (repo) {
+        const cloneDir = await resolveContained(MARKETPLACES_DIR, marketplace);
+        changes.push({ agent, kind: await kindFor(KNOWN_MARKETPLACES_PATH), path: KNOWN_MARKETPLACES_PATH, detail: `marketplace "${marketplace}"` });
+        if (!await exists(cloneDir)) {
+          changes.push({ agent, kind: "create", path: cloneDir, detail: `git clone https://github.com/${repo}.git` });
+        }
+      }
+    }
+    changes.push({ agent, kind: await kindFor(settingsPath), path: settingsPath, detail: `enabledPlugins["${pluginId}"] = true` });
+  }
+  return changes;
+}
 var pluginHandler = {
   type: "plugin",
   async install(item, agents, scope, method, force, cwd) {
@@ -814,7 +1487,8 @@ var pluginHandler = {
   },
   async listInstalled(agent, scope, cwd) {
     return getInstalledPlugins(agent, scope, cwd);
-  }
+  },
+  plan: planPlugin
 };
 
 // src/handlers/index.ts
@@ -826,91 +1500,192 @@ registerHandler(settingsHandler);
 registerHandler(pluginHandler);
 
 // src/commands/add.ts
-async function resolveItem(itemName, type) {
-  if (itemName) {
-    const item = await getItem(itemName, type);
-    if (item) return item;
-    const results = await searchItems(itemName);
-    const filtered = type ? results.filter((r) => r.type === type) : results;
-    if (filtered.length === 0) {
-      if (type && results.length > 0) {
-        const match = results.find((r) => r.slug === itemName);
-        if (match) {
-          error(`"${itemName}" is a ${match.type}, not a ${type}. Run: seedr add ${itemName} --type ${match.type}`);
-        } else {
-          error(`No ${type} matching "${itemName}". Found: ${results.map((r) => `${r.slug} (${r.type})`).join(", ")}`);
-        }
-      } else {
-        error(`"${itemName}" not found`);
-      }
-      return null;
+var CANCELLED_MESSAGE = "Operation cancelled";
+var CANCELLED = /* @__PURE__ */ Symbol("cancelled");
+function cancelPrompt() {
+  p.cancel(CANCELLED_MESSAGE);
+  return CANCELLED;
+}
+function compatibleAgentsFor(item) {
+  return filterCompatibleAgents(item.type, item.compatibility);
+}
+function explainIncompatibility(item, agent) {
+  if (!isTypeSupported(item.type, agent)) {
+    return describeIncompatibility(item.type, agent);
+  }
+  return `the registry lists "${item.slug}" for ${item.compatibility.join(", ")} only`;
+}
+function resolveRequestedAgents(agentsArg, item) {
+  const compatible = compatibleAgentsFor(item);
+  const compatibleList = compatible.length > 0 ? compatible.join(", ") : "(none)";
+  if (agentsArg === void 0 || agentsArg.trim() === "") {
+    return { ok: true, agents: [], explicit: false };
+  }
+  const deprecationWarning = agentsArg.split(",").map((raw) => raw.trim().toLowerCase()).some((id) => isLegacyAgent(id)) ? "'gemini' is now 'antigravity' (Google Antigravity, installs to .agents/)" : void 0;
+  if (agentsArg.trim() === "all") {
+    if (compatible.length === 0) {
+      return { ok: false, error: `No agent supports ${item.type} "${item.slug}"` };
     }
-    if (filtered.length === 1) {
-      return filtered[0];
+    return { ok: true, agents: compatible, explicit: true, deprecationWarning };
+  }
+  const { agents, unknown } = parseAgentsArgStrict(agentsArg);
+  if (unknown.length > 0) {
+    return {
+      ok: false,
+      error: `Unknown agent(s): ${unknown.join(", ")}. Valid agents: ${ALL_AGENTS.join(", ")} or "all"`
+    };
+  }
+  if (agents.length === 0) {
+    return { ok: false, error: "No agents given" };
+  }
+  const incompatible = agents.filter((agent) => !compatible.includes(agent));
+  if (incompatible.length > 0) {
+    const reasons = incompatible.map((agent) => `${agent}: ${explainIncompatibility(item, agent)}`);
+    return {
+      ok: false,
+      error: `Cannot install ${item.type} "${item.slug}" for ${incompatible.join(", ")}. Compatible agents: ${compatibleList}. ${reasons.join("; ")}`
+    };
+  }
+  return { ok: true, agents, explicit: true, deprecationWarning };
+}
+function decideForce(options) {
+  return Boolean(options.force) || !options.yes;
+}
+async function planInstall(handler, item, agents, scope, method, cwd) {
+  if (handler.plan) {
+    return handler.plan(item, agents, scope, method, cwd);
+  }
+  return agents.map((agent) => ({
+    agent,
+    kind: "create",
+    path: getAgentsPath(item.type, item.slug, scope, cwd),
+    detail: "(handler provides no detailed plan)"
+  }));
+}
+var KIND_LABEL = {
+  create: "create",
+  modify: "modify",
+  delete: "delete"
+};
+function formatPlan(changes) {
+  if (changes.length === 0) return ["  (no filesystem changes)"];
+  const lines = [];
+  const groups = /* @__PURE__ */ new Map();
+  for (const change of changes) {
+    const label = change.agent === "shared" ? "shared" : CODING_AGENTS[change.agent].name;
+    groups.set(label, [...groups.get(label) ?? [], change]);
+  }
+  for (const [label, group] of groups) {
+    lines.push(`  ${label}:`);
+    for (const change of group) {
+      const detail = change.detail ? `  ${chalk7.gray(`\u2014 ${change.detail}`)}` : "";
+      lines.push(`    ${chalk7.gray(`[${KIND_LABEL[change.kind]}]`)} ${change.path}${detail}`);
     }
-    warn(`Multiple matches for "${itemName}"`);
-    const selected2 = await selectSkill(filtered);
-    if (p.isCancel(selected2)) {
-      cancelled();
-      return null;
+  }
+  return lines;
+}
+function summarizeResults(results) {
+  const successful = results.filter((r) => r.success);
+  const failed = results.filter((r) => !r.success);
+  return { successful, failed, exitCode: failed.length > 0 ? 1 : 0 };
+}
+async function resolveItemByName(itemName, type) {
+  if (type) {
+    const typed = await getItem(itemName, type);
+    if (typed) return typed;
+  } else {
+    const matches = await getItemsBySlug(itemName);
+    if (matches.length === 1) return matches[0];
+    if (matches.length > 1) {
+      const types = matches.map((match) => match.type);
+      if (!isInteractive()) {
+        error(`"${itemName}" exists as ${types.join(" and ")}. Pass --type <${types.join("|")}> to choose.`);
+        return null;
+      }
+      warn(`"${itemName}" exists as ${types.join(" and ")} \u2014 pass --type to skip this question.`);
+      const chosen = await selectSkill(matches);
+      if (p.isCancel(chosen)) return cancelPrompt();
+      return chosen;
     }
-    return selected2;
   }
+  const results = await searchItems(itemName);
+  const filtered = type ? results.filter((r) => r.type === type) : results;
+  if (filtered.length === 0) {
+    reportNotFound(itemName, type, results);
+    return null;
+  }
+  if (filtered.length === 1) {
+    return filtered[0];
+  }
+  warn(`Multiple matches for "${itemName}"`);
+  const selected = await selectSkill(filtered);
+  if (p.isCancel(selected)) return cancelPrompt();
+  return selected;
+}
+function reportNotFound(itemName, type, results) {
+  if (!type || results.length === 0) {
+    error(`"${itemName}" not found`);
+    return;
+  }
+  const match = results.find((r) => r.slug === itemName);
+  if (match) {
+    error(`"${itemName}" is a ${match.type}, not a ${type}. Run: seedr add ${itemName} --type ${match.type}`);
+  } else {
+    error(`No ${type} matching "${itemName}". Found: ${results.map((r) => `${r.slug} (${r.type})`).join(", ")}`);
+  }
+}
+async function resolveItem(itemName, type) {
+  if (itemName) return resolveItemByName(itemName, type);
   const items = await listItems(type || "skill");
   if (items.length === 0) {
     error(`No ${type || "skill"}s available in registry`);
     return null;
   }
   const selected = await selectSkill(items);
-  if (p.isCancel(selected)) {
-    cancelled();
+  if (p.isCancel(selected)) return cancelPrompt();
+  return selected;
+}
+async function chooseAgents(options, item) {
+  const resolution = resolveRequestedAgents(options.agents, item);
+  if (!resolution.ok) {
+    error(resolution.error);
+    return null;
+  }
+  if (resolution.deprecationWarning) warn(resolution.deprecationWarning);
+  if (resolution.agents.length > 0) return resolution.agents;
+  const compatible = compatibleAgentsFor(item);
+  if (compatible.length === 0) {
+    error(`No agent supports ${item.type} "${item.slug}"`);
     return null;
   }
+  if (compatible.length === 1) return compatible;
+  const selected = await selectAgents(compatible);
+  if (p.isCancel(selected)) return cancelPrompt();
   return selected;
 }
-function resolveAgents(agentsArg, item) {
-  const typeCompatible = filterCompatibleAgents(item.type, item.compatibility);
-  if (!agentsArg) return [];
-  const agents = parseAgentsArg(agentsArg, typeCompatible);
-  if (agentsArg === "all") return agents;
-  const incompatible = agents.filter((a) => !typeCompatible.includes(a));
-  if (incompatible.length > 0) {
-    warn(`${incompatible.join(", ")} not compatible with this ${item.type}`);
-    return agents.filter((a) => typeCompatible.includes(a));
-  }
-  return agents;
+async function chooseScope(options, item) {
+  if (options.scope) return options.scope;
+  const supportsLocal = ["plugin", "settings", "hook"].includes(item.type);
+  const selected = await selectScope(supportsLocal);
+  if (p.isCancel(selected)) return cancelPrompt();
+  return selected;
 }
-function printDryRunSummary(item, agents, scope, method, cwd) {
-  info("Dry run - no files will be written\n");
-  console.log(brand("  Would install:"));
-  console.log(`    ${item.type}: ${chalk7.white(item.name)}`);
-  console.log(`    Scope: ${chalk7.white(scope)}`);
-  console.log(`    Method: ${chalk7.white(method)}`);
+async function chooseMethod(options, item, agents, scope, cwd) {
+  if (options.method) return options.method;
+  if (agents.length === 1) return "copy";
+  const symlinkPath = getAgentsPath(item.type, item.slug, scope, cwd);
+  const selected = await selectMethod(symlinkPath);
+  if (p.isCancel(selected)) return cancelPrompt();
+  return selected;
+}
+function printPlan(title, changes) {
   console.log();
-  if (method === "symlink" && item.type === "skill") {
-    const centralPath = getAgentsPath("skill", item.slug, scope, cwd);
-    console.log(brand("  Central storage:"));
-    console.log(`    ${chalk7.gray("\u2192")} ${chalk7.gray(centralPath)}`);
-    console.log();
-    console.log(brand("  Symlinks from agent folders:"));
-  } else {
-    console.log(brand("  Target locations:"));
-  }
-  for (const agent of agents) {
-    const config = CODING_AGENTS[agent];
-    const contentPath = getContentPath(agent, item.type, scope, cwd);
-    if (!contentPath) {
-      console.log(`    ${chalk7.gray("\u2192")} ${chalk7.white(config.name)}: ${chalk7.red("not supported")}`);
-      continue;
-    }
-    const targetPath = `${contentPath}/${item.slug}`;
-    console.log(`    ${chalk7.gray("\u2192")} ${chalk7.white(config.name)}: ${chalk7.gray(targetPath)}`);
-  }
+  console.log(brand(`  ${title}`));
+  for (const line of formatPlan(changes)) console.log(line);
   console.log();
 }
 function printInstallSummary(results) {
-  const successful = results.filter((r) => r.success);
-  const failed = results.filter((r) => !r.success);
+  const { successful, failed, exitCode } = summarizeResults(results);
   if (successful.length > 0) {
     success(`Installed for ${successful.length} agent(s)`);
     for (const r of successful) {
@@ -922,98 +1697,65 @@ function printInstallSummary(results) {
     for (const r of failed) {
       console.log(chalk7.red(`    \xD7 ${r.agent}: ${r.error}`));
     }
-    process.exit(1);
   }
+  return exitCode;
+}
+async function runAdd(name, options, cwd = process.cwd()) {
+  const optionError = validateType(options.type) || validateScope(options.scope) || validateMethod(options.method);
+  if (optionError) {
+    error(optionError);
+    return 1;
+  }
+  const item = await resolveItem(name, options.type);
+  if (item === CANCELLED) return 0;
+  if (!item) return 1;
+  step(`Selected: ${brand(item.name)} ${chalk7.gray(`(${item.type})`)} ${chalk7.gray(`- ${item.description}`)}`);
+  const handler = getHandler(item.type);
+  if (!handler) {
+    error(`No handler found for type "${item.type}"`);
+    return 1;
+  }
+  const agents = await chooseAgents(options, item);
+  if (agents === CANCELLED) return 0;
+  if (!agents) return 1;
+  step(`Agents: ${brand(agents.join(", "))}`);
+  const scope = await chooseScope(options, item);
+  if (scope === CANCELLED) return 0;
+  step(`Scope: ${brand(scope)}`);
+  const method = await chooseMethod(options, item, agents, scope, cwd);
+  if (method === CANCELLED) return 0;
+  step(`Method: ${brand(method)}`);
+  if (options.dryRun) {
+    info("Dry run - no files will be written");
+    printPlan("Would write:", await planInstall(handler, item, agents, scope, method, cwd));
+    outro("Dry run complete");
+    return 0;
+  }
+  if (!options.yes) {
+    printPlan("Will write:", await planInstall(handler, item, agents, scope, method, cwd));
+    const confirmed = await confirm("Proceed with installation?");
+    if (p.isCancel(confirmed) || !confirmed) {
+      cancelPrompt();
+      return 0;
+    }
+  }
+  console.log();
+  const results = await handler.install(item, agents, scope, method, decideForce(options), cwd);
+  void trackInstalls(item.slug, item.type, results, scope);
+  const exitCode = printInstallSummary(results);
+  if (exitCode === 0) outro("Installation complete");
+  return exitCode;
 }
 var addCommand = new Command("add").description("Install a skill, agent, hook, or other configuration").argument("[name]", "Name of the item to install").option("-t, --type <type>", "Content type: skill, agent, hook, mcp, plugin, settings").option(
   "-a, --agents <agents>",
-  "Comma-separated coding agents or 'all' (claude,copilot,gemini,codex,opencode)"
-).option("-s, --scope <scope>", "Installation scope: project, user, or local").option("-m, --method <method>", "Installation method: symlink or copy").option("-y, --yes", "Skip confirmation prompts").option("-f, --force", "Overwrite existing files").option("-n, --dry-run", "Show what would be installed without making changes").action(async (name, options) => {
+  "Comma-separated coding agents or 'all' (claude,copilot,antigravity,codex,opencode; 'gemini' is a deprecated alias of antigravity). Every named agent must support the item; 'all' means all compatible agents. MCP servers: claude, codex, opencode (copilot's and antigravity's formats are unverified)"
+).option("-s, --scope <scope>", "Installation scope: project, user, or local").option("-m, --method <method>", "Installation method: symlink or copy").option("-y, --yes", "Skip confirmation prompts").option("-f, --force", "Overwrite existing files").option("-n, --dry-run", "Show exactly which files would be written, without writing or reporting anything").addHelpText("after", `
+Telemetry: ${TELEMETRY_HELP_TEXT}.`).action(async (name, options) => {
   try {
     printLogo();
     intro("Seedr");
-    const optionError = validateType(options.type) || validateScope(options.scope) || validateMethod(options.method);
-    if (optionError) {
-      error(optionError);
-      process.exit(1);
-    }
-    const itemName = name;
-    const contentType = options.type;
-    const item = await resolveItem(itemName, contentType);
-    if (!item) process.exit(1);
-    step(`Selected: ${brand(item.name)} ${chalk7.gray(`(${item.type})`)} ${chalk7.gray(`- ${item.description}`)}`);
-    const handler = getHandler(item.type);
-    if (!handler) {
-      error(`No handler found for type "${item.type}"`);
-      process.exit(1);
-    }
-    let agents = resolveAgents(options.agents, item);
-    const typeCompatible = filterCompatibleAgents(item.type, item.compatibility);
-    if (agents.length === 0) {
-      if (typeCompatible.length === 1) {
-        agents = typeCompatible;
-      } else {
-        const selected = await selectAgents(typeCompatible);
-        if (p.isCancel(selected)) {
-          cancelled();
-          return;
-        }
-        agents = selected;
-      }
-    }
-    if (agents.length === 0) {
-      error("No valid agents selected");
-      process.exit(1);
-    }
-    step(`Agents: ${brand(agents.join(", "))}`);
-    let scope;
-    if (options.scope) {
-      scope = options.scope;
-    } else {
-      const supportsLocal = ["plugin", "settings", "hook"].includes(item.type);
-      const selected = await selectScope(supportsLocal);
-      if (p.isCancel(selected)) {
-        cancelled();
-        return;
-      }
-      scope = selected;
-    }
-    step(`Scope: ${brand(scope)}`);
-    let method;
-    if (options.method) {
-      method = options.method;
-    } else if (agents.length === 1) {
-      method = "copy";
-    } else {
-      const symlinkPath = getAgentsPath(item.type, item.slug, scope, process.cwd());
-      const selected = await selectMethod(symlinkPath);
-      if (p.isCancel(selected)) {
-        cancelled();
-        return;
-      }
-      method = selected;
-    }
-    step(`Method: ${brand(method)}`);
-    if (options.dryRun) {
-      console.log();
-      printDryRunSummary(item, agents, scope, method, process.cwd());
-      outro("Dry run complete");
-      return;
-    }
-    if (!options.yes) {
-      console.log();
-      const confirmed = await confirm("Proceed with installation?");
-      if (p.isCancel(confirmed) || !confirmed) {
-        cancelled();
-        return;
-      }
-    }
-    const force = Boolean(options.force) || !options.yes;
-    console.log();
-    const results = await handler.install(item, agents, scope, method, force, process.cwd());
-    trackInstalls(item.slug, item.type, results, scope);
-    printInstallSummary(results);
-    outro("Installation complete");
+    const exitCode = await runAdd(name, options);
+    if (exitCode !== 0) process.exit(exitCode);
   } catch (error2) {
     handleCommandError(error2);
   }
@@ -1033,13 +1775,54 @@ var TYPE_COLORS = {
   settings: chalk8.hex("#f97316"),
   mcp: chalk8.hex("#2dd4bf")
 };
-var listCommand = new Command2("list").alias("ls").description("List available or installed skills").option("-t, --type <type>", "Filter by type (skill, hook, agent, plugin)").option("-i, --installed", "Show only installed items").option("--scope <scope>", "Scope for installed check (project, user)", "project").action(async (options) => {
-  try {
-    if (options.installed) {
-      await listInstalled(options.scope);
-    } else {
-      await listAvailable(options.type);
+async function collectInstalledItems(params) {
+  const types = params.types ?? getRegisteredTypes();
+  const agents = params.agents ?? ALL_AGENTS;
+  const groups = [];
+  for (const type of types) {
+    const handler = getHandler(type);
+    if (!handler) continue;
+    for (const agent of agents) {
+      const slugs = await handler.listInstalled(agent, params.scope, params.cwd);
+      if (slugs.length > 0) {
+        groups.push({ type, agent, slugs: [...slugs].sort() });
+      }
     }
+  }
+  return groups;
+}
+function resolveListAgents(agentsArg) {
+  if (!agentsArg || agentsArg === "all") return [...ALL_AGENTS];
+  const { agents, unknown } = parseAgentsArgStrict(agentsArg);
+  if (unknown.length > 0) {
+    return `Unknown agent(s): ${unknown.join(", ")}. Valid agents: ${ALL_AGENTS.join(", ")} or "all"`;
+  }
+  return agents;
+}
+async function runList(options, cwd = process.cwd()) {
+  const optionError = validateType(options.type) || validateScope(options.scope);
+  if (optionError) {
+    console.log(chalk8.red(optionError));
+    return 1;
+  }
+  const type = options.type;
+  if (!options.installed) {
+    await listAvailable(type);
+    return 0;
+  }
+  const agents = resolveListAgents(options.agents);
+  if (typeof agents === "string") {
+    console.log(chalk8.red(agents));
+    return 1;
+  }
+  const scope = options.scope ?? "project";
+  await listInstalled({ types: type ? [type] : void 0, agents, scope, cwd });
+  return 0;
+}
+var listCommand = new Command2("list").alias("ls").description("List available or installed items").option("-t, --type <type>", "Filter by type (skill, hook, agent, plugin, mcp, settings)").option("-i, --installed", "Show only installed items").option("-a, --agents <agents>", "Comma-separated coding agents or 'all' (installed check)", "all").option("--scope <scope>", "Scope for installed check (project, user, local)", "project").action(async (options) => {
+  try {
+    const exitCode = await runList(options);
+    if (exitCode !== 0) process.exit(exitCode);
   } catch (error2) {
     handleCommandError(error2);
   }
@@ -1057,7 +1840,7 @@ async function listAvailable(type) {
 ${itemType.toUpperCase()}S`));
     console.log(chalk8.gray("\u2500".repeat(SEPARATOR_WIDTH)));
     for (const item of typeItems) {
-      const compatIcons = item.compatibility.map((a) => CODING_AGENTS[a].shortName).join(" ");
+      const compatIcons = [...new Set(item.compatibility.map((a) => CODING_AGENTS[a]?.shortName ?? a))].join(" ");
       const featured = item.featured ? chalk8.yellow("\u2605 ") : "  ";
       console.log(
         `${featured}${chalk8.white(item.slug.padEnd(SLUG_COLUMN_WIDTH))} ${chalk8.gray(compatIcons)}`
@@ -1070,27 +1853,31 @@ ${itemType.toUpperCase()}S`));
     chalk8.gray(`Total: ${items.length} items. Use 'npx @danieldeusing/seedr add <name>' to install.`)
   );
 }
-async function listInstalled(scope) {
+async function listInstalled(params) {
   console.log(brand(`
-Installed skills (${scope} scope):
+Installed items (${params.scope} scope):
 `));
+  const groups = await collectInstalledItems(params);
   let total = 0;
-  for (const agent of ALL_AGENTS) {
-    const installed = await getInstalledSkills(
-      agent,
-      scope
-    );
-    if (installed.length > 0) {
-      console.log(chalk8.blue(CODING_AGENTS[agent].name));
-      for (const skill of installed) {
-        console.log(`  ${chalk8.white(skill)}`);
-        total++;
-      }
-      console.log("");
+  let currentType = null;
+  for (const group of groups) {
+    if (group.type !== currentType) {
+      currentType = group.type;
+      const colorFn = TYPE_COLORS[group.type] ?? chalk8.white;
+      console.log(colorFn(`${group.type.toUpperCase()}S`));
     }
+    console.log(chalk8.blue(`  ${CODING_AGENTS[group.agent].name}`));
+    for (const slug of group.slugs) {
+      console.log(`    ${chalk8.white(slug)}`);
+      total++;
+    }
+    console.log("");
+  }
+  if (!params.types || params.types.includes("settings")) {
+    console.log(chalk8.gray(`Note: ${SETTINGS_NOT_DISCOVERABLE}`));
   }
   if (total === 0) {
-    console.log(chalk8.yellow("No skills installed"));
+    console.log(chalk8.yellow("No items installed"));
   } else {
     console.log(chalk8.gray(`Total: ${total} installed`));
   }
@@ -1112,41 +1899,25 @@ function groupByType(items) {
 import { Command as Command3 } from "commander";
 import chalk9 from "chalk";
 import ora6 from "ora";
-
-// src/utils/prompts.ts
-import inquirer from "inquirer";
-async function promptConfirm(message, defaultValue = true) {
-  const { confirmed } = await inquirer.prompt([
-    {
-      type: "confirm",
-      name: "confirmed",
-      message,
-      default: defaultValue
-    }
-  ]);
-  return confirmed;
-}
-
-// src/commands/remove.ts
-async function findInstalledAgents(slug, type, scope) {
+async function findInstalledAgents(slug, type, scope, cwd) {
   const handler = getHandler(type);
   if (!handler) return [];
   const agents = [];
   for (const agent of ALL_AGENTS) {
-    const installed = await handler.listInstalled(agent, scope);
+    const installed = await handler.listInstalled(agent, scope, cwd);
     if (installed.includes(slug)) {
       agents.push(agent);
     }
   }
   return agents;
 }
-async function removeFromAgents(slug, type, agents, scope) {
+async function removeFromAgents(slug, type, agents, scope, cwd) {
   const handler = getHandler(type);
   if (!handler) return 0;
   let successCount = 0;
   for (const agent of agents) {
     const spinner = ora6(`Removing from ${CODING_AGENTS[agent].name}...`).start();
-    const removed = await handler.uninstall(slug, agent, scope);
+    const removed = await handler.uninstall(slug, agent, scope, cwd);
     if (removed) {
       spinner.succeed(brand(`Removed from ${CODING_AGENTS[agent].name}`));
       successCount++;
@@ -1156,6 +1927,76 @@ async function removeFromAgents(slug, type, agents, scope) {
   }
   return successCount;
 }
+function validateRemoveRequest(name, options) {
+  if (!isValidSlug(name)) {
+    return `Invalid item name ${JSON.stringify(name)}: expected a slug matching ${SLUG_PATTERN.source} (at most ${MAX_SLUG_LENGTH} characters)`;
+  }
+  const optionError = validateScope(options.scope) || validateType(options.type);
+  if (optionError) return optionError;
+  if (!options.type) {
+    return "Please specify the content type with --type (skill, plugin, agent, hook, mcp, settings)";
+  }
+  if (options.agents && options.agents !== "all") {
+    const { unknown } = parseAgentsArgStrict(options.agents);
+    if (unknown.length > 0) {
+      return `Unknown agent(s): ${unknown.join(", ")}. Valid agents: ${ALL_AGENTS.join(", ")} or "all"`;
+    }
+  }
+  return null;
+}
+async function runRemove(name, options, cwd = process.cwd()) {
+  const requestError = validateRemoveRequest(name, options);
+  if (requestError) {
+    console.log(chalk9.red(requestError));
+    return 1;
+  }
+  const scope = options.scope ?? "project";
+  const type = options.type;
+  const handler = getHandler(type);
+  if (!handler) {
+    console.log(chalk9.red(`No handler found for type "${type}"`));
+    return 1;
+  }
+  let agents;
+  if (!options.agents) {
+    agents = await findInstalledAgents(name, type, scope, cwd);
+  } else if (options.agents === "all") {
+    agents = [...ALL_AGENTS];
+  } else {
+    agents = parseAgentsArgStrict(options.agents).agents;
+  }
+  if (agents.length === 0) {
+    if (type === "settings") {
+      console.log(chalk9.yellow(`Cannot detect where "${name}" is installed: ${SETTINGS_NOT_DISCOVERABLE}`));
+      console.log(chalk9.gray("Name the agents explicitly, e.g. --agents claude"));
+      return 1;
+    }
+    console.log(chalk9.yellow(`${type} "${name}" is not installed in ${scope} scope`));
+    return 0;
+  }
+  if (!options.yes) {
+    console.log(brand(`
+Will remove ${type} "${name}" from:`));
+    for (const agent of agents) {
+      console.log(`  - ${CODING_AGENTS[agent].name}`);
+    }
+    console.log("");
+    const answer = await confirm("Proceed with removal?");
+    const confirmed = !p.isCancel(answer) && answer;
+    if (!confirmed) {
+      console.log(chalk9.yellow("Removal cancelled"));
+      return 0;
+    }
+  }
+  const successCount = await removeFromAgents(name, type, agents, scope, cwd);
+  console.log("");
+  if (successCount > 0) {
+    console.log(brand(`Successfully removed from ${successCount} agent(s)`));
+    return 0;
+  }
+  console.log(chalk9.yellow("Nothing to remove"));
+  return 0;
+}
 var removeCommand = new Command3("remove").alias("rm").description("Remove an installed item (skill, plugin, agent, hook, mcp)").argument("<name>", "Name/slug of the item to remove").option("-t, --type <type>", "Content type: skill, agent, hook, mcp, plugin, settings").option(
   "-a, --agents <agents>",
   "Comma-separated coding agents or 'all'"
@@ -1165,53 +2006,8 @@ var removeCommand = new Command3("remove").alias("rm").description("Remove an in
   "project"
 ).option("-y, --yes", "Skip confirmation prompts").action(async (name, options) => {
   try {
-    const optionError = validateScope(options.scope) || validateType(options.type);
-    if (optionError) {
-      console.log(chalk9.red(optionError));
-      process.exit(1);
-    }
-    const scope = options.scope;
-    const type = options.type;
-    if (!type) {
-      console.log(
-        chalk9.yellow(`Please specify the content type with --type (skill, plugin, agent, hook, mcp, settings)`)
-      );
-      process.exit(1);
-    }
-    const handler = getHandler(type);
-    if (!handler) {
-      console.log(chalk9.red(`No handler found for type "${type}"`));
-      process.exit(1);
-    }
-    const agents = options.agents ? parseAgentsArg(options.agents, ALL_AGENTS) : await findInstalledAgents(name, type, scope);
-    if (agents.length === 0) {
-      console.log(
-        chalk9.yellow(`${type} "${name}" is not installed in ${scope} scope`)
-      );
-      process.exit(0);
-    }
-    if (!options.yes) {
-      console.log(brand(`
-Will remove ${type} "${name}" from:`));
-      for (const agent of agents) {
-        console.log(`  - ${CODING_AGENTS[agent].name}`);
-      }
-      console.log("");
-      const confirmed = await promptConfirm("Proceed with removal?");
-      if (!confirmed) {
-        console.log(chalk9.yellow("Removal cancelled"));
-        process.exit(0);
-      }
-    }
-    const successCount = await removeFromAgents(name, type, agents, scope);
-    console.log("");
-    if (successCount > 0) {
-      console.log(
-        brand(`Successfully removed from ${successCount} agent(s)`)
-      );
-    } else {
-      console.log(chalk9.yellow("Nothing to remove"));
-    }
+    const exitCode = await runRemove(name, options);
+    if (exitCode !== 0) process.exit(exitCode);
   } catch (error2) {
     handleCommandError(error2);
   }
@@ -1222,44 +2018,8 @@ import { Command as Command4 } from "commander";
 import chalk10 from "chalk";
 import ora7 from "ora";
 import { join as join4 } from "path";
-var initCommand = new Command4("init").description("Initialize coding agent configuration directories").option(
-  "-a, --agents <agents>",
-  "Comma-separated coding agents or 'all'",
-  "claude"
-).option("-y, --yes", "Skip confirmation prompts").action(async (options) => {
-  try {
-    const agents = parseAgentsArg(options.agents, ALL_AGENTS);
-    if (agents.length === 0) {
-      console.error(chalk10.red("No valid agents specified"));
-      process.exit(1);
-    }
-    console.log(brand("\nWill initialize configuration for:"));
-    for (const agent of agents) {
-      const path = getAgentPath(agent, "project");
-      console.log(`  - ${CODING_AGENTS[agent].name} \u2192 ${path}`);
-    }
-    console.log("");
-    if (!options.yes) {
-      const confirmed = await promptConfirm("Proceed?");
-      if (!confirmed) {
-        console.log(chalk10.yellow("Cancelled"));
-        process.exit(0);
-      }
-    }
-    for (const agent of agents) {
-      const spinner = ora7(`Initializing ${CODING_AGENTS[agent].name}...`).start();
-      const path = getAgentPath(agent, "project");
-      if (await exists(path)) {
-        spinner.info(
-          chalk10.gray(`${CODING_AGENTS[agent].name} already initialized`)
-        );
-        continue;
-      }
-      await ensureDir(path);
-      const readmePath = join4(path, "README.md");
-      await writeTextFile(
-        readmePath,
-        `# ${CODING_AGENTS[agent].name} Configuration
+function readmeFor(agent) {
+  return `# ${CODING_AGENTS[agent].name} Configuration
 
 This directory contains AI configuration files for ${CODING_AGENTS[agent].name}.
 
@@ -1269,14 +2029,65 @@ npx @danieldeusing/seedr add <skill-name> --agents ${agent}
 \`\`\`
 
 Browse available skills at https://seedr.danieldeusing.de
-`
-      );
+`;
+}
+async function initializeAgent(agent, cwd) {
+  const path = getAgentPath(agent, "project", cwd);
+  if (await exists(path)) return false;
+  await ensureDir(path);
+  await writeTextFile(join4(path, "README.md"), readmeFor(agent));
+  return true;
+}
+async function runInit(options, cwd = process.cwd()) {
+  const agentsArg = options.agents ?? "claude";
+  let agents;
+  if (agentsArg === "all") {
+    agents = [...ALL_AGENTS];
+  } else {
+    const parsed = parseAgentsArgStrict(agentsArg);
+    if (parsed.unknown.length > 0) {
+      console.error(chalk10.red(`Unknown agent(s): ${parsed.unknown.join(", ")}. Valid agents: ${ALL_AGENTS.join(", ")} or "all"`));
+      return 1;
+    }
+    agents = parsed.agents;
+  }
+  if (agents.length === 0) {
+    console.error(chalk10.red("No valid agents specified"));
+    return 1;
+  }
+  console.log(brand("\nWill initialize configuration for:"));
+  for (const agent of agents) {
+    console.log(`  - ${CODING_AGENTS[agent].name} \u2192 ${getAgentPath(agent, "project", cwd)}`);
+  }
+  console.log("");
+  if (!options.yes) {
+    const answer = await confirm("Proceed?");
+    const confirmed = !p.isCancel(answer) && answer;
+    if (!confirmed) {
+      console.log(chalk10.yellow("Cancelled"));
+      return 0;
+    }
+  }
+  for (const agent of agents) {
+    const spinner = ora7(`Initializing ${CODING_AGENTS[agent].name}...`).start();
+    if (await initializeAgent(agent, cwd)) {
       spinner.succeed(brand(`Initialized ${CODING_AGENTS[agent].name}`));
+    } else {
+      spinner.info(chalk10.gray(`${CODING_AGENTS[agent].name} already initialized`));
     }
-    console.log("");
-    console.log(
-      brand("Done! Use 'npx @danieldeusing/seedr add <skill>' to install skills.")
-    );
+  }
+  console.log("");
+  console.log(brand("Done! Use 'npx @danieldeusing/seedr add <skill>' to install skills."));
+  return 0;
+}
+var initCommand = new Command4("init").description("Initialize coding agent configuration directories").option(
+  "-a, --agents <agents>",
+  "Comma-separated coding agents or 'all'",
+  "claude"
+).option("-y, --yes", "Skip confirmation prompts").action(async (options) => {
+  try {
+    const exitCode = await runInit(options);
+    if (exitCode !== 0) process.exit(exitCode);
   } catch (error2) {
     handleCommandError(error2);
   }
@@ -1285,7 +2096,7 @@ Browse available skills at https://seedr.danieldeusing.de
 // package.json
 var package_default = {
   name: "@danieldeusing/seedr",
-  version: "0.1.87",
+  version: "0.1.88",
   description: "Seed your projects with AI configurations",
   type: "module",
   bin: {
@@ -1315,20 +2126,18 @@ var package_default = {
     "@clack/prompts": "^1.0.1",
     chalk: "^5.3.0",
     commander: "^14.0.0",
-    "gray-matter": "^4.0.3",
-    inquirer: "^13.0.0",
     ora: "^9.0.0"
   },
   devDependencies: {
     "@seedr/shared": "workspace:*",
-    "@types/inquirer": "^9.0.7",
     "@types/node": "^25.0.0",
     "@vitest/coverage-v8": "^4.1.0",
     memfs: "^4.14.0",
     tsup: "^8.3.0",
     tsx: "^4.19.0",
     typescript: "^5.7.0",
-    vitest: "^4.1.0"
+    vitest: "^4.1.0",
+    "@seedr/registry-ops": "workspace:*"
   },
   keywords: [
     "ai",