aweskill 0.1.8 → 0.2.1

package/dist/index.js

@@ -5,13 +5,13 @@ import { Command } from "commander";
 import { homedir as homedir2 } from "os";
 
 // src/commands/backup.ts
-import path3 from "path";
+import path4 from "path";
 
 // src/lib/backup.ts
-import { mkdtemp, mkdir, stat } from "fs/promises";
+import { gunzipSync, gzipSync } from "zlib";
+import { cp, mkdtemp, mkdir, readdir as readdir2, readFile as readFile2, stat, writeFile } from "fs/promises";
 import { tmpdir } from "os";
-import path2 from "path";
-import { spawn } from "child_process";
+import path3 from "path";
 
 // src/lib/fs.ts
 import { access } from "fs/promises";
@@ -24,30 +24,116 @@ async function pathExists(targetPath) {
   }
 }
 
+// src/lib/hygiene.ts
+import { lstat, readFile, readdir } from "fs/promises";
+import path from "path";
+import { parse } from "yaml";
+function relativeLabel(rootDir, targetPath) {
+  return path.relative(rootDir, targetPath).split(path.sep).join("/");
+}
+async function scanStoreHygiene(options) {
+  const includeSkills = options.includeSkills ?? true;
+  const includeBundles = options.includeBundles ?? true;
+  const findings = [];
+  const validSkills = [];
+  const validBundles = [];
+  if (includeSkills && await pathExists(options.skillsDir)) {
+    const entries = await readdir(options.skillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = path.join(options.skillsDir, entry.name);
+      const stats = await lstat(entryPath);
+      if (stats.isDirectory() || stats.isSymbolicLink()) {
+        const hasSKILLMd = await pathExists(path.join(entryPath, "SKILL.md"));
+        if (hasSKILLMd) {
+          validSkills.push({ name: entry.name, path: entryPath, hasSKILLMd: true });
+        } else {
+          findings.push({
+            kind: "missing-skill-md",
+            path: entryPath,
+            relativePath: relativeLabel(options.rootDir, entryPath)
+          });
+        }
+        continue;
+      }
+      findings.push({
+        kind: "unexpected-skill-entry",
+        path: entryPath,
+        relativePath: relativeLabel(options.rootDir, entryPath)
+      });
+    }
+  }
+  if (includeBundles && await pathExists(options.bundlesDir)) {
+    const entries = await readdir(options.bundlesDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = path.join(options.bundlesDir, entry.name);
+      if (!entry.isFile() || !entry.name.endsWith(".yaml")) {
+        findings.push({
+          kind: "unexpected-bundle-entry",
+          path: entryPath,
+          relativePath: relativeLabel(options.rootDir, entryPath)
+        });
+        continue;
+      }
+      try {
+        const parsed = parse(await readFile(entryPath, "utf8"));
+        validBundles.push({
+          name: String(parsed?.name ?? entry.name.replace(/\.yaml$/, "")).trim().toLowerCase(),
+          skills: Array.isArray(parsed?.skills) ? parsed.skills.map((skill) => String(skill).trim().toLowerCase()).filter(Boolean).sort() : []
+        });
+      } catch {
+        findings.push({
+          kind: "invalid-bundle-yaml",
+          path: entryPath,
+          relativePath: relativeLabel(options.rootDir, entryPath)
+        });
+      }
+    }
+  }
+  validSkills.sort((left, right) => left.name.localeCompare(right.name));
+  validBundles.sort((left, right) => left.name.localeCompare(right.name));
+  findings.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+  return { validSkills, validBundles, findings };
+}
+function formatHygieneHint(findings) {
+  if (findings.length === 0) {
+    return [];
+  }
+  return [
+    `Suspicious store entries detected: ${findings.length}`,
+    `Run "aweskill doctor clean" to inspect them, or "aweskill doctor clean --apply" to remove them.`
+  ];
+}
+
 // src/lib/path.ts
 import { homedir } from "os";
-import path from "path";
+import path2 from "path";
 function sanitizeName(input) {
   return input.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+/, "").replace(/-+$/, "").slice(0, 80);
 }
