@light-merlin-dark/skill-sync 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## Unreleased
+
+## 0.1.4
+- Make bare `skill-sync` / `ss` show a high-signal landing/help view instead of mutating
+- Add `doctor` as the high-signal diagnostic command and `execute` as the explicit mutating command; keep `check` and `sync` as compatibility aliases
+- Discover harness-installed skills as fallback sources, while keeping project-root sources authoritative for the same slug
+- Add frontmatter-based install scoping so harness-native skills can stay local-only or target specific harness ids instead of syncing everywhere
+- Tighten symlink-first behavior by repairing matching copied installs instead of treating them as fully healthy
+- Align CLI `--version` output with the package version
+- Harden `make release` so patch releases can auto-bump version/changelog, publish, commit, tag, push, and refresh the GitHub release in one path
+
+## 0.1.3
+- Makefile release: robust GitHub release notes generation via `--notes-file` and correct escaping of `awk $0`.
+
 ## 0.1.2
 - Report installed “orphan” skills during `skill-sync check` (helps explain why a harness skill UI didn’t update)
 - Add `make release` target (pre-publish → npm publish → git tag + push → GitHub release create/update)

package/README.md

@@ -29,6 +29,7 @@ Sync local repo-backed agent skills across Codex, Claude Code, Cursor, Gemini, H
   - top-level `SKILL.md`
   - nested `skills/*/SKILL.md`
 - Detects installed harness skill roots
+- Supports scoped installs for harness-local skills
 - Plans drift without changing anything
 - Syncs symlinked installs into harnesses
 - Warns when the same skill slug appears multiple times in your configured project roots
@@ -64,19 +65,23 @@ skill-sync sources
 Check drift:
 
 ```bash
-skill-sync check
+skill-sync doctor
+skill-sync doctor --verbose
 ```
 
-Sync:
+Execute:
 
 ```bash
-skill-sync
+skill-sync execute
+skill-sync sync
 ```
 
 Shortcut:
 
 ```bash
 ss
+ss doctor
+ss execute
 ```
 
 ## Default Model
@@ -94,8 +99,9 @@ It complements `npx skills`; it does not replace it.
 Core:
 
 ```bash
+skill-sync doctor
 skill-sync check
-skill-sync
+skill-sync execute
 skill-sync sync
 skill-sync sources
 skill-sync harnesses
@@ -124,13 +130,15 @@ skill-sync harness remove my-tool
 Agent-friendly options:
 
 ```bash
-skill-sync check --json
-skill-sync sync --dry-run --json
+skill-sync doctor --json
+skill-sync execute --dry-run --json
 skill-sync backup restore <id> --dry-run
-skill-sync check --projects-root /path/to/projects --harness codex
-skill-sync check --home /tmp/fake-home
+skill-sync doctor --projects-root /path/to/projects --harness codex
+skill-sync doctor --home /tmp/fake-home
 ```
 
+Bare `skill-sync` / `ss` prints a high-signal landing/help view. Human output defaults to a concise summary. Use `--verbose` when you want the full per-entry plan, including orphan install details during `doctor`.
+
 ## Supported Harness Model
 
 Built-in harness roots currently include:
@@ -156,10 +164,12 @@ skill-sync harness add codex-beta ~/.codex-beta/skills
 
 ## Safety Rules
 
-- `check` never mutates
-- `sync` only replaces entries the tool owns or missing entries
+- `doctor` never mutates
+- `execute` / `sync` only replace entries the tool owns or missing entries
 - unmanaged conflicts are reported, not overwritten
 - duplicate `_dev` slugs are surfaced before harness-level sync planning
+- harness-installed skills can be promoted as fallback sources when no project-root source exists for the same slug
+- harness-native skills can stay local-only via frontmatter instead of being fanned out everywhere
 - backups snapshot harness `skills` directories before or after risky changes
 - restore can recreate symlinks when the original source still exists
 - restore falls back to minimal backed-up `SKILL.md` content when the source no longer exists
@@ -210,7 +220,7 @@ Each backup includes:
 Example:
 
 ```bash
