@ichintansoni/skills-master 0.1.6 → 0.1.8

package/dist/bin.js

@@ -4,15 +4,7 @@
 import { Command } from "commander";
 
 // package.json
-var version = "0.1.6";
-
-// src/types.ts
-var ALL_TARGETS = ["claude", "cursor", "copilot", "agents"];
-var RESOURCE_FILES = {
-  reference: "reference.md",
-  examples: "examples.md",
-  checklist: "checklist.md"
-};
+var version = "0.1.8";
 
 // src/schema/projectConfig.ts
 import { z } from "zod";
@@ -38,7 +30,8 @@ var ProjectConfigSchema = z.object({
     copilot: z.string(),
     agents: z.string()
   }).partial().default({}),
-  scope: z.enum(["project"]).default("project"),
+  /** @deprecated accepted for configs written by older versions; never written. */
+  scope: z.enum(["project"]).optional(),
   /** true = commit generated files; false = add them to .gitignore. */
   commit: z.boolean().default(true)
 }).strict();
@@ -48,6 +41,32 @@ function resolvePaths(cfg) {
   return { ...DEFAULT_PATHS, ...cfg.paths };
 }
 
+// src/types.ts
+var ALL_TARGETS = ["claude", "cursor", "copilot", "agents"];
+var RESOURCE_FILES = {
+  reference: "reference.md",
+  examples: "examples.md",
+  checklist: "checklist.md"
+};
+
+// src/core/stability-note.ts
+function stabilityNote(stability, snapshotDate) {
+  switch (stability) {
+    case "stable":
+      return null;
+    case "emerging":
+      return `> **Emerging** \u2014 this covers an API that was pre-1.0, newly shipped, or still moving as of ${snapshotDate}. Treat the specifics as provisional and confirm against current documentation before relying on them.`;
+    case "contested":
+      return "> **Contested** \u2014 practitioners disagree here and the vendor does not prescribe an answer. Weigh the tradeoffs for the project at hand rather than adopting one option as the default.";
+  }
+}
+function withStabilityNote(body, note) {
+  if (!note) return body;
+  return `${note}
+
+${body.replace(/^\n+/, "")}`;
+}
+
 // src/core/yaml.ts
 import YAML from "yaml";
 function toYaml(obj) {
@@ -71,10 +90,11 @@ import { join } from "path";
 function existsRel(root, rel) {
   return existsSync(join(root, rel));
 }
-var ACRONYMS = {
+var CASED_TOKENS = {
   hig: "HIG",
   ui: "UI",
   ml: "ML",
+  ai: "AI",
   ar: "AR",
   av: "AV",
   os: "OS",
@@ -84,15 +104,48 @@ var ACRONYMS = {
   api: "API",
   sf: "SF",
   spm: "SPM",
+  m3: "M3",
+  nfc: "NFC",
+  http: "HTTP",
+  sqlite: "SQLite",
   ios: "iOS",
   ipados: "iPadOS",
   macos: "macOS",
   tvos: "tvOS",
   visionos: "visionOS",
-  watchos: "watchOS"
+  watchos: "watchOS",
+  chromeos: "ChromeOS",
+  swiftui: "SwiftUI",
+  swiftdata: "SwiftData",
+  uikit: "UIKit",
+  appkit: "AppKit",
+  xcode: "Xcode",
+  xctest: "XCTest",
+  viewmodel: "ViewModel",
+  workmanager: "WorkManager",
+  activitykit: "ActivityKit",
+  arkit: "ARKit",
+  cloudkit: "CloudKit",
+  cryptokit: "CryptoKit",
+  eventkit: "EventKit",
+  gamekit: "GameKit",
+  healthkit: "HealthKit",
+  mapkit: "MapKit",
+  musickit: "MusicKit",
+  passkit: "PassKit",
+  pencilkit: "PencilKit",
+  photokit: "PhotoKit",
+  realitykit: "RealityKit",
+  scenekit: "SceneKit",
+  screencapturekit: "ScreenCaptureKit",
+  spritekit: "SpriteKit",
+  storekit: "StoreKit",
+  tipkit: "TipKit",
+  weatherkit: "WeatherKit",
+  widgetkit: "WidgetKit"
 };
 function titleFromName(name) {
-  return name.split("-").filter(Boolean).map((w) => ACRONYMS[w] ?? w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+  return name.split("-").filter(Boolean).map((w) => CASED_TOKENS[w] ?? w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
 function globsToString(fm) {
   const g = fm.globs;
@@ -110,6 +163,8 @@ var claudeEmitter = {
   detect: (root) => existsRel(root, ".claude"),
   emit(skill, ctx) {
     const dir = `${ctx.paths.claude}/${skill.name}`;
+    const xm = skill.frontmatter["x-skills-master"];
+    const note = stabilityNote(xm.stability, xm.snapshot_date);
     const fm = {
       name: skill.frontmatter.name,
       description: skill.frontmatter.description
@@ -117,7 +172,7 @@ var claudeEmitter = {
     const files = [
       {
         path: `${dir}/SKILL.md`,
-        contents: withFrontmatter(fm, skill.body),
+        contents: withFrontmatter(fm, withStabilityNote(skill.body, note)),
         mode: "whole"
       }
     ];
@@ -152,12 +207,12 @@ function condenseBody(body, opts = {}) {
   if (opts.hadResources || strippedLink) {
     out += `
 
-> ${opts.fullSkillNote ?? DEFAULT_NOTE}`;
+> ${DEFAULT_NOTE}`;
   }
   return out + "\n";
 }
 function summarizeOpenQuestion(body) {
-  const re = /^## Open question[ \t]*\n([\s\S]*?)(?=\n## |\s*$)/m;
+  const re = /^## Open question[ \t]*\n([\s\S]*?)(?=\n## |(?![\s\S]))/m;
   return body.replace(re, (_m, section) => {
     const firstPara = section.trim().split(/\n\s*\n/)[0]?.replace(/\s+/g, " ").trim() ?? "";
     return `## Open question
@@ -166,6 +221,43 @@ Tradeoff: ${firstPara}
 `;
   });
 }
+function sectionHighlights(body, section, max) {
+  const re = new RegExp(`^## ${section}\\n([\\s\\S]*?)(?=\\n## |(?![\\s\\S]))`, "m");
+  const m = re.exec(body);
+  if (!m) return [];
+  const text = m[1];
+  const bullets = [];
+  let inFence = false;
+  for (const line of text.split("\n")) {
+    if (/^(```|~~~)/.test(line.trimStart())) {
+      inFence = !inFence;
+      continue;
+    }
+    if (!inFence && /^- /.test(line.trim())) bullets.push(line.trim());
+    if (bullets.length === max) break;
+  }
+  if (bullets.length > 0) return bullets;
+  const firstPara = text.trim().split(/\n\s*\n/)[0]?.replace(/\s+/g, " ").trim();
+  return firstPara ? [firstPara] : [];
+}
+function digestBody(body, opts) {
+  const guidance = sectionHighlights(body, "Core guidance", 6);
+  const pitfalls = sectionHighlights(body, "Pitfalls", 3);
+  const flatten = (lines) => lines.map((l) => l.replace(L3_LINK_RE, (_m, text) => text));
+  const parts = [];
+  if (opts.stabilityNote) parts.push(opts.stabilityNote);
+  parts.push(opts.description.trim());
+  if (guidance.length > 0) parts.push(`#### Core guidance
+
+${flatten(guidance).join("\n")}`);
+  if (pitfalls.length > 0) parts.push(`#### Pitfalls
+
+${flatten(pitfalls).join("\n")}`);
+  parts.push(
+    `> Digest only \u2014 the complete skill (full guidance, examples, references) ships with the Claude Code, Cursor, and Copilot projections, or via \`skills-master view ${opts.name}\`.`
+  );
+  return parts.join("\n\n");
+}
 
 // src/emitters/cursor.ts
 var cursorEmitter = {
@@ -179,10 +271,14 @@ var cursorEmitter = {
     };
     if (globs) fm.globs = globs;
     fm.alwaysApply = false;
-    const body = condenseBody(skill.body, {
-      openQuestion: "keep",
-      hadResources: hasResources(skill.resources)
-    });
+    const xm = skill.frontmatter["x-skills-master"];
+    const body = withStabilityNote(
+      condenseBody(skill.body, {
+        openQuestion: "keep",
+        hadResources: hasResources(skill.resources)
+      }),
+      stabilityNote(xm.stability, xm.snapshot_date)
+    );
     return [
       {
         path: `${ctx.paths.cursor}/${skill.name}.mdc`,
@@ -197,19 +293,25 @@ var cursorEmitter = {
 var copilotEmitter = {
   id: "copilot",
   label: "GitHub Copilot",
-  detect: (root) => existsRel(root, ".github"),
+  // A bare .github/ (workflows, templates) says nothing about Copilot use —
+  // detect only on Copilot's own customization files.
+  detect: (root) => existsRel(root, ".github/copilot-instructions.md") || existsRel(root, ".github/instructions"),
   emit(skill, ctx) {
     const base = ctx.paths.copilot;
     const instructionsPath = `${base}/instructions/${skill.name}.instructions.md`;
-    const applyTo = globsToString(skill.frontmatter) ?? "**";
+    const applyTo = globsToString(skill.frontmatter);
     const fm = {
-      applyTo,
+      ...applyTo ? { applyTo } : {},
       description: skill.frontmatter.description
     };
-    const body = condenseBody(skill.body, {
-      openQuestion: "keep",
-      hadResources: hasResources(skill.resources)
-    });
+    const xm = skill.frontmatter["x-skills-master"];
+    const body = withStabilityNote(
+      condenseBody(skill.body, {
+        openQuestion: "keep",
+        hadResources: hasResources(skill.resources)
+      }),
+      stabilityNote(xm.stability, xm.snapshot_date)
+    );
     const pointer = `For ${titleFromName(skill.name)} guidance, see \`${instructionsPath}\`.`;
     return [
       {
@@ -234,9 +336,11 @@ var agentsEmitter = {
   label: "AGENTS.md",
   detect: (root) => existsRel(root, "AGENTS.md"),
   emit(skill, ctx) {
-    const body = condenseBody(skill.body, {
-      openQuestion: "summarize",
-      hadResources: hasResources(skill.resources)
+    const xm = skill.frontmatter["x-skills-master"];
+    const body = digestBody(skill.body, {
+      name: skill.name,
+      description: skill.frontmatter.description,
+      stabilityNote: stabilityNote(xm.stability, xm.snapshot_date)
     });
     const section = `### ${titleFromName(skill.name)}
 
@@ -254,12 +358,7 @@ ${body.trim()}`;
 };
 
 // src/emitters/index.ts
-var EMITTERS = [
-  claudeEmitter,
-  cursorEmitter,
-  copilotEmitter,
-  agentsEmitter
-];
+var EMITTERS = [claudeEmitter, cursorEmitter, copilotEmitter, agentsEmitter];
 var BY_ID = new Map(EMITTERS.map((e) => [e.id, e]));
 function getEmitter(id) {
   return BY_ID.get(id);
@@ -271,6 +370,7 @@ function detectTargets(projectRoot) {
 // src/core/project.ts
 import { existsSync as existsSync2, readFileSync, writeFileSync } from "fs";
 import { join as join2 } from "path";
+import { z as z3 } from "zod";
 
 // src/schema/lockfile.ts
 import { z as z2 } from "zod";
@@ -300,6 +400,25 @@ function emptyLockfile(contentRef = "main") {
 }
 
 // src/core/project.ts
+function parseJsonFile(p, schema) {
+  let data;
+  try {
+    data = JSON.parse(readFileSync(p, "utf8"));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`${p} is not valid JSON: ${msg}`);
+  }
+  try {
+    return schema.parse(data);
+  } catch (err) {
+    if (err instanceof z3.ZodError) {
+      const first = err.issues[0];
+      const at = first?.path.length ? ` at "${first.path.join(".")}"` : "";
+      throw new Error(`${p} is invalid${at}: ${first?.message ?? "schema mismatch"}`);
+    }
+    throw err;
+  }
+}
 function configPath(root) {
   return join2(root, CONFIG_FILENAME);
 }
@@ -309,7 +428,7 @@ function lockfilePath(root) {
 function loadConfig(root) {
   const p = configPath(root);
   if (!existsSync2(p)) return null;
-  return ProjectConfigSchema.parse(JSON.parse(readFileSync(p, "utf8")));
+  return parseJsonFile(p, ProjectConfigSchema);
 }
 function loadConfigOrDefault(root) {
   return loadConfig(root) ?? ProjectConfigSchema.parse({});
@@ -321,14 +440,13 @@ function saveConfig(root, cfg) {
 function loadLockfile(root) {
   const p = lockfilePath(root);
   if (!existsSync2(p)) return emptyLockfile();
-  return LockfileSchema.parse(JSON.parse(readFileSync(p, "utf8")));
+  return parseJsonFile(p, LockfileSchema);
 }
 function saveLockfile(root, lock) {
   writeFileSync(lockfilePath(root), JSON.stringify(lock, null, 2) + "\n", "utf8");
 }
 
 // src/util/log.ts
-var quiet = false;
 var sym = {
   info: "\u2022",
   ok: "\u2713",
@@ -337,16 +455,16 @@ var sym = {
 };
 var log = {
   plain(msg) {
-    if (!quiet) console.log(msg);
+    console.log(msg);
   },
   info(msg) {
-    if (!quiet) console.log(`${sym.info} ${msg}`);
+    console.log(`${sym.info} ${msg}`);
   },
   success(msg) {
-    if (!quiet) console.log(`${sym.ok} ${msg}`);
+    console.log(`${sym.ok} ${msg}`);
   },
   warn(msg) {
-    if (!quiet) console.warn(`${sym.warn} ${msg}`);
+    console.warn(`${sym.warn} ${msg}`);
   },
   error(msg) {
     console.error(`${sym.err} ${msg}`);
@@ -357,7 +475,9 @@ var log = {
 function initCommand(opts) {
   const existing = loadConfig(opts.cwd);
   if (existing && !opts.force) {
-    log.warn(`skills-master.json already exists \u2014 leaving it untouched (use --force to overwrite).`);
+    log.warn(
+      `skills-master.json already exists \u2014 leaving it untouched (use --force to overwrite).`
+    );
     return existing;
   }
   let targets = opts.targets;
@@ -427,45 +547,40 @@ import { basename, join as join4 } from "path";
 import matter from "gray-matter";
 
 // src/schema/frontmatter.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 import semver from "semver";
 var NAME_RE = /^[a-z0-9-]{1,64}$/;
 var ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
-var StabilitySchema = z3.enum(["stable", "emerging", "contested"]);
-var SkillClassSchema = z3.enum([
-  "code",
-  "design",
-  "lang-tooling",
-  "overview"
-]);
+var StabilitySchema = z4.enum(["stable", "emerging", "contested"]);
+var SkillClassSchema = z4.enum(["code", "design", "lang-tooling", "overview"]);
 var CLASS_DIR = {
   code: "code",
   design: "design",
   "lang-tooling": "lang-tooling",
   overview: "overviews"
 };
-var XSkillsMasterSchema = z3.object({
-  domain: z3.string().min(1),
+var XSkillsMasterSchema = z4.object({
+  domain: z4.string().min(1),
   class: SkillClassSchema,
-  category: z3.string().min(1),
-  platforms: z3.array(z3.string().min(1)).min(1),
+  category: z4.string().min(1),
+  platforms: z4.array(z4.string().min(1)).min(1),
   /** domain-defined version requirements, e.g. { ios: "17", swift: "6.0" }. */
-  requires: z3.record(z3.string(), z3.string()).optional(),
-  pairs_with: z3.array(z3.string().regex(NAME_RE)).default([]),
+  requires: z4.record(z4.string(), z4.string()).optional(),
+  pairs_with: z4.array(z4.string().regex(NAME_RE)).default([]),
   /** citation URLs to canonical docs — never verbatim content. */
-  sources: z3.array(z3.string().url()).default([]),
-  snapshot_date: z3.string().regex(ISO_DATE_RE, "must be an ISO date (YYYY-MM-DD)"),
+  sources: z4.array(z4.url()).default([]),
+  snapshot_date: z4.string().regex(ISO_DATE_RE, "must be an ISO date (YYYY-MM-DD)"),
   stability: StabilitySchema,
-  version: z3.string().refine((v) => semver.valid(v) != null, "must be a valid semver version")
+  version: z4.string().refine((v) => semver.valid(v) != null, "must be a valid semver version")
 }).strict();
-var GlobsSchema = z3.union([z3.string(), z3.array(z3.string())]).transform((g) => Array.isArray(g) ? g : [g]).optional();
-var FrontmatterSchema = z3.object({
-  name: z3.string().regex(NAME_RE, "must be kebab-case ([a-z0-9-], <=64 chars)"),
-  description: z3.string().min(1, "description is required").max(1024, "description must be <= 1024 characters"),
+var GlobsSchema = z4.union([z4.string(), z4.array(z4.string())]).transform((g) => Array.isArray(g) ? g : [g]).optional();
+var FrontmatterSchema = z4.looseObject({
+  name: z4.string().regex(NAME_RE, "must be kebab-case ([a-z0-9-], <=64 chars)"),
+  description: z4.string().min(1, "description is required").max(1024, "description must be <= 1024 characters"),
   globs: GlobsSchema,
-  tags: z3.array(z3.string()).default([]),
+  tags: z4.array(z4.string()).default([]),
   "x-skills-master": XSkillsMasterSchema
-}).passthrough();
+});
 
 // src/core/parse.ts
 function loadRawSkill(dir, skillsRoot) {
@@ -555,16 +670,57 @@ function buildRegistry(skillsRoot, version2 = "0.1.0") {
   };
 }
 
+// src/schema/registry.ts
+import { z as z5 } from "zod";
+var RegistryEntrySchema = z5.object({
+  name: z5.string(),
+  domain: z5.string(),
+  class: SkillClassSchema,
+  category: z5.string(),
+  description: z5.string(),
+  platforms: z5.array(z5.string()),
+  stability: StabilitySchema,
+  version: z5.string(),
+  tags: z5.array(z5.string()).default([]),
+  pairs_with: z5.array(z5.string()).default([]),
+  /** path relative to the skills root. */
+  path: z5.string(),
+  /** which on-demand resource files exist. */
+  resources: z5.object({
+    reference: z5.boolean(),
+    examples: z5.boolean(),
+    checklist: z5.boolean()
+  })
+});
+var RegistrySchema = z5.object({
+  $schema: z5.string().optional(),
+  /** aggregate library version (bumped on release). */
+  version: z5.string().default("0.1.0"),
+  skills: z5.array(RegistryEntrySchema).default([])
+});
+var REGISTRY_FILENAME = "registry.json";
+
 // src/content/source.ts
 var DEFAULT_REPO = "github:iChintanSoni/skills-master";
 var CONTENT_REPO_PACKAGE = "skills-master-monorepo";
+var SkillNotFoundError = class extends Error {
+  constructor(skillName, root) {
+    super(`Skill "${skillName}" not found in content at ${root}`);
+    this.skillName = skillName;
+    this.name = "SkillNotFoundError";
+  }
+  skillName;
+};
 var ContentSource = class {
   constructor(root) {
     this.root = root;
   }
   root;
+  #dirs;
+  #registry;
   skillDirs() {
-    return findSkillDirs(this.root);
+    this.#dirs ??= findSkillDirs(this.root);
+    return this.#dirs;
   }
   findDir(name) {
     const dirs = this.skillDirs();
@@ -572,11 +728,27 @@ var ContentSource = class {
   }
   loadSkill(name) {
     const dir = this.findDir(name);
-    if (!dir) throw new Error(`Skill "${name}" not found in content at ${this.root}`);
+    if (!dir) throw new SkillNotFoundError(name, this.root);
     return loadSkill(dir, this.root);
   }
+  /**
+   * The catalog used by list/search/add. Reads the committed registry.json
+   * when the content ships one (it is generated and CI-gated for drift);
+   * otherwise — or if the committed file is unreadable — falls back to
+   * scanning and parsing every skill, which is always ground truth.
+   */
   registry() {
-    return buildRegistry(this.root);
+    this.#registry ??= this.readCommittedRegistry() ?? buildRegistry(this.root);
+    return this.#registry;
+  }
+  readCommittedRegistry() {
+    const p = join5(this.root, "registry.json");
+    if (!existsSync5(p)) return null;
+    try {
+      return RegistrySchema.parse(JSON.parse(readFileSync3(p, "utf8")));
+    } catch {
+      return null;
+    }
   }
 };
 function safeName(dir, root) {
@@ -589,10 +761,15 @@ function safeName(dir, root) {
 async function resolveContent(opts = {}) {
   if (opts.content) {
     const root = isAbsolute(opts.content) ? opts.content : resolve(process.cwd(), opts.content);
+    if (!existsSync5(root)) throw new Error(`--content directory not found: ${root}`);
     return new ContentSource(root);
   }
   const env = process.env.SKILLS_MASTER_CONTENT;
-  if (env) return new ContentSource(resolve(env));
+  if (env) {
+    const root = resolve(env);
+    if (!existsSync5(root)) throw new Error(`SKILLS_MASTER_CONTENT directory not found: ${root}`);
+    return new ContentSource(root);
+  }
   const local = findLocalSkillsDir(opts.cwd ?? process.cwd());
   if (local) return new ContentSource(local);
   return new ContentSource(await fetchRemote(opts.ref ?? "main"));
@@ -618,14 +795,24 @@ function isContentRepoRoot(dir) {
 }
 async function fetchRemote(ref) {
   const repo = process.env.SKILLS_MASTER_REPO ?? DEFAULT_REPO;
-  const cacheDir = join5(homedir(), ".skills-master-cache", ref.replace(/[^\w.-]/g, "_"));
+  const safeRef = ref.trim().replace(/[^\w.-]/g, "_");
+  if (!safeRef) throw new Error(`Invalid content ref "${ref}".`);
+  const cacheDir = join5(homedir(), ".skills-master-cache", safeRef);
   const { downloadTemplate } = await import("giget");
-  const { dir } = await downloadTemplate(`${repo}/skills#${ref}`, {
-    dir: cacheDir,
-    force: true,
-    forceClean: true
-  });
-  return dir;
+  try {
+    const { dir } = await downloadTemplate(`${repo}/skills#${ref.trim()}`, {
+      dir: cacheDir,
+      force: true,
+      forceClean: true
+    });
+    return dir;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Failed to fetch skills content from ${repo}#${ref.trim()}: ${msg}
+Check the ref, or point at a local checkout with --content <dir> or SKILLS_MASTER_CONTENT.`
+    );
+  }
 }
 
 // src/core/install.ts
@@ -644,7 +831,15 @@ function compileSkill(skill, targets, ctx) {
 }
 
 // src/core/writer.ts
-import { existsSync as existsSync6, mkdirSync, readdirSync as readdirSync2, readFileSync as readFileSync4, rmdirSync, rmSync, writeFileSync as writeFileSync2 } from "fs";
+import {
+  existsSync as existsSync6,
+  mkdirSync,
+  readdirSync as readdirSync2,
+  readFileSync as readFileSync4,
+  rmdirSync,
+  rmSync,
+  writeFileSync as writeFileSync2
+} from "fs";
 import { dirname, join as join6 } from "path";
 
 // src/core/markers.ts
@@ -704,21 +899,17 @@ function applyWhole(projectRoot, file, opts) {
       ensureDir(abs);
       writeFileSync2(abs, next, "utf8");
     }
-    return { path: file.path, mode: "whole", action: "created", after: next };
+    return { path: file.path, mode: "whole", action: "created" };
   }
   const current = readFileSync4(abs, "utf8");
   if (current === next) {
     return { path: file.path, mode: "whole", action: "unchanged" };
   }
-  let choice = "overwrite";
-  if (!opts.overwrite) {
-    choice = opts.onConflict ? opts.onConflict(file.path) : opts.dryRun ? "overwrite" : "skip";
-  }
-  if (choice === "skip") {
-    return { path: file.path, mode: "whole", action: "skipped", before: current, after: next };
+  if (!opts.overwrite && !opts.dryRun) {
+    return { path: file.path, mode: "whole", action: "skipped" };
   }
   if (!opts.dryRun) writeFileSync2(abs, next, "utf8");
-  return { path: file.path, mode: "whole", action: "updated", before: current, after: next };
+  return { path: file.path, mode: "whole", action: "updated" };
 }
 function applyBlock(projectRoot, file, opts) {
   const abs = join6(projectRoot, file.path);
@@ -846,13 +1037,31 @@ function ensureGitignored(root, entries) {
   writeFileSync3(p, next, "utf8");
 }
 
+// src/util/targets.ts
+var VALID = new Set(ALL_TARGETS);
+function resolveTargets(cwd, configured, explicit) {
+  if (explicit?.length) return explicit;
+  if (configured.length) return configured;
+  const detected = detectTargets(cwd);
+  return detected.length ? detected : ALL_TARGETS;
+}
+function parseTargets(value) {
+  if (!value) return void 0;
+  if (value === "all") return ALL_TARGETS;
+  const ids = value.split(",").map((s) => s.trim()).filter(Boolean);
+  for (const id of ids) {
+    if (!VALID.has(id)) {
+      throw new Error(`Unknown target "${id}". Valid: ${[...VALID, "all"].join(", ")}.`);
+    }
+  }
+  return ids;
+}
+
 // src/commands/add.ts
 async function addCommand(opts) {
   const cfg = loadConfigOrDefault(opts.cwd);
   const hadConfig = loadConfig(opts.cwd) != null;
-  let targets = opts.targets?.length ? opts.targets : cfg.targets;
-  if (!targets.length) targets = detectTargets(opts.cwd);
-  if (!targets.length) targets = ALL_TARGETS;
+  const targets = resolveTargets(opts.cwd, cfg.targets, opts.targets);
   const content = await resolveContent({
     content: opts.content,
     ref: opts.ref ?? cfg.contentRef,
@@ -871,7 +1080,7 @@ async function addCommand(opts) {
     const byClass = registry2.skills.filter((s) => s.class === token);
     const group = byCategory.length ? byCategory : byClass;
     if (group.length) {
-      group.forEach((s) => selected.add(s.name));
+      for (const s of group) selected.add(s.name);
     } else {
       log.warn(`No skill, category, or class matches "${token}".`);
       skipped.push(token);
@@ -893,16 +1102,22 @@ async function addCommand(opts) {
   const lock = loadLockfile(opts.cwd);
   lock.contentRef = opts.ref ?? cfg.contentRef;
   const installed = [];
+  const ownedFiles = /* @__PURE__ */ new Set();
+  const sharedBlockFiles = /* @__PURE__ */ new Set();
   const prefix = opts.dryRun ? "[dry-run] " : "";
   for (const name of [...selected].sort()) {
     const skill = content.loadSkill(name);
     const result = installSkill(opts.cwd, skill, targets, paths, {
       dryRun: opts.dryRun,
-      overwrite: opts.overwrite,
-      onConflict: opts.onConflict
+      overwrite: opts.overwrite
     });
     if (!opts.dryRun) lock.skills[name] = result.locked;
     installed.push({ name, version: result.version });
+    for (const e of Object.values(result.locked.emitted)) {
+      if (!e) continue;
+      for (const f of e.files) ownedFiles.add(f);
+      if (e.block) sharedBlockFiles.add(e.block);
+    }
     for (const r of result.results) {
       const tag = r.mode === "block" ? `${r.path} [${r.blockId}]` : r.path;
       log.info(`${prefix}${r.action.padEnd(9)} ${tag}`);
@@ -915,8 +1130,15 @@ async function addCommand(opts) {
       log.info("Wrote skills-master.json.");
     }
     if (!cfg.commit) {
-      const outs = targets.map((t) => paths[t]);
-      ensureGitignored(opts.cwd, outs);
+      ensureGitignored(
+        opts.cwd,
+        [...ownedFiles].sort((a, b) => a.localeCompare(b)).map((f) => `/${f}`)
+      );
+      if (sharedBlockFiles.size > 0) {
+        log.warn(
+          `Not gitignoring shared file(s) with managed blocks: ${[...sharedBlockFiles].sort().join(", ")}.`
+        );
+      }
     }
   }
   log.success(
@@ -951,8 +1173,12 @@ async function updateCommand(opts) {
     let skill;
     try {
       skill = content.loadSkill(name);
-    } catch {
-      log.warn(`"${name}" no longer exists in the content library.`);
+    } catch (err) {
+      if (err instanceof SkillNotFoundError) {
+        log.warn(`"${name}" no longer exists in the content library.`);
+      } else {
+        log.error(`Failed to load "${name}": ${err instanceof Error ? err.message : String(err)}`);
+      }
       skipped.push(name);
       continue;
     }
@@ -967,15 +1193,14 @@ async function updateCommand(opts) {
       const e = locked.emitted[t];
       return e && diskHash(opts.cwd, e.files) !== e.hash;
     });
-    if (userEdited && !opts.overwrite && !opts.onConflict) {
+    if (userEdited && !opts.overwrite) {
       log.warn(`${prefix}"${name}" has local edits \u2014 skipping (use --overwrite to replace).`);
       skipped.push(name);
       continue;
     }
     const result = installSkill(opts.cwd, skill, targets, paths, {
       dryRun: opts.dryRun,
-      overwrite: opts.overwrite || !userEdited,
-      onConflict: opts.onConflict
+      overwrite: opts.overwrite || !userEdited
     });
     if (!opts.dryRun) lock.skills[name] = result.locked;
     updated.push(name);
@@ -1009,6 +1234,11 @@ function removeCommand(opts) {
       continue;
     }
     const targets = (opts.targets?.length ? opts.targets : Object.keys(locked.emitted)).filter((t) => locked.emitted[t]);
+    if (targets.length === 0) {
+      log.warn(`"${name}" is not installed to ${opts.targets?.join(", ")} \u2014 nothing to remove.`);
+      missing.push(name);
+      continue;
+    }
     const wholeRemoved = [];
     for (const t of targets) {
       const e = locked.emitted[t];
@@ -1034,9 +1264,44 @@ function removeCommand(opts) {
   return { removed, missing };
 }
 
-// src/commands/doctor.ts
+// src/core/installed-state.ts
 import { existsSync as existsSync9, readFileSync as readFileSync7 } from "fs";
 import { join as join9 } from "path";
+var STATES = ["ok", "edited", "missing"];
+function worst(states) {
+  return states.reduce(
+    (acc, s) => STATES.indexOf(s) > STATES.indexOf(acc) ? s : acc,
+    "ok"
+  );
+}
+function diagnoseInstalled(cwd, lock) {
+  const out = [];
+  for (const name of Object.keys(lock.skills).sort()) {
+    const locked = lock.skills[name];
+    const targets = [];
+    for (const [target, e] of Object.entries(locked.emitted)) {
+      const missingFiles = e.files.filter((f) => !existsSync9(join9(cwd, f)));
+      const edited = missingFiles.length === 0 && diskHash(cwd, e.files) !== e.hash;
+      let missingBlock;
+      if (e.block) {
+        const abs = join9(cwd, e.block);
+        if (!existsSync9(abs) || !hasBlock(readFileSync7(abs, "utf8"), name)) missingBlock = e.block;
+      }
+      const state = missingFiles.length > 0 || missingBlock ? "missing" : edited ? "edited" : "ok";
+      targets.push({ target, missingFiles, edited, missingBlock, state });
+    }
+    targets.sort((a, b) => a.target.localeCompare(b.target));
+    out.push({
+      name,
+      version: locked.version,
+      targets,
+      state: worst(targets.map((t) => t.state))
+    });
+  }
+  return out;
+}
+
+// src/commands/doctor.ts
 function doctorCommand(opts) {
   const problems = [];
   const note = (msg) => problems.push(msg);
@@ -1047,32 +1312,28 @@ function doctorCommand(opts) {
     log.info(`Config targets: ${cfg.targets.length ? cfg.targets.join(", ") : "(auto-detect)"}`);
   }
   const lock = loadLockfile(opts.cwd);
-  const names = Object.keys(lock.skills);
-  if (names.length === 0) {
+  const diagnoses = diagnoseInstalled(opts.cwd, lock);
+  if (diagnoses.length === 0) {
     log.info("No skills installed.");
     return { problems, ok: true };
   }
-  for (const name of names) {
-    const locked = lock.skills[name];
-    for (const [target, e] of Object.entries(locked.emitted)) {
-      for (const file of e.files) {
-        if (!existsSync9(join9(opts.cwd, file))) note(`${name}: missing ${target} file ${file}`);
+  for (const skill of diagnoses) {
+    for (const t of skill.targets) {
+      for (const file of t.missingFiles) {
+        note(`${skill.name}: missing ${t.target} file ${file}`);
       }
-      if (e.files.every((f) => existsSync9(join9(opts.cwd, f)))) {
-        if (diskHash(opts.cwd, e.files) !== e.hash) {
-          note(`${name}: local edits to ${target} output(s) (run \`update --overwrite\` to reset)`);
-        }
+      if (t.edited) {
+        note(
+          `${skill.name}: local edits to ${t.target} output(s) (run \`update --overwrite\` to reset)`
+        );
       }
-      if (e.block) {
-        const abs = join9(opts.cwd, e.block);
-        if (!existsSync9(abs) || !hasBlock(readFileSync7(abs, "utf8"), name)) {
-          note(`${name}: missing managed block in ${e.block}`);
-        }
+      if (t.missingBlock) {
+        note(`${skill.name}: missing managed block in ${t.missingBlock}`);
       }
     }
   }
   if (problems.length === 0) {
-    log.success(`All ${names.length} installed skill(s) look healthy.`);
+    log.success(`All ${diagnoses.length} installed skill(s) look healthy.`);
   } else {
     for (const p of problems) log.warn(p);
     log.plain(`
@@ -1081,6 +1342,211 @@ ${problems.length} problem(s) found.`);
   return { problems, ok: problems.length === 0 };
 }
 
+// src/commands/status.ts
+var MARK = { ok: "ok", edited: "edited", missing: "missing" };
+function statusCommand(opts) {
+  const cfg = loadConfig(opts.cwd);
+  const lock = loadLockfile(opts.cwd);
+  let skills = diagnoseInstalled(opts.cwd, lock);
+  if (opts.names?.length) {
+    const want = new Set(opts.names);
+    skills = skills.filter((s) => want.has(s.name));
+  }
+  if (opts.problemsOnly) skills = skills.filter((s) => s.state !== "ok");
+  const counts = { ok: 0, edited: 0, missing: 0 };
+  for (const s of skills) counts[s.state]++;
+  const report = {
+    contentRef: lock.contentRef,
+    configuredTargets: cfg?.targets ?? [],
+    skills,
+    counts
+  };
+  if (opts.json) {
+    log.plain(JSON.stringify(report, null, 2));
+    return report;
+  }
+  if (Object.keys(lock.skills).length === 0) {
+    log.info("No skills installed \u2014 run `skills-master add <name>`.");
+    return report;
+  }
+  if (skills.length === 0) {
+    log.info(opts.problemsOnly ? "Nothing needs attention." : "No installed skills match.");
+    return report;
+  }
+  log.info(
+    `${skills.length} skill(s) from ref ${report.contentRef}` + (report.configuredTargets.length ? ` \xB7 config targets: ${report.configuredTargets.join(", ")}` : "")
+  );
+  log.plain("");
+  const nameWidth = Math.max(...skills.map((s) => s.name.length));
+  const verWidth = Math.max(...skills.map((s) => s.version.length + 1));
+  for (const s of skills) {
+    const targets = s.targets.map((t) => t.state === "ok" ? t.target : `${t.target} (${MARK[t.state]})`).join(", ");
+    log.plain(
+      `  ${s.name.padEnd(nameWidth)}  ${`v${s.version}`.padEnd(verWidth)}  ${MARK[s.state].padEnd(7)}  ${targets}`
+    );
+  }
+  log.plain("");
+  const parts = [`${counts.ok} ok`];
+  if (counts.edited) parts.push(`${counts.edited} edited`);
+  if (counts.missing) parts.push(`${counts.missing} missing`);
+  log.plain(parts.join(", ") + ".");
+  if (counts.edited || counts.missing) {
+    log.plain("Run `skills-master doctor` for detail, or `update --overwrite` to reset.");
+  }
+  return report;
+}
+
+// src/commands/sync.ts
+async function syncCommand(opts) {
+  const cfg = loadConfigOrDefault(opts.cwd);
+  const lock = loadLockfile(opts.cwd);
+  const targets = resolveTargets(opts.cwd, cfg.targets);
+  const paths = resolvePaths(cfg);
+  const prefix = opts.dryRun ? "[dry-run] " : "";
+  const all = Object.keys(lock.skills).sort();
+  const names = opts.names?.length ? all.filter((n) => opts.names.includes(n)) : all;
+  const result = {
+    synced: [],
+    skipped: [],
+    addedTargets: [],
+    orphaned: [],
+    stale: [],
+    pruned: false
+  };
+  if (all.length === 0) {
+    log.info("No skills installed \u2014 run `skills-master add <name>`.");
+    return result;
+  }
+  if (names.length === 0) {
+    log.warn("No installed skills match.");
+    return result;
+  }
+  const edited = new Map(
+    diagnoseInstalled(opts.cwd, lock).map((d) => [d.name, d.targets.some((t) => t.edited)])
+  );
+  const content = await resolveContent({
+    content: opts.content,
+    ref: opts.ref ?? cfg.contentRef,
+    cwd: opts.cwd
+  });
+  log.info(`Syncing ${names.length} skill(s) to targets: ${targets.join(", ")}`);
+  const addedTargets = /* @__PURE__ */ new Set();
+  const pruneNames = [];
+  const pruneTargets = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    const locked = lock.skills[name];
+    const installedTo = Object.keys(locked.emitted);
+    const orphans = installedTo.filter((t) => !targets.includes(t));
+    if (orphans.length) {
+      result.orphaned.push({ name, targets: orphans });
+      pruneNames.push(name);
+      for (const t of orphans) pruneTargets.add(t);
+    }
+    if (edited.get(name) && !opts.overwrite) {
+      log.warn(`${prefix}"${name}" has local edits \u2014 skipping (use --overwrite to replace).`);
+      result.skipped.push(name);
+      continue;
+    }
+    let skill;
+    try {
+      skill = content.loadSkill(name);
+    } catch (err) {
+      if (err instanceof SkillNotFoundError) {
+        log.warn(`"${name}" no longer exists in the content library \u2014 leaving it in place.`);
+      } else {
+        log.error(`Failed to load "${name}": ${err instanceof Error ? err.message : String(err)}`);
+      }
+      result.skipped.push(name);
+      continue;
+    }
+    for (const t of targets) if (!locked.emitted[t]) addedTargets.add(t);
+    const prevFiles = /* @__PURE__ */ new Set();
+    const prevBlocks = /* @__PURE__ */ new Map();
+    for (const t of targets) {
+      const e = locked.emitted[t];
+      if (!e) continue;
+      for (const f of e.files) prevFiles.add(f);
+      if (e.block) prevBlocks.set(t, e.block);
+    }
+    const emitted = installSkill(opts.cwd, skill, targets, paths, {
+      dryRun: opts.dryRun,
+      overwrite: true
+      // edits were already checked above
+    });
+    const nowFiles = /* @__PURE__ */ new Set();
+    for (const e of Object.values(emitted.locked.emitted)) {
+      for (const f of e.files) nowFiles.add(f);
+    }
+    const staleFiles = [...prevFiles].filter((f) => !nowFiles.has(f));
+    const staleBlocks = [...prevBlocks].filter(([t, b]) => emitted.locked.emitted[t]?.block !== b).map(([, b]) => b);
+    if (staleFiles.length || staleBlocks.length) {
+      result.stale.push({ name, files: staleFiles, blocks: staleBlocks });
+    }
+    if (!opts.dryRun) {
+      lock.skills[name] = {
+        ...emitted.locked,
+        emitted: { ...locked.emitted, ...emitted.locked.emitted }
+      };
+    }
+    result.synced.push(name);
+    for (const r of emitted.results) {
+      if (r.action === "unchanged") continue;
+      const tag = r.mode === "block" ? `${r.path} [${r.blockId}]` : r.path;
+      log.info(`${prefix}${r.action.padEnd(9)} ${tag}`);
+    }
+  }
+  result.addedTargets = [...addedTargets].sort();
+  if (!opts.dryRun) saveLockfile(opts.cwd, lock);
+  if (result.orphaned.length) {
+    const list = [...pruneTargets].sort().join(", ");
+    if (opts.prune) {
+      removeCommand({
+        cwd: opts.cwd,
+        names: pruneNames,
+        targets: [...pruneTargets],
+        dryRun: opts.dryRun
+      });
+      result.pruned = true;
+    } else {
+      log.warn(
+        `${result.orphaned.length} skill(s) still have output for target(s) the config no longer lists: ${list}. Re-run with --prune to remove.`
+      );
+    }
+  }
+  if (result.stale.length) {
+    const gone = [];
+    for (const f of result.stale.flatMap((s) => s.files)) {
+      if (removeWholeFile(opts.cwd, f, opts.dryRun)) {
+        gone.push(f);
+        log.info(`${prefix}moved-from ${f}`);
+      }
+    }
+    pruneEmptyDirs(opts.cwd, gone, opts.dryRun);
+    for (const s of result.stale) {
+      for (const b of s.blocks) {
+        if (removeBlockFromFile(opts.cwd, b, s.name, opts.dryRun)) {
+          log.info(`${prefix}unblocked  ${b} [${s.name}]`);
+        }
+      }
+    }
+  }
+  const bits = [`${result.synced.length} synced`];
+  if (result.addedTargets.length) bits.push(`new target(s): ${result.addedTargets.join(", ")}`);
+  if (result.skipped.length) bits.push(`${result.skipped.length} skipped`);
+  log.success(`${prefix}${bits.join(", ")}.`);
+  return result;
+}
+
+// src/core/search-text.ts
+function searchNormalize(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+function searchableText(parts) {
+  return searchNormalize(
+    [parts.name, parts.description, parts.domain, parts.category, parts.class].join(" ")
+  );
+}
+
 // src/commands/catalog.ts
 async function registryOf(q) {
   const content = await resolveContent({ content: q.content, ref: q.ref, cwd: q.cwd });
@@ -1124,9 +1590,11 @@ ${skills.length} skill(s).`);
 }
 async function searchCommand(opts) {
   const reg = await registryOf(opts);
-  const q = opts.query.toLowerCase();
+  const q = searchNormalize(opts.query);
   const hits = reg.skills.filter(
-    (s) => [s.name, s.description, s.domain, s.category, s.class, ...s.tags].join(" ").toLowerCase().includes(q)
+    (s) => searchNormalize(
+      [s.name, s.description, s.domain, s.category, s.class, ...s.tags].join(" ")
+    ).includes(q)
   );
   if (hits.length === 0) {
     log.info(`No matches for "${opts.query}".`);
@@ -1148,10 +1616,14 @@ async function viewCommand(opts) {
     log.plain(skill.body);
     return;
   }
-  log.plain(`${skill.name}  v${xm.version}  [${xm.domain}/${xm.class}/${xm.category}]  ${xm.stability}`);
+  log.plain(
+    `${skill.name}  v${xm.version}  [${xm.domain}/${xm.class}/${xm.category}]  ${xm.stability}`
+  );
   log.plain(`platforms: ${xm.platforms.join(", ")}`);
   if (xm.requires) {
-    log.plain(`requires: ${Object.entries(xm.requires).map(([k, v]) => `${k} ${v}`).join(", ")}`);
+    log.plain(
+      `requires: ${Object.entries(xm.requires).map(([k, v]) => `${k} ${v}`).join(", ")}`
+    );
   }
   if (xm.pairs_with.length) log.plain(`pairs with: ${xm.pairs_with.join(", ")}`);
   log.plain(`
@@ -1212,10 +1684,21 @@ function lintSkills(skillsRoot) {
       for (const issue of v.issues) {
         diagnostics.push({ relPath: raw.relPath, level: "error", message: issue });
       }
-      loaded.push({ relPath: raw.relPath, folderName: raw.folderName, body: raw.body });
+      loaded.push({
+        relPath: raw.relPath,
+        folderName: raw.folderName,
+        body: raw.body,
+        resources: raw.resources
+      });
       continue;
     }
-    loaded.push({ relPath: raw.relPath, folderName: raw.folderName, fm: v.value, body: raw.body });
+    loaded.push({
+      relPath: raw.relPath,
+      folderName: raw.folderName,
+      fm: v.value,
+      body: raw.body,
+      resources: raw.resources
+    });
     byName.set(v.value.name, v.value);
   }
   const nameDirs = /* @__PURE__ */ new Map();
@@ -1226,7 +1709,11 @@ function lintSkills(skillsRoot) {
   for (const [name, paths] of nameDirs) {
     if (paths.length > 1) {
       for (const p of paths) {
-        diagnostics.push({ relPath: p, level: "error", message: `duplicate skill name "${name}" (also at ${paths.filter((x) => x !== p).join(", ")})` });
+        diagnostics.push({
+          relPath: p,
+          level: "error",
+          message: `duplicate skill name "${name}" (also at ${paths.filter((x) => x !== p).join(", ")})`
+        });
       }
     }
   }
@@ -1245,17 +1732,58 @@ function lintSkills(skillsRoot) {
     if (xm.snapshot_date > todayStr) {
       push("error", `snapshot_date ${xm.snapshot_date} is in the future`);
     }
-    if (xm.stability === "contested" && !/^## Open question\b/m.test(s.body)) {
+    const hasOpenQuestion = /^## Open question\b/m.test(s.body);
+    if (xm.stability === "contested" && !hasOpenQuestion) {
       push("error", `stability is "contested" but no "## Open question" section is present`);
+    } else if (xm.stability !== "contested" && hasOpenQuestion) {
+      push(
+        "error",
+        `"## Open question" is reserved for stability: contested skills \u2014 retitle the section or mark the skill contested`
+      );
+    }
+    if (xm.sources.length > 3) {
+      push("warn", `${xm.sources.length} sources \u2014 keep at most 3 canonical citation URLs`);
+    }
+    const findable = searchableText({
+      name: fm.name,
+      description: fm.description,
+      domain: xm.domain,
+      category: xm.category,
+      class: xm.class
+    });
+    for (const tag of fm.tags ?? []) {
+      if (findable.includes(searchNormalize(tag))) {
+        push("warn", `tag "${tag}" is already in the name or description \u2014 it adds no search term`);
+      }
+    }
+    const l3 = [
+      ["reference", "reference.md"],
+      ["examples", "examples.md"],
+      ["checklist", "checklist.md"]
+    ];
+    for (const [key, file] of l3) {
+      if (s.resources?.[key] != null && !s.body.includes(`(${file}`) && !s.body.includes(`(./${file}`)) {
+        push("warn", `${file} exists but is never linked from the SKILL.md body`);
+      }
     }
     const lineCount = s.body.split("\n").length;
     if (lineCount > MAX_BODY_LINES) {
-      push("error", `SKILL.md body is ${lineCount} lines (max ${MAX_BODY_LINES}); move depth into reference.md/examples.md`);
+      push(
+        "error",
+        `SKILL.md body is ${lineCount} lines (max ${MAX_BODY_LINES}); move depth into reference.md/examples.md`
+      );
     } else if (lineCount > WARN_BODY_LINES) {
-      push("warn", `SKILL.md body is ${lineCount} lines (approaching the ${MAX_BODY_LINES}-line cap)`);
+      push(
+        "warn",
+        `SKILL.md body is ${lineCount} lines (approaching the ${MAX_BODY_LINES}-line cap)`
+      );
     }
-    if (!s.relPath.startsWith(`${xm.domain}/`)) {
-      push("warn", `domain "${xm.domain}" does not match the top folder of "${s.relPath}"`);
+    const expectedPath = `${xm.domain}/${CLASS_DIR[xm.class]}/${xm.category}/${fm.name}`;
+    if (s.relPath !== expectedPath) {
+      push(
+        "error",
+        `on-disk path "${s.relPath}" must be "${expectedPath}" (domain/class dir/category/name from frontmatter)`
+      );
     }
     if (xm.sources.length === 0) {
       push("warn", `no sources \u2014 add at least one canonical documentation URL`);
@@ -1270,6 +1798,12 @@ function lintSkills(skillsRoot) {
         push("warn", `missing recommended section "${heading}"`);
       }
     }
+    if (xm.pairs_with.length > 4) {
+      push(
+        "warn",
+        `${xm.pairs_with.length} pairs_with entries \u2014 keep at most 4; put wider cross-references in "## See also"`
+      );
+    }
     for (const partner of xm.pairs_with) {
       const partnerFm = byName.get(partner);
       if (!partnerFm) {
@@ -1277,7 +1811,10 @@ function lintSkills(skillsRoot) {
         continue;
       }
       if (!partnerFm["x-skills-master"].pairs_with.includes(fm.name)) {
-        push("error", `pairs_with "${partner}" is not reciprocated (add "${fm.name}" to its pairs_with)`);
+        push(
+          "error",
+          `pairs_with "${partner}" is not reciprocated (add "${fm.name}" to its pairs_with)`
+        );
       }
     }
   }
@@ -1305,39 +1842,6 @@ Linted ${result.skillCount} skill(s): ${result.errorCount} error(s), ${result.wa
 // src/commands/registry.ts
 import { existsSync as existsSync10, readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "fs";
 import { join as join10 } from "path";
-
-// src/schema/registry.ts
-import { z as z4 } from "zod";
-var RegistryEntrySchema = z4.object({
-  name: z4.string(),
-  domain: z4.string(),
-  class: SkillClassSchema,
-  category: z4.string(),
-  description: z4.string(),
-  platforms: z4.array(z4.string()),
-  stability: StabilitySchema,
-  version: z4.string(),
-  tags: z4.array(z4.string()).default([]),
-  pairs_with: z4.array(z4.string()).default([]),
-  /** path relative to the skills root. */
-  path: z4.string(),
-  /** which on-demand resource files exist. */
-  resources: z4.object({
-    reference: z4.boolean(),
-    examples: z4.boolean(),
-    checklist: z4.boolean()
-  })
-});
-var RegistrySchema = z4.object({
-  $schema: z4.string().optional(),
-  /** aggregate library version (bumped on release). */
-  version: z4.string().default("0.1.0"),
-  generatedAt: z4.string().optional(),
-  skills: z4.array(RegistryEntrySchema).default([])
-});
-var REGISTRY_FILENAME = "registry.json";
-
-// src/commands/registry.ts
 async function registryBuildCommand(opts) {
   const content = await resolveContent({ content: opts.content, cwd: opts.cwd });
   const registry2 = buildRegistry(content.root, opts.version ?? "0.1.0");
@@ -1433,7 +1937,13 @@ function buildOutputs(content, out, version2) {
       `${PLUGINS_DIR}/${name}/.claude-plugin/plugin.json`,
       JSON.stringify(manifest, null, 2) + "\n"
     );
-    plugins.push({ name, source: `./${PLUGINS_DIR}/${name}`, description, version: version2, category: CLASS_CATEGORY[cls] });
+    plugins.push({
+      name,
+      source: `./${PLUGINS_DIR}/${name}`,
+      description,
+      version: version2,
+      category: CLASS_CATEGORY[cls]
+    });
     counts.push({ name, count });
   }
   plugins.sort((a, b) => a.name.localeCompare(b.name));
@@ -1480,7 +1990,11 @@ async function marketplaceBuildCommand(opts) {
   const stale = [...onDisk].filter((rel) => !files.has(rel)).sort();
   for (const rel of stale) rmSync2(join11(out, rel), { force: true });
   pruneEmptyDirsUnder(join11(out, PLUGINS_DIR));
-  const emitted = [...files].map(([path, contents]) => ({ path, contents, mode: "whole" }));
+  const emitted = [...files].map(([path, contents]) => ({
+    path,
+    contents,
+    mode: "whole"
+  }));
   applyFiles(out, emitted, { overwrite: true });
   for (const { name, count } of counts) log.info(`Built ${name} (${count} skills).`);
   if (stale.length) log.info(`Removed ${stale.length} stale file(s).`);
@@ -1568,18 +2082,6 @@ async function newSkillCommand(opts) {
 }
 
 // src/bin.ts
-var VALID = new Set(ALL_TARGETS);
-function parseTargets(value) {
-  if (!value) return void 0;
-  if (value === "all") return ALL_TARGETS;
-  const ids = value.split(",").map((s) => s.trim()).filter(Boolean);
-  for (const id of ids) {
-    if (!VALID.has(id)) {
-      throw new Error(`Unknown target "${id}". Valid: ${[...VALID, "all"].join(", ")}.`);
-    }
-  }
-  return ids;
-}
 async function run(fn, exitOnFalse = false) {
   try {
     const result = await fn();
@@ -1602,7 +2104,7 @@ program.command("init").description("Detect tools and write skills-master.json")
     })
   )
 );
-program.command("list").description("List available skills").option("--domain <domain>", "e.g. apple, android").option("--class <class>").option("--category <category>").option("--platform <platform>").option("--json").option("--content <dir>", "local skills directory").option("--ref <ref>").action(
+program.command("list").description("List available skills").option("--domain <domain>", "e.g. apple, android").option("--class <class>", "e.g. code, design, lang-tooling, overview").option("--category <category>", "e.g. app-frameworks, compose-ui").option("--platform <platform>", "e.g. ios, watchos, android").option("--json", "machine-readable JSON output").option("--content <dir>", "local skills directory").option("--ref <ref>", "content git ref (tag/branch/sha)").action(
   (opts) => run(
     () => listCommand({
       cwd: process.cwd(),
@@ -1616,15 +2118,21 @@ program.command("list").description("List available skills").option("--domain <d
     })
   )
 );
-program.command("search <query>").description("Search skills by name, description, tags").option("--content <dir>").option("--ref <ref>").action(
+program.command("search <query>").description("Search skills by name, description, tags").option("--content <dir>", "local skills directory").option("--ref <ref>", "content git ref (tag/branch/sha)").action(
   (query, opts) => run(() => searchCommand({ cwd: process.cwd(), query, content: opts.content, ref: opts.ref }))
 );
-program.command("view <name>").description("Show a skill's metadata and body").option("--raw", "print the raw SKILL.md body").option("--content <dir>").option("--ref <ref>").action(
+program.command("view <name>").description("Show a skill's metadata and body").option("--raw", "print the raw SKILL.md body").option("--content <dir>", "local skills directory").option("--ref <ref>", "content git ref (tag/branch/sha)").action(
   (name, opts) => run(
-    () => viewCommand({ cwd: process.cwd(), name, raw: opts.raw, content: opts.content, ref: opts.ref })
+    () => viewCommand({
+      cwd: process.cwd(),
+      name,
+      raw: opts.raw,
+      content: opts.content,
+      ref: opts.ref
+    })
   )
 );
-program.command("add <names...>").description("Install skills (by name, category, or class) into your tools").option("--target <list>", "comma list or 'all'").option("--with-pairs", "also install paired (code<->design) skills").option("--dry-run", "preview without writing").option("--overwrite", "overwrite changed files without asking").option("--content <dir>").option("--ref <ref>").action(
+program.command("add <names...>").description("Install skills (by name, category, or class) into your tools").option("--target <list>", "comma list or 'all'").option("--with-pairs", "also install paired (code<->design) skills").option("--dry-run", "preview without writing").option("--overwrite", "overwrite changed files without asking").option("--content <dir>", "local skills directory").option("--ref <ref>", "content git ref (tag/branch/sha)").action(
   (names, opts) => run(
     () => addCommand({
       cwd: process.cwd(),
@@ -1638,7 +2146,7 @@ program.command("add <names...>").description("Install skills (by name, category
     })
   )
 );
-program.command("update [names...]").description("Re-install skills whose content changed").option("--dry-run").option("--overwrite", "force re-install, replacing local edits").option("--content <dir>").option("--ref <ref>").action(
+program.command("update [names...]").description("Re-install skills whose content changed").option("--dry-run", "preview without writing").option("--overwrite", "force re-install, replacing local edits").option("--content <dir>", "local skills directory").option("--ref <ref>", "content git ref (tag/branch/sha)").action(
   (names, opts) => run(
     () => updateCommand({
       cwd: process.cwd(),
@@ -1650,35 +2158,72 @@ program.command("update [names...]").description("Re-install skills whose conten
     })
   )
 );
-program.command("remove <names...>").description("Remove installed skills").option("--target <list>", "comma list or 'all'").option("--dry-run").action(
+program.command("remove <names...>").description("Remove installed skills").option("--target <list>", "comma list or 'all'").option("--dry-run", "preview without writing").action(
   (names, opts) => run(
-    () => removeCommand({ cwd: process.cwd(), names, targets: parseTargets(opts.target), dryRun: opts.dryRun })
+    () => removeCommand({
+      cwd: process.cwd(),
+      names,
+      targets: parseTargets(opts.target),
+      dryRun: opts.dryRun
+    })
   )
 );
-program.command("doctor").description("Check installed skills for drift and missing files").action(() => run(() => doctorCommand({ cwd: process.cwd() })));
-program.command("lint").description("Validate the skill library (maintainer command)").option("--content <dir>").action((opts) => run(() => lintCommand({ cwd: process.cwd(), content: opts.content }), true));
-program.command("new <spec>").description("Scaffold a new skill: class/category/name (maintainer command)").option("--content <dir>").option("--force").action(
-  (spec, opts) => run(() => newSkillCommand({ cwd: process.cwd(), spec, content: opts.content, force: opts.force }))
+program.command("sync").description("Re-emit installed skills to match the current config (new targets, moved paths)").argument("[names...]", "limit the sync to these installed skills").option("--content <dir>", "local skills directory").option("--ref <git-ref>", "content ref to read from").option("--overwrite", "replace locally edited outputs").option("--prune", "delete outputs for targets the config no longer lists").option("--dry-run", "show what would change without writing").action(
+  (names, opts) => run(
+    () => syncCommand({
+      cwd: process.cwd(),
+      names,
+      content: opts.content,
+      ref: opts.ref,
+      overwrite: opts.overwrite,
+      prune: opts.prune,
+      dryRun: opts.dryRun
+    })
+  )
+);
+program.command("status").description("Show installed skills: versions, targets, and local-edit state").argument("[names...]", "limit the report to these skills").option("--problems", "show only skills that are edited or missing files").option("--json", "machine-readable output").action(
+  (names, opts) => run(
+    () => statusCommand({
+      cwd: process.cwd(),
+      names,
+      problemsOnly: opts.problems,
+      json: opts.json
+    })
+  )
+);
+program.command("doctor").description("Check installed skills for drift and missing files").action(() => run(() => doctorCommand({ cwd: process.cwd() }).ok, true));
+program.command("lint").description("Validate the skill library (maintainer command)").option("--content <dir>", "local skills directory").action((opts) => run(() => lintCommand({ cwd: process.cwd(), content: opts.content }), true));
+program.command("new <spec>").description("Scaffold a new skill: domain/class/category/name (maintainer command)").option("--content <dir>", "local skills directory").option("--force", "overwrite an existing skill directory").action(
+  (spec, opts) => run(
+    () => newSkillCommand({ cwd: process.cwd(), spec, content: opts.content, force: opts.force })
+  )
 );
 var registry = program.command("registry").description("Registry maintenance");
-registry.command("build").description("Generate registry.json from the skill tree").option("--content <dir>").option("--check", "verify the committed registry.json is current (CI)").option("--version <v>").action(
+registry.command("build").description("Generate registry.json from the skill tree").option("--content <dir>", "local skills directory").option("--check", "verify the committed registry.json is current (CI)").option("--set-version <v>", "schema version to stamp into registry.json").action(
   (opts) => run(
-    () => registryBuildCommand({ cwd: process.cwd(), content: opts.content, check: opts.check, version: opts.version }),
+    () => registryBuildCommand({
+      cwd: process.cwd(),
+      content: opts.content,
+      check: opts.check,
+      version: opts.setVersion
+    }),
     true
   )
 );
 var marketplace = program.command("marketplace").description("Claude marketplace maintenance");
-marketplace.command("build").description("Generate .claude-plugin/marketplace.json and per-class plugins").option("--content <dir>").option("--out <dir>", "output root").option("--check", "verify the committed marketplace output is current (CI)").option("--version <v>").action(
+marketplace.command("build").description("Generate .claude-plugin/marketplace.json and per-class plugins").option("--content <dir>", "local skills directory").option("--out <dir>", "output root").option("--check", "verify the committed marketplace output is current (CI)").option("--set-version <v>", "version to stamp into plugin manifests").action(
   (opts) => run(
     () => marketplaceBuildCommand({
       cwd: process.cwd(),
       content: opts.content,
       out: opts.out,
       check: opts.check,
-      version: opts.version
+      version: opts.setVersion
     }),
     true
   )
 );
-program.parseAsync(process.argv);
-//# sourceMappingURL=bin.js.map
+program.parseAsync(process.argv).catch((err) => {
+  log.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+});