+function stripVersionSuffix(input) {
+  return input.replace(/-\d+(?:\.\d+)*$/, "");
+}
+function getDuplicateMatchKey(input) {
+  return stripVersionSuffix(sanitizeName(input)).replace(/[^a-z0-9]+/g, "");
+}
 function expandHomePath(targetPath, homeDir = homedir()) {
   if (targetPath === "~") {
     return homeDir;
   }
   if (targetPath.startsWith("~/")) {
-    return path.join(homeDir, targetPath.slice(2));
+    return path2.join(homeDir, targetPath.slice(2));
   }
   return targetPath;
 }
 function getAweskillPaths(homeDir) {
-  const rootDir = path.join(homeDir, ".aweskill");
+  const rootDir = path2.join(homeDir, ".aweskill");
   return {
     homeDir,
     rootDir,
-    skillsDir: path.join(rootDir, "skills"),
-    dupSkillsDir: path.join(rootDir, "dup_skills"),
-    backupDir: path.join(rootDir, "backup"),
-    bundlesDir: path.join(rootDir, "bundles")
+    skillsDir: path2.join(rootDir, "skills"),
+    dupSkillsDir: path2.join(rootDir, "dup_skills"),
+    backupDir: path2.join(rootDir, "backup"),
+    bundlesDir: path2.join(rootDir, "bundles")
   };
 }
 function uniqueSorted(items) {
@@ -58,44 +144,212 @@ function splitCommaValues(input) {
 }
 
 // src/lib/backup.ts
+var TAR_BLOCK_SIZE = 512;
 function formatTimestamp(date) {
   return date.toISOString().replace(/:/g, "-").replace(/\.\d{3}Z$/, "Z");
 }
-async function runTar(args) {
-  await new Promise((resolve, reject) => {
-    const child = spawn("tar", args, { stdio: "ignore" });
-    child.on("error", reject);
-    child.on("exit", (code) => {
-      if (code === 0) {
-        resolve();
-        return;
+function formatBackupLabel(includeBundles) {
+  return includeBundles ? "skills and bundles" : "skills";
+}
+function normalizeTarPath(entryPath) {
+  return entryPath.split(path3.sep).join("/");
+}
+function encodeOctal(value, length) {
+  const encoded = value.toString(8).padStart(length - 1, "0");
+  return Buffer.from(`${encoded}\0`, "ascii");
+}
+function writeString(field, value) {
+  field.fill(0);
+  field.write(value, 0, Math.min(Buffer.byteLength(value, "utf8"), field.length), "utf8");
+}
+function splitTarName(name) {
+  if (Buffer.byteLength(name, "utf8") <= 100) {
+    return { name, prefix: "" };
+  }
+  const parts = name.split("/");
+  while (parts.length > 1) {
+    const candidatePrefix = parts.slice(0, -1).join("/");
+    const candidateName = parts[parts.length - 1] ?? "";
+    if (Buffer.byteLength(candidateName, "utf8") <= 100 && Buffer.byteLength(candidatePrefix, "utf8") <= 155) {
+      return { name: candidateName, prefix: candidatePrefix };
+    }
+    parts.shift();
+  }
+  throw new Error(`Path is too long for tar header: ${name}`);
+}
+function createTarHeader(entry) {
+  const header = Buffer.alloc(TAR_BLOCK_SIZE, 0);
+  const entryName = entry.type === "directory" && !entry.name.endsWith("/") ? `${entry.name}/` : entry.name;
+  const { name, prefix } = splitTarName(entryName);
+  writeString(header.subarray(0, 100), name);
+  encodeOctal(entry.mode, 8).copy(header, 100);
+  encodeOctal(0, 8).copy(header, 108);
+  encodeOctal(0, 8).copy(header, 116);
+  encodeOctal(entry.type === "file" ? entry.data?.length ?? 0 : 0, 12).copy(header, 124);
+  encodeOctal(Math.floor(Date.now() / 1e3), 12).copy(header, 136);
+  header.fill(32, 148, 156);
+  header[156] = entry.type === "directory" ? "5".charCodeAt(0) : "0".charCodeAt(0);
+  writeString(header.subarray(257, 263), "ustar");
+  writeString(header.subarray(263, 265), "00");
+  writeString(header.subarray(345, 500), prefix);
+  let checksum = 0;
+  for (const byte of header) {
+    checksum += byte;
+  }
+  Buffer.from(checksum.toString(8).padStart(6, "0") + "\0 ", "ascii").copy(header, 148);
+  return header;
+}
+function buildTarArchive(entries) {
+  const chunks = [];
+  for (const entry of entries) {
+    chunks.push(createTarHeader(entry));
+    if (entry.type === "file") {
+      const data = entry.data ?? Buffer.alloc(0);
+      chunks.push(data);
+      const remainder = data.length % TAR_BLOCK_SIZE;
+      if (remainder !== 0) {
+        chunks.push(Buffer.alloc(TAR_BLOCK_SIZE - remainder, 0));
       }
-      reject(new Error(`tar exited with code ${code ?? "unknown"}`));
+    }
+  }
+  chunks.push(Buffer.alloc(TAR_BLOCK_SIZE * 2, 0));
+  return Buffer.concat(chunks);
+}
+function isZeroBlock(block) {
+  for (const byte of block) {
+    if (byte !== 0) {
+      return false;
+    }
+  }
+  return true;
+}
+function readTarString(block, start, end) {
+  const value = block.subarray(start, end).toString("utf8");
+  return value.replace(/\0.*$/, "");
+}
+function readTarNumber(block, start, end) {
+  const value = readTarString(block, start, end).trim();
+  return value === "" ? 0 : Number.parseInt(value, 8);
+}
+function safeExtractPath(baseDir, entryName) {
+  const normalized = entryName.replace(/\\/g, "/");
+  if (normalized.startsWith("/") || normalized.split("/").includes("..")) {
+    throw new Error(`Archive contains unsafe path: ${entryName}`);
+  }
+  return path3.join(baseDir, ...normalized.split("/").filter(Boolean));
+}
+async function extractTarArchive(buffer, destinationDir) {
+  let offset = 0;
+  while (offset + TAR_BLOCK_SIZE <= buffer.length) {
+    const header = buffer.subarray(offset, offset + TAR_BLOCK_SIZE);
+    offset += TAR_BLOCK_SIZE;
+    if (isZeroBlock(header)) {
+      break;
+    }
+    const name = readTarString(header, 0, 100);
+    const prefix = readTarString(header, 345, 500);
+    const entryName = prefix ? `${prefix}/${name}` : name;
+    const typeFlag = String.fromCharCode(header[156] || "0".charCodeAt(0));
+    const size = readTarNumber(header, 124, 136);
+    const outputPath = safeExtractPath(destinationDir, entryName);
+    if (typeFlag === "5") {
+      await mkdir(outputPath, { recursive: true });
+      continue;
+    }
+    const fileData = buffer.subarray(offset, offset + size);
+    offset += Math.ceil(size / TAR_BLOCK_SIZE) * TAR_BLOCK_SIZE;
+    await mkdir(path3.dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, fileData);
+  }
+}
+async function collectTarEntries(rootDir, relativeDir) {
+  const entries = [
+    {
+      name: normalizeTarPath(relativeDir),
+      type: "directory",
+      mode: 493
+    }
+  ];
+  const absoluteDir = path3.join(rootDir, relativeDir);
+  const directoryEntries = await readdir2(absoluteDir, { withFileTypes: true });
+  for (const entry of directoryEntries) {
+    const absolutePath = path3.join(absoluteDir, entry.name);
+    const archivePath = normalizeTarPath(path3.join(relativeDir, entry.name));
+    if (entry.isDirectory()) {
+      entries.push(...await collectTarEntries(rootDir, path3.join(relativeDir, entry.name)));
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    const entryStats = await stat(absolutePath);
+    entries.push({
+      name: archivePath,
+      type: "file",
+      mode: entryStats.mode & 511,
+      data: await readFile2(absolutePath)
     });
-  });
+  }
+  return entries;
 }
-function formatBackupLabel(includeBundles) {
-  return includeBundles ? "skills and bundles" : "skills";
+async function collectTarEntriesForFile(rootDir, relativeFilePath) {
+  const absolutePath = path3.join(rootDir, relativeFilePath);
+  const entryStats = await stat(absolutePath);
+  return [{
+    name: normalizeTarPath(relativeFilePath),
+    type: "file",
+    mode: entryStats.mode & 511,
+    data: await readFile2(absolutePath)
+  }];
 }
-function archiveEntries(homeDir, includeBundles) {
+async function archiveEntries(homeDir, includeBundles) {
   const { rootDir, skillsDir, bundlesDir } = getAweskillPaths(homeDir);
-  return includeBundles ? [path2.relative(rootDir, skillsDir), path2.relative(rootDir, bundlesDir)] : [path2.relative(rootDir, skillsDir)];
+  const entries = [];
+  const hygiene = await scanStoreHygiene({ rootDir, skillsDir, bundlesDir, includeBundles });
+  if (hygiene.validSkills.length > 0) {
+    entries.push({ name: "skills", type: "directory", mode: 493 });
+    for (const skill of hygiene.validSkills) {
+      entries.push(...await collectTarEntries(rootDir, path3.relative(rootDir, skill.path)));
+    }
+  }
+  if (includeBundles && hygiene.validBundles.length > 0) {
+    entries.push({ name: "bundles", type: "directory", mode: 493 });
+    for (const bundle of hygiene.validBundles) {
+      entries.push(...await collectTarEntriesForFile(rootDir, path3.join("bundles", `${bundle.name}.yaml`)));
+    }
+  }
+  return entries;
 }
 async function createSkillsBackupArchive(homeDir, options = {}) {
-  const { rootDir, backupDir } = getAweskillPaths(homeDir);
+  const { backupDir } = getAweskillPaths(homeDir);
   const includeBundles = options.includeBundles ?? false;
   const archivePath = await resolveBackupArchivePath(backupDir, options.archivePath);
-  await mkdir(path2.dirname(archivePath), { recursive: true });
-  await runTar(["-czf", archivePath, "-C", rootDir, ...archiveEntries(homeDir, includeBundles)]);
+  await mkdir(path3.dirname(archivePath), { recursive: true });
+  const tarArchive = buildTarArchive(await archiveEntries(homeDir, includeBundles));
+  await writeFile(archivePath, gzipSync(tarArchive));
   return archivePath;
 }
 async function extractSkillsArchive(archivePath) {
-  const tempDir = await mkdtemp(path2.join(tmpdir(), "aweskill-restore-"));
-  await runTar(["-xzf", archivePath, "-C", tempDir]);
+  const tempDir = await mkdtemp(path3.join(tmpdir(), "aweskill-restore-"));
+  const sourceStats = await stat(archivePath);
+  if (sourceStats.isDirectory()) {
+    const sourceSkillsDir = path3.join(archivePath, "skills");
+    const sourceBundlesDir = path3.join(archivePath, "bundles");
+    if (!await pathExists(sourceSkillsDir)) {
+      throw new Error(`Restore source does not contain a skills/ directory: ${archivePath}`);
+    }
+    await cp(sourceSkillsDir, path3.join(tempDir, "skills"), { recursive: true });
+    if (await pathExists(sourceBundlesDir)) {
+      await cp(sourceBundlesDir, path3.join(tempDir, "bundles"), { recursive: true });
+    }
+  } else {
+    const archiveBuffer = await readFile2(archivePath);
+    await extractTarArchive(gunzipSync(archiveBuffer), tempDir);
+  }
   return {
     tempDir,
-    extractedSkillsDir: path2.join(tempDir, "skills"),
-    extractedBundlesDir: path2.join(tempDir, "bundles")
+    extractedSkillsDir: path3.join(tempDir, "skills"),
+    extractedBundlesDir: path3.join(tempDir, "bundles")
   };
 }
 async function resolveBackupArchivePath(backupDir, requestedPath) {
@@ -113,13 +367,13 @@ async function resolveBackupArchivePath(backupDir, requestedPath) {
 }
 async function nextBackupArchivePath(backupDir) {
   const base = `skills-${formatTimestamp(/* @__PURE__ */ new Date())}`;
-  const primary = path2.join(backupDir, `${base}.tar.gz`);
+  const primary = path3.join(backupDir, `${base}.tar.gz`);
   if (!await pathExists(primary)) {
     return primary;
   }
   let index = 1;
   while (true) {
-    const candidate = path2.join(backupDir, `${base}-${index}.tar.gz`);
+    const candidate = path3.join(backupDir, `${base}-${index}.tar.gz`);
     if (!await pathExists(candidate)) {
       return candidate;
     }
@@ -129,22 +383,28 @@ async function nextBackupArchivePath(backupDir) {
 
 // src/commands/backup.ts
 async function runBackup(context, options = {}) {
+  const includeBundles = options.includeBundles ?? true;
+  const { rootDir, skillsDir, bundlesDir } = getAweskillPaths(context.homeDir);
+  const { findings } = await scanStoreHygiene({ rootDir, skillsDir, bundlesDir, includeBundles });
   const archivePath = await createSkillsBackupArchive(context.homeDir, {
-    archivePath: options.archivePath ? path3.resolve(context.cwd, expandHomePath(options.archivePath, context.homeDir)) : void 0,
-    includeBundles: options.includeBundles
+    archivePath: options.archivePath ? path4.resolve(context.cwd, expandHomePath(options.archivePath, context.homeDir)) : void 0,
+    includeBundles
   });
-  context.write(`Backed up ${formatBackupLabel(options.includeBundles ?? false)} to ${archivePath}`);
+  context.write(`Backed up ${formatBackupLabel(includeBundles)} to ${archivePath}`);
+  if (findings.length > 0) {
+    context.write(`Skipped suspicious store entries during backup: ${findings.map((finding) => finding.relativePath).join(", ")}`);
+  }
   return { archivePath };
 }
 
 // src/lib/bundles.ts
-import { mkdir as mkdir3, readFile, readdir as readdir2, rm, writeFile } from "fs/promises";
-import path5 from "path";
-import { parse, stringify } from "yaml";
+import { mkdir as mkdir3, readFile as readFile3, readdir as readdir4, rm, writeFile as writeFile2 } from "fs/promises";
+import path6 from "path";
+import { parse as parse2, stringify } from "yaml";
 
 // src/lib/skills.ts
-import { mkdir as mkdir2, readdir } from "fs/promises";
-import path4 from "path";
+import { mkdir as mkdir2, readdir as readdir3 } from "fs/promises";
+import path5 from "path";
 async function ensureHomeLayout(homeDir) {
   const paths = getAweskillPaths(homeDir);
   await mkdir2(paths.rootDir, { recursive: true });
@@ -154,7 +414,7 @@ async function ensureHomeLayout(homeDir) {
   await mkdir2(paths.bundlesDir, { recursive: true });
 }
 function getSkillPath(homeDir, skillName) {
-  return path4.join(getAweskillPaths(homeDir).skillsDir, sanitizeName(skillName));
+  return path5.join(getAweskillPaths(homeDir).skillsDir, sanitizeName(skillName));
 }
 async function listSkills(homeDir) {
   const skillsDir = getAweskillPaths(homeDir).skillsDir;
@@ -164,21 +424,21 @@ async function listSkillEntriesInDirectory(skillsDir) {
   if (!await pathExists(skillsDir)) {
     return [];
   }
-  const entries = await readdir(skillsDir, { withFileTypes: true });
+  const entries = await readdir3(skillsDir, { withFileTypes: true });
   const skills = await Promise.all(
     entries.filter((entry) => entry.isDirectory() || entry.isSymbolicLink()).map(async (entry) => {
-      const skillPath = path4.join(skillsDir, entry.name);
+      const skillPath = path5.join(skillsDir, entry.name);
       return {
         name: entry.name,
         path: skillPath,
-        hasSKILLMd: await pathExists(path4.join(skillPath, "SKILL.md"))
+        hasSKILLMd: await pathExists(path5.join(skillPath, "SKILL.md"))
       };
     })
   );
   return skills.sort((left, right) => left.name.localeCompare(right.name));
 }
 async function assertSkillSource(sourcePath) {
-  const skillReadme = path4.join(sourcePath, "SKILL.md");
+  const skillReadme = path5.join(sourcePath, "SKILL.md");
   if (!await pathExists(skillReadme)) {
     throw new Error(`Skill source must contain SKILL.md: ${sourcePath}`);
   }
@@ -186,13 +446,22 @@ async function assertSkillSource(sourcePath) {
 async function skillExists(homeDir, skillName) {
   return pathExists(getSkillPath(homeDir, skillName));
 }
+function getSkillSuspicionReason(skill) {
+  if (!skill.hasSKILLMd) {
+    return "missing-skill-md";
+  }
+  if (skill.name.startsWith(".")) {
+    return "reserved-name";
+  }
+  return null;
+}
 
 // src/lib/bundles.ts
 function bundleFilePath(homeDir, bundleName) {
-  return path5.join(getAweskillPaths(homeDir).bundlesDir, `${sanitizeName(bundleName)}.yaml`);
+  return path6.join(getAweskillPaths(homeDir).bundlesDir, `${sanitizeName(bundleName)}.yaml`);
 }
 function bundleFilePathInDirectory(bundlesDir, bundleName) {
-  return path5.join(bundlesDir, `${sanitizeName(bundleName)}.yaml`);
+  return path6.join(bundlesDir, `${sanitizeName(bundleName)}.yaml`);
 }
 function normalizeBundle(raw, fallbackName) {
   const data = raw ?? {};
@@ -207,7 +476,7 @@ async function listBundles(homeDir) {
 }
 async function listBundlesInDirectory(bundlesDir) {
   await mkdir3(bundlesDir, { recursive: true });
-  const entries = await readdir2(bundlesDir, { withFileTypes: true });
+  const entries = await readdir4(bundlesDir, { withFileTypes: true });
   const bundles = await Promise.all(
     entries.filter((entry) => entry.isFile() && entry.name.endsWith(".yaml")).map(async (entry) => readBundleFromDirectory(bundlesDir, entry.name.replace(/\.yaml$/, "")))
   );
@@ -215,19 +484,19 @@ async function listBundlesInDirectory(bundlesDir) {
 }
 async function readBundle(homeDir, bundleName) {
   const filePath = bundleFilePath(homeDir, bundleName);
-  const content = await readFile(filePath, "utf8");
-  return normalizeBundle(parse(content), bundleName);
+  const content = await readFile3(filePath, "utf8");
+  return normalizeBundle(parse2(content), bundleName);
 }
 async function readBundleFromDirectory(bundlesDir, bundleName) {
   const filePath = bundleFilePathInDirectory(bundlesDir, bundleName);
-  const content = await readFile(filePath, "utf8");
-  return normalizeBundle(parse(content), bundleName);
+  const content = await readFile3(filePath, "utf8");
+  return normalizeBundle(parse2(content), bundleName);
 }
 async function writeBundle(homeDir, bundle) {
   const normalized = normalizeBundle(bundle, bundle.name);
   const filePath = bundleFilePath(homeDir, normalized.name);
-  await mkdir3(path5.dirname(filePath), { recursive: true });
-  await writeFile(filePath, stringify(normalized), "utf8");
+  await mkdir3(path6.dirname(filePath), { recursive: true });
+  await writeFile2(filePath, stringify(normalized), "utf8");
   return normalized;
 }
 async function createBundle(homeDir, bundleName) {
@@ -259,13 +528,13 @@ async function deleteBundle(homeDir, bundleName) {
 }
 
 // src/lib/templates.ts
-import path6 from "path";
+import path7 from "path";
 import { fileURLToPath } from "url";
 async function getTemplateBundlesDir() {
-  const moduleDir = path6.dirname(fileURLToPath(import.meta.url));
+  const moduleDir = path7.dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    path6.resolve(moduleDir, "..", "..", "resources", "bundle_templates"),
-    path6.resolve(moduleDir, "..", "resources", "bundle_templates")
+    path7.resolve(moduleDir, "..", "..", "resources", "bundle_templates"),
+    path7.resolve(moduleDir, "..", "resources", "bundle_templates")
   ];
   for (const candidate of candidates) {
     if (await pathExists(candidate)) {
@@ -352,8 +621,236 @@ async function runBundleAddTemplate(context, bundleName) {
 }
 
 // src/lib/import.ts
-import { cp, lstat, mkdir as mkdir4, readlink, readdir as readdir3, rename, rm as rm2, stat as stat2 } from "fs/promises";
-import path7 from "path";
+import { cp as cp3, lstat as lstat3, mkdir as mkdir5, readlink as readlink2, readdir as readdir6, stat as stat2 } from "fs/promises";
+import path9 from "path";
+
+// src/lib/symlink.ts
+import { cp as cp2, lstat as lstat2, mkdir as mkdir4, readFile as readFile4, readdir as readdir5, readlink, rm as rm2, symlink, unlink, writeFile as writeFile3 } from "fs/promises";
+import path8 from "path";
+var COPY_MARKER = ".aweskill-projection.json";
+async function tryLstat(targetPath) {
+  try {
+    return await lstat2(targetPath);
+  } catch {
+    return null;
+  }
+}
+async function readCopyMarker(targetPath) {
+  try {
+    const content = await readFile4(path8.join(targetPath, COPY_MARKER), "utf8");
+    const parsed = JSON.parse(content);
+    return parsed.managedBy === "aweskill" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function getDirectoryLinkTypeForPlatform(platform = process.platform) {
+  return platform === "win32" ? "junction" : "dir";
+}
+async function defaultDirectoryLinkCreator(sourcePath, targetPath) {
+  const linkTarget = path8.relative(path8.dirname(targetPath), sourcePath) || ".";
+  await symlink(linkTarget, targetPath, getDirectoryLinkTypeForPlatform());
+}
+var directoryLinkCreator = defaultDirectoryLinkCreator;
+function shouldFallbackToCopy(error, platform = process.platform) {
+  if (platform !== "win32") {
+    return false;
+  }
+  const code = typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+  return code === "EPERM" || code === "EACCES" || code === "EINVAL" || code === "UNKNOWN";
+}
+async function inspectProjectionTarget(targetPath, options = {}) {
+  const existing = await tryLstat(targetPath);
+  if (!existing) {
+    return { kind: "missing" };
+  }
+  const centralRoot = options.centralSkillsDir ? path8.resolve(options.centralSkillsDir) : void 0;
+  const expectedSource = options.sourcePath ? path8.resolve(options.sourcePath) : void 0;
+  if (existing.isSymbolicLink()) {
+    const currentTarget = await readlink(targetPath);
+    const resolvedCurrent = path8.resolve(path8.dirname(targetPath), currentTarget);
+    if (centralRoot && resolvedCurrent.startsWith(centralRoot)) {
+      return {
+        kind: "managed_symlink",
+        sourcePath: resolvedCurrent,
+        matchesSource: expectedSource ? resolvedCurrent === expectedSource : true
+      };
+    }
+    return { kind: "foreign_symlink", sourcePath: resolvedCurrent };
+  }
+  if (existing.isDirectory()) {
+    const marker = await readCopyMarker(targetPath);
+    if (marker) {
+      return {
+        kind: "managed_copy",
+        sourcePath: marker.sourcePath,
+        matchesSource: expectedSource ? marker.sourcePath === expectedSource : true
+      };
+    }
+    return { kind: "directory" };
+  }
+  return { kind: "file" };
+}
+async function createSkillSymlink(sourcePath, targetPath, options = {}) {
+  await mkdir4(path8.dirname(targetPath), { recursive: true });
+  const existing = await tryLstat(targetPath);
+  if (existing?.isSymbolicLink()) {
+    const currentTarget = await readlink(targetPath);
+    const resolvedCurrent = path8.resolve(path8.dirname(targetPath), currentTarget);
+    if (resolvedCurrent === path8.resolve(sourcePath)) {
+      return { status: "skipped", mode: "symlink" };
+    }
+    await unlink(targetPath);
+  } else if (existing) {
+    if (existing.isDirectory()) {
+      const marker = await readCopyMarker(targetPath);
+      if (marker?.sourcePath === path8.resolve(sourcePath)) {
+        return { status: "skipped", mode: "copy" };
+      }
+    }
+    if (!options.allowReplaceExisting) {
+      throw new Error(`Refusing to overwrite non-symlink target: ${targetPath}`);
+    }
+    await rm2(targetPath, { force: true, recursive: true });
+  }
+  try {
+    await directoryLinkCreator(sourcePath, targetPath);
+    return { status: "created", mode: "symlink" };
+  } catch (error) {
+    if (!shouldFallbackToCopy(error)) {
+      throw error;
+    }
+    return createSkillCopy(sourcePath, targetPath, options);
+  }
+}
+async function createSkillCopy(sourcePath, targetPath, options = {}) {
+  await mkdir4(path8.dirname(targetPath), { recursive: true });
+  const existing = await tryLstat(targetPath);
+  if (existing?.isSymbolicLink()) {
+    await unlink(targetPath);
+  } else if (existing) {
+    const marker2 = await readCopyMarker(targetPath);
+    if (marker2?.sourcePath === path8.resolve(sourcePath)) {
+      return { status: "skipped", mode: "copy" };
+    }
+    if (!marker2 && !options.allowReplaceExisting) {
+      throw new Error(`Refusing to overwrite unmanaged directory: ${targetPath}`);
+    }
+    await rm2(targetPath, { force: true, recursive: true });
+  }
+  await cp2(sourcePath, targetPath, { recursive: true });
+  const marker = { managedBy: "aweskill", sourcePath: path8.resolve(sourcePath) };
+  await writeFile3(path8.join(targetPath, COPY_MARKER), JSON.stringify(marker, null, 2), "utf8");
+  return { status: "created", mode: "copy" };
+}
+async function removeManagedProjection(targetPath) {
+  const existing = await tryLstat(targetPath);
+  if (!existing) {
+    return false;
+  }
+  if (existing.isSymbolicLink()) {
+    await unlink(targetPath);
+    return true;
+  }
+  if (existing.isDirectory()) {
+    const marker = await readCopyMarker(targetPath);
+    if (marker) {
+      await rm2(targetPath, { force: true, recursive: true });
+      return true;
+    }
+  }
+  return false;
+}
+async function removeProjectionTarget(targetPath, options = {}) {
+  const status = await inspectProjectionTarget(targetPath, { centralSkillsDir: options.centralSkillsDir });
+  if (status.kind === "missing") {
+    return false;
+  }
+  if (status.kind === "managed_symlink") {
+    await unlink(targetPath);
+    return true;
+  }
+  if (status.kind === "managed_copy" || status.kind === "directory") {
+    if (status.kind === "directory" && !options.force) {
+      return false;
+    }
+    await rm2(targetPath, { force: true, recursive: true });
+    return true;
+  }
+  if (status.kind === "foreign_symlink") {
+    if (!options.force) {
+      return false;
+    }
+    await unlink(targetPath);
+    return true;
+  }
+  if (status.kind === "file") {
+    if (!options.force) {
+      return false;
+    }
+    await rm2(targetPath, { force: true });
+    return true;
+  }
+  return false;
+}
+async function listManagedSkillNames(skillsDir, centralSkillsDir) {
+  const result = /* @__PURE__ */ new Map();
+  try {
+    const entries = await readdir5(skillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const targetPath = path8.join(skillsDir, entry.name);
+      const stats = await tryLstat(targetPath);
+      if (stats?.isSymbolicLink()) {
+        try {
+          const currentTarget = await readlink(targetPath);
+          const resolvedCurrent = path8.resolve(path8.dirname(targetPath), currentTarget);
+          if (resolvedCurrent.startsWith(path8.resolve(centralSkillsDir))) {
+            result.set(entry.name, "symlink");
+          }
+        } catch {
+          result.set(entry.name, "symlink");
+        }
+        continue;
+      }
+      if (stats?.isDirectory()) {
+        const marker = await readCopyMarker(targetPath);
+        if (marker) {
+          result.set(entry.name, "copy");
+        }
+      }
+    }
+  } catch {
+    return result;
+  }
+  return result;
+}
+async function listBrokenSymlinkNames(skillsDir) {
+  const result = /* @__PURE__ */ new Set();
+  try {
+    const entries = await readdir5(skillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const targetPath = path8.join(skillsDir, entry.name);
+      const stats = await tryLstat(targetPath);
+      if (!stats?.isSymbolicLink()) {
+        continue;
+      }
+      try {
+        const currentTarget = await readlink(targetPath);
+        const resolvedCurrent = path8.resolve(path8.dirname(targetPath), currentTarget);
+        if (!await tryLstat(resolvedCurrent)) {
+          result.add(entry.name);
+        }
+      } catch {
+        result.add(entry.name);
+      }
+    }
+  } catch {
+    return result;
+  }
+  return result;
+}
+
+// src/lib/import.ts
 var MissingSymlinkSourceError = class extends Error {
   sourcePath;
   resolvedSourcePath;
@@ -365,15 +862,15 @@ var MissingSymlinkSourceError = class extends Error {
   }
 };
 async function resolveImportSource(sourcePath) {
-  const statResult = await lstat(sourcePath);
+  const statResult = await lstat3(sourcePath);
   if (!statResult.isSymbolicLink()) {
     return {
       effectiveSourcePath: sourcePath,
       isSymlinkSource: false
     };
   }
-  const linkTarget = await readlink(sourcePath);
-  const resolvedSourcePath = path7.resolve(path7.dirname(sourcePath), linkTarget);
+  const linkTarget = await readlink2(sourcePath);
+  const resolvedSourcePath = path9.resolve(path9.dirname(sourcePath), linkTarget);
   if (!await pathExists(resolvedSourcePath)) {
     throw new MissingSymlinkSourceError(sourcePath, resolvedSourcePath);
   }
@@ -385,37 +882,32 @@ async function resolveImportSource(sourcePath) {
 async function mergeMissingEntries(sourcePath, destinationPath) {
   const sourceStat = await stat2(sourcePath);
   if (sourceStat.isDirectory()) {
-    await mkdir4(destinationPath, { recursive: true });
-    const entries = await readdir3(sourcePath, { withFileTypes: true });
+    await mkdir5(destinationPath, { recursive: true });
+    const entries = await readdir6(sourcePath, { withFileTypes: true });
     for (const entry of entries) {
-      await mergeMissingEntries(path7.join(sourcePath, entry.name), path7.join(destinationPath, entry.name));
+      await mergeMissingEntries(path9.join(sourcePath, entry.name), path9.join(destinationPath, entry.name));
     }
     return;
   }
   if (await pathExists(destinationPath)) {
     return;
   }
-  await mkdir4(path7.dirname(destinationPath), { recursive: true });
-  await cp(sourcePath, destinationPath, { recursive: false, errorOnExist: true, force: false });
+  await mkdir5(path9.dirname(destinationPath), { recursive: true });
+  await cp3(sourcePath, destinationPath, { recursive: false, errorOnExist: true, force: false });
 }
 async function copyIntoDestination(sourcePath, destination, override) {
   if (!override && await pathExists(destination)) {
     await mergeMissingEntries(sourcePath, destination);
     return;
   }
-  await cp(sourcePath, destination, { recursive: true, errorOnExist: false, force: override });
+  await cp3(sourcePath, destination, { recursive: true, errorOnExist: false, force: override });
 }
-async function moveIntoDestination(sourcePath, destination, override) {
-  if (!await pathExists(destination)) {
-    await rename(sourcePath, destination);
-    return;
-  }
-  if (override) {
-    await cp(sourcePath, destination, { recursive: true, errorOnExist: false, force: true });
-    await rm2(sourcePath, { recursive: true, force: true });
-    return;
+async function relinkImportedSource(sourcePath, destination) {
+  if (path9.resolve(sourcePath) === path9.resolve(destination)) {
+    return void 0;
   }
-  await mergeMissingEntries(sourcePath, destination);
+  await createSkillSymlink(destination, sourcePath, { allowReplaceExisting: true });
+  return sourcePath;
 }
 async function importBatchSources(options) {
   const seen = /* @__PURE__ */ new Set();
@@ -424,6 +916,7 @@ async function importBatchSources(options) {
   const overwritten = [];
   const warnings = [];
   const errors = [];
+  const linkedSources = [];
   let missingSources = 0;
   for (const source of options.sources) {
     if (seen.has(source.name)) {
@@ -432,22 +925,31 @@ async function importBatchSources(options) {
     }
     seen.add(source.name);
     const alreadyExists = await skillExists(options.homeDir, source.name);
-    if (alreadyExists && !options.override) {
-      skipped.push(source.name);
-      continue;
-    }
     try {
-      const result = await importSkill({
-        homeDir: options.homeDir,
-        sourcePath: source.path,
-        mode: options.mode,
-        override: options.override
-      });
-      warnings.push(...result.warnings);
-      if (alreadyExists) {
-        overwritten.push(source.name);
+      if (!alreadyExists || options.override) {
+        const result = await importSkill({
+          homeDir: options.homeDir,
+          sourcePath: source.path,
+          override: options.override,
+          linkSource: options.linkSource
+        });
+        warnings.push(...result.warnings);
+        if (result.linkedSourcePath) {
+          linkedSources.push(result.name);
+        }
+        if (alreadyExists) {
+          overwritten.push(source.name);
+        } else {
+          imported.push(source.name);
+        }
       } else {
-        imported.push(source.name);
+        if (options.linkSource) {
+          const linkedPath = await relinkImportedSource(source.path, getSkillPath(options.homeDir, source.name));
+          if (linkedPath) {
+            linkedSources.push(source.name);
+          }
+        }
+        skipped.push(source.name);
       }
     } catch (error) {
       if (error instanceof MissingSymlinkSourceError) {
@@ -462,17 +964,17 @@ async function importBatchSources(options) {
       throw error;
     }
   }
-  return { imported, skipped, overwritten, warnings, errors, missingSources };
+  return { imported, skipped, overwritten, warnings, errors, missingSources, linkedSources };
 }
 async function listImportableChildren(sourceRoot) {
-  const entries = await readdir3(sourceRoot, { withFileTypes: true });
+  const entries = await readdir6(sourceRoot, { withFileTypes: true });
   const sources = [];
   for (const entry of entries) {
     if (!(entry.isDirectory() || entry.isSymbolicLink())) {
       continue;
     }
-    const childPath = path7.join(sourceRoot, entry.name);
-    if (await pathExists(path7.join(childPath, "SKILL.md"))) {
+    const childPath = path9.join(sourceRoot, entry.name);
+    if (await pathExists(path9.join(childPath, "SKILL.md"))) {
       sources.push({
         name: sanitizeName(entry.name),
         path: childPath
@@ -491,22 +993,19 @@ async function listImportableChildren(sourceRoot) {
 async function importSkill(options) {
   const { effectiveSourcePath, isSymlinkSource } = await resolveImportSource(options.sourcePath);
   await assertSkillSource(effectiveSourcePath);
-  const skillName = sanitizeName(path7.basename(options.sourcePath));
+  const skillName = sanitizeName(path9.basename(options.sourcePath));
   if (!skillName) {
     throw new Error(`Unable to infer skill name from path: ${options.sourcePath}`);
   }
   const destination = getSkillPath(options.homeDir, skillName);
-  await mkdir4(path7.dirname(destination), { recursive: true });
+  await mkdir5(path9.dirname(destination), { recursive: true });
   const warnings = [];
   if (isSymlinkSource) {
     warnings.push(`Source ${options.sourcePath} is a symlink; copied from ${effectiveSourcePath} to ${destination}`);
   }
-  if (options.mode === "mv" && !isSymlinkSource) {
-    await moveIntoDestination(effectiveSourcePath, destination, options.override ?? false);
-  } else {
-    await copyIntoDestination(effectiveSourcePath, destination, options.override ?? false);
-  }
-  return { name: skillName, destination, warnings };
+  await copyIntoDestination(effectiveSourcePath, destination, options.override ?? false);
+  const linkedSourcePath = options.linkSource ? await relinkImportedSource(options.sourcePath, destination) : void 0;
+  return { name: skillName, destination, warnings, linkedSourcePath };
 }
 async function importScannedSkills(options) {
   return importBatchSources({
@@ -515,21 +1014,23 @@ async function importScannedSkills(options) {
       name: candidate.name,
       path: candidate.path
     })),
-    mode: options.mode,
-    override: options.override
+    override: options.override,
+    linkSource: options.linkSource
   });
 }
 async function importPath(options) {
-  if (await pathExists(path7.join(options.sourcePath, "SKILL.md"))) {
-    const skillName = sanitizeName(path7.basename(options.sourcePath));
+  if (await pathExists(path9.join(options.sourcePath, "SKILL.md"))) {
+    const skillName = sanitizeName(path9.basename(options.sourcePath));
     const alreadyExisted = skillName ? await skillExists(options.homeDir, skillName) : false;
     if (alreadyExisted && !options.override) {
+      const linkedSourcePath = options.linkSource ? await relinkImportedSource(options.sourcePath, getSkillPath(options.homeDir, skillName)) : void 0;
       return {
         kind: "single",
         alreadyExisted: true,
         name: skillName,
         destination: getSkillPath(options.homeDir, skillName),
-        warnings: []
+        warnings: [],
+        linkedSourcePath
       };
     }
     const result = await importSkill(options);
@@ -542,18 +1043,18 @@ async function importPath(options) {
   const batchResult = await importBatchSources({
     homeDir: options.homeDir,
     sources,
-    mode: options.mode,
-    override: options.override
+    override: options.override,
+    linkSource: options.linkSource
   });
   return { kind: "batch", ...batchResult };
 }
 
 // src/lib/scanner.ts
-import { access as access2, lstat as lstat2, readdir as readdir4, readlink as readlink2 } from "fs/promises";
-import path9 from "path";
+import { access as access2, lstat as lstat4, readdir as readdir7, readlink as readlink3 } from "fs/promises";
+import path11 from "path";
 
 // src/lib/agents.ts
-import path8 from "path";
+import path10 from "path";
 function defineAgent(id, displayName, options) {
   return {
     id,
@@ -568,238 +1069,238 @@ function defineAgent(id, displayName, options) {
 }
 var AGENTS = {
   adal: defineAgent("adal", "AdaL", {
-    rootDir: (homeDir) => path8.join(homeDir, ".adal"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".adal", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".adal", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".adal"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".adal", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".adal", "skills")
   }),
   amp: defineAgent("amp", "Amp", {
-    rootDir: (homeDir) => path8.join(homeDir, ".agents"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".agents", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".agents", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".agents"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".agents", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".agents", "skills")
   }),
   antigravity: defineAgent("antigravity", "Antigravity", {
-    rootDir: (homeDir) => path8.join(homeDir, ".gemini", "antigravity"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".gemini", "antigravity", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".gemini", "antigravity", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".gemini", "antigravity"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".gemini", "antigravity", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".gemini", "antigravity", "skills")
   }),
   augment: defineAgent("augment", "Augment", {
-    rootDir: (homeDir) => path8.join(homeDir, ".augment"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".augment", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".augment", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".augment"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".augment", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".augment", "skills")
   }),
   bob: defineAgent("bob", "IBM Bob", {
-    rootDir: (homeDir) => path8.join(homeDir, ".bob"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".bob", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".bob", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".bob"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".bob", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".bob", "skills")
   }),
   "claude-code": defineAgent("claude-code", "Claude Code", {
-    rootDir: (homeDir) => path8.join(homeDir, ".claude"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".claude", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".claude", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".claude"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".claude", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".claude", "skills")
   }),
   cline: defineAgent("cline", "Cline", {
-    rootDir: (homeDir) => path8.join(homeDir, ".cline"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".cline", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".cline", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".cline"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".cline", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".cline", "skills")
   }),
   codebuddy: defineAgent("codebuddy", "CodeBuddy", {
-    rootDir: (homeDir) => path8.join(homeDir, ".codebuddy"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".codebuddy", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".codebuddy", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".codebuddy"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".codebuddy", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".codebuddy", "skills")
   }),
   "command-code": defineAgent("command-code", "Command Code", {
-    rootDir: (homeDir) => path8.join(homeDir, ".commandcode"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".commandcode", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".commandcode", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".commandcode"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".commandcode", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".commandcode", "skills")
   }),
   continue: defineAgent("continue", "Continue", {
-    rootDir: (homeDir) => path8.join(homeDir, ".continue"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".continue", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".continue", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".continue"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".continue", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".continue", "skills")
   }),
   codex: defineAgent("codex", "Codex", {
-    rootDir: (homeDir) => path8.join(homeDir, ".codex"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".codex", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".codex", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".codex"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".codex", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".codex", "skills")
   }),
   copilot: defineAgent("copilot", "GitHub Copilot", {
-    rootDir: (homeDir) => path8.join(homeDir, ".copilot"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".copilot", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".copilot", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".copilot"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".copilot", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".copilot", "skills")
   }),
   cortex: defineAgent("cortex", "Cortex Code", {
-    rootDir: (homeDir) => path8.join(homeDir, ".snowflake", "cortex"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".snowflake", "cortex", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".cortex", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".snowflake", "cortex"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".snowflake", "cortex", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".cortex", "skills")
   }),
   crush: defineAgent("crush", "Crush", {
-    rootDir: (homeDir) => path8.join(homeDir, ".config", "crush"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".config", "crush", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".config", "crush", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".config", "crush"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".config", "crush", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".config", "crush", "skills")
   }),
   cursor: defineAgent("cursor", "Cursor", {
-    rootDir: (homeDir) => path8.join(homeDir, ".cursor"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".cursor", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".cursor", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".cursor"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".cursor", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".cursor", "skills")
   }),
   deepagents: defineAgent("deepagents", "Deep Agents", {
-    rootDir: (homeDir) => path8.join(homeDir, ".deepagents"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".deepagents", "agent", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".deepagents", "agent", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".deepagents"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".deepagents", "agent", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".deepagents", "agent", "skills")
   }),
   droid: defineAgent("droid", "Droid", {
-    rootDir: (homeDir) => path8.join(homeDir, ".factory"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".factory", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".factory", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".factory"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".factory", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".factory", "skills")
   }),
   firebender: defineAgent("firebender", "Firebender", {
-    rootDir: (homeDir) => path8.join(homeDir, ".firebender"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".firebender", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".firebender", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".firebender"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".firebender", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".firebender", "skills")
   }),
   "gemini-cli": defineAgent("gemini-cli", "Gemini CLI", {
-    rootDir: (homeDir) => path8.join(homeDir, ".gemini"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".gemini", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".gemini", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".gemini"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".gemini", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".gemini", "skills")
   }),
   "github-copilot": defineAgent("github-copilot", "GitHub Copilot", {
-    rootDir: (homeDir) => path8.join(homeDir, ".copilot"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".copilot", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".copilot", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".copilot"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".copilot", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".copilot", "skills")
   }),
   goose: defineAgent("goose", "Goose", {
-    rootDir: (homeDir) => path8.join(homeDir, ".goose"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".goose", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".goose", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".goose"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".goose", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".goose", "skills")
   }),
   "iflow-cli": defineAgent("iflow-cli", "iFlow CLI", {
-    rootDir: (homeDir) => path8.join(homeDir, ".iflow"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".iflow", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".iflow", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".iflow"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".iflow", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".iflow", "skills")
   }),
   junie: defineAgent("junie", "Junie", {
-    rootDir: (homeDir) => path8.join(homeDir, ".junie"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".junie", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".junie", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".junie"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".junie", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".junie", "skills")
   }),
   kilo: defineAgent("kilo", "Kilo Code", {
-    rootDir: (homeDir) => path8.join(homeDir, ".kilocode"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".kilocode", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".kilocode", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".kilocode"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".kilocode", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".kilocode", "skills")
   }),
   "kiro-cli": defineAgent("kiro-cli", "Kiro CLI", {
-    rootDir: (homeDir) => path8.join(homeDir, ".kiro"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".kiro", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".kiro", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".kiro"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".kiro", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".kiro", "skills")
   }),
   "kilo-code": defineAgent("kilo-code", "Kilo Code", {
-    rootDir: (homeDir) => path8.join(homeDir, ".kilocode"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".kilocode", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".kilocode", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".kilocode"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".kilocode", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".kilocode", "skills")
   }),
   "kimi-cli": defineAgent("kimi-cli", "Kimi Code CLI", {
-    rootDir: (homeDir) => path8.join(homeDir, ".kimi"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".kimi", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".kimi", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".kimi"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".kimi", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".kimi", "skills")
   }),
   kode: defineAgent("kode", "Kode", {
-    rootDir: (homeDir) => path8.join(homeDir, ".kode"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".kode", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".kode", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".kode"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".kode", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".kode", "skills")
   }),
   mcpjam: defineAgent("mcpjam", "MCPJam", {
-    rootDir: (homeDir) => path8.join(homeDir, ".mcpjam"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".mcpjam", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".mcpjam", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".mcpjam"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".mcpjam", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".mcpjam", "skills")
   }),
   "mistral-vibe": defineAgent("mistral-vibe", "Mistral Vibe", {
-    rootDir: (homeDir) => path8.join(homeDir, ".vibe"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".vibe", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".vibe", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".vibe"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".vibe", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".vibe", "skills")
   }),
   mux: defineAgent("mux", "Mux", {
-    rootDir: (homeDir) => path8.join(homeDir, ".mux"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".mux", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".mux", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".mux"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".mux", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".mux", "skills")
   }),
   neovate: defineAgent("neovate", "Neovate", {
-    rootDir: (homeDir) => path8.join(homeDir, ".neovate"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".neovate", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".neovate", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".neovate"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".neovate", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".neovate", "skills")
   }),
   openclaw: defineAgent("openclaw", "OpenClaw", {
-    rootDir: (homeDir) => path8.join(homeDir, ".openclaw"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".openclaw", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".openclaw", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".openclaw"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".openclaw", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".openclaw", "skills")
   }),
   "openclaude-ide": defineAgent("openclaude-ide", "OpenClaude IDE", {
-    rootDir: (homeDir) => path8.join(homeDir, ".openclaude"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".openclaude", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".openclaude", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".openclaude"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".openclaude", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".openclaude", "skills")
   }),
   openhands: defineAgent("openhands", "OpenHands", {
-    rootDir: (homeDir) => path8.join(homeDir, ".openhands"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".openhands", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".openhands", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".openhands"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".openhands", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".openhands", "skills")
   }),
   opencode: defineAgent("opencode", "OpenCode", {
-    rootDir: (homeDir) => path8.join(homeDir, ".opencode"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".opencode", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".opencode", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".opencode"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".opencode", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".opencode", "skills")
   }),
   pi: defineAgent("pi", "Pi", {
-    rootDir: (homeDir) => path8.join(homeDir, ".pi", "agent"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".pi", "agent", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".pi", "agent", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".pi", "agent"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".pi", "agent", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".pi", "agent", "skills")
   }),
   pochi: defineAgent("pochi", "Pochi", {
-    rootDir: (homeDir) => path8.join(homeDir, ".pochi"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".pochi", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".pochi", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".pochi"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".pochi", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".pochi", "skills")
   }),
   qoder: defineAgent("qoder", "Qoder", {
-    rootDir: (homeDir) => path8.join(homeDir, ".qoder"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".qoder", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".qoder", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".qoder"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".qoder", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".qoder", "skills")
   }),
   "qwen-code": defineAgent("qwen-code", "Qwen Code", {
-    rootDir: (homeDir) => path8.join(homeDir, ".qwen"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".qwen", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".qwen", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".qwen"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".qwen", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".qwen", "skills")
   }),
   replit: defineAgent("replit", "Replit", {
-    rootDir: (homeDir) => path8.join(homeDir, ".config", "replit"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".agent", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".config", "replit"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".agent", "skills")
   }),
   roo: defineAgent("roo", "Roo Code", {
-    rootDir: (homeDir) => path8.join(homeDir, ".roo"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".roo", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".roo", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".roo"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".roo", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".roo", "skills")
   }),
   trae: defineAgent("trae", "Trae", {
-    rootDir: (homeDir) => path8.join(homeDir, ".trae"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".trae", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".trae", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".trae"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".trae", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".trae", "skills")
   }),
   "trae-cn": defineAgent("trae-cn", "Trae CN", {
-    rootDir: (homeDir) => path8.join(homeDir, ".trae-cn"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".trae-cn", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".trae-cn", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".trae-cn"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".trae-cn", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".trae-cn", "skills")
   }),
   warp: defineAgent("warp", "Warp", {
-    rootDir: (homeDir) => path8.join(homeDir, ".warp"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".warp", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".warp", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".warp"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".warp", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".warp", "skills")
   }),
   windsurf: defineAgent("windsurf", "Windsurf", {
-    rootDir: (homeDir) => path8.join(homeDir, ".codeium", "windsurf"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".codeium", "windsurf", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".codeium", "windsurf", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".codeium", "windsurf"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".codeium", "windsurf", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".codeium", "windsurf", "skills")
   }),
   zencoder: defineAgent("zencoder", "Zencoder", {
-    rootDir: (homeDir) => path8.join(homeDir, ".zencoder"),
-    globalSkillsDir: (homeDir) => path8.join(homeDir, ".zencoder", "skills"),
-    projectSkillsDir: (projectDir) => path8.join(projectDir, ".zencoder", "skills")
+    rootDir: (homeDir) => path10.join(homeDir, ".zencoder"),
+    globalSkillsDir: (homeDir) => path10.join(homeDir, ".zencoder", "skills"),
+    projectSkillsDir: (projectDir) => path10.join(projectDir, ".zencoder", "skills")
   })
 };
 function listSupportedAgents() {
@@ -808,6 +1309,13 @@ function listSupportedAgents() {
 function listSupportedAgentIds() {
   return listSupportedAgents().map((agent) => agent.id);
 }
+function formatDetectedAgentsForScope(scope, agents, projectDir) {
+  const countLabel = `${agents.length} agent${agents.length === 1 ? "" : "s"}`;
+  if (scope === "global") {
+    return `Detected ${countLabel} for global scope: ${agents.join(", ")}`;
+  }
+  return `Detected ${countLabel} for project scope at ${projectDir}: ${agents.join(", ")}`;
+}
 function supportsScope(agentId, scope) {
   const definition = getAgentDefinition(agentId);
   return scope === "global" ? definition.supportsGlobal : definition.supportsProject;
@@ -844,27 +1352,96 @@ async function detectInstalledAgents(options) {
   }
   return installed;
 }
-
-// src/lib/scanner.ts
-async function hasSkillReadme(skillDir) {
-  try {
-    await access2(path9.join(skillDir, "SKILL.md"));
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function isSymlinkPath(targetPath) {
-  try {
-    return (await lstat2(targetPath)).isSymbolicLink();
-  } catch {
-    return false;
+async function listSupportedAgentsWithGlobalStatus(homeDir) {
+  const results = [];
+  for (const agent of listSupportedAgents()) {
+    if (!agent.supportsGlobal || !agent.globalSkillsDir) {
+      results.push({
+        id: agent.id,
+        displayName: agent.displayName,
+        installed: false
+      });
+      continue;
+    }
+    const skillsDir = agent.globalSkillsDir(homeDir);
+    results.push({
+      id: agent.id,
+      displayName: agent.displayName,
+      installed: await pathExists(agent.rootDir(homeDir)),
+      skillsDir
+    });
+  }
+  return results;
+}
+async function detectAgentsForListingScope(homeDir, scope, projectDir) {
+  const installed = [];
+  for (const agent of listSupportedAgents()) {
+    if (scope === "global") {
+      if (!agent.supportsGlobal) {
+        continue;
+      }
+      const rootPath = agent.rootDir(homeDir);
+      if (await pathExists(rootPath)) {
+        installed.push(agent.id);
+      }
+    } else {
+      if (!agent.supportsProject || !projectDir) {
+        continue;
+      }
+      const skillsPath = resolveAgentSkillsDir(agent.id, "project", projectDir);
+      if (await pathExists(skillsPath)) {
+        installed.push(agent.id);
+      }
+    }
+  }
+  return installed;
+}
+async function resolveAgentsForListingOrSync(options) {
+  const wantsAll = options.requestedAgents.length === 0 || options.requestedAgents.includes("all");
+  if (!wantsAll) {
+    const agents2 = uniqueSorted(
+      options.requestedAgents.map((agent) => {
+        if (!isAgentId(agent)) {
+          throw new Error(`Unsupported agent: ${agent}`);
+        }
+        if (!supportsScope(agent, options.scope)) {
+          throw new Error(`Agent ${agent} does not support ${options.scope} scope.`);
+        }
+        return agent;
+      })
+    );
+    return { agents: agents2, explicit: true };
+  }
+  const agents = await detectAgentsForListingScope(options.homeDir, options.scope, options.projectDir);
+  return { agents, explicit: false };
+}
+function formatNoAgentsDetectedForScope(scope, projectDir) {
+  if (scope === "global") {
+    return "No agents detected for global scope (no supported agent installation directories were found). Install an agent or pass --agent <id> to inspect a specific agent.";
+  }
+  return `No agents detected for project scope at ${projectDir}. Add project-local agent skill directories or pass --agent <id> to inspect a specific agent.`;
+}
+
+// src/lib/scanner.ts
+async function hasSkillReadme(skillDir) {
+  try {
+    await access2(path11.join(skillDir, "SKILL.md"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function isSymlinkPath(targetPath) {
+  try {
+    return (await lstat4(targetPath)).isSymbolicLink();
+  } catch {
+    return false;
   }
 }
 async function resolveSymlinkSource(targetPath) {
   try {
-    const linkTarget = await readlink2(targetPath);
-    const sourcePath = path9.resolve(path9.dirname(targetPath), linkTarget);
+    const linkTarget = await readlink3(targetPath);
+    const sourcePath = path11.resolve(path11.dirname(targetPath), linkTarget);
     return {
       sourcePath,
       isBroken: !await pathExists(sourcePath)
@@ -877,13 +1454,13 @@ async function resolveSymlinkSource(targetPath) {
 }
 async function scanDirectory(baseDir, agentId, scope, projectDir) {
   try {
-    const entries = await readdir4(baseDir, { withFileTypes: true });
+    const entries = await readdir7(baseDir, { withFileTypes: true });
     const candidates = [];
     for (const entry of entries) {
       if (!entry.isDirectory() && !entry.isSymbolicLink()) {
         continue;
       }
-      const fullPath = path9.join(baseDir, entry.name);
+      const fullPath = path11.join(baseDir, entry.name);
       const isSymlink = await isSymlinkPath(fullPath);
       const symlinkInfo = isSymlink ? await resolveSymlinkSource(fullPath) : { isBroken: false };
       if (!await hasSkillReadme(fullPath) && !symlinkInfo.isBroken) {
@@ -905,33 +1482,54 @@ async function scanDirectory(baseDir, agentId, scope, projectDir) {
     return [];
   }
 }
+function uniqueSorted2(items) {
+  return [...new Set(items)].sort((left, right) => left.localeCompare(right));
+}
+function resolveRequestedAgents(requestedAgents, scope) {
+  if (requestedAgents.length === 0 || requestedAgents.includes("all")) {
+    return listSupportedAgentIds().filter((agentId) => supportsScope(agentId, scope));
+  }
+  return uniqueSorted2(
+    requestedAgents.map((agent) => {
+      if (!isAgentId(agent)) {
+        throw new Error(`Unsupported agent: ${agent}`);
+      }
+      if (!supportsScope(agent, scope)) {
+        throw new Error(`Agent ${agent} does not support ${scope} scope.`);
+      }
+      return agent;
+    })
+  );
+}
 async function scanSkills(options) {
   const results = [];
-  for (const agent of listSupportedAgents()) {
-    if (supportsScope(agent.id, "global")) {
-      results.push(...await scanDirectory(agent.globalSkillsDir(options.homeDir), agent.id, "global"));
-    }
-    for (const projectDir of options.projectDirs ?? []) {
-      if (supportsScope(agent.id, "project")) {
-        results.push(...await scanDirectory(agent.projectSkillsDir(projectDir), agent.id, "project", projectDir));
-      }
-    }
+  const agents = resolveRequestedAgents(options.agents ?? [], options.scope);
+  for (const agentId of agents) {
+    const baseDir = options.scope === "global" ? options.homeDir : options.projectDir;
+    const skillsDir = resolveAgentSkillsDir(agentId, options.scope, baseDir);
+    results.push(...await scanDirectory(skillsDir, agentId, options.scope, options.projectDir));
   }
   return results.sort((left, right) => left.path.localeCompare(right.path));
 }
 
 // src/commands/import.ts
 async function runImport(context, options) {
+  if (options.keepSource && options.linkSource) {
+    throw new Error("Choose either --keep-source or --link-source, not both.");
+  }
+  const linkSource = options.scan ? !options.keepSource : Boolean(options.linkSource);
   if (options.scan) {
     const candidates = await scanSkills({
       homeDir: context.homeDir,
-      projectDirs: [context.cwd]
+      scope: options.scope ?? "global",
+      agents: options.agents,
+      projectDir: (options.scope ?? "global") === "project" ? options.projectDir ?? context.cwd : void 0
     });
     const result2 = await importScannedSkills({
       homeDir: context.homeDir,
       candidates,
-      mode: options.mode,
-      override: options.override
+      override: options.override,
+      linkSource
     });
     for (const warning of result2.warnings) {
       context.write(`Warning: ${warning}`);
@@ -949,6 +1547,11 @@ async function runImport(context, options) {
     if (result2.missingSources > 0) {
       context.write(`Missing source files: ${result2.missingSources}`);
     }
+    if (linkSource) {
+      context.write(`Replaced ${result2.linkedSources.length} scanned source paths with aweskill-managed projections.`);
+    } else {
+      context.write("Source paths were kept in place. Re-run without --keep-source to replace scanned agent skills with aweskill-managed projections.");
+    }
     return result2;
   }
   if (!options.sourcePath) {
@@ -957,8 +1560,8 @@ async function runImport(context, options) {
   const result = await importPath({
     homeDir: context.homeDir,
     sourcePath: options.sourcePath,
-    mode: options.mode,
-    override: options.override
+    override: options.override,
+    linkSource
   });
   if (result.kind === "single") {
     for (const warning of result.warnings) {
@@ -971,6 +1574,11 @@ async function runImport(context, options) {
     } else {
       context.write(`Imported ${result.name}`);
     }
+    if (result.linkedSourcePath) {
+      context.write(`Replaced source path with an aweskill-managed projection: ${result.linkedSourcePath}`);
+    } else {
+      context.write("Source was kept in place. Re-run with --link-source to replace it with an aweskill-managed projection.");
+    }
     return result;
   }
   for (const warning of result.warnings) {
@@ -989,150 +1597,16 @@ async function runImport(context, options) {
   if (result.missingSources > 0) {
     context.write(`Missing source files: ${result.missingSources}`);
   }
-  return result;
-}
-
-// src/lib/symlink.ts
-import { cp as cp2, lstat as lstat3, mkdir as mkdir5, readFile as readFile2, readdir as readdir5, readlink as readlink3, rm as rm3, symlink, unlink, writeFile as writeFile2 } from "fs/promises";
-import path10 from "path";
-var COPY_MARKER = ".aweskill-projection.json";
-async function tryLstat(targetPath) {
-  try {
-    return await lstat3(targetPath);
-  } catch {
-    return null;
-  }
-}
-async function readCopyMarker(targetPath) {
-  try {
-    const content = await readFile2(path10.join(targetPath, COPY_MARKER), "utf8");
-    const parsed = JSON.parse(content);
-    return parsed.managedBy === "aweskill" ? parsed : null;
-  } catch {
-    return null;
-  }
-}
-async function assertProjectionTargetSafe(mode, sourcePath, targetPath, options = {}) {
-  const existing = await tryLstat(targetPath);
-  if (!existing) {
-    return;
-  }
-  if (mode === "symlink") {
-    if (!existing.isSymbolicLink()) {
-      if (options.allowReplaceExisting) {
-        return;
-      }
-      throw new Error(`Refusing to overwrite non-symlink target: ${targetPath}`);
-    }
-    const currentTarget = await readlink3(targetPath);
-    const resolvedCurrent = path10.resolve(path10.dirname(targetPath), currentTarget);
-    if (resolvedCurrent === path10.resolve(sourcePath)) {
-      return;
-    }
-    return;
-  }
-  if (existing.isSymbolicLink()) {
-    return;
-  }
-  const marker = await readCopyMarker(targetPath);
-  if (!marker) {
-    if (options.allowReplaceExisting) {
-      return;
-    }
-    throw new Error(`Refusing to overwrite unmanaged directory: ${targetPath}`);
-  }
-}
-async function createSkillSymlink(sourcePath, targetPath, options = {}) {
-  await mkdir5(path10.dirname(targetPath), { recursive: true });
-  const existing = await tryLstat(targetPath);
-  if (existing?.isSymbolicLink()) {
-    const currentTarget = await readlink3(targetPath);
-    const resolvedCurrent = path10.resolve(path10.dirname(targetPath), currentTarget);
-    if (resolvedCurrent === path10.resolve(sourcePath)) {
-      return "skipped";
-    }
-    await unlink(targetPath);
-  } else if (existing) {
-    if (options.allowReplaceExisting) {
-      await rm3(targetPath, { force: true, recursive: true });
-    } else {
-      throw new Error(`Refusing to overwrite non-symlink target: ${targetPath}`);
-    }
-  }
-  const linkTarget = path10.relative(path10.dirname(targetPath), sourcePath) || ".";
-  await symlink(linkTarget, targetPath, "dir");
-  return "created";
-}
-async function createSkillCopy(sourcePath, targetPath, options = {}) {
-  await mkdir5(path10.dirname(targetPath), { recursive: true });
-  const existing = await tryLstat(targetPath);
-  if (existing?.isSymbolicLink()) {
-    await unlink(targetPath);
-  } else if (existing) {
-    const marker2 = await readCopyMarker(targetPath);
-    if (!marker2) {
-      if (!options.allowReplaceExisting) {
-        throw new Error(`Refusing to overwrite unmanaged directory: ${targetPath}`);
-      }
-    }
-    await rm3(targetPath, { force: true, recursive: true });
-  }
-  await cp2(sourcePath, targetPath, { recursive: true });
-  const marker = { managedBy: "aweskill", sourcePath: path10.resolve(sourcePath) };
-  await writeFile2(path10.join(targetPath, COPY_MARKER), JSON.stringify(marker, null, 2), "utf8");
-  return "created";
-}
-async function removeManagedProjection(targetPath) {
-  const existing = await tryLstat(targetPath);
-  if (!existing) {
-    return false;
-  }
-  if (existing.isSymbolicLink()) {
-    await unlink(targetPath);
-    return true;
-  }
-  if (existing.isDirectory()) {
-    const marker = await readCopyMarker(targetPath);
-    if (marker) {
-      await rm3(targetPath, { force: true, recursive: true });
-      return true;
-    }
-  }
-  return false;
-}
-async function listManagedSkillNames(skillsDir, centralSkillsDir) {
-  const result = /* @__PURE__ */ new Map();
-  try {
-    const entries = await readdir5(skillsDir, { withFileTypes: true });
-    for (const entry of entries) {
-      const targetPath = path10.join(skillsDir, entry.name);
-      if (entry.isSymbolicLink()) {
-        try {
-          const currentTarget = await readlink3(targetPath);
-          const resolvedCurrent = path10.resolve(path10.dirname(targetPath), currentTarget);
-          if (resolvedCurrent.startsWith(path10.resolve(centralSkillsDir))) {
-            result.set(entry.name, "symlink");
-          }
-        } catch {
-          result.set(entry.name, "symlink");
-        }
-        continue;
-      }
-      if (entry.isDirectory()) {
-        const marker = await readCopyMarker(targetPath);
-        if (marker) {
-          result.set(entry.name, "copy");
-        }
-      }
-    }
-  } catch {
-    return result;
+  if (linkSource) {
+    context.write(`Replaced ${result.linkedSources.length} source paths with aweskill-managed projections.`);
+  } else {
+    context.write("Source paths were kept in place. Re-run with --link-source to replace them with aweskill-managed projections.");
   }
   return result;
 }
 
-// src/commands/check.ts
-var DEFAULT_PREVIEW_COUNT = 5;
+// src/commands/disable.ts
+import path12 from "path";
 function getProjectDir(context, explicitProjectDir) {
   return explicitProjectDir ?? context.cwd;
 }
@@ -1157,125 +1631,6 @@ async function resolveAgentsForScope(context, requestedAgents, scope, projectDir
     })
   );
 }
-function formatSkillBlockWithSummary(title, skills, verbose = false) {
-  if (skills.length === 0) {
-    return [`No skills found for ${title.replace(/:$/, "").toLowerCase()}.`];
-  }
-  const lines = [title];
-  const categories = [
-    { title: "  linked", marker: "\u2713", key: "linked" },
-    { title: "  duplicate", marker: "!", key: "duplicate" },
-    { title: "  new", marker: "+", key: "new" }
-  ];
-  for (const category of categories) {
-    const entries = skills.filter((skill) => skill.category === category.key);
-    lines.push(`${category.title}: ${entries.length}`);
-    const preview = verbose ? entries : entries.slice(0, DEFAULT_PREVIEW_COUNT);
-    for (const skill of preview) {
-      lines.push(`    ${category.marker} ${skill.name} ${skill.path}`);
-    }
-    if (!verbose && entries.length > preview.length) {
-      lines.push(`    ... and ${entries.length - preview.length} more (use --verbose to show all)`);
-    }
-  }
-  return lines;
-}
-async function runCheck(context, options) {
-  const lines = [];
-  const centralSkillEntries = await listSkills(context.homeDir);
-  const centralSkills = new Set(centralSkillEntries.map((skill) => skill.name));
-  const projectDir = options.scope === "project" ? getProjectDir(context, options.projectDir) : void 0;
-  const agents = await resolveAgentsForScope(context, options.agents, options.scope, projectDir);
-  const updated = [];
-  const skipped = [];
-  let importedCount = 0;
-  for (const agentId of agents) {
-    const baseDir = options.scope === "global" ? context.homeDir : projectDir;
-    const skillsDir = resolveAgentSkillsDir(agentId, options.scope, baseDir);
-    const managed = await listManagedSkillNames(skillsDir, getAweskillPaths(context.homeDir).skillsDir);
-    const skills = await listSkillEntriesInDirectory(skillsDir);
-    const checked = skills.map((skill) => {
-      let category = "new";
-      if (managed.has(skill.name)) {
-        category = "linked";
-      } else if (centralSkills.has(skill.name)) {
-        category = "duplicate";
-      }
-      return {
-        name: skill.name,
-        path: skill.path,
-        category,
-        hasSKILLMd: skill.hasSKILLMd
-      };
-    });
-    if (options.update) {
-      for (const skill of checked) {
-        if (skill.category === "linked") {
-          continue;
-        }
-        if (!skill.hasSKILLMd) {
-          context.write(`Warning: Skipping ${agentId}:${skill.name}; missing SKILL.md in ${skill.path}`);
-          skipped.push(`${agentId}:${skill.name}`);
-          continue;
-        }
-        if (skill.category === "new") {
-          await importSkill({
-            homeDir: context.homeDir,
-            sourcePath: skill.path,
-            mode: "mv"
-          });
-          centralSkills.add(skill.name);
-          importedCount += 1;
-        }
-        await createSkillSymlink(getSkillPath(context.homeDir, skill.name), skill.path, {
-          allowReplaceExisting: true
-        });
-        updated.push(`${agentId}:${skill.name}`);
-      }
-    }
-    const title = options.scope === "global" ? `Global skills for ${agentId}:` : `Project skills for ${agentId} (${projectDir}):`;
-    lines.push("");
-    lines.push(...formatSkillBlockWithSummary(title, checked, options.verbose));
-  }
-  if (options.update) {
-    lines.push("");
-    lines.push(`Updated ${updated.length} skills`);
-    if (importedCount > 0) {
-      lines.push(`Imported ${importedCount} new skills into the central repo`);
-    }
-    if (skipped.length > 0) {
-      lines.push(`Skipped ${skipped.length} entries: ${skipped.join(", ")}`);
-    }
-  }
-  context.write(lines.join("\n").trim());
-  return { agents, updated, importedCount, skipped };
-}
-
-// src/commands/disable.ts
-function getProjectDir2(context, explicitProjectDir) {
-  return explicitProjectDir ?? context.cwd;
-}
-async function resolveAgentsForScope2(context, requestedAgents, scope, projectDir) {
-  if (requestedAgents.length === 0 || requestedAgents.includes("all")) {
-    const detected = await detectInstalledAgents({
-      homeDir: context.homeDir,
-      projectDir: scope === "project" ? projectDir : void 0
-    });
-    const candidates = detected.length > 0 ? detected : listSupportedAgentIds();
-    return candidates.filter((agentId) => supportsScope(agentId, scope));
-  }
-  return uniqueSorted(
-    requestedAgents.map((agent) => {
-      if (!isAgentId(agent)) {
-        throw new Error(`Unsupported agent: ${agent}`);
-      }
-      if (!supportsScope(agent, scope)) {
-        throw new Error(`Agent ${agent} does not support ${scope} scope.`);
-      }
-      return agent;
-    })
-  );
-}
 async function resolveSkillNames(context, type, names) {
   const normalizedNames = uniqueSorted(splitCommaValues(names).map((name) => sanitizeName(name)));
   if (normalizedNames.includes("all")) {
@@ -1337,12 +1692,12 @@ async function bundlesWithCoEnabledSiblings(options) {
   return [...hit].sort();
 }
 async function runDisable(context, options) {
-  const projectDir = options.scope === "project" ? getProjectDir2(context, options.projectDir) : void 0;
-  const agents = await resolveAgentsForScope2(context, options.agents, options.scope, projectDir);
+  const projectDir = options.scope === "project" ? getProjectDir(context, options.projectDir) : void 0;
+  const agents = await resolveAgentsForScope(context, options.agents, options.scope, projectDir);
   const baseDir = options.scope === "global" ? context.homeDir : projectDir ?? context.cwd;
   const skillNames = await resolveSkillNames(context, options.type, options.name);
+  const { skillsDir: centralSkillsDir } = getAweskillPaths(context.homeDir);
   if (splitCommaValues(options.name).map((name) => sanitizeName(name)).includes("all") && options.type === "skill") {
-    const { skillsDir: centralSkillsDir } = getAweskillPaths(context.homeDir);
     const scopedManaged = await Promise.all(
       agents.map(async (agentId) => {
         const agentSkillsDir = resolveAgentSkillsDir(agentId, options.scope, baseDir);
@@ -1368,12 +1723,36 @@ async function runDisable(context, options) {
       );
     }
   }
+  for (const agentId of agents) {
+    const skillsDir = resolveAgentSkillsDir(agentId, options.scope, baseDir);
+    for (const skillName of skillNames) {
+      const targetPath = path12.join(skillsDir, skillName);
+      const status = await inspectProjectionTarget(targetPath, { centralSkillsDir });
+      if (status.kind === "missing" || status.kind === "managed_symlink" || status.kind === "managed_copy") {
+        continue;
+      }
+      if (status.kind === "foreign_symlink" && !options.force) {
+        throw new Error(
+          `Target path is a symlink that is not managed by aweskill: ${targetPath}. Re-run with --force to remove it.`
+        );
+      }
+      if (status.kind === "directory" && !options.force) {
+        throw new Error(`Target path already exists as a directory: ${targetPath}. Re-run with --force to remove it.`);
+      }
+      if (status.kind === "file" && !options.force) {
+        throw new Error(`Target path already exists as a file: ${targetPath}. Re-run with --force to remove it.`);
+      }
+    }
+  }
   const removed = [];
   for (const agentId of agents) {
     const skillsDir = resolveAgentSkillsDir(agentId, options.scope, baseDir);
     for (const skillName of skillNames) {
-      const targetPath = `${skillsDir}/${skillName}`;
-      const wasRemoved = await removeManagedProjection(targetPath);
+      const targetPath = path12.join(skillsDir, skillName);
+      const wasRemoved = await removeProjectionTarget(targetPath, {
+        force: options.force,
+        centralSkillsDir
+      });
       if (wasRemoved) {
         removed.push(`${agentId}:${skillName}`);
       }
@@ -1387,10 +1766,11 @@ async function runDisable(context, options) {
 
 // src/commands/enable.ts
 import { mkdir as mkdir6 } from "fs/promises";
-function getProjectDir3(context, explicitProjectDir) {
+import path13 from "path";
+function getProjectDir2(context, explicitProjectDir) {
   return explicitProjectDir ?? context.cwd;
 }
-async function resolveAgentsForScope3(context, requestedAgents, scope, projectDir) {
+async function resolveAgentsForScope2(context, requestedAgents, scope, projectDir) {
   if (requestedAgents.length === 0 || requestedAgents.includes("all")) {
     const detected = await detectInstalledAgents({
       homeDir: context.homeDir,
@@ -1446,17 +1826,44 @@ async function resolveSkillNames2(context, type, names) {
   return normalizedNames;
 }
 async function runEnable(context, options) {
-  const projectDir = options.scope === "project" ? getProjectDir3(context, options.projectDir) : void 0;
-  const agents = await resolveAgentsForScope3(context, options.agents, options.scope, projectDir);
+  const projectDir = options.scope === "project" ? getProjectDir2(context, options.projectDir) : void 0;
+  const agents = await resolveAgentsForScope2(context, options.agents, options.scope, projectDir);
   const skillNames = await resolveSkillNames2(context, options.type, options.name);
   const baseDir = options.scope === "global" ? context.homeDir : projectDir ?? context.cwd;
+  const { skillsDir: centralSkillsDir } = getAweskillPaths(context.homeDir);
   for (const agentId of agents) {
     const skillsDir = resolveAgentSkillsDir(agentId, options.scope, baseDir);
     await mkdir6(skillsDir, { recursive: true });
     for (const skillName of skillNames) {
       const sourcePath = getSkillPath(context.homeDir, skillName);
-      const targetPath = `${skillsDir}/${skillName}`;
-      await assertProjectionTargetSafe(getProjectionMode(agentId), sourcePath, targetPath);
+      const targetPath = path13.join(skillsDir, skillName);
+      const status = await inspectProjectionTarget(targetPath, { centralSkillsDir, sourcePath });
+      if (status.kind === "missing") {
+        continue;
+      }
+      if (status.kind === "managed_symlink" || status.kind === "managed_copy") {
+        if (status.matchesSource && !options.force) {
+          throw new Error(
+            `Target path is already an aweskill-managed projection for ${skillName}: ${targetPath}. Re-run with --force to recreate it.`
+          );
+        }
+        continue;
+      }
+      if (status.kind === "foreign_symlink" && !options.force) {
+        throw new Error(
+          `Target path is a symlink that is not managed by aweskill: ${targetPath}. Re-run with --force to replace it with an aweskill-managed projection.`
+        );
+      }
+      if (status.kind === "directory" && !options.force) {
+        throw new Error(
+          `Target path already exists as a directory: ${targetPath}. Re-run with --force to replace it with an aweskill-managed projection.`
+        );
+      }
+      if (status.kind === "file" && !options.force) {
+        throw new Error(
+          `Target path already exists as a file: ${targetPath}. Re-run with --force to replace it with an aweskill-managed projection.`
+        );
+      }
     }
   }
   const created = [];
@@ -1465,9 +1872,9 @@ async function runEnable(context, options) {
     const mode = getProjectionMode(agentId);
     for (const skillName of skillNames) {
       const sourcePath = getSkillPath(context.homeDir, skillName);
-      const targetPath = `${skillsDir}/${skillName}`;
-      const result = mode === "symlink" ? await createSkillSymlink(sourcePath, targetPath) : await createSkillCopy(sourcePath, targetPath);
-      if (result === "created") {
+      const targetPath = path13.join(skillsDir, skillName);
+      const result = mode === "symlink" ? await createSkillSymlink(sourcePath, targetPath, { allowReplaceExisting: options.force }) : await createSkillCopy(sourcePath, targetPath, { allowReplaceExisting: options.force });
+      if (result.status === "created") {
         created.push(`${agentId}:${skillName}`);
       }
     }
@@ -1506,17 +1913,23 @@ function formatScanSummary(candidates, verbose = false) {
   return lines.join("\n");
 }
 async function runScan(context, options) {
+  if (options.keepSource && options.linkSource) {
+    throw new Error("Choose either --keep-source or --link-source, not both.");
+  }
   const candidates = await scanSkills({
     homeDir: context.homeDir,
-    projectDirs: [context.cwd]
+    scope: options.scope,
+    agents: options.agents,
+    projectDir: options.scope === "project" ? options.projectDir ?? context.cwd : void 0
   });
   context.write(formatScanSummary(candidates, options.verbose));
   if (options.add) {
+    const linkSource = !options.keepSource;
     const result = await importScannedSkills({
       homeDir: context.homeDir,
       candidates,
-      mode: options.mode ?? "cp",
-      override: options.override
+      override: options.override,
+      linkSource
     });
     for (const warning of result.warnings) {
       context.write(`Warning: ${warning}`);
@@ -1534,6 +1947,11 @@ async function runScan(context, options) {
     if (result.missingSources > 0) {
       context.write(`Missing source files: ${result.missingSources}`);
     }
+    if (linkSource) {
+      context.write(`Replaced ${result.linkedSources.length} scanned source paths with aweskill-managed projections.`);
+    } else {
+      context.write("Source paths were kept in place. Re-run without --keep-source to replace scanned agent skills with aweskill-managed projections.");
+    }
     return { candidates, ...result };
   }
   return candidates;
@@ -1544,7 +1962,7 @@ async function runInit(context, options) {
   await ensureHomeLayout(context.homeDir);
   context.write(`Initialized ${context.homeDir}/.aweskill`);
   if (options.scan) {
-    const candidates = await scanSkills({ homeDir: context.homeDir, projectDirs: [context.cwd] });
+    const candidates = await scanSkills({ homeDir: context.homeDir, scope: "global" });
     context.write(formatScanSummary(candidates, options.verbose));
     return candidates;
   }
@@ -1552,14 +1970,15 @@ async function runInit(context, options) {
 }
 
 // src/commands/list.ts
-var DEFAULT_PREVIEW_COUNT2 = 5;
+var DEFAULT_PREVIEW_COUNT = 5;
 async function runListSkills(context, options = {}) {
-  const skills = await listSkills(context.homeDir);
+  const { rootDir, skillsDir, bundlesDir } = getAweskillPaths(context.homeDir);
+  const { validSkills: skills, findings } = await scanStoreHygiene({ rootDir, skillsDir, bundlesDir, includeBundles: true });
   if (skills.length === 0) {
-    context.write("No skills found in central repo.");
+    context.write(["No skills found in central repo.", ...formatHygieneHint(findings)].join("\n"));
     return skills;
   }
-  const preview = options.verbose ? skills : skills.slice(0, DEFAULT_PREVIEW_COUNT2);
+  const preview = options.verbose ? skills : skills.slice(0, DEFAULT_PREVIEW_COUNT);
   const lines = [`Skills in central repo: ${skills.length} total`];
   if (!options.verbose && skills.length > preview.length) {
     lines.push(`Showing first ${preview.length} skills (use --verbose to show all)`);
@@ -1568,6 +1987,7 @@ async function runListSkills(context, options = {}) {
     const marker = skill.hasSKILLMd ? "\u2713" : "!";
     lines.push(`  ${marker} ${skill.name} ${skill.path}`);
   }
+  lines.push(...formatHygieneHint(findings));
   context.write(lines.join("\n"));
   return skills;
 }
@@ -1575,21 +1995,22 @@ function formatBundleLines(title, bundles, verbose) {
   if (bundles.length === 0) {
     return [title, "(none)"];
   }
-  const preview = verbose ? bundles : bundles.slice(0, DEFAULT_PREVIEW_COUNT2);
+  const preview = verbose ? bundles : bundles.slice(0, DEFAULT_PREVIEW_COUNT);
   const lines = [`${title}: ${bundles.length} total`];
   if (!verbose && bundles.length > preview.length) {
     lines.push(`Showing first ${preview.length} bundles (use --verbose to show all)`);
   }
   for (const bundle of preview) {
-    const skillsPreview = verbose ? bundle.skills : bundle.skills.slice(0, DEFAULT_PREVIEW_COUNT2);
+    const skillsPreview = verbose ? bundle.skills : bundle.skills.slice(0, DEFAULT_PREVIEW_COUNT);
     const suffix = !verbose && bundle.skills.length > skillsPreview.length ? `, ... (+${bundle.skills.length - skillsPreview.length} more)` : "";
     lines.push(`  - ${bundle.name}: ${bundle.skills.length} skills${skillsPreview.length > 0 ? ` -> ${skillsPreview.join(", ")}${suffix}` : " -> (empty)"}`);
   }
   return lines;
 }
 async function runListBundles(context, options = {}) {
-  const bundles = await listBundles(context.homeDir);
-  context.write(formatBundleLines("Bundles in central repo", bundles, options.verbose).join("\n"));
+  const { rootDir, skillsDir, bundlesDir } = getAweskillPaths(context.homeDir);
+  const { validBundles: bundles, findings } = await scanStoreHygiene({ rootDir, skillsDir, bundlesDir, includeSkills: true });
+  context.write([...formatBundleLines("Bundles in central repo", bundles, options.verbose), ...formatHygieneHint(findings)].join("\n"));
   return bundles;
 }
 async function runListTemplateBundles(context, options = {}) {
@@ -1600,12 +2021,12 @@ async function runListTemplateBundles(context, options = {}) {
 }
 
 // src/commands/recover.ts
-import { cp as cp3, mkdir as mkdir7, readlink as readlink4, unlink as unlink2 } from "fs/promises";
-import path11 from "path";
-function getProjectDir4(context, explicitProjectDir) {
+import { cp as cp4, mkdir as mkdir7, readlink as readlink4, unlink as unlink2 } from "fs/promises";
+import path14 from "path";
+function getProjectDir3(context, explicitProjectDir) {
   return explicitProjectDir ?? context.cwd;
 }
-async function resolveAgentsForScope4(context, requestedAgents, scope, projectDir) {
+async function resolveAgentsForScope3(context, requestedAgents, scope, projectDir) {
   if (requestedAgents.length === 0 || requestedAgents.includes("all")) {
     const detected = await detectInstalledAgents({
       homeDir: context.homeDir,
@@ -1627,8 +2048,8 @@ async function resolveAgentsForScope4(context, requestedAgents, scope, projectDi
   );
 }
 async function runRecover(context, options) {
-  const projectDir = options.scope === "project" ? getProjectDir4(context, options.projectDir) : void 0;
-  const agents = await resolveAgentsForScope4(context, options.agents, options.scope, projectDir);
+  const projectDir = options.scope === "project" ? getProjectDir3(context, options.projectDir) : void 0;
+  const agents = await resolveAgentsForScope3(context, options.agents, options.scope, projectDir);
   const { skillsDir: centralSkillsDir } = getAweskillPaths(context.homeDir);
   const baseDir = options.scope === "global" ? context.homeDir : projectDir ?? context.cwd;
   const recovered = [];
@@ -1639,16 +2060,16 @@ async function runRecover(context, options) {
       if (mode !== "symlink") {
         continue;
       }
-      const targetPath = path11.join(agentSkillsDir, skillName);
-      const sourcePath = path11.join(centralSkillsDir, skillName);
+      const targetPath = path14.join(agentSkillsDir, skillName);
+      const sourcePath = path14.join(centralSkillsDir, skillName);
       const currentTarget = await readlink4(targetPath);
-      const resolvedCurrent = path11.resolve(path11.dirname(targetPath), currentTarget);
-      if (resolvedCurrent !== path11.resolve(sourcePath)) {
+      const resolvedCurrent = path14.resolve(path14.dirname(targetPath), currentTarget);
+      if (resolvedCurrent !== path14.resolve(sourcePath)) {
         continue;
       }
       await unlink2(targetPath);
-      await mkdir7(path11.dirname(targetPath), { recursive: true });
-      await cp3(sourcePath, targetPath, { recursive: true });
+      await mkdir7(path14.dirname(targetPath), { recursive: true });
+      await cp4(sourcePath, targetPath, { recursive: true });
       recovered.push(`${agentId}:${skillName}`);
     }
   }
@@ -1659,7 +2080,7 @@ async function runRecover(context, options) {
 
 // src/lib/references.ts
 import { rm as rm4 } from "fs/promises";
-import path12 from "path";
+import path15 from "path";
 async function findSkillReferences(options) {
   const normalizedSkill = sanitizeName(options.skillName);
   const { skillsDir } = getAweskillPaths(options.homeDir);
@@ -1710,7 +2131,7 @@ async function removeSkillWithReferences(options) {
       const agentSkillsDir = resolveAgentSkillsDir(agent.id, scope, dir);
       const managed = await listManagedSkillNames(agentSkillsDir, skillsDir);
       if (managed.has(normalizedSkill)) {
-        await removeManagedProjection(path12.join(agentSkillsDir, normalizedSkill));
+        await removeManagedProjection(path15.join(agentSkillsDir, normalizedSkill));
       }
     }
   }
@@ -1744,79 +2165,109 @@ async function runRemove(context, options) {
 }
 
 // src/commands/restore.ts
-import { cp as cp4, mkdir as mkdir8, rm as rm5 } from "fs/promises";
-import path13 from "path";
+import { cp as cp5, mkdir as mkdir8, rm as rm5 } from "fs/promises";
+import path16 from "path";
 async function runRestore(context, options) {
-  const includeBundles = options.includeBundles ?? false;
+  const includeBundles = options.includeBundles ?? true;
   const { tempDir, extractedSkillsDir, extractedBundlesDir } = await extractSkillsArchive(options.archivePath);
   try {
-    const extracted = await listSkillEntriesInDirectory(extractedSkillsDir);
+    const extractedScan = await scanStoreHygiene({
+      rootDir: tempDir,
+      skillsDir: extractedSkillsDir,
+      bundlesDir: extractedBundlesDir,
+      includeBundles
+    });
+    const extracted = extractedScan.validSkills;
     if (extracted.length === 0) {
       throw new Error(`Archive does not contain a skills/ directory: ${options.archivePath}`);
     }
     const { skillsDir, bundlesDir } = getAweskillPaths(context.homeDir);
-    const current = await listSkillEntriesInDirectory(skillsDir);
+    const currentScan = await scanStoreHygiene({
+      rootDir: getAweskillPaths(context.homeDir).rootDir,
+      skillsDir,
+      bundlesDir,
+      includeBundles
+    });
+    const current = currentScan.validSkills;
     const currentNames = new Set(current.map((entry) => entry.name));
     const conflicts = extracted.map((entry) => entry.name).filter((name) => currentNames.has(name));
-    const extractedBundles = includeBundles ? await listBundlesInDirectory(extractedBundlesDir) : [];
-    const currentBundles = includeBundles ? await listBundlesInDirectory(bundlesDir) : [];
+    const extractedBundles = includeBundles ? extractedScan.validBundles : [];
+    const currentBundles = includeBundles ? currentScan.validBundles : [];
     const currentBundleNames = new Set(currentBundles.map((bundle) => bundle.name));
     const bundleConflicts = extractedBundles.map((bundle) => bundle.name).filter((name) => currentBundleNames.has(name));
-    if ((conflicts.length > 0 || bundleConflicts.length > 0) && !options.override) {
-      const conflictMessages = [];
-      if (conflicts.length > 0) {
-        conflictMessages.push(`skills: ${conflicts.join(", ")}`);
-      }
-      if (bundleConflicts.length > 0) {
-        conflictMessages.push(`bundles: ${bundleConflicts.join(", ")}`);
-      }
-      throw new Error(`Restore would overwrite existing ${conflictMessages.join("; ")}. Use --override to replace them.`);
-    }
     const backupArchivePath = await createSkillsBackupArchive(context.homeDir, { includeBundles });
+    const skippedSkills = new Set(options.override ? [] : conflicts);
+    const skippedBundles = new Set(options.override ? [] : bundleConflicts);
     if (options.override) {
       await rm5(skillsDir, { recursive: true, force: true });
-      await mkdir8(path13.dirname(skillsDir), { recursive: true });
-      await cp4(extractedSkillsDir, skillsDir, { recursive: true });
+      await mkdir8(path16.dirname(skillsDir), { recursive: true });
+      await cp5(extractedSkillsDir, skillsDir, { recursive: true });
       if (includeBundles) {
         await rm5(bundlesDir, { recursive: true, force: true });
-        await mkdir8(path13.dirname(bundlesDir), { recursive: true });
-        await cp4(extractedBundlesDir, bundlesDir, { recursive: true });
+        if (await pathExists(extractedBundlesDir)) {
+          await mkdir8(path16.dirname(bundlesDir), { recursive: true });
+          await cp5(extractedBundlesDir, bundlesDir, { recursive: true });
+        }
       }
     } else {
       await mkdir8(skillsDir, { recursive: true });
       for (const entry of extracted) {
-        await cp4(entry.path, path13.join(skillsDir, entry.name), { recursive: true });
+        if (skippedSkills.has(entry.name)) {
+          continue;
+        }
+        await cp5(entry.path, path16.join(skillsDir, entry.name), { recursive: true });
       }
       if (includeBundles) {
         await mkdir8(bundlesDir, { recursive: true });
         for (const bundle of extractedBundles) {
-          await cp4(path13.join(extractedBundlesDir, `${bundle.name}.yaml`), path13.join(bundlesDir, `${bundle.name}.yaml`), { recursive: true });
+          if (skippedBundles.has(bundle.name)) {
+            continue;
+          }
+          await cp5(path16.join(extractedBundlesDir, `${bundle.name}.yaml`), path16.join(bundlesDir, `${bundle.name}.yaml`), { recursive: true });
         }
       }
     }
-    const restoredLabel = includeBundles ? `Restored ${extracted.length} skills and ${extractedBundles.length} bundles from ${options.archivePath}` : `Restored ${extracted.length} skills from ${options.archivePath}`;
+    const restoredSkillCount = options.override ? extracted.length : extracted.length - skippedSkills.size;
+    const restoredBundleCount = includeBundles ? options.override ? extractedBundles.length : extractedBundles.length - skippedBundles.size : 0;
+    const restoredLabel = includeBundles ? `Restored ${restoredSkillCount} skills and ${restoredBundleCount} bundles from ${options.archivePath}` : `Restored ${restoredSkillCount} skills from ${options.archivePath}`;
     context.write(restoredLabel);
+    if (skippedSkills.size > 0) {
+      context.write(`Skipped existing skills: ${[...skippedSkills].sort().join(", ")}`);
+    }
+    if (skippedBundles.size > 0) {
+      context.write(`Skipped existing bundles: ${[...skippedBundles].sort().join(", ")}`);
+    }
+    if (extractedScan.findings.length > 0) {
+      context.write(`Skipped suspicious restore source entries: ${extractedScan.findings.map((finding) => finding.relativePath).join(", ")}`);
+    }
     context.write(`Backed up current ${formatBackupLabel(includeBundles)} to ${backupArchivePath}`);
-    return { restored: extracted.map((entry) => entry.name), backupArchivePath };
+    return {
+      restored: extracted.map((entry) => entry.name).filter((name) => !skippedSkills.has(name)),
+      skipped: [...skippedSkills],
+      backupArchivePath
+    };
   } finally {
     await rm5(tempDir, { recursive: true, force: true });
   }
 }
 
 // src/lib/rmdup.ts
-import { mkdir as mkdir9, readdir as readdir7, rename as rename2, rm as rm6 } from "fs/promises";
-import path14 from "path";
+import { mkdir as mkdir9, readdir as readdir9, rename, rm as rm6 } from "fs/promises";
+import path17 from "path";
 var NUMERIC_SUFFIX_PATTERN = /^(.*?)-(\d+(?:\.\d+)*)$/;
 function parseSkillName(name) {
-  const match = name.match(NUMERIC_SUFFIX_PATTERN);
+  const normalizedName = sanitizeName(name);
+  const match = normalizedName.match(NUMERIC_SUFFIX_PATTERN);
   if (!match) {
     return {
-      baseName: name,
+      baseName: stripVersionSuffix(normalizedName),
+      matchKey: getDuplicateMatchKey(name),
       hasNumericSuffix: false
     };
   }
   return {
-    baseName: match[1],
+    baseName: stripVersionSuffix(normalizedName),
+    matchKey: getDuplicateMatchKey(name),
     hasNumericSuffix: true,
     numericKey: match[2].split(".").map((part) => Number.parseInt(part, 10))
   };
@@ -1851,14 +2302,35 @@ function choosePreferredSkill(entries) {
     return left.name.localeCompare(right.name);
   })[0];
 }
+function buildCanonicalSkillIndex(entries) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const parsed = parseSkillName(entry.name);
+    const bucket = grouped.get(parsed.matchKey) ?? [];
+    bucket.push(entry);
+    grouped.set(parsed.matchKey, bucket);
+  }
+  const canonical = /* @__PURE__ */ new Map();
+  for (const [baseName, group] of grouped) {
+    canonical.set(baseName, choosePreferredSkill(group));
+  }
+  return canonical;
+}
+function resolveCanonicalSkillName(skillName, canonicalSkills) {
+  if (canonicalSkills.has(skillName)) {
+    return canonicalSkills.get(skillName).name;
+  }
+  const parsed = parseSkillName(skillName);
+  return canonicalSkills.get(parsed.matchKey)?.name;
+}
 async function findDuplicateSkills(homeDir) {
   const skills = await listSkills(homeDir);
   const grouped = /* @__PURE__ */ new Map();
   for (const skill of skills) {
     const parsed = parseSkillName(skill.name);
-    const bucket = grouped.get(parsed.baseName) ?? [];
+    const bucket = grouped.get(parsed.matchKey) ?? [];
     bucket.push(skill);
-    grouped.set(parsed.baseName, bucket);
+    grouped.set(parsed.matchKey, bucket);
   }
   const duplicates = [];
   for (const [baseName, entries] of grouped) {
@@ -1868,7 +2340,7 @@ async function findDuplicateSkills(homeDir) {
     const kept = choosePreferredSkill(entries);
     const removed = entries.filter((entry) => entry.path !== kept.path).sort((left, right) => left.name.localeCompare(right.name));
     if (removed.length > 0) {
-      duplicates.push({ baseName, kept, removed });
+      duplicates.push({ baseName: parseSkillName(kept.name).baseName, kept, removed });
     }
   }
   return duplicates.sort((left, right) => left.baseName.localeCompare(right.baseName));
@@ -1886,28 +2358,28 @@ async function removeDuplicateSkills(homeDir, duplicates, options = {}) {
         continue;
       }
       const targetPath = await nextAvailableDupPath(paths.dupSkillsDir, skill.name);
-      await rename2(skill.path, targetPath);
+      await rename(skill.path, targetPath);
       moved.push(`${skill.name} -> ${targetPath}`);
     }
   }
   return { moved, deleted };
 }
 async function nextAvailableDupPath(dupSkillsDir, skillName) {
-  const entries = new Set(await readdir7(dupSkillsDir).catch(() => []));
+  const entries = new Set(await readdir9(dupSkillsDir).catch(() => []));
   if (!entries.has(skillName)) {
-    return path14.join(dupSkillsDir, skillName);
+    return path17.join(dupSkillsDir, skillName);
   }
   let index = 1;
   while (entries.has(`${skillName}-${index}`)) {
     index += 1;
   }
-  return path14.join(dupSkillsDir, `${skillName}-${index}`);
+  return path17.join(dupSkillsDir, `${skillName}-${index}`);
 }
 
 // src/commands/rmdup.ts
 async function runRmdup(context, options) {
-  if (options.delete && !options.remove) {
-    throw new Error("--delete requires --remove");
+  if (options.delete && !options.apply) {
+    throw new Error("--delete requires --apply");
   }
   const duplicates = await findDuplicateSkills(context.homeDir);
   if (duplicates.length === 0) {
@@ -1924,7 +2396,7 @@ async function runRmdup(context, options) {
   }
   let moved = [];
   let deleted = [];
-  if (options.remove) {
+  if (options.apply) {
     const result = await removeDuplicateSkills(context.homeDir, duplicates, { delete: options.delete });
     moved = result.moved;
     deleted = result.deleted;
@@ -1936,55 +2408,328 @@ async function runRmdup(context, options) {
     }
   } else {
     lines.push("");
-    lines.push("Dry run only. Use --remove to move duplicates into dup_skills, or --remove --delete to delete them.");
+    lines.push("Dry run only. Use --apply to move duplicates into dup_skills, or --apply --delete to delete them.");
   }
   context.write(lines.join("\n"));
   return { duplicates, moved, deleted };
 }
 
 // src/commands/sync.ts
-import path15 from "path";
+import path18 from "path";
+import { rm as rm7 } from "fs/promises";
+
+// src/commands/agent-inspection.ts
+function classifyCheckedSkill(skill, managed, canonicalSkillNames) {
+  const suspicionReason = getSkillSuspicionReason(skill);
+  if (suspicionReason) {
+    return {
+      name: skill.name,
+      path: skill.path,
+      category: "suspicious",
+      hasSKILLMd: skill.hasSKILLMd,
+      suspicionReason
+    };
+  }
+  let category = "new";
+  let duplicateKind;
+  let canonicalName;
+  if (managed.has(skill.name)) {
+    category = "linked";
+  } else {
+    canonicalName = resolveCanonicalSkillName(skill.name, canonicalSkillNames);
+    if (canonicalName) {
+      category = canonicalName === skill.name ? "duplicate" : "matched";
+      duplicateKind = canonicalName === skill.name ? "exact" : "family";
+    }
+  }
+  if (category === "linked") {
+    const parsed = parseSkillName(skill.name);
+    canonicalName = canonicalSkillNames.get(parsed.baseName)?.name;
+  }
+  return {
+    name: skill.name,
+    path: skill.path,
+    category,
+    hasSKILLMd: skill.hasSKILLMd,
+    duplicateKind,
+    canonicalName
+  };
+}
+function buildCentralCanonicalSkills(centralSkillEntries) {
+  return buildCanonicalSkillIndex(centralSkillEntries);
+}
+
+// src/commands/sync.ts
+var DEFAULT_PREVIEW_COUNT2 = 5;
+function getProjectDir4(context, explicitProjectDir) {
+  return explicitProjectDir ?? context.cwd;
+}
+function formatSkillBlockWithSummary(title, skills, verbose = false) {
+  if (skills.length === 0) {
+    return [`No skills found for ${title.replace(/:$/, "").toLowerCase()}.`];
+  }
+  const lines = [title];
+  const categories = [
+    { title: "  linked", marker: "\u2713", key: "linked" },
+    { title: "  broken", marker: "!", key: "broken" },
+    { title: "  duplicate", marker: "!", key: "duplicate" },
+    { title: "  matched", marker: "~", key: "matched" },
+    { title: "  new", marker: "+", key: "new" },
+    { title: "  suspicious", marker: "?", key: "suspicious" }
+  ];
+  for (const category of categories) {
+    const entries = skills.filter((skill) => skill.category === category.key);
+    lines.push(`${category.title}: ${entries.length}`);
+    const preview = verbose ? entries : entries.slice(0, DEFAULT_PREVIEW_COUNT2);
+    for (const skill of preview) {
+      lines.push(`    ${category.marker} ${skill.name} ${skill.path}`);
+    }
+    if (!verbose && entries.length > preview.length) {
+      lines.push(`    ... and ${entries.length - preview.length} more (use --verbose to show all)`);
+    }
+  }
+  return lines;
+}
 async function runSync(context, options) {
-  const { skillsDir } = getAweskillPaths(context.homeDir);
-  const baseDirs = /* @__PURE__ */ new Set();
-  baseDirs.add({ scope: "global", dir: context.homeDir });
-  if (options.projectDir) {
-    baseDirs.add({ scope: "project", dir: options.projectDir });
+  if (options.removeSuspicious && !options.apply) {
+    throw new Error("--remove-suspicious requires --apply.");
   }
-  if (await pathExists(path15.join(context.cwd, ".aweskill.yaml"))) {
-    baseDirs.add({ scope: "project", dir: context.cwd });
+  const projectDir = options.scope === "project" ? getProjectDir4(context, options.projectDir) : void 0;
+  const { agents, explicit } = await resolveAgentsForListingOrSync({
+    requestedAgents: options.agents,
+    scope: options.scope,
+    homeDir: context.homeDir,
+    projectDir
+  });
+  if (agents.length === 0) {
+    context.write(formatNoAgentsDetectedForScope(options.scope, projectDir));
+    return { relinked: [], repairedBroken: [], removedBroken: [], removedSuspicious: [], newEntries: [] };
   }
-  let removed = 0;
-  const warnings = [];
-  for (const { scope, dir } of baseDirs) {
-    for (const agent of listSupportedAgents()) {
-      if (!supportsScope(agent.id, scope)) {
+  const { skillsDir: centralSkillsDir } = getAweskillPaths(context.homeDir);
+  const centralSkillEntries = await listSkills(context.homeDir);
+  const canonicalSkillNames = buildCentralCanonicalSkills(centralSkillEntries);
+  const baseDir = options.scope === "global" ? context.homeDir : projectDir;
+  const lines = [];
+  if (!explicit) {
+    lines.push(formatDetectedAgentsForScope(options.scope, agents, projectDir));
+  }
+  const relinked = [];
+  const repairedBroken = [];
+  const removedBroken = [];
+  const removedSuspicious = [];
+  const newEntries = [];
+  let suspiciousCount = 0;
+  let repairableCount = 0;
+  for (const agentId of agents) {
+    const skillsDir = resolveAgentSkillsDir(agentId, options.scope, baseDir);
+    const managed = await listManagedSkillNames(skillsDir, centralSkillsDir);
+    const brokenSymlinks = await listBrokenSymlinkNames(skillsDir);
+    const skills = await listSkillEntriesInDirectory(skillsDir);
+    const entries = [];
+    for (const skillName of Array.from(brokenSymlinks).sort((left, right) => left.localeCompare(right))) {
+      const targetPath = path18.join(skillsDir, skillName);
+      entries.push({ name: skillName, path: targetPath, category: "broken" });
+      repairableCount += 1;
+      if (!options.apply) {
         continue;
       }
-      const skillsDir2 = resolveAgentSkillsDir(agent.id, scope, dir);
-      const managed = await listManagedSkillNames(skillsDir2, skillsDir);
-      for (const [skillName] of managed) {
-        const sourcePath = path15.join(skillsDir, skillName);
-        if (!await pathExists(sourcePath)) {
-          const wasRemoved = await removeManagedProjection(path15.join(skillsDir2, skillName));
-          if (wasRemoved) {
-            removed += 1;
-            warnings.push(`Removed stale projection: ${agent.id}:${skillName} (source missing)`);
-          }
-        }
+      const canonicalName = resolveCanonicalSkillName(skillName, canonicalSkillNames);
+      if (canonicalName) {
+        await createSkillSymlink(getSkillPath(context.homeDir, canonicalName), targetPath, {
+          allowReplaceExisting: true
+        });
+        repairedBroken.push(`${agentId}:${skillName}`);
+        continue;
+      }
+      const wasRemoved = await removeManagedProjection(targetPath);
+      if (wasRemoved) {
+        removedBroken.push(`${agentId}:${skillName}`);
+      }
+    }
+    for (const skill of skills) {
+      if (brokenSymlinks.has(skill.name)) {
+        continue;
+      }
+      const checkedSkill = classifyCheckedSkill(skill, managed, canonicalSkillNames);
+      entries.push({ name: checkedSkill.name, path: checkedSkill.path, category: checkedSkill.category });
+      if (checkedSkill.category === "duplicate" || checkedSkill.category === "matched") {
+        repairableCount += 1;
+      }
+      if (checkedSkill.category === "suspicious") {
+        suspiciousCount += 1;
+      }
+      if (checkedSkill.category === "new") {
+        newEntries.push(`${agentId}:${checkedSkill.name}`);
+      }
+      if (!options.apply) {
+        continue;
+      }
+      if (checkedSkill.category === "duplicate" || checkedSkill.category === "matched") {
+        await createSkillSymlink(getSkillPath(context.homeDir, checkedSkill.canonicalName ?? checkedSkill.name), checkedSkill.path, {
+          allowReplaceExisting: true
+        });
+        relinked.push(`${agentId}:${checkedSkill.name}`);
+        continue;
+      }
+      if (checkedSkill.category === "suspicious" && options.removeSuspicious) {
+        await rm7(checkedSkill.path, { recursive: true, force: true });
+        removedSuspicious.push(`${agentId}:${checkedSkill.name}`);
+      }
+    }
+    for (const [skillName] of managed) {
+      if (brokenSymlinks.has(skillName)) {
+        continue;
+      }
+      const sourcePath = path18.join(centralSkillsDir, skillName);
+      if (await pathExists(sourcePath)) {
+        continue;
+      }
+      const targetPath = path18.join(skillsDir, skillName);
+      entries.push({ name: skillName, path: targetPath, category: "broken" });
+      repairableCount += 1;
+      if (!options.apply) {
+        continue;
+      }
+      const wasRemoved = await removeManagedProjection(targetPath);
+      if (wasRemoved) {
+        removedBroken.push(`${agentId}:${skillName}`);
       }
     }
+    const title = options.scope === "global" ? `Global skills for ${agentId}:` : `Project skills for ${agentId} (${projectDir}):`;
+    lines.push("");
+    lines.push(...formatSkillBlockWithSummary(title, entries, options.verbose));
+  }
+  lines.push("");
+  if (!options.apply) {
+    if (repairableCount > 0) {
+      lines.push("Re-run with aweskill doctor sync --apply to repair broken projections and relink duplicate/matched entries.");
+    }
+    if (suspiciousCount > 0) {
+      lines.push("Suspicious agent skill entries were reported only. Re-run with aweskill doctor sync --apply --remove-suspicious to remove them.");
+    }
+    if (newEntries.length > 0) {
+      lines.push("New agent skill entries found. Use aweskill store import --scan with same scope and agent filters to import them.");
+    }
+  } else {
+    lines.push(`Repaired ${repairedBroken.length} broken symlink projection${repairedBroken.length === 1 ? "" : "s"}.`);
+    lines.push(`Removed ${removedBroken.length} broken projection${removedBroken.length === 1 ? "" : "s"}.`);
+    lines.push(`Relinked ${relinked.length} duplicate or matched agent skill entr${relinked.length === 1 ? "y" : "ies"}.`);
+    if (options.removeSuspicious) {
+      lines.push(`Removed ${removedSuspicious.length} suspicious agent skill entr${removedSuspicious.length === 1 ? "y" : "ies"}.`);
+    } else if (suspiciousCount > 0) {
+      lines.push("Suspicious agent skill entries were reported only. Re-run with --apply --remove-suspicious to remove them.");
+    }
+    if (newEntries.length > 0) {
+      lines.push("New agent skill entries were found. Use aweskill store import --scan with same scope and agent filters to import them.");
+    }
+  }
+  context.write(lines.join("\n").trim());
+  return { relinked, repairedBroken, removedBroken, removedSuspicious, newEntries };
+}
+
+// src/commands/clean.ts
+import { rm as rm8 } from "fs/promises";
+var DEFAULT_PREVIEW_COUNT3 = 5;
+function formatFindingGroups(relativePaths, options) {
+  const groups = [
+    options.includeSkills ? {
+      label: "skills",
+      entries: relativePaths.filter((entry) => entry.startsWith("skills/"))
+    } : void 0,
+    options.includeBundles ? {
+      label: "bundles",
+      entries: relativePaths.filter((entry) => entry.startsWith("bundles/"))
+    } : void 0
+  ].filter((group) => Boolean(group));
+  const lines = [];
+  for (const group of groups) {
+    if (group.entries.length === 0) {
+      continue;
+    }
+    lines.push(`${group.label}: ${group.entries.length}`);
+    const preview = options.verbose ? group.entries : group.entries.slice(0, DEFAULT_PREVIEW_COUNT3);
+    if (!options.verbose && group.entries.length > preview.length) {
+      lines.push(`Showing first ${preview.length} suspicious entries in ${group.label} (use --verbose to show all)`);
+    }
+    for (const entry of preview) {
+      lines.push(`  - ${entry}`);
+    }
+    if (!options.verbose && group.entries.length > preview.length) {
+      lines.push(`... and ${group.entries.length - preview.length} more (use --verbose to show all)`);
+    }
+  }
+  return lines;
+}
+async function runClean(context, options = {}) {
+  const { rootDir, skillsDir, bundlesDir } = getAweskillPaths(context.homeDir);
+  const includeSkills = !options.bundlesOnly;
+  const includeBundles = !options.skillsOnly;
+  const { findings } = await scanStoreHygiene({ rootDir, skillsDir, bundlesDir, includeSkills, includeBundles });
+  if (findings.length === 0) {
+    context.write("No suspicious store entries found.");
+    return { findings, removed: [] };
+  }
+  const lines = [
+    "Suspicious store entries:",
+    ...formatFindingGroups(
+      findings.map((finding) => finding.relativePath),
+      { verbose: options.verbose, includeSkills, includeBundles }
+    )
+  ];
+  if (!options.apply) {
+    lines.push("");
+    lines.push("Dry run only. Use --apply to remove suspicious entries.");
+    context.write(lines.join("\n"));
+    return { findings, removed: [] };
   }
-  context.write(`Sync complete. Removed ${removed} stale projection(s).`);
-  if (warnings.length > 0) {
-    context.write(warnings.join("\n"));
+  const removed = [];
+  for (const finding of findings) {
+    await rm8(finding.path, { recursive: true, force: true });
+    removed.push(finding.relativePath);
+  }
+  lines.push("");
+  lines.push(`Removed ${removed.length} suspicious store entries`);
+  context.write(lines.join("\n"));
+  return { findings, removed };
+}
+
+// src/commands/where.ts
+import { readdir as readdir10 } from "fs/promises";
+async function countEntries(targetPath) {
+  if (!await pathExists(targetPath)) {
+    return 0;
+  }
+  return (await readdir10(targetPath)).length;
+}
+function formatEntryCount(count) {
+  return `${count} ${count === 1 ? "entry" : "entries"}`;
+}
+async function runStoreWhere(context, options = {}) {
+  const paths = getAweskillPaths(context.homeDir);
+  if (!options.verbose) {
+    context.write(`aweskill store: ${paths.rootDir}`);
+    return paths.rootDir;
+  }
+  const entries = [
+    { label: "skills", path: paths.skillsDir, entryCount: await countEntries(paths.skillsDir) },
+    { label: "dup_skills", path: paths.dupSkillsDir, entryCount: await countEntries(paths.dupSkillsDir) },
+    { label: "backup", path: paths.backupDir, entryCount: await countEntries(paths.backupDir) },
+    { label: "bundles", path: paths.bundlesDir, entryCount: await countEntries(paths.bundlesDir) }
+  ];
+  const lines = [`aweskill store: ${paths.rootDir}`];
+  for (const entry of entries) {
+    lines.push(`  - ${entry.label}: ${formatEntryCount(entry.entryCount)} -> ${entry.path}`);
   }
-  return { removed, warnings };
+  context.write(lines.join("\n"));
+  return {
+    rootDir: paths.rootDir,
+    entries
+  };
 }
 
 // src/lib/version.ts
 import { existsSync, readFileSync } from "fs";
-import path16 from "path";
+import path19 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function readVersionFromPackageJson(packageJsonPath) {
   const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
@@ -1994,9 +2739,9 @@ function readVersionFromPackageJson(packageJsonPath) {
   return packageJson.version;
 }
 function resolveVersionForModuleUrl(moduleUrl) {
-  const moduleDir = path16.dirname(fileURLToPath2(moduleUrl));
+  const moduleDir = path19.dirname(fileURLToPath2(moduleUrl));
   for (const relativePath of ["../package.json", "../../package.json"]) {
-    const packageJsonPath = path16.resolve(moduleDir, relativePath);
+    const packageJsonPath = path19.resolve(moduleDir, relativePath);
     if (existsSync(packageJsonPath)) {
       return readVersionFromPackageJson(packageJsonPath);
     }
@@ -2041,11 +2786,11 @@ function emitMessage(line) {
     p.log.success(trimmed);
     return;
   }
-  if (trimmed.startsWith("Skills in central repo:") || trimmed === "Scanned skills:" || trimmed === "Duplicate skill groups in central repo:" || trimmed === "Bundles:" || trimmed.startsWith("Global skills for ") || trimmed.startsWith("Project skills for ")) {
+  if (trimmed.startsWith("Skills in central repo:") || trimmed === "Scanned skills:" || trimmed === "Duplicate skill groups in central repo:" || trimmed === "Bundles:" || trimmed === "Supported agents:" || trimmed.startsWith("Global skills for ") || trimmed.startsWith("Project skills for ")) {
     console.log(pc.bold(trimmed));
     return;
   }
-  if (trimmed.startsWith("linked:") || trimmed.startsWith("duplicate:") || trimmed.startsWith("new:")) {
+  if (trimmed.startsWith("linked:") || trimmed.startsWith("duplicate:") || trimmed.startsWith("matched:") || trimmed.startsWith("new:") || trimmed.startsWith("suspicious:")) {
     console.log(pc.dim(trimmed));
     return;
   }
@@ -2075,6 +2820,19 @@ function emitMessage(line) {
     console.log(`  ${pc.green("\u2713")} ${pc.cyan(name)} ${pc.dim(location)}`);
     return;
   }
+  if (line.startsWith("\u2713 ")) {
+    const rest = line.slice(2);
+    const firstSpace = rest.indexOf(" ");
+    const name = firstSpace === -1 ? rest : rest.slice(0, firstSpace);
+    const location = firstSpace === -1 ? "" : rest.slice(firstSpace + 1);
+    console.log(`${pc.green("\u2713")} ${pc.cyan(name)}${location ? ` ${pc.dim(location)}` : ""}`);
+    return;
+  }
+  if (line.startsWith("x ")) {
+    const rest = line.slice(2);
+    console.log(`${pc.red("x")} ${pc.cyan(rest)}`);
+    return;
+  }
   if (line.startsWith("  ! ")) {
     const rest = line.slice(4);
     const firstSpace = rest.indexOf(" ");
@@ -2087,13 +2845,13 @@ function emitMessage(line) {
     console.log(`  ${pc.yellow("!")} ${pc.cyan(name)} ${pc.dim(location)}`);
     return;
   }
-  if (line.startsWith("    \u2713 ") || line.startsWith("    ! ") || line.startsWith("    + ")) {
+  if (line.startsWith("    \u2713 ") || line.startsWith("    ! ") || line.startsWith("    ~ ") || line.startsWith("    + ") || line.startsWith("    ? ")) {
     const marker = line.slice(4, 5);
     const rest = line.slice(6);
     const firstSpace = rest.indexOf(" ");
     const name = firstSpace === -1 ? rest : rest.slice(0, firstSpace);
     const location = firstSpace === -1 ? "" : rest.slice(firstSpace + 1);
-    const coloredMarker = marker === "\u2713" ? pc.green("\u2713") : marker === "!" ? pc.yellow("!") : pc.cyan("+");
+    const coloredMarker = marker === "\u2713" ? pc.green("\u2713") : marker === "!" ? pc.yellow("!") : marker === "~" ? pc.blue("~") : marker === "?" ? pc.red("?") : pc.cyan("+");
     console.log(`    ${coloredMarker} ${pc.cyan(name)}${location ? ` ${pc.dim(location)}` : ""}`);
     return;
   }
@@ -2144,12 +2902,6 @@ async function runFramedCommand(title, action) {
 function collectAgents(value, previous) {
   return [...previous ?? [], ...value.split(",").map((entry) => entry.trim()).filter(Boolean)];
 }
-function getMode(value) {
-  if (value === "mv" || value === "cp") {
-    return value;
-  }
-  throw new Error(`Unsupported import mode: ${value}. Use "cp" or "mv".`);
-}
 function getActivationType(value) {
   if (value === "bundle" || value === "skill") {
     return value;
@@ -2174,7 +2926,7 @@ function formatCliErrorMessage(message) {
     }
     const unknownSkillMatch = normalizedMessage.match(/^Unknown skill: (.+)$/);
     if (unknownSkillMatch) {
-      return `Unknown skill: ${unknownSkillMatch[1]}. Run "aweskill skill list" to see available skills.`;
+      return `Unknown skill: ${unknownSkillMatch[1]}. Run "aweskill store list" to see available skills.`;
     }
     const bundleNotFoundMatch = normalizedMessage.match(/^Bundle not found: (.+)$/);
     if (bundleNotFoundMatch) {
@@ -2193,11 +2945,16 @@ function formatCliErrorMessage(message) {
   const hint = hints[argName];
   return `Missing required argument <${argName}>.${hint ? ` ${hint}` : ""}`;
 }
-function writeSupportedAgents(context) {
-  const lines = [
-    "Supported agents:",
-    ...listSupportedAgents().map((agent) => `${agent.id} (${agent.displayName})`)
-  ];
+async function writeSupportedAgents(context) {
+  const lines = ["Supported agents:"];
+  const agents = await listSupportedAgentsWithGlobalStatus(context.homeDir);
+  const installedAgents = agents.filter((agent) => agent.installed).map((agent) => agent.id);
+  lines.push(
+    `Detected ${installedAgents.length} installed global agent${installedAgents.length === 1 ? "" : "s"}: ${installedAgents.length > 0 ? installedAgents.join(", ") : "none"}`
+  );
+  for (const agent of agents) {
+    lines.push(agent.installed ? `\u2713 ${agent.id} (${agent.displayName}) ${agent.skillsDir}` : `x ${agent.id} (${agent.displayName})`);
+  }
   for (const line of lines) {
     context.write(line);
   }
@@ -2205,49 +2962,44 @@ function writeSupportedAgents(context) {
 function configureCommandTree(command) {
   command.showHelpAfterError();
   command.exitOverride((error) => {
-    throw new Error(formatCliErrorMessage(error.message));
+    error.message = formatCliErrorMessage(error.message);
+    throw error;
   });
   for (const child of command.commands) {
     configureCommandTree(child);
   }
 }
+function normalizeVersionAlias(argv) {
+  return argv.map((arg, index) => {
+    if (index >= 2 && arg === "-V") {
+      return "-v";
+    }
+    return arg;
+  });
+}
+function isInitializationExempt(args) {
+  if (args.length === 0) {
+    return true;
+  }
+  if (args.includes("-h") || args.includes("--help") || args.includes("-v") || args.includes("-V") || args.includes("--version")) {
+    return true;
+  }
+  return args[0] === "store" && args[1] === "init";
+}
+async function assertStoreInitialized(homeDir, args) {
+  if (isInitializationExempt(args)) {
+    return;
+  }
+  const { rootDir } = getAweskillPaths(homeDir);
+  if (await pathExists(rootDir)) {
+    return;
+  }
+  throw new Error(`aweskill store is not initialized at ${rootDir}. Run "aweskill store init" first.`);
+}
 function createProgram(overrides = {}) {
   const context = createRuntimeContext(overrides);
   const program = new Command();
-  program.name("aweskill").description("Local skill orchestration CLI for AI agents").version(AWESKILL_VERSION).helpOption("-h, --help", "Display help");
-  const skill = program.command("skill").description("Manage skills in the central store");
-  skill.command("list").description("List skills in the central store").option("--verbose", "show all skills instead of a short preview", false).action(async (options) => {
-    await runListSkills(context, { verbose: options.verbose });
-  });
-  skill.command("scan").description("Scan supported agent skill directories").option("--verbose", "show scanned skill details instead of per-agent totals", false).action(async (options) => {
-    await runFramedCommand(
-      " aweskill skill scan ",
-      async () => runScan(context, {
-        verbose: options.verbose
-      })
-    );
-  });
-  skill.command("import").argument("[path]").description("Import one skill or a skills root directory").option("--scan", "import scanned skills", false).option("--mode <mode>", "import mode: cp (default) or mv", getMode, "cp").option("--override", "overwrite existing files when importing", false).action(async (sourcePath, options) => {
-    await runFramedCommand(
-      " aweskill skill import ",
-      async () => runImport(context, {
-        sourcePath,
-        scan: options.scan,
-        mode: options.mode,
-        override: options.override
-      })
-    );
-  });
-  skill.command("remove").argument("<skill>").description("Remove a skill from the central store").option("--force", "remove and clean references", false).option("--project <dir>", "project config to inspect").action(async (skillName, options) => {
-    await runFramedCommand(
-      " aweskill skill remove ",
-      async () => runRemove(context, {
-        skillName,
-        force: options.force,
-        projectDir: options.project
-      })
-    );
-  });
+  program.name("aweskill").description("Local skill orchestration CLI for AI agents").version(AWESKILL_VERSION, "-v, --version", "output the version number").helpOption("-h, --help", "Display help");
   const bundle = program.command("bundle").description("Manage skill bundles");
   bundle.command("list").description("List bundles in the central store").option("--verbose", "show all bundles instead of a short preview", false).action(async (options) => {
     await runListBundles(context, { verbose: options.verbose });
@@ -2276,24 +3028,28 @@ function createProgram(overrides = {}) {
   });
   const agent = program.command("agent").description("Manage skills used by agents");
   agent.command("supported").description("List supported agent ids and display names").action(async () => {
-    writeSupportedAgents(context);
+    await writeSupportedAgents(context);
   });
-  agent.command("list").description("Inspect agent skill directories and optionally normalize them").option("--global", "check global scope (default when no scope flag given)").option("--project [dir]", "check project scope; uses cwd when dir is omitted").option("--agent <agent>", 'repeat or use comma list; defaults to all; run "aweskill agent supported" to see supported ids', collectAgents).option("--update", "import missing skills into the central store and relink duplicates/new skills", false).option("--verbose", "show all skills in each category instead of a short preview", false).action(async (options) => {
+  agent.command("list").description("Inspect agent skill directories").option("--global", "check global scope (default when no scope flag given)").option("--project [dir]", "check project scope; uses cwd when dir is omitted").option(
+    "--agent <agent>",
+    'repeat or use comma list; defaults to all agents detected at this scope; run "aweskill agent supported" to see supported ids',
+    collectAgents
+  ).option("--verbose", "show all skills in each category instead of a short preview", false).action(async (options) => {
     const isProject = options.project !== void 0;
     const scope = isProject ? "project" : "global";
     const projectDir = isProject && typeof options.project === "string" ? options.project : void 0;
     await runFramedCommand(
       " aweskill agent list ",
-      async () => runCheck(context, {
+      async () => runSync(context, {
         scope,
         agents: options.agent ?? [],
         projectDir,
-        update: options.update,
+        apply: false,
         verbose: options.verbose
       })
     );
   });
-  agent.command("add").description("Create skill projections in agent directories").argument("<type>", "bundle or skill", getActivationType).argument("<name>", 'bundle or skill name(s), comma-separated, or "all"').option("--global", "apply to global scope (default when no scope flag given)").option("--project [dir]", "apply to project scope; uses cwd when dir is omitted").option("--agent <agent>", 'repeat or use comma list; defaults to all; run "aweskill agent supported" to see supported ids', collectAgents).action(async (type, targetName, options) => {
+  agent.command("add").description("Create skill projections in agent directories").argument("<type>", "bundle or skill", getActivationType).argument("<name>", 'bundle or skill name(s), comma-separated, or "all"').option("--global", "apply to global scope (default when no scope flag given)").option("--project [dir]", "apply to project scope; uses cwd when dir is omitted").option("--agent <agent>", 'repeat or use comma list; defaults to all; run "aweskill agent supported" to see supported ids', collectAgents).option("--force", "replace existing duplicate, foreign, or unmanaged targets in agent directories", false).action(async (type, targetName, options) => {
     const isProject = options.project !== void 0;
     const scope = isProject ? "project" : "global";
     const projectDir = isProject && typeof options.project === "string" ? options.project : void 0;
@@ -2304,13 +3060,14 @@ function createProgram(overrides = {}) {
         name: targetName,
         scope,
         agents: options.agent ?? [],
-        projectDir
+        projectDir,
+        force: options.force
       })
     );
   });
   agent.command("remove").description("Remove skill projections in agent directories").argument("<type>", "bundle or skill", getActivationType).argument("<name>", 'bundle or skill name(s), comma-separated, or "all"').option("--global", "apply to global scope (default when no scope flag given)").option("--project [dir]", "apply to project scope; uses cwd when dir is omitted").option("--agent <agent>", 'repeat or use comma list; defaults to all; run "aweskill agent supported" to see supported ids', collectAgents).option(
     "--force",
-    "with skill: remove projection even when this skill is in a bundle that still has other members enabled here",
+    "with skill: remove a single bundle member or delete duplicate, foreign, or unmanaged targets in agent directories",
     false
   ).action(async (type, targetName, options) => {
     const isProject = options.project !== void 0;
@@ -2328,9 +3085,6 @@ function createProgram(overrides = {}) {
       })
     );
   });
-  agent.command("sync").description("Remove stale managed projections whose source skill no longer exists").option("--project <dir>", "also check this project directory").action(async (options) => {
-    await runFramedCommand(" aweskill agent sync ", async () => runSync(context, { projectDir: options.project }));
-  });
   agent.command("recover").description("Convert aweskill-managed symlink projections into full skill directories").option("--global", "recover global scope (default when no scope flag given)").option("--project [dir]", "recover project scope; uses cwd when dir is omitted").option("--agent <agent>", 'repeat or use comma list; defaults to all; run "aweskill agent supported" to see supported ids', collectAgents).action(async (options) => {
     const isProject = options.project !== void 0;
     const scope = isProject ? "project" : "global";
@@ -2348,43 +3102,129 @@ function createProgram(overrides = {}) {
   store.command("init").description("Create ~/.aweskill layout").option("--scan", "scan existing agent directories after init", false).option("--verbose", "show scanned skill details instead of per-agent totals", false).action(async (options) => {
     await runFramedCommand(" aweskill store init ", async () => runInit(context, options));
   });
-  store.command("backup").argument("[archive]").description("Create a timestamped archive of the central skills repository").option("--both", "include bundle definitions in the backup archive", false).action(async (archivePath, options) => {
+  store.command("list").description("List skills in the central store").option("--verbose", "show all skills instead of a short preview", false).action(async (options) => {
+    await runListSkills(context, { verbose: options.verbose });
+  });
+  store.command("scan").description("Scan supported agent skill directories").option("--global", "scan global scope (default when no scope flag given)").option("--project [dir]", "scan project scope; uses cwd when dir is omitted").option("--agent <agent>", 'repeat or use comma list; defaults to all; run "aweskill agent supported" to see supported ids', collectAgents).option("--verbose", "show scanned skill details instead of per-agent totals", false).action(async (options) => {
+    const isProject = options.project !== void 0;
+    const scope = isProject ? "project" : "global";
+    const projectDir = isProject && typeof options.project === "string" ? options.project : void 0;
+    await runFramedCommand(
+      " aweskill store scan ",
+      async () => runScan(context, {
+        scope,
+        agents: options.agent ?? [],
+        projectDir,
+        verbose: options.verbose
+      })
+    );
+  });
+  store.command("import").argument("[path]").description("Import one skill or a skills root directory").option("--scan", "import scanned skills", false).option("--global", "scan global scope when used with --scan (default when no scope flag given)").option("--project [dir]", "scan project scope when used with --scan; uses cwd when dir is omitted").option("--agent <agent>", 'repeat or use comma list; defaults to all; run "aweskill agent supported" to see supported ids', collectAgents).option("--keep-source", "keep the source path in place after importing", false).option("--link-source", "replace the source path with an aweskill-managed projection after importing", false).option("--override", "overwrite existing files when importing", false).action(async (sourcePath, options) => {
+    const isProject = options.project !== void 0;
+    const scope = isProject ? "project" : "global";
+    const projectDir = isProject && typeof options.project === "string" ? options.project : void 0;
+    await runFramedCommand(
+      " aweskill store import ",
+      async () => runImport(context, {
+        sourcePath,
+        scan: options.scan,
+        scope,
+        agents: options.agent ?? [],
+        projectDir,
+        override: options.override,
+        keepSource: options.keepSource,
+        linkSource: options.linkSource
+      })
+    );
+  });
+  store.command("remove").argument("<skill>").description("Remove a skill from the central store").option("--force", "remove and clean references", false).option("--project <dir>", "project config to inspect").action(async (skillName, options) => {
+    await runFramedCommand(
+      " aweskill store remove ",
+      async () => runRemove(context, {
+        skillName,
+        force: options.force,
+        projectDir: options.project
+      })
+    );
+  });
+  store.command("backup").argument("[archive]").description("Create a timestamped archive of the central skills repository").option("--both", "include bundle definitions in the backup archive (default behavior)", true).option("--skills-only", "back up only skills/ without bundles/", false).action(async (archivePath, options) => {
     await runFramedCommand(
       " aweskill store backup ",
       async () => runBackup(context, {
         archivePath,
-        includeBundles: options.both
+        includeBundles: options.skillsOnly ? false : options.both
       })
     );
   });
-  store.command("restore").argument("<archive>").description("Restore skills from a backup archive and auto-back up the current skills first").option("--override", "replace existing skills with the archive contents", false).option("--both", "restore bundle definitions and include them in the pre-restore backup", false).action(async (archivePath, options) => {
+  store.command("restore").argument("<archive>").description("Restore skills from a backup archive or unpacked backup directory and auto-back up the current store first").option("--override", "replace existing skills with the archive contents", false).option("--both", "restore bundle definitions and include them in the pre-restore backup (default behavior)", true).option("--skills-only", "restore only skills/ without bundles/", false).action(async (archivePath, options) => {
     await runFramedCommand(
       " aweskill store restore ",
       async () => runRestore(context, {
         archivePath,
         override: options.override,
-        includeBundles: options.both
+        includeBundles: options.skillsOnly ? false : options.both
       })
     );
   });
+  store.command("where").description("Show the aweskill store location and optionally summarize its contents").option("--verbose", "show core store directories and entry counts", false).action(async (options) => {
+    await runStoreWhere(context, { verbose: options.verbose });
+  });
   const doctor = program.command("doctor").description("Diagnose and repair repository issues");
-  doctor.command("dedupe").description("Find or remove duplicate central-store skills with numeric/version suffixes").option("--fix", "move duplicate skills into dup_skills (or delete them with --delete)", false).option("--delete", "when used with --fix, permanently delete duplicates instead of moving them", false).action(async (options) => {
+  doctor.command("clean").description("Find and optionally remove suspicious non-store entries in skills/ and bundles/").option("--apply", "remove suspicious entries instead of reporting only", false).option("--skills-only", "scan only skills/", false).option("--bundles-only", "scan only bundles/", false).option("--verbose", "show all suspicious entries instead of a short preview", false).action(async (options) => {
+    await runFramedCommand(
+      " aweskill doctor clean ",
+      async () => runClean(context, {
+        apply: options.apply,
+        skillsOnly: options.skillsOnly,
+        bundlesOnly: options.bundlesOnly,
+        verbose: options.verbose
+      })
+    );
+  });
+  doctor.command("dedup").description("Find or remove duplicate central-store skills with numeric/version suffixes").option("--apply", "move duplicate skills into dup_skills (or delete them with --delete)", false).option("--delete", "when used with --apply, permanently delete duplicates instead of moving them", false).action(async (options) => {
     await runFramedCommand(
-      " aweskill doctor dedupe ",
+      " aweskill doctor dedup ",
       async () => runRmdup(context, {
-        remove: options.fix,
+        apply: options.apply,
         delete: options.delete
       })
     );
   });
+  doctor.command("sync").description("Inspect and optionally repair agent-side projections; dry-run by default").option("--apply", "repair broken projections and relink duplicate and matched entries", false).option("--remove-suspicious", "when used with --apply, remove suspicious agent entries instead of only reporting them", false).option("--global", "check global scope (default when no scope flag given)").option("--project [dir]", "check project scope; uses cwd when dir is omitted").option(
+    "--agent <agent>",
+    'repeat or use comma list; defaults to all agents detected at this scope; run "aweskill agent supported" to see supported ids',
+    collectAgents
+  ).option("--verbose", "show all agent skill entries instead of a short preview", false).action(async (options) => {
+    const isProject = options.project !== void 0;
+    const scope = isProject ? "project" : "global";
+    const projectDir = isProject && typeof options.project === "string" ? options.project : void 0;
+    await runFramedCommand(
+      " aweskill doctor sync ",
+      async () => runSync(context, {
+        apply: options.apply,
+        removeSuspicious: options.removeSuspicious,
+        scope,
+        agents: options.agent ?? [],
+        projectDir,
+        verbose: options.verbose
+      })
+    );
+  });
   configureCommandTree(program);
   return program;
 }
 async function main(argv = process.argv) {
   const program = createProgram();
   try {
-    await program.parseAsync(argv);
+    const normalizedArgv = normalizeVersionAlias(argv);
+    const context = createRuntimeContext();
+    await assertStoreInitialized(context.homeDir, normalizedArgv.slice(2));
+    await program.parseAsync(normalizedArgv);
   } catch (error) {
+    const code = typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+    if (code === "commander.version" || code === "commander.helpDisplayed") {
+      return;
+    }
     const message = error instanceof Error ? error.message : String(error);
     if (message === "(outputHelp)" || message === "outputHelp") {
       return;