-skill-sync check --json
+skill-sync doctor --json
 ```
 
 Returns structured data for:
@@ -229,6 +239,13 @@ For every immediate child repo under each configured projects root, `skill-sync`
 - `<repo>/SKILL.md`
 - `<repo>/skills/*/SKILL.md`
 
+It also inspects detected harness roots and can treat installed skills there as fallback sources. Project-root sources win over harness-installed sources when the same slug exists in both places.
+
+Harness-root sources can also declare install scope in frontmatter:
+
+- `skill-sync-scope: local-only` keeps that source on its owning harness only
+- `skill-sync-install-on: [codex, hermes]` limits installs to specific harness ids
+
 Canonical install names default to:
 
 - `slugify(frontmatter name)` when `name:` exists
@@ -262,7 +279,7 @@ bun install
 Run the CLI directly:
 
 ```bash
-bun run src/index.ts check
+bun run src/index.ts doctor
 ```
 
 Run tests:
@@ -277,6 +294,16 @@ Build:
 bun run build
 ```
 
+## Release
+
+Patch release:
+
+```bash
+make release
+```
+
+This bumps the patch version, moves the `## Unreleased` notes into the new versioned changelog section, runs lint/test/build, publishes to npm, commits the release, pushes `main`, tags the release, and creates or updates the GitHub release.
+
 ## Positioning
 
 Use `npx skills` when:
@@ -293,3 +320,7 @@ Use `skill-sync` when:
 ## License
 
 MIT
+
+---
+
+Built by [Robert E. Beckner III (Merlin)](https://rbeckner.com)

package/SKILL.md

@@ -9,9 +9,9 @@ Use `skill-sync` as the default interface for local skill-harness maintenance.
 
 ## Core Workflow
 1. Inspect harness detection and discovered skill sources.
-2. Run a dry check before making changes.
+2. Run a doctor pass before making changes.
 3. Create a backup before risky cleanup or restore work.
-4. Sync or restore.
+4. Execute or restore.
 5. Verify the resulting symlinks or restored content.
 
 Start with:
@@ -19,19 +19,21 @@ Start with:
 ```bash
 skill-sync harnesses
 skill-sync sources
-skill-sync check
+skill-sync doctor
+skill-sync doctor --verbose
 ```
 
 Apply changes:
 
 ```bash
-skill-sync
+skill-sync execute
+skill-sync sync
 ```
 
 Or explicitly:
 
 ```bash
-skill-sync sync
+skill-sync execute
 ```
 
 ## Backup Workflow
@@ -65,17 +67,22 @@ skill-sync backup restore <backup-id>
 Use JSON when the output will be consumed by another tool or agent:
 
 ```bash
-skill-sync check --json
+skill-sync doctor --json
 skill-sync sources --json
 skill-sync harnesses --json
+skill-sync execute --json
 ```
 
+Bare `skill-sync` prints a high-signal landing/help view. Default human output is concise. Add `--verbose` when you need the full per-entry plan and orphan listing.
+
 ## Safety Rules
 
-- Prefer `check` before `sync`.
-- If `check` reports a `conflict` due to an existing *unmanaged* install (common case: a skill folder already exists in a harness root like `~/.hermes/skills/<skill>`), resolve by either:
-  - removing the unmanaged directory/file and re-running `sync`, or
+- Prefer `doctor` before `execute`.
+- If `doctor` reports a `conflict` due to an existing *unmanaged* install (common case: a skill folder already exists in a harness root like `~/.hermes/skills/<skill>`), resolve by either:
+  - removing the unmanaged directory/file and re-running `execute`, or
   - restoring via `skill-sync backup restore <backup-id>`.
   Do not leave mixed symlink + real directories behind.
 - Use `--home` for isolated testing against a fake home directory.
 - Use `--projects-root` when you need to constrain discovery to a specific source tree.
+- Project-root sources are authoritative. Harness-installed skills act as fallback sources when no project-root source exists for the same slug.
+- If a harness-native skill should not fan out globally, add `skill-sync-scope: local-only` to its frontmatter. Use `skill-sync-install-on: [harness-a, harness-b]` for explicit multi-harness targeting.

package/dist/index.js

@@ -666,18 +666,53 @@ function timestampId() {
 function slugify(input) {
   return input.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").replace(/[^a-zA-Z0-9.-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
 }
-function parseSkillFrontmatterName(skillFilePath) {
-  const content = readFileSync(skillFilePath, "utf8");
-  if (!content.startsWith("---")) {
-    return;
-  }
-  const parts = content.split(`
----`);
-  if (parts.length < 2) {
-    return;
+function parseSkillFrontmatterContent(content) {
+  const frontmatterLines = extractFrontmatterLines(content);
+  if (!frontmatterLines) {
+    return {};
+  }
+  const frontmatter = {};
+  for (let index = 0;index < frontmatterLines.length; index += 1) {
+    const line = frontmatterLines[index];
+    const nameMatch = line.match(/^name:\s*(.+)\s*$/);
+    if (nameMatch) {
+      frontmatter.name = stripYamlQuotes(nameMatch[1].trim());
+      continue;
+    }
+    const scopeMatch = line.match(/^skill-sync-scope:\s*(.+)\s*$/);
+    if (scopeMatch) {
+      const value = stripYamlQuotes(scopeMatch[1].trim()).toLowerCase();
+      if (value === "global" || value === "local-only") {
+        frontmatter.skillSyncScope = value;
+      }
+      continue;
+    }
+    const installOnInlineMatch = line.match(/^skill-sync-install-on:\s*(.+)\s*$/);
+    if (installOnInlineMatch) {
+      const parsed = parseFrontmatterListValue(installOnInlineMatch[1]);
+      if (parsed.length > 0) {
+        frontmatter.skillSyncInstallOn = parsed;
+      }
+      continue;
+    }
+    if (!/^skill-sync-install-on:\s*$/.test(line)) {
+      continue;
+    }
+    const values = [];
+    while (index + 1 < frontmatterLines.length) {
+      const nextLine = frontmatterLines[index + 1];
+      const itemMatch = nextLine.match(/^\s*-\s+(.+)\s*$/);
+      if (!itemMatch) {
+        break;
+      }
+      values.push(stripYamlQuotes(itemMatch[1].trim()));
+      index += 1;
+    }
+    if (values.length > 0) {
+      frontmatter.skillSyncInstallOn = values;
+    }
   }
-  const match = parts[0].match(/^name:\s*(.+)\s*$/m);
-  return match?.[1]?.trim();
+  return frontmatter;
 }
 function hashContent(content) {
   return createHash("sha1").update(content).digest("hex");
@@ -718,13 +753,45 @@ function readFileSyncLink(path) {
   return readlinkSync(path);
 }
 function pathOwnsEntry(rootPath, entryPath) {
-  const normalizedRoot = resolve(rootPath);
-  const normalizedEntry = resolve(entryPath);
+  const normalizedRoot = normalizeComparablePath(rootPath);
+  const normalizedEntry = normalizeComparablePath(entryPath);
   return normalizedEntry === normalizedRoot || normalizedEntry.startsWith(`${normalizedRoot}/`);
 }
 function removePath(path) {
   rmSync(path, { recursive: true, force: true });
 }
+function extractFrontmatterLines(content) {
+  const lines = content.split(/\r?\n/);
+  if (lines[0] !== "---") {
+    return;
+  }
+  const closingIndex = lines.findIndex((line, index) => index > 0 && line === "---");
+  if (closingIndex === -1) {
+    return;
+  }
+  return lines.slice(1, closingIndex);
+}
+function stripYamlQuotes(value) {
+  if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+function parseFrontmatterListValue(rawValue) {
+  const value = stripYamlQuotes(rawValue.trim());
+  if (!value) {
+    return [];
+  }
+  const inner = value.startsWith("[") && value.endsWith("]") ? value.slice(1, -1) : value;
+  return [...new Set(inner.split(",").map((item) => stripYamlQuotes(item.trim())).filter(Boolean))];
+}
+function normalizeComparablePath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
 
 // src/core/backup.ts
 function createBackup(runtime, harnesses, state) {
@@ -950,7 +1017,8 @@ function getDefaultConfig(homeDir) {
     projectsRoots: [join3(homeDir, "_dev")],
     discovery: {
       ignorePathPrefixes: [],
-      preferPathPrefixes: []
+      preferPathPrefixes: [],
+      includeHarnessRoots: true
     },
     harnesses: {
       custom: []
@@ -975,7 +1043,8 @@ function loadConfig(runtime) {
     projectsRoots: (config.projectsRoots || []).map((root) => expandHomePath(root, runtime.homeDir)),
     discovery: {
       ignorePathPrefixes: (config.discovery?.ignorePathPrefixes || []).map((path) => expandHomePath(path, runtime.homeDir)),
-      preferPathPrefixes: (config.discovery?.preferPathPrefixes || []).map((path) => expandHomePath(path, runtime.homeDir))
+      preferPathPrefixes: (config.discovery?.preferPathPrefixes || []).map((path) => expandHomePath(path, runtime.homeDir)),
+      includeHarnessRoots: config.discovery?.includeHarnessRoots !== false
     },
     harnesses: {
       custom: config.harnesses?.custom || []
@@ -1089,9 +1158,9 @@ function filterHarnesses(harnesses, selectedIds) {
 }
 
 // src/core/sources.ts
-import { existsSync as existsSync5, readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync5, readdirSync as readdirSync3, readFileSync as readFileSync3, realpathSync as realpathSync3 } from "node:fs";
 import { basename as basename2, join as join4, relative as relative2, resolve as resolve4 } from "node:path";
-function discoverSkillSet(config) {
+function discoverSkillSet(config, harnesses = []) {
   const discovered = [];
   const discovery = getDiscoveryConfig(config);
   for (const projectsRoot of config.projectsRoots) {
@@ -1110,6 +1179,9 @@ function discoverSkillSet(config) {
       }
     }
   }
+  if (discovery.includeHarnessRoots) {
+    discovered.push(...discoverHarnessSkills(harnesses));
+  }
   const filtered = discovered.filter((skill) => !isIgnoredSource(skill.sourcePath, discovery.ignorePathPrefixes));
   const deduped = new Map;
   for (const skill of filtered) {
@@ -1119,7 +1191,7 @@ function discoverSkillSet(config) {
       deduped.set(key, skill);
       continue;
     }
-    if (existing.sourceType === "nested" && skill.sourceType === "repo-root") {
+    if (compareEquivalentSourcePreference(skill, existing) < 0) {
       deduped.set(key, skill);
     }
   }
@@ -1129,27 +1201,39 @@ function discoverSkillSet(config) {
     sourceDiagnostics
   };
 }
-function buildDiscoveredSkill(projectsRoot, repoPath, sourcePath, skillFilePath, sourceType) {
-  const metadataName = parseSkillFrontmatterName(skillFilePath);
-  const contentHash = hashContent(readFileSync3(skillFilePath, "utf8"));
+function buildDiscoveredSkill(projectsRoot, repoPath, sourcePath, skillFilePath, sourceType, harnessId) {
+  const normalizedProjectsRoot = normalizeExistingPath(projectsRoot);
+  const normalizedRepoPath = normalizeExistingPath(repoPath);
+  const normalizedSourcePath = normalizeExistingPath(sourcePath);
+  const normalizedSkillFilePath = normalizeExistingPath(skillFilePath);
+  const skillContent = readFileSync3(normalizedSkillFilePath, "utf8");
+  const frontmatter = parseSkillFrontmatterContent(skillContent);
+  const metadataName = frontmatter.name;
+  const contentHash = hashContent(skillContent);
   const fallbackName = sourceType === "repo-root" ? basename2(repoPath) : basename2(sourcePath);
   const canonicalSlug = slugify(metadataName || fallbackName);
-  const sourceKey = resolve4(sourcePath);
+  const sourceKey = normalizedSourcePath;
   return {
     sourceKey,
-    sourcePath: resolve4(sourcePath),
-    skillFilePath: resolve4(skillFilePath),
-    repoPath: resolve4(repoPath),
-    projectsRoot: resolve4(projectsRoot),
+    sourcePath: normalizedSourcePath,
+    skillFilePath: normalizedSkillFilePath,
+    repoPath: normalizedRepoPath,
+    projectsRoot: normalizedProjectsRoot,
     sourceType,
+    harnessId,
     metadataName,
+    installHarnessIds: resolveInstallHarnessIds(sourceType, harnessId, frontmatter),
     canonicalSlug,
     contentHash
   };
 }
 function describeSkill(skill) {
+  const scopeSuffix = describeInstallScope(skill);
+  if (skill.sourceType === "harness-root" && skill.harnessId) {
+    return `${skill.canonicalSlug} <= ${skill.harnessId}:${skill.sourcePath}${scopeSuffix}`;
+  }
   const repoRelative = relative2(skill.projectsRoot, skill.sourcePath) || basename2(skill.sourcePath);
-  return `${skill.canonicalSlug} <= ${repoRelative}`;
+  return `${skill.canonicalSlug} <= ${repoRelative}${scopeSuffix}`;
 }
 function isIgnoredSource(sourcePath, ignorePrefixes) {
   return ignorePrefixes.some((prefix) => sourcePath === prefix || sourcePath.startsWith(`${prefix}/`));
@@ -1165,29 +1249,41 @@ function resolveGlobalDuplicates(skills, preferPrefixes) {
   const warnings = [];
   const errors = [];
   for (const group of grouped.values()) {
-    if (group.length === 1) {
-      resolved.push(group[0]);
+    const uniqueGroup = dedupeEquivalentSources(group);
+    const projectBacked = uniqueGroup.filter((skill) => skill.sourceType !== "harness-root");
+    const preferredGroup = projectBacked.length > 0 ? projectBacked : uniqueGroup;
+    if (preferredGroup.length === 1) {
+      resolved.push(preferredGroup[0]);
+      if (uniqueGroup.length > preferredGroup.length) {
+        warnings.push({
+          slug: uniqueGroup[0].canonicalSlug,
+          severity: "warning",
+          resolution: "resolved-by-preference",
+          chosenSourcePath: preferredGroup[0].sourcePath,
+          sourcePaths: uniqueGroup.map((skill) => skill.sourcePath).sort()
+        });
+      }
       continue;
     }
-    const distinctHashes = new Set(group.map((skill) => skill.contentHash));
+    const distinctHashes = new Set(preferredGroup.map((skill) => skill.contentHash));
     if (distinctHashes.size !== 1) {
-      resolved.push(...group);
+      resolved.push(...preferredGroup);
       errors.push({
-        slug: group[0].canonicalSlug,
+        slug: preferredGroup[0].canonicalSlug,
         severity: "error",
         resolution: "unresolved",
-        sourcePaths: group.map((skill) => skill.sourcePath).sort()
+        sourcePaths: preferredGroup.map((skill) => skill.sourcePath).sort()
       });
       continue;
     }
-    const sorted = [...group].sort((a, b) => compareDiscoveredSkills(a, b, preferPrefixes));
+    const sorted = [...preferredGroup].sort((a, b) => compareDiscoveredSkills(a, b, preferPrefixes));
     resolved.push(sorted[0]);
     warnings.push({
-      slug: group[0].canonicalSlug,
+      slug: preferredGroup[0].canonicalSlug,
       severity: "warning",
       resolution: "resolved-by-preference",
       chosenSourcePath: sorted[0].sourcePath,
-      sourcePaths: group.map((skill) => skill.sourcePath).sort()
+      sourcePaths: uniqueGroup.map((skill) => skill.sourcePath).sort()
     });
   }
   return {
@@ -1201,10 +1297,15 @@ function resolveGlobalDuplicates(skills, preferPrefixes) {
 function getDiscoveryConfig(config) {
   return {
     ignorePathPrefixes: config.discovery?.ignorePathPrefixes ?? [],
-    preferPathPrefixes: config.discovery?.preferPathPrefixes ?? []
+    preferPathPrefixes: config.discovery?.preferPathPrefixes ?? [],
+    includeHarnessRoots: config.discovery?.includeHarnessRoots !== false
   };
 }
 function compareDiscoveredSkills(a, b, preferPrefixes) {
+  const typePriority = compareSourceTypePriority(a, b);
+  if (typePriority !== 0) {
+    return typePriority;
+  }
   const rankA = getPreferenceRank(a.sourcePath, preferPrefixes);
   const rankB = getPreferenceRank(b.sourcePath, preferPrefixes);
   if (rankA !== rankB) {
@@ -1212,6 +1313,18 @@ function compareDiscoveredSkills(a, b, preferPrefixes) {
   }
   return a.sourcePath.localeCompare(b.sourcePath);
 }
+function compareSourceTypePriority(a, b) {
+  return getSourceTypePriority(a.sourceType) - getSourceTypePriority(b.sourceType);
+}
+function getSourceTypePriority(sourceType) {
+  if (sourceType === "repo-root") {
+    return 0;
+  }
+  if (sourceType === "nested") {
+    return 1;
+  }
+  return 2;
+}
 function getPreferenceRank(sourcePath, preferPrefixes) {
   const matchIndex = preferPrefixes.findIndex((prefix) => sourcePath === prefix || sourcePath.startsWith(`${prefix}/`));
   return matchIndex === -1 ? Number.MAX_SAFE_INTEGER : matchIndex;
@@ -1221,10 +1334,124 @@ function compareDiagnostics(a, b) {
 `).localeCompare(b.sourcePaths.join(`
 `));
 }
+function discoverHarnessSkills(harnesses) {
+  const discovered = [];
+  for (const harness of harnesses) {
+    if (!harness.detected) {
+      continue;
+    }
+    let children = [];
+    try {
+      children = readdirSync3(harness.rootPath);
+    } catch {
+      continue;
+    }
+    for (const child of children) {
+      if (shouldIgnoreHarnessSkillName(child)) {
+        continue;
+      }
+      const entryPath = join4(harness.rootPath, child);
+      const resolved = resolveHarnessSkillSource(entryPath);
+      if (!resolved) {
+        continue;
+      }
+      const ownerHarnessId = resolveSourceHarnessId(resolved.sourcePath, harnesses) || harness.id;
+      const ownerHarnessRoot = harnesses.find((candidate) => candidate.id === ownerHarnessId)?.rootPath || harness.rootPath;
+      discovered.push(buildDiscoveredSkill(ownerHarnessRoot, resolved.sourcePath, resolved.sourcePath, resolved.skillFilePath, "harness-root", ownerHarnessId));
+    }
+  }
+  return discovered;
+}
+function resolveHarnessSkillSource(entryPath) {
+  const inspection = inspectEntry(entryPath);
+  if (!inspection.exists) {
+    return null;
+  }
+  if (inspection.type === "directory") {
+    const skillFilePath = join4(entryPath, "SKILL.md");
+    if (!existsSync5(skillFilePath)) {
+      return null;
+    }
+    return {
+      sourcePath: resolve4(entryPath),
+      skillFilePath: resolve4(skillFilePath)
+    };
+  }
+  if (inspection.type === "symlink" && inspection.resolvedTarget) {
+    const skillFilePath = join4(inspection.resolvedTarget, "SKILL.md");
+    if (!existsSync5(skillFilePath)) {
+      return null;
+    }
+    return {
+      sourcePath: resolve4(inspection.resolvedTarget),
+      skillFilePath: resolve4(skillFilePath)
+    };
+  }
+  return null;
+}
+function shouldIgnoreHarnessSkillName(name) {
+  return name.startsWith(".") || name.includes(".backup-");
+}
+function normalizeExistingPath(path) {
+  try {
+    return realpathSync3(path);
+  } catch {
+    return resolve4(path);
+  }
+}
+function dedupeEquivalentSources(skills) {
+  const unique = new Map;
+  for (const skill of skills) {
+    const key = `${skill.canonicalSlug}::${skill.sourcePath}`;
+    const existing = unique.get(key);
+    if (!existing || compareEquivalentSourcePreference(skill, existing) < 0) {
+      unique.set(key, skill);
+    }
+  }
+  return [...unique.values()];
+}
+function resolveInstallHarnessIds(sourceType, harnessId, frontmatter) {
+  if (frontmatter.skillSyncInstallOn && frontmatter.skillSyncInstallOn.length > 0) {
+    return frontmatter.skillSyncInstallOn;
+  }
+  if (sourceType === "harness-root" && harnessId && frontmatter.skillSyncScope === "local-only") {
+    return [harnessId];
+  }
+  return;
+}
+function describeInstallScope(skill) {
+  if (!skill.installHarnessIds || skill.installHarnessIds.length === 0) {
+    return "";
+  }
+  if (skill.sourceType === "harness-root" && skill.harnessId && skill.installHarnessIds.length === 1 && skill.installHarnessIds[0] === skill.harnessId) {
+    return ` [local-only: ${skill.harnessId}]`;
+  }
+  return ` [install-on: ${skill.installHarnessIds.join(", ")}]`;
+}
+function resolveSourceHarnessId(sourcePath, harnesses) {
+  return harnesses.filter((harness) => pathOwnsEntry(harness.rootPath, sourcePath)).sort((a, b) => b.rootPath.length - a.rootPath.length || a.id.localeCompare(b.id))[0]?.id;
+}
+function compareEquivalentSourcePreference(a, b) {
+  const sourceTypePriority = compareSourceTypePriority(a, b);
+  if (sourceTypePriority !== 0) {
+    return sourceTypePriority;
+  }
+  const ownerPriorityA = a.harnessId ? 0 : 1;
+  const ownerPriorityB = b.harnessId ? 0 : 1;
+  if (ownerPriorityA !== ownerPriorityB) {
+    return ownerPriorityA - ownerPriorityB;
+  }
+  const scopePriorityA = a.installHarnessIds ? 0 : 1;
+  const scopePriorityB = b.installHarnessIds ? 0 : 1;
+  if (scopePriorityA !== scopePriorityB) {
+    return scopePriorityA - scopePriorityB;
+  }
+  return a.sourcePath.localeCompare(b.sourcePath);
+}
 
 // src/core/sync.ts
 import { join as join5, resolve as resolve5 } from "node:path";
-import { existsSync as existsSync6, readdirSync as readdirSync3, readFileSync as readFileSync4, symlinkSync as symlinkSync2 } from "node:fs";
+import { existsSync as existsSync6, readdirSync as readdirSync4, readFileSync as readFileSync4, realpathSync as realpathSync4, symlinkSync as symlinkSync2 } from "node:fs";
 function buildSyncPlan(skills, harnesses, config, state, sourceDiagnostics) {
   const harnessPlans = harnesses.map((harness) => ({
     harness,
@@ -1238,6 +1465,9 @@ function buildSyncPlan(skills, harnesses, config, state, sourceDiagnostics) {
     desiredByHarness.set(harnessPlan.harness.id, new Set);
     const pathClaims = new Map;
     for (const skill of skills) {
+      if (!shouldInstallOnHarness(skill, harnessPlan.harness.id)) {
+        continue;
+      }
       const installName = resolveInstallName(skill, harnessPlan.harness.id, config);
       const destinationPath = join5(harnessPlan.harness.rootPath, installName);
       const existingClaim = pathClaims.get(destinationPath);
@@ -1293,7 +1523,7 @@ function buildSyncPlan(skills, harnesses, config, state, sourceDiagnostics) {
     const desiredSet = desiredByHarness.get(harnessPlan.harness.id) || new Set;
     let children = [];
     try {
-      children = readdirSync3(harnessPlan.harness.rootPath);
+      children = readdirSync4(harnessPlan.harness.rootPath);
     } catch {
       continue;
     }
@@ -1339,7 +1569,7 @@ function buildSyncPlan(skills, harnesses, config, state, sourceDiagnostics) {
 function buildPlannedEntry(skill, harness, installName, destinationPath, state, config) {
   const inspection = inspectEntry(destinationPath);
   const stateEntry = state.managedEntries[destinationPath];
-  const sameSource = inspection.type === "symlink" && inspection.resolvedTarget === resolve5(skill.sourcePath);
+  const sameSource = normalizeComparablePath2(destinationPath) === normalizeComparablePath2(skill.sourcePath) || inspection.type === "symlink" && inspection.resolvedTarget === resolve5(skill.sourcePath);
   const compatibility = inspectCompatibility(destinationPath, skill);
   if (!inspection.exists) {
     return makePlannedEntry(skill, harness, installName, destinationPath, "create", "missing entry will be created");
@@ -1348,7 +1578,7 @@ function buildPlannedEntry(skill, harness, installName, destinationPath, state,
     return makePlannedEntry(skill, harness, installName, destinationPath, "ok", "already synced");
   }
   if (compatibility === "matching-skill") {
-    return makePlannedEntry(skill, harness, installName, destinationPath, "ok", "compatible existing install");
+    return makePlannedEntry(skill, harness, installName, destinationPath, "repair", "matching install will be replaced with a symlink to the authoritative source");
   }
   if (stateEntry) {
     return makePlannedEntry(skill, harness, installName, destinationPath, "repair", "managed entry drift will be repaired");
@@ -1365,7 +1595,7 @@ function inspectCompatibility(destinationPath, skill) {
   }
   const sourceSkillText = readFileSync4(skill.skillFilePath, "utf8");
   if (inspection.type === "directory") {
-    if (readdirSync3(destinationPath).length === 0) {
+    if (readdirSync4(destinationPath).length === 0) {
       return "empty-directory";
     }
     const installedSkillPath = join5(destinationPath, "SKILL.md");
@@ -1385,6 +1615,13 @@ function inspectCompatibility(destinationPath, skill) {
   }
   return "none";
 }
+function normalizeComparablePath2(path) {
+  try {
+    return realpathSync4(path);
+  } catch {
+    return resolve5(path);
+  }
+}
 function makePlannedEntry(skill, harness, installName, destinationPath, action, message) {
   return {
     harnessId: harness.id,
@@ -1397,6 +1634,12 @@ function makePlannedEntry(skill, harness, installName, destinationPath, action,
     message
   };
 }
+function shouldInstallOnHarness(skill, harnessId) {
+  if (!skill.installHarnessIds || skill.installHarnessIds.length === 0) {
+    return true;
+  }
+  return skill.installHarnessIds.includes(harnessId);
+}
 function resolveInstallName(skill, harnessId, config) {
   const override = config.aliases[skill.sourceKey];
   if (override?.harnesses?.[harnessId]) {
@@ -1460,7 +1703,7 @@ function hasDrift(plan) {
 
 // src/index.ts
 var cli = cac("skill-sync");
-var version = "0.1.1";
+var version = "0.1.3";
 function normalizeList(value) {
   if (!value) {
     return [];
@@ -1487,10 +1730,34 @@ function print(value, json) {
   }
   console.log(value);
 }
-function renderPlan(plan) {
+function renderLandingHelp() {
+  return [
+    "skill-sync",
+    "",
+    "High-signal commands:",
+    "  skill-sync doctor           Inspect sources, drift, and orphan installs",
+    "  skill-sync doctor --verbose Show the full per-entry plan",
+    "  skill-sync execute          Apply symlink updates",
+    "  skill-sync sync             Alias for execute",
+    "  skill-sync sources          List discovered source skills",
+    "  skill-sync harnesses        List detected harness roots",
+    "",
+    "Short alias:",
+    "  ss doctor",
+    "  ss execute",
+    "",
+    "Safety:",
+    "  skill-sync backup create",
+    "  skill-sync backup list",
+    "",
+    "Use --help for the full command reference."
+  ].join(`
+`);
+}
+function renderDetailedPlan(plan, options) {
   const lines = [];
   appendSourceDiagnostics(lines, plan.sourceDiagnostics);
-  if (plan.orphanSkills && plan.orphanSkills.length > 0) {
+  if (options?.includeOrphans !== false && plan.orphanSkills && plan.orphanSkills.length > 0) {
     if (lines.length > 0) {
       lines.push("");
     }
@@ -1522,6 +1789,98 @@ function renderPlan(plan) {
   return lines.join(`
 `);
 }
+function renderPlan(plan, options) {
+  if (options.verbose || hasConflicts(plan)) {
+    return renderDetailedPlan(plan, options);
+  }
+  const lines = [];
+  appendSourceDiagnostics(lines, plan.sourceDiagnostics);
+  if (options.includeOrphans !== false && plan.orphanSkills && plan.orphanSkills.length > 0) {
+    if (lines.length > 0) {
+      lines.push("");
+    }
+    const harnessCount = new Set(plan.orphanSkills.map((orphan) => orphan.harnessId)).size;
+    lines.push(`Orphan installed skills: ${plan.orphanSkills.length} detected across ${harnessCount} harness(es)`);
+    lines.push("Run `skill-sync doctor --verbose` to inspect orphan entries.");
+  }
+  const counts = countPlanActions(plan);
+  if (lines.length > 0) {
+    lines.push("");
+  }
+  lines.push(`Summary: ${plan.ok} ok, ${plan.changes} change(s), ${plan.conflicts} conflict(s)`);
+  lines.push(`Actions: ${Object.entries(counts).map(([action, count]) => `${action}=${count}`).join(", ")}`);
+  const harnessLines = summarizeHarnessPlans(plan);
+  if (harnessLines.length > 0) {
+    lines.push("");
+    lines.push("Harness changes:");
+    lines.push(...harnessLines);
+  }
+  return lines.join(`
+`);
+}
+function summarizeHarnessPlans(plan) {
+  const lines = [];
+  for (const harnessPlan of plan.harnesses) {
+    const interestingEntries = harnessPlan.entries.filter((entry) => entry.action !== "ok");
+    if (interestingEntries.length === 0) {
+      continue;
+    }
+    const counts = {};
+    for (const entry of interestingEntries) {
+      counts[entry.action] = (counts[entry.action] || 0) + 1;
+    }
+    lines.push(`- ${harnessPlan.harness.id}: ${Object.entries(counts).map(([action, count]) => `${action}=${count}`).join(", ")}`);
+  }
+  return lines;
+}
+function renderDoctorReport(plan, state, skills, harnessCount, verbose) {
+  if (verbose || hasConflicts(plan)) {
+    return renderDetailedPlan(plan, { includeOrphans: true });
+  }
+  const totalExpectedInstalls = plan.harnesses.flatMap((harness) => harness.entries).filter((entry) => entry.action !== "remove-managed" && entry.action !== "prune-state").length;
+  const trackedExpectedInstalls = plan.harnesses.flatMap((harness) => harness.entries).filter((entry) => entry.action !== "conflict" && Boolean(state.managedEntries[entry.destinationPath])).length;
+  const okButUntracked = plan.harnesses.flatMap((harness) => harness.entries).filter((entry) => entry.action === "ok" && !state.managedEntries[entry.destinationPath]).length;
+  const compatibleCopies = plan.harnesses.flatMap((harness) => harness.entries).filter((entry) => entry.message === "matching install will be replaced with a symlink to the authoritative source").length;
+  const lines = [];
+  appendSourceDiagnostics(lines, plan.sourceDiagnostics);
+  if (lines.length > 0) {
+    lines.push("");
+  }
+  lines.push("Doctor");
+  lines.push(`Sources: ${skills.length} discovered skill source(s)`);
+  const scopedSources = skills.filter((skill) => skill.installHarnessIds && skill.installHarnessIds.length > 0).length;
+  if (scopedSources > 0) {
+    lines.push(`Scope: ${skills.length - scopedSources} global, ${scopedSources} scoped`);
+  }
+  lines.push(`Harnesses: ${harnessCount} detected/enabled root(s)`);
+  lines.push(`Expected installs: ${totalExpectedInstalls}`);
+  lines.push(`State: ${trackedExpectedInstalls} tracked, ${okButUntracked} ok-but-untracked`);
+  lines.push(`Sync: ${plan.changes} change(s), ${plan.conflicts} conflict(s), ${plan.ok} ok`);
+  if (compatibleCopies > 0) {
+    lines.push(`Copies: ${compatibleCopies} matching install(s) still need conversion from copied content to authoritative symlinks`);
+  }
+  if (plan.orphanSkills && plan.orphanSkills.length > 0) {
+    const groupedOrphans = new Map;
+    for (const orphan of plan.orphanSkills) {
+      groupedOrphans.set(orphan.harnessId, (groupedOrphans.get(orphan.harnessId) || 0) + 1);
+    }
+    const topHarnesses = [...groupedOrphans.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 5).map(([harnessId, count]) => `${harnessId}=${count}`).join(", ");
+    lines.push(`Orphans: ${plan.orphanSkills.length} installed skill(s) exist outside the discovered source set`);
+    lines.push(`Top orphan roots: ${topHarnesses}`);
+    lines.push("Diagnosis: project-root skills are syncing correctly. The remaining orphans are typically slug mismatches, backup artifacts, or installed entries that do not yet map to a canonical source.");
+    lines.push("Run `skill-sync doctor --verbose` to inspect orphan entries.");
+  } else {
+    lines.push("Orphans: 0");
+  }
+  const harnessLines = summarizeHarnessPlans(plan);
+  if (harnessLines.length > 0) {
+    lines.push("");
+    lines.push("Harness changes:");
+    lines.push(...harnessLines);
+  }
+  return lines.join(`
+`);
+}
 function appendSourceDiagnostics(lines, sourceDiagnostics) {
   if (sourceDiagnostics.errors.length === 0 && sourceDiagnostics.warnings.length === 0) {
     return;
@@ -1557,39 +1916,58 @@ function planSync(options) {
   return withRuntime(options, (runtime) => {
     const config = loadConfig(runtime);
     config.projectsRoots = resolveProjectsOverride(config.projectsRoots, options);
-    const harnesses = resolveSelectedHarnesses(resolveHarnesses(runtime.homeDir, config), options);
-    const { skills, sourceDiagnostics } = discoverSkillSet(config);
+    const allHarnesses = resolveHarnesses(runtime.homeDir, config).filter((harness) => harness.enabled);
+    const harnesses = resolveSelectedHarnesses(allHarnesses, options);
+    const { skills, sourceDiagnostics } = discoverSkillSet(config, allHarnesses);
     const state = loadState(runtime);
     const plan = buildSyncPlan(skills, harnesses, config, state, sourceDiagnostics);
-    return { runtime, plan, harnesses, skillsCount: skills.length };
+    return { runtime, plan, harnesses, skills, state };
   });
 }
-function printCheckResult(plan, json) {
-  print(json ? plan : renderPlan(plan), json);
+function printDoctorResult(plan, options, state, skills, harnessCount) {
+  print(options.json ? {
+    ...plan,
+    summary: {
+      sourcesDiscovered: skills.length,
+      scopedSources: skills.filter((skill) => skill.installHarnessIds && skill.installHarnessIds.length > 0).length,
+      harnessesDetected: harnessCount,
+      expectedInstalls: plan.harnesses.flatMap((harness) => harness.entries).filter((entry) => entry.action !== "remove-managed" && entry.action !== "prune-state").length,
+      changes: plan.changes,
+      conflicts: plan.conflicts,
+      ok: plan.ok,
+      orphans: plan.orphanSkills?.length || 0
+    }
+  } : renderDoctorReport(plan, state, skills, harnessCount, options.verbose), Boolean(options.json));
   process.exit(hasConflicts(plan) ? 3 : hasDrift(plan) ? 2 : 0);
 }
-cli.command("check", "Show drift without changing anything").option("--json", "Output JSON").option("--dry-run", "Accepted for parity; check is always read-only").option("--projects-root <path>", "Override configured projects root").option("--harness <id>", "Filter to one or more harness ids").option("--home <path>", "Override HOME for skill-sync state and harness resolution").action((options) => {
-  const { plan } = planSync(options);
-  printCheckResult(plan, Boolean(options.json));
+cli.command("doctor", "Inspect current sources, drift, and orphan installs").option("--json", "Output JSON").option("--dry-run", "Accepted for parity; check is always read-only").option("--verbose", "Show detailed plan output").option("--projects-root <path>", "Override configured projects root").option("--harness <id>", "Filter to one or more harness ids").option("--home <path>", "Override HOME for skill-sync state and harness resolution").action((options) => {
+  const { plan, state, skills, harnesses } = planSync(options);
+  printDoctorResult(plan, options, state, skills, harnesses.length);
+});
+cli.command("check", "Alias for doctor").option("--json", "Output JSON").option("--dry-run", "Accepted for parity; check is always read-only").option("--verbose", "Show detailed plan output").option("--projects-root <path>", "Override configured projects root").option("--harness <id>", "Filter to one or more harness ids").option("--home <path>", "Override HOME for skill-sync state and harness resolution").action((options) => {
+  const { plan, state, skills, harnesses } = planSync(options);
+  printDoctorResult(plan, options, state, skills, harnesses.length);
 });
-cli.command("sync", "Apply the desired symlink state").option("--json", "Output JSON").option("--dry-run", "Show changes without mutating").option("--projects-root <path>", "Override configured projects root").option("--harness <id>", "Filter to one or more harness ids").option("--home <path>", "Override HOME for skill-sync state and harness resolution").action((options) => {
-  const { runtime, plan } = planSync(options);
+function runExecute(options) {
+  const { runtime, plan, state } = planSync(options);
   if (hasConflicts(plan)) {
-    print(options.json ? plan : renderPlan(plan), Boolean(options.json));
+    print(options.json ? plan : renderPlan(plan, { verbose: true, includeOrphans: true }), Boolean(options.json));
     process.exit(3);
   }
-  const state = loadState(runtime);
   const nextState = applySyncPlan(plan, state, Boolean(options.dryRun));
   if (!options.dryRun) {
     saveState(runtime, nextState);
   }
-  print(options.json ? plan : renderPlan(plan), Boolean(options.json));
-});
+  print(options.json ? plan : renderPlan(plan, { verbose: options.verbose, includeOrphans: false }), Boolean(options.json));
+}
+cli.command("execute", "Apply the desired symlink state").option("--json", "Output JSON").option("--dry-run", "Show changes without mutating").option("--verbose", "Show detailed plan output").option("--projects-root <path>", "Override configured projects root").option("--harness <id>", "Filter to one or more harness ids").option("--home <path>", "Override HOME for skill-sync state and harness resolution").action(runExecute);
+cli.command("sync", "Alias for execute").option("--json", "Output JSON").option("--dry-run", "Show changes without mutating").option("--verbose", "Show detailed plan output").option("--projects-root <path>", "Override configured projects root").option("--harness <id>", "Filter to one or more harness ids").option("--home <path>", "Override HOME for skill-sync state and harness resolution").action(runExecute);
 cli.command("sources", "List discovered source skills").option("--json", "Output JSON").option("--projects-root <path>", "Override configured projects root").option("--home <path>", "Override HOME for skill-sync state and harness resolution").action((options) => {
   withRuntime(options, (runtime) => {
     const config = loadConfig(runtime);
     config.projectsRoots = resolveProjectsOverride(config.projectsRoots, options);
-    const { skills, sourceDiagnostics } = discoverSkillSet(config);
+    const harnesses = resolveHarnesses(runtime.homeDir, config).filter((harness) => harness.enabled);
+    const { skills, sourceDiagnostics } = discoverSkillSet(config, harnesses);
     if (options.json) {
       print({ skills, sourceDiagnostics }, true);
       return;
@@ -1742,22 +2120,16 @@ cli.help();
 cli.version(version);
 cli.option("--json", "Output JSON");
 cli.option("--dry-run", "Show changes without mutating");
+cli.option("--verbose", "Show detailed plan output");
 cli.option("--projects-root <path>", "Override configured projects root");
 cli.option("--harness <id>", "Filter to one or more harness ids");
 cli.option("--home <path>", "Override HOME for skill-sync state and harness resolution");
 var rawArgs = process.argv.slice(2);
 cli.parse();
-var shouldRunDefaultSync = !rawArgs.includes("--help") && !rawArgs.includes("-h") && !rawArgs.includes("--version") && !rawArgs.includes("-v") && !cli.matchedCommand;
+var shouldRunDefaultSync = rawArgs.length > 0 && !rawArgs.includes("--help") && !rawArgs.includes("-h") && !rawArgs.includes("--version") && !rawArgs.includes("-v") && !cli.matchedCommand;
 if (shouldRunDefaultSync) {
-  const options = cli.options;
-  const { runtime, plan } = planSync(options);
-  if (hasConflicts(plan)) {
-    console.log(renderPlan(plan));
-    process.exit(3);
-  }
-  const nextState = applySyncPlan(plan, loadState(runtime), Boolean(options.dryRun));
-  if (!options.dryRun) {
-    saveState(runtime, nextState);
-  }
-  console.log(renderPlan(plan));
+  print(renderLandingHelp(), false);
+}
+if (rawArgs.length === 0) {
+  print(renderLandingHelp(), false);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@light-merlin-dark/skill-sync",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Sync local repo-backed agent skills across Codex, Claude Code, Cursor, Gemini, Hermes, and other harnesses.",
   "type": "module",
   "main": "dist/index.js",