@rhize/skill-forge 0.8.0 → 0.10.0

package/dist/cli.js

@@ -561,7 +561,7 @@ function resolveMcpCandidateDetail(profile) {
 }
 
 // src/provenance.ts
-import { appendFileSync, existsSync as existsSync6, statSync as statSync3, writeFileSync as writeFileSync3 } from "fs";
+import { appendFileSync, existsSync as existsSync6, readFileSync as readFileSync5, statSync as statSync3, writeFileSync as writeFileSync3 } from "fs";
 import { join as join7 } from "path";
 var FORGE_VERBS = ["DEFER", "ABSORB", "FORK", "REJECT", "WATCH"];
 var LEDGER_HEADER = "# Skill Forge \u2014 Provenance Ledger\n\nOne entry per external-skill ingestion decision.\n";
@@ -600,6 +600,55 @@ function appendProvenance(entry, skillsRoot) {
   appendFileSync(ledgerPath, block, "utf-8");
   return ledgerPath;
 }
+function extractField(block, label) {
+  const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = block.match(new RegExp(`\\*\\*${escaped}:\\*\\*\\s*(.*)`));
+  return match ? match[1].trim() : void 0;
+}
+function parseProvenanceLedger(text) {
+  const entries = [];
+  const warnings = [];
+  const blocks = text.split(/\n## /);
+  for (const block of blocks.slice(1)) {
+    const headerLine = block.split("\n", 1)[0] ?? "";
+    const [namePart, ...dateParts] = headerLine.split(" \u2014 ");
+    const name = namePart?.trim();
+    if (!name) {
+      warnings.push(`skipped malformed ledger block: missing "## <name> \u2014 <date>" header (saw "${headerLine.slice(0, 80)}")`);
+      continue;
+    }
+    const date = dateParts.join(" \u2014 ").trim();
+    const verbRaw = extractField(block, "Verb");
+    if (!verbRaw || !FORGE_VERBS.includes(verbRaw)) {
+      warnings.push(`skipped malformed ledger block for "${name}": missing or invalid Verb (saw "${verbRaw ?? ""}")`);
+      continue;
+    }
+    const driftCheckMatch = block.match(/\*\*Drift check:\*\*\s*`([^`]*)`/);
+    entries.push({
+      name,
+      date,
+      source: extractField(block, "Source") ?? "",
+      upstreamRef: extractField(block, "Upstream ref") ?? "",
+      license: extractField(block, "License") ?? "",
+      verb: verbRaw,
+      target: extractField(block, "Target") ?? "",
+      took: extractField(block, "Took") ?? "",
+      verified: extractField(block, "Verified") ?? "",
+      driftCheck: driftCheckMatch ? driftCheckMatch[1] : "",
+      notes: extractField(block, "Notes") ?? ""
+    });
+  }
+  return { entries, warnings };
+}
+function readProvenanceLedger(skillsRoot) {
+  const ledgerPath = join7(skillsRoot, "SOURCES.md");
+  if (!existsSync6(ledgerPath)) {
+    return { ledgerPath, exists: false, entries: [], warnings: [] };
+  }
+  const text = readFileSync5(ledgerPath, "utf-8");
+  const parsed = parseProvenanceLedger(text);
+  return { ledgerPath, exists: true, ...parsed };
+}
 
 // src/commands/gatePipeline.ts
 import { readdirSync as readdirSync5 } from "fs";
@@ -612,7 +661,7 @@ import {
   existsSync as existsSync8,
   mkdtempSync,
   openSync,
-  readFileSync as readFileSync6,
+  readFileSync as readFileSync7,
   readdirSync as readdirSync3,
   readSync,
   rmSync as rmSync2,
@@ -622,13 +671,13 @@ import { tmpdir } from "os";
 import { basename as basename3, dirname as dirname3, extname as extname3, join as join9, resolve as resolve2 } from "path";
 
 // src/gate/mcpCapabilities.ts
-import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
+import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
 import { extname as extname2, join as join8 } from "path";
 var SOURCE_EXT = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 var MAX_ITEMS_PER_CATEGORY = 200;
 function readJsonSafe(file) {
   try {
-    return JSON.parse(readFileSync5(file, "utf-8"));
+    return JSON.parse(readFileSync6(file, "utf-8"));
   } catch {
     return void 0;
   }
@@ -856,7 +905,7 @@ function readPackageJsonSafe(root) {
   const pkgPath = join9(root, "package.json");
   if (!existsSync8(pkgPath)) return void 0;
   try {
-    return JSON.parse(readFileSync6(pkgPath, "utf-8"));
+    return JSON.parse(readFileSync7(pkgPath, "utf-8"));
   } catch {
     return void 0;
   }
@@ -1016,7 +1065,7 @@ function detectLicense(root, fm) {
   for (const name of names) {
     const p = join9(root, name);
     if (existsSync8(p) && statSync4(p).isFile()) {
-      const head = readFileSync6(p, "utf-8").slice(0, 2e3).toLowerCase();
+      const head = readFileSync7(p, "utf-8").slice(0, 2e3).toLowerCase();
       for (const [hint, label] of Object.entries(SPDX_HINTS)) {
         if (head.includes(hint)) return label;
       }
@@ -1055,7 +1104,7 @@ function scanMcpAndImports(text, root) {
   if (isDir(scriptsDir)) {
     for (const f of walkFiles(scriptsDir)) {
       if (!f.endsWith(".py")) continue;
-      const ft = readFileSync6(f, "utf-8");
+      const ft = readFileSync7(f, "utf-8");
       for (const m2 of ft.match(mcpRefRe) ?? []) mcpRefs.add(m2);
       const importRe = /^\s*(?:import|from)\s+([a-zA-Z0-9_]+)/gm;
       let m;
@@ -1072,7 +1121,7 @@ function scanMcpAndImports(text, root) {
 function profileSkillDir(inputPath) {
   const { skillMd, root, tmpDir } = resolveSkillMd(inputPath);
   try {
-    const text = readFileSync6(skillMd, "utf-8");
+    const text = readFileSync7(skillMd, "utf-8");
     const fm = parseFrontmatter(text);
     const bodyLines = (text.match(/\n/g)?.length ?? 0) + 1;
     const headers = Array.from(text.matchAll(/^#{1,3}\s+(.+)$/gm)).map((m) => m[1]);
@@ -1103,7 +1152,7 @@ function profilePlugin(p) {
   const manifestPath = join9(p, ".claude-plugin", "plugin.json");
   let manifest;
   try {
-    manifest = JSON.parse(readFileSync6(manifestPath, "utf-8"));
+    manifest = JSON.parse(readFileSync7(manifestPath, "utf-8"));
   } catch (err) {
     throw new Error(`could not parse plugin.json under ${p}: ${err.message}`);
   }
@@ -1134,7 +1183,7 @@ function profileMcp(p) {
   if (explicitConfig) {
     let cfg;
     try {
-      cfg = JSON.parse(readFileSync6(explicitConfig, "utf-8"));
+      cfg = JSON.parse(readFileSync7(explicitConfig, "utf-8"));
     } catch (err) {
       throw new Error(`could not parse MCP config ${explicitConfig}: ${err.message}`);
     }
@@ -1153,7 +1202,7 @@ function profileMcp(p) {
   const pkgPath = join9(p, "package.json");
   let pkg2;
   try {
-    pkg2 = JSON.parse(readFileSync6(pkgPath, "utf-8"));
+    pkg2 = JSON.parse(readFileSync7(pkgPath, "utf-8"));
   } catch (err) {
     throw new Error(`could not parse package.json ${pkgPath}: ${err.message}`);
   }
@@ -1311,7 +1360,7 @@ async function scanSafety(targetPath, strictness = DEFAULT_STRICTNESS) {
 }
 
 // src/gate/overlap.ts
-import { existsSync as existsSync9, readFileSync as readFileSync7, readdirSync as readdirSync4 } from "fs";
+import { existsSync as existsSync9, readFileSync as readFileSync8, readdirSync as readdirSync4 } from "fs";
 import { basename as basename4, dirname as dirname4, join as join11, resolve as resolve3 } from "path";
 var STOPWORDS = new Set(
   `
@@ -1321,20 +1370,20 @@ skill skills user claude code based comprehensive enhanced practical including i
 `.split(/\s+/).filter(Boolean)
 );
 var DEFAULT_SET_THRESHOLD = 0.45;
-function splitLimited(text, sep2, maxSplit) {
+function splitLimited(text, sep3, maxSplit) {
   const parts = [];
   let rest = text;
   for (let i = 0; i < maxSplit; i++) {
-    const idx = rest.indexOf(sep2);
+    const idx = rest.indexOf(sep3);
     if (idx === -1) break;
     parts.push(rest.slice(0, idx));
-    rest = rest.slice(idx + sep2.length);
+    rest = rest.slice(idx + sep3.length);
   }
   parts.push(rest);
   return parts;
 }
 function readFrontmatter(skillMdPath) {
-  const text = readFileSync7(skillMdPath, "utf-8");
+  const text = readFileSync8(skillMdPath, "utf-8");
   const meta = { name: basename4(dirname4(skillMdPath)), description: "" };
   if (text.startsWith("---\n")) {
     const block = splitLimited(text, "---", 2)[1] ?? "";
@@ -1705,14 +1754,14 @@ async function mcpScan(targetPath, strictness = DEFAULT_STRICTNESS) {
 }
 
 // src/gate/mcpOverlap.ts
-import { existsSync as existsSync10, readFileSync as readFileSync8 } from "fs";
+import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
 import { resolve as resolve4 } from "path";
 function readTargetServers(targetPath) {
   const path = resolve4(expandHome(targetPath));
   if (!existsSync10(path)) return [];
   let cfg;
   try {
-    cfg = JSON.parse(readFileSync8(path, "utf-8"));
+    cfg = JSON.parse(readFileSync9(path, "utf-8"));
   } catch {
     return [];
   }
@@ -2020,7 +2069,7 @@ async function runGate(candidatePath, skillsRoot, {
 
 // src/queue.ts
 import { randomUUID as randomUUID2 } from "crypto";
-import { existsSync as existsSync11, mkdirSync as mkdirSync5, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync5, readFileSync as readFileSync10, renameSync as renameSync2, rmSync as rmSync3, writeFileSync as writeFileSync4 } from "fs";
 import { join as join13 } from "path";
 function getQueuePath() {
   return join13(getHomeDir(), "queue.json");
@@ -2030,26 +2079,46 @@ function readQueue() {
   if (!existsSync11(path)) {
     return { version: 1, entries: [] };
   }
-  const raw = readFileSync9(path, "utf-8");
+  const raw = readFileSync10(path, "utf-8");
   const parsed = JSON.parse(raw);
   return { version: 1, entries: parsed.entries ?? [] };
 }
-function writeQueue(queue) {
-  mkdirSync5(getHomeDir(), { recursive: true });
-  writeFileSync4(getQueuePath(), JSON.stringify(queue, null, 2) + "\n", "utf-8");
+function writeQueue(queue2) {
+  const home = getHomeDir();
+  mkdirSync5(home, { recursive: true });
+  const finalPath = getQueuePath();
+  const tempPath = join13(home, `.queue.json.tmp-${randomUUID2()}`);
+  try {
+    writeFileSync4(tempPath, JSON.stringify(queue2, null, 2) + "\n", "utf-8");
+    renameSync2(tempPath, finalPath);
+  } catch (err) {
+    rmSync3(tempPath, { force: true });
+    throw err;
+  }
 }
 function appendQueueEntry(entry) {
-  const queue = readQueue();
-  const existingIds = new Set(queue.entries.map((e) => e.id));
+  const queue2 = readQueue();
+  const existingIds = new Set(queue2.entries.map((e) => e.id));
   const full = {
     ...entry,
     id: generateId(existingIds),
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  queue.entries.push(full);
-  writeQueue(queue);
+  queue2.entries.push(full);
+  writeQueue(queue2);
   return full;
 }
+function updateQueueEntry(id, patch) {
+  const queue2 = readQueue();
+  const index = queue2.entries.findIndex((e) => e.id === id);
+  if (index === -1) {
+    throw new Error(`no queue entry with id: ${id}`);
+  }
+  const updated = { ...queue2.entries[index], ...patch };
+  queue2.entries[index] = updated;
+  writeQueue(queue2);
+  return updated;
+}
 function generateId(existingIds) {
   let id;
   do {
@@ -2376,15 +2445,15 @@ import {
   existsSync as existsSync13,
   lstatSync,
   mkdtempSync as mkdtempSync2,
-  readFileSync as readFileSync10,
+  readFileSync as readFileSync11,
   readdirSync as readdirSync6,
   realpathSync,
-  renameSync as renameSync2,
-  rmSync as rmSync3,
+  renameSync as renameSync3,
+  rmSync as rmSync4,
   statSync as statSync8,
   writeFileSync as writeFileSync5
 } from "fs";
-import { basename as basename6, extname as extname5, join as join16, resolve as resolvePath2 } from "path";
+import { basename as basename6, delimiter as delimiter2, extname as extname5, join as join16, resolve as resolvePath2 } from "path";
 var OVERSIZED_SKILL_EST_TOKENS = 5e3;
 function toAuditFindings(source) {
   return source.map((f) => ({ severity: f.severity, rule: f.rule, target: f.file, detail: f.detail }));
@@ -2545,7 +2614,7 @@ function profileAuditedSkill(group, findings, unreadableSkillMdPaths) {
   let sizeBytes;
   try {
     sizeBytes = statSync8(skillMdPath).size;
-    text = readFileSync10(skillMdPath, "utf-8");
+    text = readFileSync11(skillMdPath, "utf-8");
   } catch (err) {
     findings.push({
       severity: "MEDIUM",
@@ -2623,7 +2692,7 @@ function auditMcpTarget(targetPath, notices) {
   }
   if (isToml) {
     try {
-      readFileSync10(targetPath, "utf-8");
+      readFileSync11(targetPath, "utf-8");
     } catch (err) {
       findings.push({
         severity: "MEDIUM",
@@ -2638,7 +2707,7 @@ function auditMcpTarget(targetPath, notices) {
   }
   let raw;
   try {
-    raw = readFileSync10(targetPath, "utf-8");
+    raw = readFileSync11(targetPath, "utf-8");
   } catch (err) {
     findings.push({
       severity: "MEDIUM",
@@ -2672,7 +2741,7 @@ function auditMcpTarget(targetPath, notices) {
 }
 function clusterOverlapPairs(pairs) {
   const parent = /* @__PURE__ */ new Map();
-  function find(x) {
+  function find2(x) {
     if (!parent.has(x)) parent.set(x, x);
     let root = x;
     while (parent.get(root) !== root) root = parent.get(root);
@@ -2685,14 +2754,14 @@ function clusterOverlapPairs(pairs) {
     return root;
   }
   function union(a, b) {
-    const ra = find(a);
-    const rb = find(b);
+    const ra = find2(a);
+    const rb = find2(b);
     if (ra !== rb) parent.set(ra, rb);
   }
   for (const pair of pairs) union(pair.aPath, pair.bPath);
   const groups = /* @__PURE__ */ new Map();
   for (const pair of pairs) {
-    const root = find(pair.aPath);
+    const root = find2(pair.aPath);
     const group = groups.get(root) ?? { members: /* @__PURE__ */ new Set(), topScore: 0 };
     group.members.add(pair.aPath);
     group.members.add(pair.bPath);
@@ -2708,6 +2777,45 @@ function toClusterMembers(members) {
   }
   return sorted;
 }
+function defaultWhich(cmd) {
+  const pathEnv = process.env.PATH ?? "";
+  const dirs = pathEnv.split(delimiter2).filter(Boolean);
+  const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = join16(dir, cmd + ext);
+      try {
+        if (statSync8(candidate).isFile()) return candidate;
+      } catch {
+      }
+    }
+  }
+  return void 0;
+}
+var SKILLSPECTOR_PROVIDER_KEYMAP = {
+  openai: "OPENAI_API_KEY",
+  anthropic: "ANTHROPIC_API_KEY",
+  nv_build: "NVIDIA_INFERENCE_KEY"
+};
+function checkTooling(which2, env) {
+  const skillspectorPath = which2("skillspector");
+  const skillspector = skillspectorPath ? { installed: true } : {
+    installed: false,
+    hint: "NOT installed \u2014 github.com/NVIDIA/skillspector (git clone + make install; Python 3.12+)"
+  };
+  const tokenPresent = Boolean(env.VERCEL_OIDC_TOKEN);
+  const skillsShToken = tokenPresent ? { present: true } : {
+    present: false,
+    hint: "missing \u2014 enable OIDC Federation on your Vercel project, then `vercel link && vercel env pull`"
+  };
+  const provider = env.SKILLSPECTOR_PROVIDER;
+  const providerKeyEnv = provider ? SKILLSPECTOR_PROVIDER_KEYMAP[provider] : void 0;
+  const skillspectorLlm = {
+    configured: Boolean(provider && providerKeyEnv && env[providerKeyEnv]),
+    provider: provider || void 0
+  };
+  return { skillspector, skillsShToken, skillspectorLlm };
+}
 async function auditConfiguredSet(config, options = {}) {
   const now = options.now ?? (() => /* @__PURE__ */ new Date());
   const oversizedThreshold = options.oversizedSkillTokens ?? OVERSIZED_SKILL_EST_TOKENS;
@@ -2828,12 +2936,14 @@ async function auditConfiguredSet(config, options = {}) {
     overlapClusterCount: overlapClusters.length,
     evolveEligibleCount: evolveEligible.length
   };
+  const tooling = checkTooling(options.which ?? defaultWhich, options.env ?? process.env);
   return {
     schemaVersion: 1,
     generatedAt: now().toISOString(),
     inventory: { skillRoots, skills, mcpTargets },
     hygiene: findings,
     opportunities: { overlapClusters, evolveEligible, foundation, overlapLocked: !overlapStatus.enabled },
+    tooling,
     notices,
     summary
   };
@@ -2927,6 +3037,28 @@ function renderOpportunitiesSection(report) {
     `- ${foundation.message}`
   ];
 }
+function renderToolingSection(tooling) {
+  const lines = ["## Tooling", ""];
+  if (!tooling) {
+    lines.push("- (not available in this report)");
+    return lines;
+  }
+  lines.push(`- SkillSpector CLI: ${tooling.skillspector.installed ? "installed" : "NOT installed"}`);
+  if (tooling.skillspector.hint) lines.push(`  - ${tooling.skillspector.hint}`);
+  lines.push(`- skills.sh auth (VERCEL_OIDC_TOKEN): ${tooling.skillsShToken.present ? "present" : "missing"}`);
+  if (tooling.skillsShToken.hint) lines.push(`  - ${tooling.skillsShToken.hint}`);
+  const llm = tooling.skillspectorLlm;
+  if (llm.configured) {
+    lines.push(`- SkillSpector LLM stage (optional): configured (provider: ${sanitizeForMarkdown(llm.provider ?? "")})`);
+  } else if (llm.provider) {
+    lines.push(`- SkillSpector LLM stage (optional): not configured \u2014 SKILLSPECTOR_PROVIDER is "${sanitizeForMarkdown(llm.provider)}" but its API key env var is not set`);
+  } else {
+    lines.push(
+      "- SkillSpector LLM stage (optional): not set \u2014 static scan works without it (use --no-llm); set SKILLSPECTOR_PROVIDER + its API key for semantic analysis"
+    );
+  }
+  return lines;
+}
 function renderAuditMarkdown(report) {
   const { summary } = report;
   const lines = [
@@ -2953,6 +3085,8 @@ function renderAuditMarkdown(report) {
     "",
     ...renderOpportunitiesSection(report),
     "",
+    ...renderToolingSection(report.tooling),
+    "",
     "## Notices",
     "",
     ...bulletList(report.notices, "(none)")
@@ -3024,9 +3158,9 @@ async function scaffoldFoundationSkill(config, profile, targetRoot) {
         `refusing to scaffold a foundation skill: the generated SKILL.md was flagged by the safety scan (${safety.findings.map(formatSafetyFinding).join("; ")})`
       );
     }
-    renameSync2(tempDir, destDir);
+    renameSync3(tempDir, destDir);
   } catch (err) {
-    rmSync3(tempDir, { recursive: true, force: true });
+    rmSync4(tempDir, { recursive: true, force: true });
     throw err;
   }
   try {
@@ -3664,7 +3798,7 @@ async function status() {
 // src/evolve.ts
 import { createInterface as createInterface4 } from "readline/promises";
 import { createHash } from "crypto";
-import { cpSync as cpSync3, existsSync as existsSync16, lstatSync as lstatSync2, mkdtempSync as mkdtempSync3, readFileSync as readFileSync11, rmSync as rmSync4 } from "fs";
+import { cpSync as cpSync3, existsSync as existsSync16, lstatSync as lstatSync2, mkdtempSync as mkdtempSync3, readFileSync as readFileSync12, rmSync as rmSync5 } from "fs";
 import { tmpdir as tmpdir2 } from "os";
 import { basename as basename7, dirname as dirname7, join as join20, resolve as resolvePath4, sep } from "path";
 var SKILLOPT_BIN = "skillopt-sleep";
@@ -3765,7 +3899,7 @@ async function evolve(targetSkillDir, options = {}, deps = {}) {
     safety = await scanSafety(tempDir, strictness);
   } finally {
     try {
-      rmSync4(tempDir, { recursive: true, force: true });
+      rmSync5(tempDir, { recursive: true, force: true });
     } catch (err) {
       console.error(`[skill-forge] failed to clean up temp re-gate dir ${tempDir}: ${err.message}`);
     }
@@ -3847,7 +3981,7 @@ async function evolve(targetSkillDir, options = {}, deps = {}) {
     logOutcome("[skill-forge] queued for ingestion review", json);
   } else if (decision === "reject") {
     try {
-      rmSync4(stagingDir, { recursive: true, force: true });
+      rmSync5(stagingDir, { recursive: true, force: true });
     } catch (err) {
       throw new UserError(
         `rejected the proposal, but removing the staging dir ${stagingDir} failed: ${err.message} \u2014 remove it manually.`
@@ -3902,7 +4036,7 @@ function readManifest(stagingDir) {
   const manifestPath = join20(stagingDir, "manifest.json");
   let raw;
   try {
-    raw = readFileSync11(manifestPath, "utf-8");
+    raw = readFileSync12(manifestPath, "utf-8");
   } catch (err) {
     throw new UserError(`could not read staging manifest ${manifestPath}: ${err.message}`);
   }
@@ -3937,7 +4071,7 @@ function validateManifest(raw, manifestPath) {
 }
 function filesIdentical(a, b) {
   if (!existsSync16(a) || !existsSync16(b)) return false;
-  return readFileSync11(a).equals(readFileSync11(b));
+  return readFileSync12(a).equals(readFileSync12(b));
 }
 function isAlreadyAdopted(stagingDir, manifest) {
   const proposedSkillMd = join20(stagingDir, "proposed_SKILL.md");
@@ -3966,7 +4100,7 @@ function assertNotSymlink(path, label) {
 }
 function sha256File(path) {
   if (!existsSync16(path)) return null;
-  return createHash("sha256").update(readFileSync11(path)).digest("hex");
+  return createHash("sha256").update(readFileSync12(path)).digest("hex");
 }
 
 // src/commands/evolve.ts
@@ -3974,19 +4108,2440 @@ async function evolveCommand(targetSkillDir, options = {}) {
   await evolve(targetSkillDir, options);
 }
 
-// src/cli.ts
-var require2 = createRequire(import.meta.url);
-var pkg = require2("../package.json");
-function parseArtifact(value) {
-  if (value !== "skill" && value !== "mcp") {
-    throw new UserError(`--artifact must be "skill" or "mcp" (got "${value}")`);
+// src/commands/organize.ts
+import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync7 } from "fs";
+import { dirname as dirname8, resolve as resolvePath6 } from "path";
+
+// src/organize.ts
+import { existsSync as existsSync17, readFileSync as readFileSync13, readdirSync as readdirSync7, realpathSync as realpathSync2, statSync as statSync9 } from "fs";
+import { basename as basename8, join as join21, resolve as resolvePath5 } from "path";
+var PRO_FEATURE_LABEL3 = "set-level organizer reports";
+var TIERS = /* @__PURE__ */ new Set(["resource", "custom"]);
+var MATURITIES = /* @__PURE__ */ new Set(["seedling", "stable", "deprecated"]);
+function listSubdirs2(dir) {
+  let entries;
+  try {
+    entries = readdirSync7(dir, { withFileTypes: true });
+  } catch {
+    return [];
   }
-  return value;
+  const out = [];
+  for (const entry of entries) {
+    const full = join21(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(full);
+      continue;
+    }
+    if (entry.isSymbolicLink()) {
+      try {
+        if (statSync9(full).isDirectory()) out.push(full);
+      } catch {
+      }
+    }
+  }
+  return out;
 }
-function parseLookbackHours(value) {
-  const n = Number(value);
-  if (value.trim() === "" || !Number.isFinite(n) || n < 0) {
-    throw new UserError(`--lookback-hours must be a non-negative number (got "${value}")`);
+function findSkillDirsUnderRoot2(root) {
+  const found = /* @__PURE__ */ new Set();
+  const topDirs = listSubdirs2(root);
+  for (const dir of topDirs) {
+    if (existsSync17(join21(dir, "SKILL.md"))) found.add(dir);
+  }
+  for (const dir of listSubdirs2(join21(root, "skills"))) {
+    if (existsSync17(join21(dir, "SKILL.md"))) found.add(dir);
+  }
+  for (const topDir of topDirs) {
+    for (const dir of listSubdirs2(join21(topDir, "skills"))) {
+      if (existsSync17(join21(dir, "SKILL.md"))) found.add(dir);
+    }
+  }
+  return Array.from(found).filter((p) => !p.includes("/.git/"));
+}
+function collectCandidates(roots) {
+  const out = [];
+  for (const root of roots) {
+    const resolvedRoot = resolvePath5(expandHome(root));
+    if (!isDir(resolvedRoot)) continue;
+    for (const dirPath of findSkillDirsUnderRoot2(resolvedRoot)) {
+      out.push({ dirPath, root });
+    }
+  }
+  return out;
+}
+function parseYamlList(block, key) {
+  const inlineMatch = block.match(new RegExp(`^${key}:\\s*\\[(.*?)\\]\\s*$`, "m"));
+  if (inlineMatch) {
+    return inlineMatch[1].split(",").map((x) => stripQuotes(x.trim())).filter(Boolean);
+  }
+  if (!new RegExp(`^${key}:\\s*$`, "m").test(block)) return [];
+  const lines = block.split(/\r\n|\r|\n/);
+  const startIdx = lines.findIndex((l) => new RegExp(`^${key}:\\s*$`).test(l));
+  if (startIdx === -1) return [];
+  const out = [];
+  for (const line of lines.slice(startIdx + 1)) {
+    const itemMatch = line.match(/^\s*-\s*(.+)$/);
+    if (itemMatch) {
+      out.push(stripQuotes(itemMatch[1].trim()));
+    } else if (line.trim() === "") {
+      continue;
+    } else {
+      break;
+    }
+  }
+  return out;
+}
+function extractFrontmatterBlock(text) {
+  if (!text.startsWith("---\n")) return null;
+  const afterOpen = text.slice(4);
+  const closeIdx = afterOpen.indexOf("\n---");
+  if (closeIdx === -1) return null;
+  return afterOpen.slice(0, closeIdx);
+}
+function parseCapabilityFrontmatter(text, fallbackName) {
+  const block = extractFrontmatterBlock(text);
+  if (block === null) {
+    return { name: fallbackName, consumes: [], validFrontmatter: false };
+  }
+  const fields = {};
+  for (const key of ["name", "tier", "domain", "provenance", "maturity"]) {
+    const m = block.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+    if (m) fields[key] = stripQuotes(m[1].trim());
+  }
+  return {
+    name: fields.name ?? fallbackName,
+    tier: fields.tier,
+    domain: fields.domain,
+    provenance: fields.provenance,
+    maturity: fields.maturity,
+    consumes: parseYamlList(block, "consumes"),
+    validFrontmatter: true
+  };
+}
+function loadUsageSnapshot(snapshotPath) {
+  const resolvedPath = resolvePath5(expandHome(snapshotPath));
+  let raw;
+  try {
+    raw = readFileSync13(resolvedPath, "utf-8");
+  } catch (err) {
+    return { usage: /* @__PURE__ */ new Map(), warning: `could not read usage snapshot (${err.message}); proceeding without usage` };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { usage: /* @__PURE__ */ new Map(), warning: `could not parse usage snapshot (${err.message}); proceeding without usage` };
+  }
+  const usage = /* @__PURE__ */ new Map();
+  const outer = parsed;
+  const report = outer && typeof outer === "object" ? outer.report : void 0;
+  const topSkills = report && typeof report === "object" ? report.top_skills : void 0;
+  if (Array.isArray(topSkills)) {
+    for (const row of topSkills) {
+      if (Array.isArray(row) && row.length === 2 && typeof row[0] === "string" && typeof row[1] === "number") {
+        const [name, count] = row;
+        usage.set(name, count);
+        if (name.includes(":")) {
+          const bare = name.split(":").pop();
+          if (!usage.has(bare)) usage.set(bare, count);
+        }
+      }
+    }
+  }
+  return { usage };
+}
+var WHITE = 0;
+var GRAY = 1;
+var BLACK = 2;
+function findCycles(adjacency) {
+  const color = /* @__PURE__ */ new Map();
+  for (const id of adjacency.keys()) color.set(id, WHITE);
+  const stack = [];
+  const cycles = [];
+  function dfs(u) {
+    color.set(u, GRAY);
+    stack.push(u);
+    for (const v of adjacency.get(u) ?? []) {
+      if (!color.has(v)) continue;
+      if (color.get(v) === GRAY && stack.includes(v)) {
+        const idx = stack.indexOf(v);
+        cycles.push([...stack.slice(idx), v]);
+      } else if (color.get(v) === WHITE) {
+        dfs(v);
+      }
+    }
+    color.set(u, BLACK);
+    stack.pop();
+  }
+  for (const id of adjacency.keys()) {
+    if (color.get(id) === WHITE) dfs(id);
+  }
+  return cycles;
+}
+function buildGraph(entries, nameToIds) {
+  const nodes = entries.map((e) => ({ id: e.id, name: e.name, tier: e.tier, domain: e.domain }));
+  const edges = [];
+  const dangling = [];
+  const ambiguous = [];
+  const incoming = new Map(entries.map((e) => [e.id, 0]));
+  const adjacency = new Map(entries.map((e) => [e.id, []]));
+  for (const e of entries) {
+    for (const target of e.consumes) {
+      const matches = nameToIds.get(target) ?? [];
+      edges.push({ from: e.id, to: target, resolvedIds: matches });
+      if (matches.length === 0) {
+        dangling.push({ from: e.id, to: target });
+      } else if (matches.length === 1) {
+        incoming.set(matches[0], (incoming.get(matches[0]) ?? 0) + 1);
+        adjacency.get(e.id).push(matches[0]);
+      } else {
+        ambiguous.push({ from: e.id, to: target, matches });
+      }
+    }
+  }
+  const orphans = entries.filter((e) => e.tier === "custom" && e.consumes.length === 0).map((e) => e.id);
+  const byId = new Map(entries.map((e) => [e.id, e]));
+  const hotResources = Array.from(incoming.entries()).filter(([, count]) => count > 0).map(([id, count]) => ({ id, name: byId.get(id).name, consumedBy: count })).sort((a, b) => b.consumedBy - a.consumedBy);
+  const cycles = findCycles(adjacency);
+  return {
+    nodeCount: nodes.length,
+    edgeCount: edges.length,
+    nodes,
+    edges,
+    orphans,
+    hotResources,
+    danglingEdges: dangling,
+    ambiguousConsumesTargets: ambiguous,
+    cycles
+  };
+}
+function buildRegistryEntries(candidates, warnings) {
+  const entries = [];
+  const seenRealPaths = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    let realPath;
+    try {
+      realPath = realpathSync2(candidate.dirPath);
+    } catch (err) {
+      warnings.push(`could not resolve skill directory ${candidate.dirPath}: ${err.message}`);
+      continue;
+    }
+    if (seenRealPaths.has(realPath)) continue;
+    seenRealPaths.add(realPath);
+    const skillMdPath = join21(realPath, "SKILL.md");
+    let text;
+    try {
+      text = readFileSync13(skillMdPath, "utf-8");
+    } catch (err) {
+      warnings.push(`could not read ${skillMdPath}: ${err.message}`);
+      continue;
+    }
+    const fm = parseCapabilityFrontmatter(text, basename8(realPath));
+    const name = fm.name ?? basename8(realPath);
+    if (fm.tier && !TIERS.has(fm.tier)) {
+      warnings.push(`${name}: tier '${fm.tier}' not in ${JSON.stringify(Array.from(TIERS).sort())}`);
+    }
+    if (fm.maturity && !MATURITIES.has(fm.maturity)) {
+      warnings.push(`${name}: maturity '${fm.maturity}' not in ${JSON.stringify(Array.from(MATURITIES).sort())}`);
+    }
+    entries.push({
+      id: realPath,
+      name,
+      path: realPath,
+      root: candidate.root,
+      tier: fm.tier,
+      domain: fm.domain,
+      consumes: fm.consumes,
+      provenance: fm.provenance,
+      maturity: fm.maturity,
+      validFrontmatter: fm.validFrontmatter
+    });
+  }
+  return entries;
+}
+function joinUsageSnapshot(entries, snapshotPath, warnings) {
+  const { usage, warning } = loadUsageSnapshot(snapshotPath);
+  if (warning) warnings.push(warning);
+  if (usage.size === 0) return false;
+  for (const entry of entries) {
+    const count = usage.get(entry.name);
+    if (count !== void 0) entry.usage = count;
+  }
+  if (!entries.some((e) => e.usage !== void 0)) {
+    warnings.push(
+      "usage snapshot loaded but 0 skills matched by name \u2014 registry `name:` vs telemetry key mismatch; the usage column will be empty"
+    );
+  }
+  return true;
+}
+function buildNameToIds(entries, warnings) {
+  const nameToIds = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    const ids = nameToIds.get(e.name) ?? [];
+    ids.push(e.id);
+    nameToIds.set(e.name, ids);
+  }
+  for (const [name, ids] of nameToIds) {
+    if (ids.length > 1) {
+      warnings.push(`duplicate skill name "${name}" across ${ids.length} locations: ${ids.join(", ")}`);
+    }
+  }
+  return nameToIds;
+}
+function findUntagged(entries) {
+  return entries.filter((e) => !e.tier || !e.domain).map((e) => ({
+    id: e.id,
+    name: e.name,
+    missing: [!e.tier ? "tier" : void 0, !e.domain ? "domain" : void 0].filter((v) => Boolean(v))
+  }));
+}
+function countByTierAndDomain(entries) {
+  const byTier = {};
+  const byDomain = {};
+  for (const e of entries) {
+    byTier[e.tier ?? "untagged"] = (byTier[e.tier ?? "untagged"] ?? 0) + 1;
+    byDomain[e.domain ?? "untagged"] = (byDomain[e.domain ?? "untagged"] ?? 0) + 1;
+  }
+  return { byTier, byDomain };
+}
+function buildOrganizeReport(config, options = {}) {
+  const proStatus = proFeatureStatus(PRO_FEATURE_LABEL3);
+  if (!proStatus.enabled) {
+    throw new UserError(proStatus.notice ?? upgradeNotice(PRO_FEATURE_LABEL3));
+  }
+  const notices = proStatus.notice ? [proStatus.notice] : [];
+  const warnings = [];
+  const candidates = collectCandidates(config.skillsRoots);
+  if (candidates.length === 0) {
+    throw new UserError(
+      `no SKILL.md found under any configured skills root (${config.skillsRoots.join(", ") || "(none configured)"})`
+    );
+  }
+  const entries = buildRegistryEntries(candidates, warnings);
+  const usageJoined = options.usageSnapshot ? joinUsageSnapshot(entries, options.usageSnapshot, warnings) : false;
+  const nameToIds = buildNameToIds(entries, warnings);
+  const untagged = findUntagged(entries);
+  const { byTier, byDomain } = countByTierAndDomain(entries);
+  const registry = {
+    skillsRoots: [...config.skillsRoots],
+    count: entries.length,
+    byTier,
+    byDomain,
+    untagged,
+    warnings,
+    usageJoined,
+    skills: entries
+  };
+  const graph = buildGraph(entries, nameToIds);
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    registry,
+    graph,
+    notices
+  };
+}
+
+// src/commands/organize.ts
+function writeReport2(outPath, contents) {
+  const resolved = resolvePath6(outPath);
+  mkdirSync7(dirname8(resolved), { recursive: true });
+  try {
+    writeFileSync7(resolved, contents, { flag: "wx", mode: 384 });
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      throw new UserError(`output file already exists: ${resolved} \u2014 pass a different --out path`);
+    }
+    throw err;
+  }
+  return resolved;
+}
+function renderSummary(report) {
+  const { registry, graph } = report;
+  const lines = [];
+  lines.push(`[skill-forge] organize: ${registry.count} skill(s) across ${registry.skillsRoots.length} root(s)`);
+  lines.push(`  by tier:   ${JSON.stringify(registry.byTier)}`);
+  lines.push(`  by domain: ${JSON.stringify(registry.byDomain)}`);
+  lines.push(`  usage joined: ${registry.usageJoined}`);
+  lines.push(`  untagged (missing tier/domain): ${registry.untagged.length}`);
+  for (const u of registry.untagged.slice(0, 30)) {
+    lines.push(`    - ${sanitizeForMarkdown(u.name)}: missing ${u.missing.join(", ")}`);
+  }
+  if (registry.warnings.length > 0) {
+    lines.push("  warnings:");
+    for (const w of registry.warnings) lines.push(`    ! ${sanitizeForMarkdown(w)}`);
+  }
+  lines.push("");
+  lines.push(`  graph: ${graph.nodeCount} nodes, ${graph.edgeCount} edges`);
+  if (graph.hotResources.length > 0) {
+    lines.push("  hot resources (consumed by N customs):");
+    for (const h of graph.hotResources) lines.push(`    ${h.consumedBy}x  ${sanitizeForMarkdown(h.name)}`);
+  }
+  if (graph.danglingEdges.length > 0) {
+    lines.push("  dangling edges (consumes a target not in the set):");
+    for (const d of graph.danglingEdges) lines.push(`    ${sanitizeForMarkdown(d.from)}  ->  ${sanitizeForMarkdown(d.to)}  (missing)`);
+  }
+  if (graph.ambiguousConsumesTargets.length > 0) {
+    lines.push("  ambiguous consumes targets (name matched multiple skills):");
+    for (const a of graph.ambiguousConsumesTargets) {
+      lines.push(
+        `    ${sanitizeForMarkdown(a.from)}  ->  ${sanitizeForMarkdown(a.to)}  (matches: ${a.matches.map(sanitizeForMarkdown).join(", ")})`
+      );
+    }
+  }
+  if (graph.cycles.length > 0) {
+    lines.push("  cycles (consumes should be acyclic):");
+    for (const c of graph.cycles) lines.push(`    ${c.map(sanitizeForMarkdown).join(" -> ")}`);
+  }
+  if (graph.orphans.length > 0) {
+    lines.push(`  custom skills with no declared consumes (${graph.orphans.length}):`);
+    for (const o of graph.orphans.slice(0, 30)) lines.push(`    - ${sanitizeForMarkdown(o)}`);
+  }
+  for (const n of report.notices) lines.push(`  [notice] ${sanitizeForMarkdown(n)}`);
+  return lines;
+}
+async function organizeCommand(options = {}) {
+  const config = loadConfig();
+  const report = buildOrganizeReport(config, { usageSnapshot: options.usageSnapshot });
+  let outPath;
+  if (options.out) {
+    outPath = writeReport2(options.out, JSON.stringify(report, null, 2) + "\n");
+  }
+  if (options.json) {
+    for (const n of report.notices) console.error(`[skill-forge] ${n}`);
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  for (const line of renderSummary(report)) console.log(line);
+  if (outPath) console.log(`  report -> ${outPath}`);
+}
+
+// src/gate/skillsShApi.ts
+var SKILLS_SH_ORIGIN = "https://skills.sh";
+var SKILLS_SH_API_BASE = "/api/v1";
+var MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+var REQUEST_TIMEOUT_MS = 15e3;
+var ID_PATTERN = /^[A-Za-z0-9._/-]+$/;
+var TOKEN_HINT = "No VERCEL_OIDC_TOKEN found. skills.sh authenticates with a short-lived Vercel OIDC token:\n  1. Vercel dashboard -> your project -> Settings -> OIDC Federation -> enable.\n  2. npm i -g vercel && vercel link && vercel env pull   (writes VERCEL_OIDC_TOKEN to .env.local)\n  3. export VERCEL_OIDC_TOKEN from .env.local into your shell before running this command\n  (or set it directly: export VERCEL_OIDC_TOKEN=...)   -   docs: https://skills.sh/docs/api";
+var SkillsShError = class extends Error {
+  exitCode;
+  constructor(message, exitCode) {
+    super(message);
+    this.name = "SkillsShError";
+    this.exitCode = exitCode;
+  }
+};
+var RISK_ORDER = { NONE: 0, LOW: 1, MEDIUM: 2, HIGH: 3, CRITICAL: 4 };
+function getToken(env = process.env) {
+  const tok = env.VERCEL_OIDC_TOKEN;
+  return tok ? tok : void 0;
+}
+function assertValidId(id) {
+  if (id.length === 0 || !ID_PATTERN.test(id)) {
+    throw new SkillsShError(`invalid skills.sh id: ${JSON.stringify(id)}`, 1);
+  }
+}
+function validatedIdSegments(id) {
+  assertValidId(id);
+  const segments = id.split("/");
+  if (segments.some((s) => s === "" || s === "." || s === "..")) {
+    throw new SkillsShError(`invalid skills.sh id: ${JSON.stringify(id)}`, 1);
+  }
+  return segments;
+}
+function buildUrl(pathSegments, params) {
+  const url = new URL(SKILLS_SH_API_BASE + "/" + pathSegments.map((s) => encodeURIComponent(s)).join("/"), SKILLS_SH_ORIGIN);
+  if (params) {
+    const search2 = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) search2.set(k, String(v));
+    url.search = search2.toString();
+  }
+  return url;
+}
+async function readCappedText(res) {
+  const text = await res.text();
+  if (new TextEncoder().encode(text).length > MAX_RESPONSE_BYTES) {
+    throw new SkillsShError("skills.sh response exceeded the 2 MB size cap", 1);
+  }
+  return text;
+}
+async function call(pathSegments, params, options = {}) {
+  const env = options.env ?? process.env;
+  const token = getToken(env);
+  if (!token) {
+    throw new SkillsShError(TOKEN_HINT, 3);
+  }
+  const url = buildUrl(pathSegments, params);
+  const fetchImpl = options.fetchImpl ?? fetch;
+  let res;
+  try {
+    res = await fetchImpl(url, {
+      headers: { Authorization: `Bearer ${token}` },
+      redirect: "error",
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new SkillsShError(`skills.sh request failed: ${message}`, 1);
+  }
+  if (res.status === 404) {
+    return void 0;
+  }
+  if (!res.ok) {
+    if (res.status === 401) {
+      throw new SkillsShError("skills.sh HTTP 401: unauthorized \u2014 the VERCEL_OIDC_TOKEN was rejected (expired or invalid)", 3);
+    }
+    let snippet = "";
+    try {
+      snippet = (await readCappedText(res)).slice(0, 300);
+    } catch {
+    }
+    throw new SkillsShError(`skills.sh HTTP ${res.status}${snippet ? `: ${snippet}` : ""}`, 1);
+  }
+  const text = await readCappedText(res);
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new SkillsShError("skills.sh returned malformed JSON", 1);
+  }
+  return parsed;
+}
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+async function search(query, limit, options = {}) {
+  const data = await call(["skills", "search"], { q: query, limit }, options);
+  if (!isRecord(data) || !Array.isArray(data.data)) {
+    throw new SkillsShError("skills.sh search response had an unexpected shape", 1);
+  }
+  return data;
+}
+async function audit(id, options = {}) {
+  const data = await call(["skills", "audit", ...validatedIdSegments(id)], void 0, options);
+  if (data === void 0) return void 0;
+  if (!isRecord(data) || !Array.isArray(data.audits)) {
+    throw new SkillsShError("skills.sh audit response had an unexpected shape", 1);
+  }
+  return data;
+}
+async function get(id, options = {}) {
+  return call(["skills", ...validatedIdSegments(id)], void 0, options);
+}
+async function curated(options = {}) {
+  return call(["skills", "curated"], void 0, options);
+}
+function auditVerdict(data) {
+  const audits = data.audits ?? [];
+  const statuses = new Set(audits.map((a) => a.status));
+  let worst = "NONE";
+  let worstRank = 0;
+  for (const a of audits) {
+    const rl = a.riskLevel ?? "NONE";
+    const rank = RISK_ORDER[rl] ?? 0;
+    if (rank > worstRank) {
+      worstRank = rank;
+      worst = rl;
+    }
+  }
+  const verdict = statuses.has("fail") ? "fail" : statuses.has("warn") ? "warn" : audits.length > 0 ? "pass" : "none";
+  return { verdict, risk: worst, audits };
+}
+
+// src/commands/find.ts
+var INSTALL_HINT_NOTE = "Results are unvetted \u2014 `skill-forge add <id>` runs the full quarantine + safety gate; `skill-forge find --audit <id>` shows partner audit verdicts.";
+function isRecordWithDataArray(v) {
+  return typeof v === "object" && v !== null && Array.isArray(v.data);
+}
+function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+function printSearchResults(data, query) {
+  const items = data.data;
+  const count = data.count ?? items.length;
+  const searchType = data.searchType ? ` (${sanitizeForMarkdown(data.searchType)})` : "";
+  console.log(`skills.sh \u2014 ${count} matches for ${JSON.stringify(query)}${searchType}:`);
+  for (const item of items) {
+    const name = sanitizeForMarkdown(String(item.name ?? item.id));
+    const id = sanitizeForMarkdown(String(item.id));
+    const installs = item.installs ?? "?";
+    console.log(`  - ${name}  [${id}]  ${installs} installs  [unvetted]`);
+    console.log(`      install: skill-forge add ${id}`);
+  }
+  console.log("");
+  console.log(INSTALL_HINT_NOTE);
+}
+async function find(query, options = {}, deps = {}) {
+  const modes = [query !== void 0, options.audit !== void 0, options.get !== void 0, Boolean(options.curated)];
+  const activeCount = modes.filter(Boolean).length;
+  if (activeCount === 0) {
+    throw new UserError("skill-forge find: provide a search query, or exactly one of --audit <id>, --get <id>, --curated");
+  }
+  if (activeCount > 1) {
+    throw new UserError("skill-forge find: exactly one mode per invocation \u2014 a search query, or exactly one of --audit <id>, --get <id>, --curated");
+  }
+  const callOptions = { fetchImpl: deps.fetchImpl, env: deps.env };
+  try {
+    if (query !== void 0) {
+      if (query.trim().length < 2) {
+        throw new UserError("skill-forge find: query must be at least 2 characters");
+      }
+      const limit = options.limit ?? 10;
+      const data2 = await search(query, limit, callOptions);
+      if (options.json) {
+        printJson(data2);
+        return;
+      }
+      printSearchResults(data2, query);
+      return;
+    }
+    if (options.audit !== void 0) {
+      const id = options.audit;
+      const data2 = await audit(id, callOptions);
+      if (!data2) {
+        console.log(`no partner audits yet for ${sanitizeForMarkdown(id)} (generated after first install).`);
+        return;
+      }
+      if (options.json) {
+        printJson(data2);
+        return;
+      }
+      const { verdict, risk, audits } = auditVerdict(data2);
+      console.log(
+        `skills.sh audit for ${sanitizeForMarkdown(id)}: ${verdict.toUpperCase()} (max risk ${sanitizeForMarkdown(risk)}) \u2014 ${audits.length} partner(s)`
+      );
+      for (const entry of audits) {
+        const provider = sanitizeForMarkdown(String(entry.provider ?? "unknown"));
+        const status2 = sanitizeForMarkdown(String(entry.status ?? "unknown"));
+        const riskLevel = entry.riskLevel ? ` \xB7 ${sanitizeForMarkdown(String(entry.riskLevel))}` : "";
+        const summary = entry.summary ? ` \u2014 ${sanitizeForMarkdown(String(entry.summary))}` : "";
+        console.log(`  - ${provider}: ${status2}${riskLevel}${summary}`);
+      }
+      return;
+    }
+    if (options.get !== void 0) {
+      const data2 = await get(options.get, callOptions);
+      printJson(data2);
+      return;
+    }
+    const data = await curated(callOptions);
+    if (options.json) {
+      printJson(data);
+      return;
+    }
+    if (isRecordWithDataArray(data)) {
+      printSearchResults(data, "(curated)");
+      return;
+    }
+    printJson(data);
+  } catch (err) {
+    if (err instanceof SkillsShError) {
+      console.error(err.message);
+      process.exitCode = err.exitCode;
+      return;
+    }
+    throw err;
+  }
+}
+
+// src/commands/watch.ts
+import { realpathSync as realpathSync3 } from "fs";
+import { join as join22, resolve as resolvePath7 } from "path";
+var PRO_FEATURE_LABEL4 = "provenance drift watch (watch)";
+function isGitUrl(source) {
+  const s = source.trim();
+  return /^https?:\/\/\S+$/i.test(s) || /^git@[\w.-]+:\S+$/i.test(s);
+}
+function looksLikeGitRef(ref) {
+  const r = ref.trim();
+  return /^[0-9a-fA-F]{7,40}$/.test(r);
+}
+function firstNonEmptyLine(text) {
+  return text.split("\n").find((l) => l.trim().length > 0)?.trim() ?? "(no output)";
+}
+async function checkGitDrift(exec, url, ref) {
+  let result;
+  try {
+    result = await exec("git", ["ls-remote", "--", url, ref], { cwd: process.cwd() });
+  } catch (err) {
+    return { status: "unreachable", detail: `git ls-remote failed to run: ${err.message}` };
+  }
+  if (result.code !== 0) {
+    return { status: "unreachable", detail: `git ls-remote exited ${result.code}: ${firstNonEmptyLine(result.stderr || result.stdout)}` };
+  }
+  const shas = result.stdout.split("\n").map((l) => l.trim()).filter((l) => l.length > 0).map((l) => l.split(/\s+/)[0] ?? "").filter((sha) => sha.length > 0);
+  if (shas.length === 0) {
+    return { status: "unreachable", detail: `no ref matching "${ref}" found on remote` };
+  }
+  const recorded = ref.trim().toLowerCase();
+  if (shas.some((sha) => sha.toLowerCase() === recorded)) {
+    return { status: "unchanged", detail: `current: ${recorded}` };
+  }
+  return { status: "moved", detail: `recorded ${ref}, remote now resolves to ${shas[0]}` };
+}
+async function runWatch(config, options = {}, deps = {}) {
+  const proStatus = proFeatureStatus(PRO_FEATURE_LABEL4);
+  if (!proStatus.enabled) {
+    return { roots: [], rows: [], warnings: [], notices: [proStatus.notice ?? "Pro feature (watch) locked."] };
+  }
+  const notices = proStatus.notice ? [proStatus.notice] : [];
+  const exec = deps.exec ?? defaultExec;
+  const roots = [];
+  const rows = [];
+  const warnings = [];
+  const seenRealPaths = /* @__PURE__ */ new Set();
+  for (const root of config.skillsRoots) {
+    const resolvedRoot = resolvePath7(expandHome(root));
+    const exists = isDir(resolvedRoot);
+    let realPath = resolvedRoot;
+    if (exists) {
+      try {
+        realPath = realpathSync3(resolvedRoot);
+      } catch {
+        realPath = resolvedRoot;
+      }
+    }
+    if (seenRealPaths.has(realPath)) continue;
+    seenRealPaths.add(realPath);
+    let ledger;
+    try {
+      ledger = readProvenanceLedger(resolvedRoot);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const ledgerPath = join22(resolvedRoot, "SOURCES.md");
+      roots.push({ root, realPath, exists, ledgerPath, ledgerExists: false });
+      warnings.push(`${ledgerPath}: could not read ledger: ${message}`);
+      continue;
+    }
+    roots.push({ root, realPath, exists, ledgerPath: ledger.ledgerPath, ledgerExists: ledger.exists });
+    warnings.push(...ledger.warnings.map((w) => `${ledger.ledgerPath}: ${w}`));
+    for (const entry of ledger.entries) {
+      if (entry.verb === "REJECT") continue;
+      const rowBase = {
+        root,
+        ledgerPath: ledger.ledgerPath,
+        name: entry.name,
+        verb: entry.verb,
+        source: entry.source,
+        upstreamRef: entry.upstreamRef,
+        driftCheckCommand: entry.driftCheck
+      };
+      if (!(isGitUrl(entry.source) && looksLikeGitRef(entry.upstreamRef))) {
+        rows.push({
+          ...rowBase,
+          checkMethod: "manual",
+          driftStatus: "not-checked",
+          detail: "source is not a recognized git URL + ref pin \u2014 check manually"
+        });
+        continue;
+      }
+      if (options.offline) {
+        rows.push({
+          ...rowBase,
+          checkMethod: "git-ls-remote",
+          driftStatus: "not-checked",
+          detail: "--offline: network check skipped"
+        });
+        continue;
+      }
+      const { status: status2, detail } = await checkGitDrift(exec, entry.source, entry.upstreamRef);
+      rows.push({ ...rowBase, checkMethod: "git-ls-remote", driftStatus: status2, detail });
+    }
+  }
+  return { roots, rows, warnings, notices };
+}
+function printWatchTerminal(report) {
+  console.log("[skill-forge] watch \u2014 provenance drift check");
+  for (const notice of report.notices) console.log(`[notice] ${notice}`);
+  if (report.roots.length === 0) {
+    console.log("\nNo configured skills roots.");
+  }
+  for (const root of report.roots) {
+    console.log(`
+${sanitizeForMarkdown(root.root)} (${sanitizeForMarkdown(root.realPath)})`);
+    if (!root.exists) {
+      console.log("  root does not exist on disk");
+      continue;
+    }
+    if (!root.ledgerExists) {
+      console.log(`  no ledger at ${sanitizeForMarkdown(root.ledgerPath)}`);
+      continue;
+    }
+    console.log(`  ledger: ${sanitizeForMarkdown(root.ledgerPath)}`);
+    const rowsForRoot = report.rows.filter((r) => r.root === root.root);
+    if (rowsForRoot.length === 0) {
+      console.log("  (no tracked, non-REJECT sources)");
+      continue;
+    }
+    for (const row of rowsForRoot) {
+      console.log(`  \u2022 ${sanitizeForMarkdown(row.name)}  [${sanitizeForMarkdown(row.verb)}]  ref=${sanitizeForMarkdown(row.upstreamRef)}`);
+      if (row.checkMethod === "git-ls-remote") {
+        console.log(`      drift: ${row.driftStatus} \u2014 ${sanitizeForMarkdown(row.detail)}`);
+      } else {
+        console.log(`      manual check \u2014 stored drift-check command (data, NOT executed): ${sanitizeForMarkdown(row.driftCheckCommand)}`);
+      }
+    }
+  }
+  if (report.warnings.length > 0) {
+    console.log("\nWarnings:");
+    for (const w of report.warnings) console.log(`  - ${sanitizeForMarkdown(w)}`);
+  }
+  console.log("\nCompare each stored ref to current upstream; re-run ingestion on any that moved.");
+}
+async function watchCommand(options = {}) {
+  const report = await runWatch(loadConfig(), options);
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    for (const notice of report.notices) console.error(`[skill-forge] ${notice}`);
+    return;
+  }
+  printWatchTerminal(report);
+}
+
+// src/commands/ingest.ts
+import { realpathSync as realpathSync4 } from "fs";
+import { dirname as dirname9, isAbsolute, relative, resolve as resolvePath8 } from "path";
+var PRO_FEATURE_LABEL5 = "the pending-ingestion queue";
+var VALID_STATUSES = ["ingested", "dismissed"];
+function requireProFeature() {
+  const status2 = proFeatureStatus(PRO_FEATURE_LABEL5);
+  if (!status2.enabled) {
+    throw new UserError(
+      status2.notice ?? "ingest is a Pro feature \u2014 set SKILL_FORGE_LICENSE or config.licenseKey to a valid license to unlock."
+    );
+  }
+  if (status2.notice) console.error(`[skill-forge] ${status2.notice}`);
+}
+function pluralizeEntries(count) {
+  return `entr${count === 1 ? "y" : "ies"}`;
+}
+function toListRow(entry) {
+  return {
+    id: entry.id,
+    source: entry.source,
+    artifactType: entry.artifactType ?? "skill",
+    safetyVerdict: entry.gate.safetyVerdict,
+    createdAt: entry.createdAt
+  };
+}
+function printPendingList(pending, json) {
+  if (json) {
+    console.log(JSON.stringify({ entries: pending.map(toListRow) }, null, 2));
+    return;
+  }
+  if (pending.length === 0) {
+    console.log("[skill-forge] no pending queue entries.");
+    return;
+  }
+  console.log(`[skill-forge] ${pending.length} pending ${pluralizeEntries(pending.length)}:`);
+  for (const entry of pending) {
+    const row = toListRow(entry);
+    console.log(`  ${row.id}  ${row.source}  (${row.artifactType})  verdict=${row.safetyVerdict}  created=${row.createdAt}`);
+  }
+}
+function realpathOrNull(p) {
+  try {
+    return realpathSync4(p);
+  } catch {
+    return null;
+  }
+}
+function isUnderRoot(candidate, root) {
+  const rel = relative(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+function validatePendingEntries(entries, config) {
+  const quarantineRoot = realpathOrNull(resolvePath8(config.quarantineDir));
+  const skillsRoots = config.skillsRoots.map((r) => realpathOrNull(resolvePath8(r))).filter((r) => r !== null);
+  const mcpTargetDirs = (config.mcpTargets ?? []).map((f) => realpathOrNull(dirname9(resolvePath8(f)))).filter((r) => r !== null);
+  const allowedRoots = [quarantineRoot, ...skillsRoots, ...mcpTargetDirs].filter((r) => r !== null);
+  const valid = [];
+  const excluded = [];
+  for (const entry of entries) {
+    const effectivePath = entry.installedPath ?? entry.quarantinePath;
+    if (!effectivePath) {
+      excluded.push({ entry, reason: "no installedPath or quarantinePath recorded on the entry" });
+      continue;
+    }
+    const real = realpathOrNull(resolvePath8(effectivePath));
+    if (!real) {
+      excluded.push({ entry, reason: `path does not exist or could not be resolved: ${effectivePath}` });
+      continue;
+    }
+    if (allowedRoots.length === 0 || !allowedRoots.some((root) => isUnderRoot(real, root))) {
+      excluded.push({ entry, reason: `path escapes every configured root (quarantineDir/skillsRoots/mcpTargets): ${effectivePath}` });
+      continue;
+    }
+    valid.push(entry);
+  }
+  return { valid, excluded };
+}
+async function ingest(options = {}) {
+  requireProFeature();
+  const queue2 = readQueue();
+  const pending = queue2.entries.filter((e) => e.status === "pending");
+  if (options.list) {
+    printPendingList(pending, options.json);
+    return;
+  }
+  if (pending.length === 0) {
+    console.log("[skill-forge] no pending queue entries to ingest.");
+    return;
+  }
+  const config = loadConfig();
+  const { valid, excluded } = validatePendingEntries(pending, config);
+  if (excluded.length > 0) {
+    console.error(`[skill-forge] excluded ${excluded.length} pending ${pluralizeEntries(excluded.length)} that failed path validation:`);
+    for (const { entry, reason } of excluded) {
+      console.error(`  - ${entry.id} (${entry.source}): ${reason}`);
+    }
+    console.error(
+      "[skill-forge] excluded entries stay in the queue \u2014 review each, then dismiss with: skill-forge queue close <id> --status dismissed"
+    );
+  }
+  if (valid.length === 0) {
+    console.log("[skill-forge] no pending entries passed path validation \u2014 nothing to hand off.");
+    return;
+  }
+  console.log(`[skill-forge] ${valid.length} pending ${pluralizeEntries(valid.length)} ready for ingest:`);
+  for (const entry of valid) {
+    console.log(`  - ${entry.id}  ${entry.source}  (${entry.artifactType ?? "skill"})`);
+  }
+  runHandoff(config, getQueuePath(), { promptAsset: "ingest-prompt.md" });
+}
+async function queueClose(id, options = {}) {
+  requireProFeature();
+  const status2 = options.status;
+  if (!status2 || !VALID_STATUSES.includes(status2)) {
+    throw new UserError(`--status must be one of: ${VALID_STATUSES.join(", ")} (got ${status2 ? JSON.stringify(status2) : "nothing"})`);
+  }
+  let updated;
+  try {
+    updated = updateQueueEntry(id, { status: status2 });
+  } catch (err) {
+    throw new UserError(err instanceof Error ? err.message : String(err));
+  }
+  console.log(`[skill-forge] queue entry ${updated.id} closed -> status: ${updated.status}`);
+}
+
+// src/commands/refine.ts
+import { createHash as createHash3, randomUUID as randomUUID4 } from "crypto";
+import { chmodSync, existsSync as existsSync20, lstatSync as lstatSync3, mkdirSync as mkdirSync9, readFileSync as readFileSync15, realpathSync as realpathSync7, renameSync as renameSync5, rmSync as rmSync7, writeFileSync as writeFileSync9 } from "fs";
+import { dirname as dirname11, isAbsolute as isAbsolute3, join as join25, relative as relative3, resolve as resolvePath11, sep as sep2 } from "path";
+import { createInterface as createInterface5 } from "readline/promises";
+
+// src/refine/context.ts
+import { existsSync as existsSync19, realpathSync as realpathSync6, statSync as statSync11 } from "fs";
+import { isAbsolute as isAbsolute2, join as join24, relative as relative2, resolve as resolvePath10 } from "path";
+
+// src/refine/models.ts
+import { randomBytes } from "crypto";
+var REFINEMENT_CATEGORIES = ["trigger", "content", "hook", "tool", "pattern", "config", "new"];
+var OVERRIDE_TYPES = ["patch", "extend", "config", "full", "hook", "script", "new"];
+var PATCH_ACTIONS = ["append", "prepend", "replace-section", "insert-after", "insert-before", "delete-section"];
+var PATTERN_STATUSES = ["tracking", "ready", "generalized", "dismissed"];
+function isRefinementCategory(value) {
+  return REFINEMENT_CATEGORIES.includes(value);
+}
+function isOverrideType(value) {
+  return OVERRIDE_TYPES.includes(value);
+}
+function isPatchAction(value) {
+  return PATCH_ACTIONS.includes(value);
+}
+function isPatternStatus(value) {
+  return PATTERN_STATUSES.includes(value);
+}
+var REFINEMENT_STATUSES = ["pending", "applied", "generalized"];
+function isRefinementStatus(value) {
+  return REFINEMENT_STATUSES.includes(value);
+}
+function patternCount(pattern) {
+  return new Set(pattern.occurrences.map((o) => o.projectRealpath)).size;
+}
+function defaultRandomHex() {
+  return randomBytes(2).toString("hex");
+}
+function formatYYYYMMDD(date) {
+  const yyyy = date.getUTCFullYear().toString().padStart(4, "0");
+  const mm = (date.getUTCMonth() + 1).toString().padStart(2, "0");
+  const dd = date.getUTCDate().toString().padStart(2, "0");
+  return `${yyyy}${mm}${dd}`;
+}
+function generateRefinementId(existingIds = /* @__PURE__ */ new Set(), now = /* @__PURE__ */ new Date(), randomHex = defaultRandomHex) {
+  const datePart = formatYYYYMMDD(now);
+  let id;
+  do {
+    id = `REF-${datePart}-${randomHex()}`;
+  } while (existingIds.has(id));
+  return id;
+}
+function generatePatternId(existingIds = /* @__PURE__ */ new Set(), randomHex = defaultRandomHex) {
+  let id;
+  do {
+    id = `PAT-${randomHex()}`;
+  } while (existingIds.has(id));
+  return id;
+}
+function fingerprintKey(skill, target, overrideType, action) {
+  const normalize = (s) => s.trim().toLowerCase().replace(/\s+/g, " ");
+  return [normalize(skill), normalize(target), overrideType, action ?? ""].join("::");
+}
+function contentSimilarity(a, b) {
+  const tokenize2 = (s) => new Set(s.toLowerCase().split(/\s+/).filter(Boolean));
+  const tokensA = tokenize2(a);
+  const tokensB = tokenize2(b);
+  if (tokensA.size === 0 || tokensB.size === 0) return 0;
+  let intersectionSize = 0;
+  for (const token of tokensA) {
+    if (tokensB.has(token)) intersectionSize++;
+  }
+  const unionSize2 = tokensA.size + tokensB.size - intersectionSize;
+  return unionSize2 === 0 ? 0 : intersectionSize / unionSize2;
+}
+
+// src/refine/store.ts
+import { createHash as createHash2, randomUUID as randomUUID3 } from "crypto";
+import { existsSync as existsSync18, mkdirSync as mkdirSync8, readFileSync as readFileSync14, renameSync as renameSync4, rmSync as rmSync6, statSync as statSync10, writeFileSync as writeFileSync8, realpathSync as realpathSync5 } from "fs";
+import { basename as basename9, dirname as dirname10, join as join23, resolve as resolvePath9 } from "path";
+var SIMILARITY_JOIN_THRESHOLD = 0.7;
+var READY_THRESHOLD = 2;
+function getRefinementsDir() {
+  return join23(getHomeDir(), "refinements");
+}
+function getRefinementsPath() {
+  return join23(getRefinementsDir(), "refinements.json");
+}
+function getPatternsPath() {
+  return join23(getRefinementsDir(), "patterns.json");
+}
+function getBackupsDir() {
+  return join23(getRefinementsDir(), "backups");
+}
+function writeJsonAtomic(path, data) {
+  const dir = dirname10(path);
+  mkdirSync8(dir, { recursive: true });
+  const tempPath = join23(dir, `.${basename9(path)}.tmp-${randomUUID3()}`);
+  try {
+    writeFileSync8(tempPath, JSON.stringify(data, null, 2) + "\n", { encoding: "utf-8", mode: 384 });
+    renameSync4(tempPath, path);
+  } catch (err) {
+    rmSync6(tempPath, { force: true });
+    throw err;
+  }
+}
+function readJsonFile(path, label) {
+  let raw;
+  try {
+    raw = readFileSync14(path, "utf-8");
+  } catch (err) {
+    throw new UserError(`unable to read ${label} at ${path}: ${err.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new UserError(`malformed ${label} at ${path}: not valid JSON`);
+  }
+}
+function readStore(path, label, validateRecord) {
+  if (!existsSync18(path)) {
+    return { schemaVersion: 1, records: [] };
+  }
+  const parsed = readJsonFile(path, label);
+  if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.records)) {
+    throw new UserError(`malformed ${label} at ${path}: expected an object with a "records" array`);
+  }
+  const records = parsed.records;
+  if (validateRecord) {
+    records.forEach((record, index) => validateRecord(record, index));
+  }
+  return { schemaVersion: 1, records };
+}
+function validateRefinementRecordShape(record, index, path) {
+  if (typeof record !== "object" || record === null) {
+    throw new UserError(`malformed refinements.json at ${path}: record[${index}] is not an object`);
+  }
+  const r = record;
+  if (typeof r.id !== "string" || r.id.length === 0) {
+    throw new UserError(`malformed refinements.json at ${path}: record[${index}] is missing a valid "id"`);
+  }
+  if (typeof r.createdAt !== "string" || r.createdAt.length === 0) {
+    throw new UserError(`malformed refinements.json at ${path}: record "${r.id}" is missing a valid "createdAt"`);
+  }
+  if (typeof r.status !== "string" || r.status.length === 0) {
+    throw new UserError(`malformed refinements.json at ${path}: record "${r.id}" is missing a valid "status"`);
+  }
+  if (typeof r.skill !== "string" || r.skill.length === 0) {
+    throw new UserError(`malformed refinements.json at ${path}: record "${r.id}" is missing a valid "skill"`);
+  }
+  const patchActionsRequiringMarker = /* @__PURE__ */ new Set(["insert-after", "insert-before", "replace-section", "delete-section"]);
+  if (r.overrideType === "patch") {
+    if (typeof r.patchAction !== "string" || r.patchAction.length === 0) {
+      throw new UserError(`malformed refinements.json at ${path}: record "${r.id}" has overrideType "patch" but is missing "patchAction"`);
+    }
+    if (patchActionsRequiringMarker.has(r.patchAction) && (typeof r.patchMarker !== "string" || r.patchMarker.length === 0)) {
+      throw new UserError(
+        `malformed refinements.json at ${path}: record "${r.id}" has patchAction "${r.patchAction}" but is missing "patchMarker"`
+      );
+    }
+    if (typeof r.patchContent !== "string" || r.patchContent.length === 0) {
+      throw new UserError(`malformed refinements.json at ${path}: record "${r.id}" has overrideType "patch" but is missing "patchContent"`);
+    }
+  } else if (r.patchAction !== void 0) {
+    throw new UserError(
+      `malformed refinements.json at ${path}: record "${r.id}" has overrideType "${String(r.overrideType)}" but carries "patchAction" \u2014 only valid when overrideType is "patch"`
+    );
+  }
+}
+function validatePatternRecordShape(record, index, path) {
+  if (typeof record !== "object" || record === null) {
+    throw new UserError(`malformed patterns.json at ${path}: record[${index}] is not an object`);
+  }
+  const p = record;
+  if (typeof p.id !== "string" || p.id.length === 0) {
+    throw new UserError(`malformed patterns.json at ${path}: record[${index}] is missing a valid "id"`);
+  }
+  if (typeof p.status !== "string" || p.status.length === 0) {
+    throw new UserError(`malformed patterns.json at ${path}: record "${p.id}" is missing a valid "status"`);
+  }
+  if (!Array.isArray(p.occurrences)) {
+    throw new UserError(`malformed patterns.json at ${path}: record "${p.id}" is missing a valid "occurrences" array`);
+  }
+  if (p.status === "dismissed" && (typeof p.dismissedReason !== "string" || p.dismissedReason.length === 0)) {
+    throw new UserError(`malformed patterns.json at ${path}: record "${p.id}" has status "dismissed" but is missing "dismissedReason"`);
+  }
+  if (p.status === "generalized") {
+    if (typeof p.generalizedAt !== "string" || p.generalizedAt.length === 0) {
+      throw new UserError(`malformed patterns.json at ${path}: record "${p.id}" has status "generalized" but is missing "generalizedAt"`);
+    }
+    if (typeof p.generalizedBackupId !== "string" || p.generalizedBackupId.length === 0) {
+      throw new UserError(`malformed patterns.json at ${path}: record "${p.id}" has status "generalized" but is missing "generalizedBackupId"`);
+    }
+  }
+}
+function readRefinementsStore() {
+  const path = getRefinementsPath();
+  return readStore(path, "refinements.json", (record, index) => validateRefinementRecordShape(record, index, path));
+}
+function writeRefinementsStore(store) {
+  writeJsonAtomic(getRefinementsPath(), store);
+}
+function readPatternsStore() {
+  const path = getPatternsPath();
+  return readStore(path, "patterns.json", (record, index) => validatePatternRecordShape(record, index, path));
+}
+function writePatternsStore(store) {
+  writeJsonAtomic(getPatternsPath(), store);
+}
+function resolveProjectRealpath(projectRoot) {
+  const resolved = resolvePath9(projectRoot);
+  try {
+    return realpathSync5(resolved);
+  } catch {
+    return resolved;
+  }
+}
+function generatePatternName(refinement) {
+  const parts = refinement.targetSection.replace(/\//g, " ").replace(/-/g, " ").split(/\s+/).filter(Boolean);
+  const lastThree = parts.slice(-3);
+  if (lastThree.length === 0) return refinement.targetSection || `pattern-${refinement.skill}`;
+  return lastThree.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function generatePatternDescription(refinement) {
+  const category = refinement.category.charAt(0).toUpperCase() + refinement.category.slice(1);
+  const cause = refinement.rootCause || refinement.expectedBehavior;
+  return `${category} modification for ${refinement.skill}: ${cause}`;
+}
+function upsertPattern(records, refinement, projectRealpath, nowIso, randomHex, explicitPatternId) {
+  let pattern;
+  if (explicitPatternId) {
+    pattern = records.find((p) => p.id === explicitPatternId);
+    if (!pattern) {
+      throw new UserError(`no pattern with id: ${explicitPatternId}`);
+    }
+    if (pattern.status === "dismissed" || pattern.status === "generalized") {
+      throw new UserError(`cannot join pattern ${explicitPatternId}: it is ${pattern.status} and no longer accepts new occurrences`);
+    }
+  } else {
+    const joinable = records.filter((p) => p.status !== "generalized" && p.status !== "dismissed");
+    const fingerprint = fingerprintKey(refinement.skill, refinement.targetSection, refinement.overrideType, refinement.patchAction);
+    pattern = joinable.find((p) => p.fingerprint === fingerprint);
+    if (!pattern && refinement.patchContent) {
+      pattern = joinable.find((p) => {
+        const sample = p.proposedChanges.content;
+        return sample ? contentSimilarity(refinement.patchContent, sample) > SIMILARITY_JOIN_THRESHOLD : false;
+      });
+    }
+  }
+  const wasTracking = pattern?.status === "tracking";
+  if (!pattern) {
+    const created = {
+      id: generatePatternId(new Set(records.map((p) => p.id)), randomHex),
+      name: generatePatternName(refinement),
+      description: generatePatternDescription(refinement),
+      affectedSkills: [refinement.skill],
+      refinementIds: [refinement.id],
+      occurrences: [{ refinementId: refinement.id, projectRealpath, timestamp: nowIso }],
+      status: "tracking",
+      proposedChanges: refinement.patchContent ? { content: refinement.patchContent } : {},
+      fingerprint: fingerprintKey(refinement.skill, refinement.targetSection, refinement.overrideType, refinement.patchAction),
+      firstSeen: nowIso,
+      lastSeen: nowIso
+    };
+    records.push(created);
+    return { pattern: created, becameReady: false };
+  }
+  if (!pattern.affectedSkills.includes(refinement.skill)) pattern.affectedSkills.push(refinement.skill);
+  if (!pattern.refinementIds.includes(refinement.id)) pattern.refinementIds.push(refinement.id);
+  pattern.occurrences.push({ refinementId: refinement.id, projectRealpath, timestamp: nowIso });
+  pattern.lastSeen = nowIso;
+  const becameReady = wasTracking && patternCount(pattern) >= READY_THRESHOLD;
+  if (becameReady) pattern.status = "ready";
+  return { pattern, becameReady };
+}
+function recordRefinement(input, deps = {}) {
+  const now = deps.now ?? /* @__PURE__ */ new Date();
+  const nowIso = now.toISOString();
+  const refinementsStore = readRefinementsStore();
+  const patternsStore = readPatternsStore();
+  const existingRefIds = new Set(refinementsStore.records.map((r) => r.id));
+  const refinementId = deps.id ?? generateRefinementId(existingRefIds, now, deps.randomHex);
+  const projectRealpath = resolveProjectRealpath(input.projectRoot);
+  const refinement = {
+    id: refinementId,
+    skill: input.skill,
+    category: input.category,
+    overrideType: input.overrideType,
+    targetSection: input.targetSection,
+    expectedBehavior: input.expectedBehavior,
+    actualBehavior: input.actualBehavior,
+    example: input.example,
+    desiredOutcome: input.desiredOutcome,
+    rootCause: input.rootCause,
+    confidence: input.confidence,
+    project: input.project,
+    projectRoot: projectRealpath,
+    patchAction: input.patchAction,
+    patchMarker: input.patchMarker,
+    patchContent: input.patchContent,
+    generalizationPotential: input.generalizationPotential,
+    scope: input.scope,
+    status: input.status ?? "applied",
+    createdAt: nowIso
+  };
+  const { pattern, becameReady } = upsertPattern(patternsStore.records, refinement, projectRealpath, nowIso, deps.randomHex, input.patternId);
+  refinement.patternId = pattern.id;
+  refinementsStore.records.push(refinement);
+  writeRefinementsStore(refinementsStore);
+  try {
+    writePatternsStore(patternsStore);
+  } catch (err) {
+    throw new UserError(
+      `refinements.json was updated with refinement ${refinement.id}, but patterns.json failed to update: ${err.message}`
+    );
+  }
+  return { refinement, pattern, patternBecameReady: becameReady };
+}
+function markGeneralized(id, backupId) {
+  const store = readPatternsStore();
+  const pattern = store.records.find((p) => p.id === id);
+  if (!pattern) {
+    throw new UserError(`no pattern with id: ${id}`);
+  }
+  const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+  pattern.status = "generalized";
+  pattern.generalizedAt = nowIso;
+  pattern.generalizedBackupId = backupId;
+  pattern.lastSeen = nowIso;
+  writePatternsStore(store);
+  return pattern;
+}
+function formatBackupTimestamp(date) {
+  return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+}
+var BACKUP_ID_PATTERN = /^\d{8}T\d{6}Z-[0-9a-f]{4}$/;
+function isValidBackupId(id) {
+  return BACKUP_ID_PATTERN.test(id);
+}
+function createBackup(filePaths, deps = {}) {
+  const now = deps.now ?? /* @__PURE__ */ new Date();
+  const randomHex = deps.randomHex ?? defaultRandomHex;
+  const id = `${formatBackupTimestamp(now)}-${randomHex()}`;
+  const files = filePaths.map((path) => {
+    if (!existsSync18(path)) {
+      return { path, existed: false, sha256: null, mode: null, contentBase64: null };
+    }
+    const bytes = readFileSync14(path);
+    const mode = statSync10(path).mode & 511;
+    const sha256 = createHash2("sha256").update(bytes).digest("hex");
+    return { path, existed: true, sha256, mode, contentBase64: bytes.toString("base64") };
+  });
+  const manifest = { id, createdAt: now.toISOString(), files };
+  writeJsonAtomic(join23(getBackupsDir(), id, "manifest.json"), manifest);
+  return manifest;
+}
+function validateBackupManifestShape(value, path) {
+  if (typeof value !== "object" || value === null) {
+    throw new UserError(`malformed backup manifest at ${path}: not an object`);
+  }
+  const m = value;
+  if (typeof m.id !== "string" || m.id.length === 0) {
+    throw new UserError(`malformed backup manifest at ${path}: missing a valid "id"`);
+  }
+  if (typeof m.createdAt !== "string" || m.createdAt.length === 0) {
+    throw new UserError(`malformed backup manifest at ${path}: missing a valid "createdAt"`);
+  }
+  if (!Array.isArray(m.files)) {
+    throw new UserError(`malformed backup manifest at ${path}: missing a valid "files" array`);
+  }
+  m.files.forEach((entry, index) => {
+    if (typeof entry !== "object" || entry === null) {
+      throw new UserError(`malformed backup manifest at ${path}: files[${index}] is not an object`);
+    }
+    const f = entry;
+    if (typeof f.path !== "string" || f.path.length === 0) {
+      throw new UserError(`malformed backup manifest at ${path}: files[${index}] is missing a valid "path"`);
+    }
+    if (typeof f.existed !== "boolean") {
+      throw new UserError(`malformed backup manifest at ${path}: files[${index}] ("${f.path}") is missing a valid "existed" (must be boolean)`);
+    }
+    if (f.existed) {
+      if (typeof f.sha256 !== "string" || f.sha256.length === 0) {
+        throw new UserError(`malformed backup manifest at ${path}: files[${index}] ("${f.path}") has existed:true but is missing "sha256"`);
+      }
+      if (typeof f.mode !== "number") {
+        throw new UserError(`malformed backup manifest at ${path}: files[${index}] ("${f.path}") has existed:true but is missing a numeric "mode"`);
+      }
+      if (typeof f.contentBase64 !== "string") {
+        throw new UserError(`malformed backup manifest at ${path}: files[${index}] ("${f.path}") has existed:true but is missing "contentBase64"`);
+      }
+    } else {
+      if (f.sha256 !== null || f.mode !== null || f.contentBase64 !== null) {
+        throw new UserError(`malformed backup manifest at ${path}: files[${index}] ("${f.path}") has existed:false (a tombstone) but sha256/mode/contentBase64 are not all null`);
+      }
+    }
+  });
+}
+function readBackupManifest(id) {
+  if (!isValidBackupId(id)) {
+    throw new UserError(`invalid backup id "${id}" \u2014 expected the format produced by \`skill-forge refine promote\` (e.g. 20260720T142305Z-a1b2)`);
+  }
+  const manifestPath = join23(getBackupsDir(), id, "manifest.json");
+  if (!existsSync18(manifestPath)) {
+    throw new UserError(`no backup with id: ${id}`);
+  }
+  const parsed = readJsonFile(manifestPath, "backup manifest");
+  validateBackupManifestShape(parsed, manifestPath);
+  return parsed;
+}
+
+// src/refine/context.ts
+function resolveConfiguredRoot2(root) {
+  return resolvePath10(expandHome(root));
+}
+function assertPlainSkillName(name) {
+  if (!name || name.trim().length === 0) {
+    throw new UserError("skill name must not be empty");
+  }
+  if (name.includes("/") || name.includes("\\") || name === "." || name === "..") {
+    throw new UserError(`invalid skill name "${name}" \u2014 must be a plain directory name, not a path`);
+  }
+}
+function realpathOrNull2(p) {
+  try {
+    return realpathSync6(p);
+  } catch {
+    return null;
+  }
+}
+function isUnderRoot2(candidate, root) {
+  const rel = relative2(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
+}
+function resolveScopes(config, cwd, skill, userRootFlag) {
+  assertPlainSkillName(skill);
+  const resolvedCwd = resolvePath10(cwd);
+  const localDir = join24(resolvedCwd, ".claude", "skills", skill);
+  const sharedDir = join24(resolvedCwd, "skills", skill);
+  const local = { scope: "local", dir: localDir, exists: existsSync19(localDir) };
+  const shared = { scope: "shared", dir: sharedDir, exists: existsSync19(sharedDir) };
+  const user = resolveUserScope(config, resolvedCwd, skill, userRootFlag);
+  return { local, shared, user };
+}
+function resolveUserScope(config, resolvedCwd, skill, userRootFlag) {
+  if (userRootFlag) {
+    const root = resolvePath10(userRootFlag);
+    return { resolved: true, dir: join24(root, skill), root: userRootFlag, reason: "flag" };
+  }
+  const cwdReal = realpathOrNull2(resolvedCwd) ?? resolvedCwd;
+  const candidates = config.skillsRoots.map((root) => ({ root, dir: join24(resolveConfiguredRoot2(root), skill) }));
+  for (const candidate of candidates) {
+    const skillReal = realpathOrNull2(candidate.dir);
+    if (skillReal) {
+      return { resolved: true, dir: candidate.dir, root: candidate.root, reason: "contains-skill" };
+    }
+  }
+  const externalCandidates = candidates.filter((candidate) => {
+    const rootReal = realpathOrNull2(resolveConfiguredRoot2(candidate.root)) ?? resolveConfiguredRoot2(candidate.root);
+    return !isUnderRoot2(rootReal, cwdReal) && !isUnderRoot2(cwdReal, rootReal);
+  });
+  if (externalCandidates.length === 1) {
+    return { resolved: true, dir: externalCandidates[0].dir, root: externalCandidates[0].root, reason: "sole-external-root" };
+  }
+  return { resolved: false, candidates: externalCandidates.length > 0 ? externalCandidates : candidates };
+}
+function isFile2(p) {
+  try {
+    return statSync11(p).isFile();
+  } catch {
+    return false;
+  }
+}
+function isDirectory(p) {
+  try {
+    return statSync11(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function inventoryScopeDir(scope, dir) {
+  return {
+    scope,
+    dir,
+    dirExists: isDirectory(dir),
+    skillMd: isFile2(join24(dir, "SKILL.md")),
+    patchMd: isFile2(join24(dir, "SKILL.patch.md")),
+    extendMd: isFile2(join24(dir, "SKILL.extend.md")),
+    configJson: isFile2(join24(dir, "skill-config.json")),
+    hooksDir: isDirectory(join24(dir, "hooks")),
+    scriptsDir: isDirectory(join24(dir, "scripts"))
+  };
+}
+function inventoryAllScopes(resolution) {
+  const rows = [inventoryScopeDir("local", resolution.local.dir), inventoryScopeDir("shared", resolution.shared.dir)];
+  if (resolution.user.resolved) {
+    rows.push(inventoryScopeDir("user", resolution.user.dir));
+  }
+  return rows;
+}
+
+// src/refine/patch.ts
+var FENCE_RE = /^\s*(```|~~~)/;
+var HEADING_RE = /^(#{1,6})\s+(.*)$/;
+function frontmatterOffset(lines) {
+  if (lines[0] !== "---") return 0;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") return i + 1;
+  }
+  return 0;
+}
+function buildHeadingTree(lines, bodyOffset) {
+  const flat = [];
+  let inFence = false;
+  for (let i = bodyOffset; i < lines.length; i++) {
+    const line = lines[i];
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const m = HEADING_RE.exec(line);
+    if (m) flat.push({ level: m[1].length, text: m[2].trim(), line: i });
+  }
+  const root = { level: 0, heading: "", headingLine: bodyOffset - 1, bodyStart: bodyOffset, bodyEnd: lines.length, children: [] };
+  const stack = [root];
+  for (const h of flat) {
+    while (stack.length > 1 && stack[stack.length - 1].level >= h.level) {
+      const done = stack.pop();
+      if (done) done.bodyEnd = h.line;
+    }
+    const node = { level: h.level, heading: h.text, headingLine: h.line, bodyStart: h.line + 1, bodyEnd: lines.length, children: [] };
+    stack[stack.length - 1].children.push(node);
+    stack.push(node);
+  }
+  return root;
+}
+function normalizeText(s) {
+  return s.trim().replace(/\s+/g, " ");
+}
+function splitHeadingPath(target) {
+  return target.split(">").map((segment) => segment.trim()).filter((segment) => segment.length > 0);
+}
+function collectDescendants(node, acc) {
+  acc.push(node);
+  for (const child of node.children) collectDescendants(child, acc);
+}
+function resolveHeadingPath(root, segments) {
+  if (segments.length === 0) return root;
+  const allNodes = [];
+  collectDescendants(root, allNodes);
+  const headingNodes = allNodes.filter((n) => n.level > 0);
+  const firstNorm = normalizeText(segments[0]);
+  let candidates = headingNodes.filter((n) => normalizeText(n.heading) === firstNorm);
+  if (candidates.length === 0) {
+    const available = headingNodes.map((n) => n.heading);
+    throw new UserError(`No section matching "${segments[0]}" found (available headings: ${available.length > 0 ? available.join(", ") : "none"})`);
+  }
+  for (let i = 1; i < segments.length; i++) {
+    const segment = segments[i];
+    const norm = normalizeText(segment);
+    const next = [];
+    for (const candidate of candidates) {
+      for (const child of candidate.children) {
+        if (normalizeText(child.heading) === norm) next.push(child);
+      }
+    }
+    if (next.length === 0) {
+      const available = [...new Set(candidates.flatMap((c) => c.children.map((child) => child.heading)))];
+      throw new UserError(`No section matching "${segment}" found (available headings: ${available.length > 0 ? available.join(", ") : "none"})`);
+    }
+    candidates = next;
+  }
+  if (candidates.length > 1) {
+    throw new UserError(`Target selector "${segments.join(" > ")}" matched ${candidates.length} sections; be more specific`);
+  }
+  return candidates[0];
+}
+function findMarkerLine(lines, start, end, marker) {
+  const norm = normalizeText(marker);
+  const matches = [];
+  for (let i = start; i < end; i++) {
+    if (normalizeText(lines[i]).includes(norm)) matches.push(i);
+  }
+  if (matches.length === 0) {
+    throw new UserError(`No line matching marker "${marker}" found in target section`);
+  }
+  if (matches.length > 1) {
+    const preview = matches.map((i) => `line ${i + 1}: "${lines[i].trim()}"`).join("; ");
+    throw new UserError(`Marker "${marker}" matched ${matches.length} lines, expected exactly 1 (${preview})`);
+  }
+  return matches[0];
+}
+function findChildByMarker(target, marker) {
+  const norm = normalizeText(marker);
+  const matches = target.children.filter((c) => normalizeText(c.heading).includes(norm));
+  if (matches.length === 0) {
+    const available = target.children.map((c) => c.heading).join(", ") || "none";
+    throw new UserError(`No subsection matching "${marker}" found under target section (available: ${available})`);
+  }
+  if (matches.length > 1) {
+    throw new UserError(`Marker "${marker}" matched ${matches.length} subsections: ${matches.map((c) => c.heading).join(", ")}`);
+  }
+  return matches[0];
+}
+function requireMarker(block) {
+  if (!block.marker || block.marker.trim().length === 0) {
+    throw new UserError(`Action "${block.action}" requires a marker`);
+  }
+  return block.marker;
+}
+function applyOneAction(lines, target, block) {
+  const contentLines = block.content.length === 0 ? [""] : block.content.split("\n");
+  switch (block.action) {
+    case "append": {
+      lines.splice(target.bodyEnd, 0, ...contentLines);
+      return;
+    }
+    case "prepend": {
+      lines.splice(target.bodyStart, 0, ...contentLines);
+      return;
+    }
+    case "insert-after":
+    case "insert-before": {
+      const idx = findMarkerLine(lines, target.bodyStart, target.bodyEnd, requireMarker(block));
+      lines.splice(block.action === "insert-after" ? idx + 1 : idx, 0, ...contentLines);
+      return;
+    }
+    case "replace-section":
+    case "delete-section": {
+      const child = findChildByMarker(target, requireMarker(block));
+      const replacement = block.action === "replace-section" ? contentLines : [];
+      lines.splice(child.headingLine, child.bodyEnd - child.headingLine, ...replacement);
+      return;
+    }
+    default: {
+      const exhaustive = block.action;
+      throw new UserError(`Unknown patch action "${exhaustive}"`);
+    }
+  }
+}
+function applyPatchBlocks(skillMd, blocks) {
+  const lines = skillMd.split("\n");
+  for (const block of blocks) {
+    const bodyOffset = frontmatterOffset(lines);
+    const root = buildHeadingTree(lines, bodyOffset);
+    const segments = block.target ? splitHeadingPath(block.target) : [];
+    const target = resolveHeadingPath(root, segments);
+    applyOneAction(lines, target, block);
+  }
+  return lines.join("\n");
+}
+function renderExtendFile(meta) {
+  return [
+    "# SKILL.extend.md",
+    `# Extensions for: ${meta.skillName}`,
+    `# Generated: ${meta.generatedAt}`,
+    `# Refinement: ${meta.refinementId}`,
+    "",
+    `## EXTEND: ${meta.targetSection}`,
+    "<!-- ACTION: append -->",
+    meta.content,
+    ""
+  ].join("\n");
+}
+function renderConfigOverride(meta) {
+  const payload = {
+    skill: meta.skillName,
+    version: "1.0.0",
+    generated: meta.generatedAt,
+    config: meta.config
+  };
+  return `${JSON.stringify(payload, null, 2)}
+`;
+}
+function computeLcsDiff(a, b) {
+  const n = a.length;
+  const m = b.length;
+  const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i2 = n - 1; i2 >= 0; i2--) {
+    for (let j2 = m - 1; j2 >= 0; j2--) {
+      dp[i2][j2] = a[i2] === b[j2] ? dp[i2 + 1][j2 + 1] + 1 : Math.max(dp[i2 + 1][j2], dp[i2][j2 + 1]);
+    }
+  }
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ type: "context", line: a[i] });
+      i++;
+      j++;
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      ops.push({ type: "remove", line: a[i] });
+      i++;
+    } else {
+      ops.push({ type: "add", line: b[j] });
+      j++;
+    }
+  }
+  while (i < n) {
+    ops.push({ type: "remove", line: a[i] });
+    i++;
+  }
+  while (j < m) {
+    ops.push({ type: "add", line: b[j] });
+    j++;
+  }
+  return ops;
+}
+function previewDiff(before, after, path) {
+  const a = before.split("\n");
+  const b = after.split("\n");
+  const ops = computeLcsDiff(a, b);
+  const lines = [`--- ${path}`, `+++ ${path}`];
+  for (const op of ops) {
+    const prefix = op.type === "add" ? "+" : op.type === "remove" ? "-" : " ";
+    lines.push(`${prefix}${op.line}`);
+  }
+  return lines.join("\n");
+}
+
+// src/commands/refine.ts
+var PRO_FEATURE_LABEL6 = "skill refinement";
+var REFINE_PROMPT_ASSET = "refine-prompt.md";
+function requireProFeature2() {
+  const status2 = proFeatureStatus(PRO_FEATURE_LABEL6);
+  if (!status2.enabled) {
+    throw new UserError(status2.notice ?? "refine is a Pro feature \u2014 set SKILL_FORGE_LICENSE or config.licenseKey to a valid license to unlock.");
+  }
+  if (status2.notice) console.error(`[skill-forge] ${status2.notice}`);
+}
+function isInteractive(json) {
+  return !json && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+}
+function emit(json, payload, renderText) {
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    renderText();
+  }
+}
+async function confirmYesNo(rl, question) {
+  const answer = (await rl.question(question)).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
+}
+async function confirmWrite(yes, json, prompt) {
+  if (yes) return true;
+  if (!isInteractive(json)) {
+    throw new UserError("refusing to write without confirmation \u2014 pass --yes, or run interactively.");
+  }
+  const rl = createInterface5({ input: process.stdin, output: process.stdout });
+  try {
+    return await confirmYesNo(rl, prompt);
+  } finally {
+    rl.close();
+  }
+}
+function resolveConfiguredRoot3(root) {
+  return resolvePath11(expandHome(root));
+}
+function isUnderRoot3(candidate, root) {
+  const rel = relative3(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute3(rel);
+}
+function sanitizeDiffForConsole(diff) {
+  return diff.split("\n").map((line) => sanitizeForMarkdown(line)).join("\n");
+}
+function resolveContentOption(options) {
+  if (options.content !== void 0) return options.content;
+  if (options.contentFile) return readFileSync15(resolvePath11(options.contentFile), "utf-8");
+  return void 0;
+}
+function validateCaptureOptions(options) {
+  if (!options.skill) throw new UserError("--skill is required");
+  assertPlainSkillName(options.skill);
+  if (!options.category || !isRefinementCategory(options.category)) {
+    throw new UserError(`--category is required and must be one of: trigger, content, hook, tool, pattern, config, new`);
+  }
+  if (!options.target) throw new UserError("--target is required (heading-path selector or a short description for whole-file override types)");
+  if (!options.overrideType || !isOverrideType(options.overrideType)) {
+    throw new UserError("--override-type is required and must be one of: patch, extend, config, full, hook, script, new");
+  }
+  if (!options.expected) throw new UserError("--expected is required");
+  if (!options.actual) throw new UserError("--actual is required");
+  const scopeRaw = options.scope ?? "local";
+  if (scopeRaw !== "local" && scopeRaw !== "shared") {
+    throw new UserError('--scope must be "local" or "shared"');
+  }
+  let action;
+  if (options.overrideType === "patch") {
+    if (!options.action || !isPatchAction(options.action)) {
+      throw new UserError(
+        "--action is required for --override-type patch (one of: append, prepend, replace-section, insert-after, insert-before, delete-section)"
+      );
+    }
+    action = options.action;
+  }
+  return {
+    skill: options.skill,
+    category: options.category,
+    target: options.target,
+    overrideType: options.overrideType,
+    action,
+    marker: options.marker,
+    expected: options.expected,
+    actual: options.actual,
+    example: options.example,
+    outcome: options.outcome,
+    rootCause: options.rootCause,
+    patternId: options.patternId,
+    scope: scopeRaw,
+    dryRun: options.dryRun ?? false,
+    json: options.json ?? false,
+    yes: options.yes ?? false,
+    handoff: options.handoff ?? false
+  };
+}
+function renderPatchActionBlock(params) {
+  const lines = [];
+  lines.push(params.marker ? `<!-- ACTION: ${params.action} "${params.marker}" -->` : `<!-- ACTION: ${params.action} -->`);
+  lines.push(`<!-- TARGET: ${params.target} -->`);
+  lines.push(params.content);
+  return lines.join("\n");
+}
+function defaultOverrideFilename(overrideType) {
+  switch (overrideType) {
+    case "full":
+      return "SKILL.md";
+    case "hook":
+      return "hooks/refinement.sh";
+    case "script":
+      return "scripts/refinement.sh";
+    default: {
+      const exhaustive = overrideType;
+      throw new Error(`internal error: defaultOverrideFilename called for non-whole-file override type "${exhaustive}"`);
+    }
+  }
+}
+function renderCaptureArtifact(opts, content, refinementId, generatedAt, existingContent) {
+  switch (opts.overrideType) {
+    case "patch": {
+      if (!content) throw new UserError("--content or --content-file is required for --override-type patch");
+      const block = renderPatchActionBlock({ action: opts.action, marker: opts.marker, target: opts.target, content });
+      const preamble = `# SKILL.patch.md
+# Patches for: ${opts.skill}
+`;
+      const base = existingContent.trim().length > 0 ? existingContent.trimEnd() : preamble.trimEnd();
+      return { relPath: "SKILL.patch.md", content: `${base}
+
+${block}
+` };
+    }
+    case "extend":
+    case "new": {
+      if (!content) throw new UserError(`--content or --content-file is required for --override-type ${opts.overrideType}`);
+      const rendered = renderExtendFile({ skillName: opts.skill, refinementId, generatedAt, targetSection: opts.target, content });
+      const combined = existingContent.trim().length > 0 ? `${existingContent.trimEnd()}
+
+${rendered}` : rendered;
+      return { relPath: "SKILL.extend.md", content: combined };
+    }
+    case "config": {
+      if (!content) throw new UserError("--content or --content-file (JSON object) is required for --override-type config");
+      let parsed;
+      try {
+        parsed = JSON.parse(content);
+      } catch (err) {
+        throw new UserError(`--content for --override-type config must be valid JSON: ${err.message}`);
+      }
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new UserError("--content for --override-type config must be a JSON object");
+      }
+      const rendered = renderConfigOverride({
+        skillName: opts.skill,
+        refinementId,
+        generatedAt,
+        config: parsed
+      });
+      return { relPath: "skill-config.json", content: rendered };
+    }
+    case "full":
+    case "hook":
+    case "script": {
+      if (!content) throw new UserError(`--content or --content-file is required for --override-type ${opts.overrideType}`);
+      return { relPath: opts.marker && opts.marker.trim().length > 0 ? opts.marker.trim() : defaultOverrideFilename(opts.overrideType), content };
+    }
+    default: {
+      const exhaustive = opts.overrideType;
+      throw new UserError(`unknown override type "${exhaustive}"`);
+    }
+  }
+}
+function ensureScopeDirSafe(scopeDir, resolvedCwd) {
+  let lst;
+  try {
+    lst = lstatSync3(scopeDir);
+  } catch {
+    lst = void 0;
+  }
+  if (lst?.isSymbolicLink()) {
+    throw new UserError(`refusing to write under ${scopeDir}: scope directory is a symlink`);
+  }
+  mkdirSync9(scopeDir, { recursive: true });
+  const real = resolveConfiguredRoot3(scopeDir);
+  const lexical = resolvePath11(scopeDir);
+  let realResolved;
+  try {
+    realResolved = realpathSync7(scopeDir);
+  } catch {
+    realResolved = real;
+  }
+  if (realResolved !== lexical) {
+    throw new UserError(`refusing to write under ${scopeDir}: path contains a symlink`);
+  }
+  if (!isUnderRoot3(realResolved, resolveConfiguredRoot3(resolvedCwd))) {
+    throw new UserError(`refusing to write under ${scopeDir}: resolves outside the project root ${resolvedCwd}`);
+  }
+  return realResolved;
+}
+function writeOverrideFile(scopeDir, relPath, content, resolvedCwd) {
+  const realScopeDir = ensureScopeDirSafe(scopeDir, resolvedCwd);
+  const destPath = join25(scopeDir, relPath);
+  const destDir = dirname11(destPath);
+  mkdirSync9(destDir, { recursive: true });
+  const realDestDir = realpathSync7(destDir);
+  if (!isUnderRoot3(realDestDir, realScopeDir)) {
+    throw new UserError(`refusing to write ${destPath}: resolves outside scope directory ${scopeDir}`);
+  }
+  let destLst;
+  try {
+    destLst = lstatSync3(destPath);
+  } catch {
+    destLst = void 0;
+  }
+  if (destLst?.isSymbolicLink()) {
+    throw new UserError(`refusing to write ${destPath}: destination is a symlink`);
+  }
+  writeFileSync9(destPath, content, { mode: 384 });
+  chmodSync(destPath, 384);
+  return destPath;
+}
+async function refineCaptureCommand(rawOptions = {}) {
+  requireProFeature2();
+  const opts = validateCaptureOptions(rawOptions);
+  const config = loadConfig();
+  const cwd = process.cwd();
+  const scopes = resolveScopes(config, cwd, opts.skill);
+  const scopeDir = opts.scope === "local" ? scopes.local.dir : scopes.shared.dir;
+  const content = resolveContentOption(rawOptions);
+  const now = /* @__PURE__ */ new Date();
+  const existingIds = new Set(readRefinementsStore().records.map((r) => r.id));
+  const refinementId = generateRefinementId(existingIds, now, defaultRandomHex);
+  const preview = renderCaptureArtifactPreview(opts, content, refinementId, now.toISOString(), scopeDir);
+  if (opts.dryRun) {
+    emit(opts.json, { dryRun: true, path: preview.destPath, diff: preview.diff }, () => {
+      console.log(`[skill-forge] refine capture \u2014 ${opts.overrideType} override for "${sanitizeForMarkdown(opts.skill)}" at ${opts.scope} scope`);
+      console.log(sanitizeDiffForConsole(preview.diff));
+    });
+    return;
+  }
+  if (!opts.json) {
+    console.log(`[skill-forge] refine capture \u2014 ${opts.overrideType} override for "${sanitizeForMarkdown(opts.skill)}" at ${opts.scope} scope`);
+    console.log(sanitizeDiffForConsole(preview.diff));
+  }
+  const proceed = await confirmWrite(opts.yes, opts.json, `
+Write ${preview.destPath}? [y/N] `);
+  if (!proceed) {
+    emit(opts.json, { written: false, cancelled: true, path: preview.destPath }, () => {
+      console.log("[skill-forge] capture cancelled \u2014 nothing written.");
+    });
+    return;
+  }
+  const writtenPath = writeOverrideFile(scopeDir, preview.relPath, preview.content, cwd);
+  let result;
+  try {
+    result = recordRefinement(
+      {
+        skill: opts.skill,
+        category: opts.category,
+        overrideType: opts.overrideType,
+        targetSection: opts.target,
+        expectedBehavior: opts.expected,
+        actualBehavior: opts.actual,
+        example: opts.example,
+        desiredOutcome: opts.outcome,
+        rootCause: opts.rootCause,
+        project: cwd,
+        projectRoot: cwd,
+        patchAction: opts.action,
+        patchMarker: opts.marker,
+        patchContent: content,
+        status: "applied",
+        scope: opts.scope,
+        patternId: opts.patternId
+      },
+      { now, id: refinementId }
+    );
+  } catch (err) {
+    throw new UserError(`wrote the override artifact at ${writtenPath}, but recording the refinement in the store failed: ${err.message}`);
+  }
+  emit(
+    opts.json,
+    { written: true, path: writtenPath, refinementId: result.refinement.id, patternId: result.pattern.id, patternBecameReady: result.patternBecameReady },
+    () => {
+      console.log(`[skill-forge] wrote ${writtenPath}`);
+      console.log(`[skill-forge] recorded refinement ${result.refinement.id} -> pattern ${result.pattern.id} (status: ${result.pattern.status})`);
+      if (result.patternBecameReady) {
+        console.log(`[skill-forge] pattern ${result.pattern.id} is now READY (seen in a second project) \u2014 consider \`skill-forge refine promote ${result.pattern.id}\``);
+      }
+    }
+  );
+  if (opts.handoff) {
+    runHandoff(config, writtenPath, { promptAsset: REFINE_PROMPT_ASSET, log: opts.json ? console.error : console.log });
+  }
+}
+function renderCaptureArtifactPreview(opts, content, refinementId, generatedAt, scopeDir) {
+  const probeRelPath = opts.overrideType === "patch" ? "SKILL.patch.md" : opts.overrideType === "extend" || opts.overrideType === "new" ? "SKILL.extend.md" : void 0;
+  const probePath = probeRelPath ? join25(scopeDir, probeRelPath) : void 0;
+  const existingContent = probePath && existsSync20(probePath) ? readFileSync15(probePath, "utf-8") : "";
+  const rendered = renderCaptureArtifact(opts, content, refinementId, generatedAt, existingContent);
+  const relPath = rendered.relPath;
+  const destPath = join25(scopeDir, relPath);
+  const before = existsSync20(destPath) ? readFileSync15(destPath, "utf-8") : "";
+  const diff = previewDiff(before, rendered.content, destPath);
+  return { relPath, content: rendered.content, destPath, diff };
+}
+async function refineListCommand(options = {}) {
+  requireProFeature2();
+  const { records } = readRefinementsStore();
+  let rows = records;
+  if (options.skill) rows = rows.filter((r) => r.skill === options.skill);
+  if (options.project) rows = rows.filter((r) => r.project === options.project || r.projectRoot === resolvePath11(options.project));
+  if (options.status) {
+    if (!isRefinementStatus(options.status)) {
+      throw new UserError("--status must be one of: pending, applied, generalized");
+    }
+    rows = rows.filter((r) => r.status === options.status);
+  }
+  const filtered = Boolean(options.skill || options.project || options.status);
+  emit(options.json, { records: rows }, () => {
+    if (rows.length === 0) {
+      if (filtered && records.length > 0) {
+        console.log(`[skill-forge] no refinements match the given filter(s) (${records.length} total recorded).`);
+      } else {
+        console.log("[skill-forge] no refinements recorded.");
+      }
+      return;
+    }
+    console.log(`[skill-forge] ${rows.length} refinement(s):`);
+    for (const r of rows) {
+      console.log(
+        `  ${r.id}  ${sanitizeForMarkdown(r.skill)}  [${r.category}/${r.overrideType}]  status=${r.status}  pattern=${r.patternId ?? "(none)"}  ${r.createdAt}`
+      );
+    }
+  });
+}
+async function refinePatternsCommand(options = {}) {
+  requireProFeature2();
+  const { records } = readPatternsStore();
+  let rows = records;
+  if (options.status) {
+    if (!isPatternStatus(options.status)) {
+      throw new UserError("--status must be one of: tracking, ready, generalized, dismissed");
+    }
+    rows = rows.filter((p) => p.status === options.status);
+  }
+  if (options.skill) rows = rows.filter((p) => p.affectedSkills.includes(options.skill));
+  if (options.project) {
+    const resolvedProject = resolvePath11(options.project);
+    rows = rows.filter((p) => p.occurrences.some((o) => o.projectRealpath === resolvedProject));
+  }
+  const filtered = Boolean(options.skill || options.project || options.status);
+  emit(options.json, { records: rows.map((p) => ({ ...p, count: patternCount(p) })) }, () => {
+    if (rows.length === 0) {
+      if (filtered && records.length > 0) {
+        console.log(`[skill-forge] no patterns match the given filter(s) (${records.length} total recorded).`);
+      } else {
+        console.log("[skill-forge] no patterns recorded.");
+      }
+      return;
+    }
+    console.log(`[skill-forge] ${rows.length} pattern(s):`);
+    for (const p of rows) {
+      console.log(
+        `  ${p.id}  ${sanitizeForMarkdown(p.name)}  status=${p.status}  count=${patternCount(p)}  skills=${p.affectedSkills.map(sanitizeForMarkdown).join(", ")}`
+      );
+    }
+  });
+}
+function renderInventoryLine(row) {
+  const present = [
+    row.skillMd ? "SKILL.md" : void 0,
+    row.patchMd ? "SKILL.patch.md" : void 0,
+    row.extendMd ? "SKILL.extend.md" : void 0,
+    row.configJson ? "skill-config.json" : void 0,
+    row.hooksDir ? "hooks/" : void 0,
+    row.scriptsDir ? "scripts/" : void 0
+  ].filter((v) => Boolean(v));
+  return `  [${row.scope}] ${row.dir}${row.dirExists ? "" : " (missing)"} \u2014 ${present.length > 0 ? present.join(", ") : "(no override files)"}`;
+}
+async function refineWhichCommand(skill, options = {}) {
+  requireProFeature2();
+  if (!skill) throw new UserError("a skill name is required: skill-forge refine which <skill>");
+  const config = loadConfig();
+  const cwd = process.cwd();
+  const scopes = resolveScopes(config, cwd, skill, options.userRoot);
+  const inventory = inventoryAllScopes(scopes);
+  emit(options.json, { scopes, inventory }, () => {
+    console.log(`[skill-forge] refine which "${sanitizeForMarkdown(skill)}" \u2014 resolution order (highest precedence first):`);
+    for (const row of inventory) console.log(renderInventoryLine(row));
+    if (!scopes.user.resolved) {
+      console.log(
+        `  [user] ambiguous \u2014 candidates: ${scopes.user.candidates.map((c) => c.root).join(", ") || "(none configured)"} (pass --user-root to disambiguate)`
+      );
+    }
+  });
+}
+function writePostWriteSidecar(backupId, files) {
+  const sidecar = { schemaVersion: 1, files };
+  const dir = join25(getBackupsDir(), backupId);
+  mkdirSync9(dir, { recursive: true });
+  writeFileSync9(join25(dir, "post.json"), JSON.stringify(sidecar, null, 2) + "\n", { mode: 384 });
+}
+function readPostWriteSidecar(backupId) {
+  const path = join25(getBackupsDir(), backupId, "post.json");
+  if (!existsSync20(path)) return { hashes: /* @__PURE__ */ new Map(), status: "missing" };
+  let raw;
+  try {
+    raw = readFileSync15(path, "utf-8");
+  } catch {
+    return { hashes: /* @__PURE__ */ new Map(), status: "unreadable" };
+  }
+  const hashes = /* @__PURE__ */ new Map();
+  try {
+    const parsed = JSON.parse(raw);
+    for (const f of parsed.files ?? []) {
+      if (typeof f !== "object" || f === null || typeof f.path !== "string" || typeof f.sha256 !== "string") {
+        throw new Error("malformed post.json files entry");
+      }
+      hashes.set(f.path, f.sha256);
+    }
+  } catch {
+    return { hashes: /* @__PURE__ */ new Map(), status: "corrupt" };
+  }
+  return { hashes, status: "ok" };
+}
+async function refinePromoteCommand(patternId, options = {}) {
+  requireProFeature2();
+  if (!patternId) throw new UserError("a pattern id is required: skill-forge refine promote <pattern-id>");
+  const patternsStore = readPatternsStore();
+  const pattern = patternsStore.records.find((p) => p.id === patternId);
+  if (!pattern) throw new UserError(`no pattern with id: ${patternId}`);
+  if (pattern.status === "generalized" && !options.force) {
+    throw new UserError(`pattern ${patternId} is already generalized (backup ${pattern.generalizedBackupId ?? "(unknown)"}) \u2014 pass --force to re-promote.`);
+  }
+  if (pattern.status !== "ready" && pattern.status !== "generalized" && !options.force) {
+    throw new UserError(`pattern ${patternId} is not ready (status: ${pattern.status}) \u2014 pass --force to promote anyway.`);
+  }
+  const skill = pattern.affectedSkills[0];
+  if (!skill) throw new UserError(`pattern ${patternId} has no affected skills recorded`);
+  assertPlainSkillName(skill);
+  const config = loadConfig();
+  const cwd = process.cwd();
+  const scopes = resolveScopes(config, cwd, skill, options.userRoot);
+  if (!scopes.user.resolved) {
+    throw new UserError(
+      `cannot resolve a single user scope for skill "${skill}" \u2014 candidates: ${scopes.user.candidates.map((c) => c.root).join(", ") || "(none configured)"}. Pass --user-root to disambiguate.`
+    );
+  }
+  const skillDir = scopes.user.dir;
+  const resolvedUserRoot = resolveConfiguredRoot3(scopes.user.root);
+  let realUserRoot;
+  try {
+    realUserRoot = realpathSync7(resolvedUserRoot);
+  } catch {
+    realUserRoot = resolvedUserRoot;
+  }
+  let realSkillDir;
+  try {
+    realSkillDir = realpathSync7(skillDir);
+  } catch {
+    realSkillDir = resolvePath11(skillDir);
+  }
+  if (!isUnderRoot3(realSkillDir, realUserRoot)) {
+    throw new UserError(`refusing to promote: resolved skill directory ${skillDir} is outside the configured user scope root ${scopes.user.root}`);
+  }
+  const skillMdPath = join25(skillDir, "SKILL.md");
+  if (!existsSync20(skillMdPath)) {
+    throw new UserError(`user-scope SKILL.md not found at ${skillMdPath} \u2014 refusing to promote against a missing base skill.`);
+  }
+  const refinementsStore = readRefinementsStore();
+  const patternRefinements = refinementsStore.records.filter((r) => pattern.refinementIds.includes(r.id));
+  const representative = patternRefinements[patternRefinements.length - 1];
+  if (!representative) throw new UserError(`pattern ${patternId} has no recorded refinements to promote`);
+  let block;
+  if (representative.overrideType === "patch" && representative.patchAction && representative.patchContent) {
+    block = { action: representative.patchAction, marker: representative.patchMarker, target: representative.targetSection, content: representative.patchContent };
+  } else if ((representative.overrideType === "extend" || representative.overrideType === "new") && representative.patchContent) {
+    block = { action: "append", target: representative.targetSection, content: representative.patchContent };
+  } else {
+    throw new UserError(
+      `pattern ${patternId}'s representative refinement is a '${representative.overrideType}' override \u2014 promote currently only materializes patch/extend/new-type patterns against the user-scope SKILL.md; other override types must be merged manually.`
+    );
+  }
+  const before = readFileSync15(skillMdPath, "utf-8");
+  const after = applyPatchBlocks(before, [block]);
+  const diff = previewDiff(before, after, skillMdPath);
+  if (options.dryRun) {
+    emit(options.json, { dryRun: true, path: skillMdPath, diff }, () => {
+      console.log(`[skill-forge] refine promote ${patternId} -> ${skillMdPath}`);
+      console.log(sanitizeDiffForConsole(diff));
+    });
+    return;
+  }
+  if (!options.json) {
+    console.log(`[skill-forge] refine promote ${patternId} -> ${skillMdPath}`);
+    console.log(sanitizeDiffForConsole(diff));
+  }
+  const proceed = await confirmWrite(options.yes, options.json, `
+Promote pattern ${patternId} into ${skillMdPath}? [y/N] `);
+  if (!proceed) {
+    emit(options.json, { promoted: false, cancelled: true }, () => {
+      console.log("[skill-forge] promote cancelled \u2014 nothing written.");
+    });
+    return;
+  }
+  const backup = createBackup([skillMdPath]);
+  const tempPath = `${skillMdPath}.tmp-${randomUUID4()}`;
+  try {
+    writeFileSync9(tempPath, after, "utf-8");
+    renameSync5(tempPath, skillMdPath);
+  } catch (err) {
+    rmSync7(tempPath, { force: true });
+    throw err;
+  }
+  try {
+    const postSha256 = createHash3("sha256").update(readFileSync15(skillMdPath)).digest("hex");
+    writePostWriteSidecar(backup.id, [{ path: skillMdPath, sha256: postSha256 }]);
+    markGeneralized(patternId, backup.id);
+    const skillsRoot = resolveConfiguredRoot3(scopes.user.root);
+    appendProvenance(
+      {
+        name: skill,
+        source: `skill-forge refine (${patternId})`,
+        verb: "DEFER",
+        target: skillMdPath,
+        took: `applied a ${block.action} patch materializing pattern ${patternId}`,
+        notes: `generalized from ${patternId} via skill-forge refine`
+      },
+      skillsRoot
+    );
+  } catch (err) {
+    throw new UserError(
+      `the user-scope skill was updated at ${skillMdPath} (backup ${backup.id}), but recording post-write verification and/or pattern/provenance state failed: ${err.message}`
+    );
+  }
+  emit(options.json, { promoted: true, path: skillMdPath, backupId: backup.id }, () => {
+    console.log(`[skill-forge] promoted pattern ${patternId} -> ${skillMdPath} (backup: ${backup.id})`);
+  });
+}
+function assertBackupDirContained(backupId) {
+  const backupsDir = getBackupsDir();
+  if (!existsSync20(backupsDir)) return;
+  const realBackupsDir = realpathSync7(backupsDir);
+  const backupDir = join25(backupsDir, backupId);
+  if (!existsSync20(backupDir)) return;
+  const realBackupDir = realpathSync7(backupDir);
+  if (!isUnderRoot3(realBackupDir, realBackupsDir)) {
+    throw new UserError(`refusing rollback: backup id "${backupId}" resolves outside the backups directory`);
+  }
+}
+function resolveTargetRealPath(path) {
+  let lexicalAncestor = resolvePath11(path);
+  while (true) {
+    try {
+      const real = realpathSync7(lexicalAncestor);
+      const remainder = relative3(lexicalAncestor, resolvePath11(path));
+      return remainder === "" ? real : join25(real, remainder);
+    } catch {
+      const parent = dirname11(lexicalAncestor);
+      if (parent === lexicalAncestor) return resolvePath11(path);
+      lexicalAncestor = parent;
+    }
+  }
+}
+function assertManifestPathsWithinRoots(manifest, config) {
+  if (config.skillsRoots.length === 0) {
+    throw new UserError(`refusing rollback ${manifest.id}: no skillsRoots are configured \u2014 cannot verify the backup's file paths are within a trusted skills root.`);
+  }
+  const roots = config.skillsRoots.map((root) => {
+    const resolved = resolveConfiguredRoot3(root);
+    try {
+      return realpathSync7(resolved);
+    } catch {
+      return resolved;
+    }
+  });
+  for (const file of manifest.files) {
+    const resolvedTarget = resolveTargetRealPath(file.path);
+    const withinAnyRoot = roots.some((root) => isUnderRoot3(resolvedTarget, root));
+    if (!withinAnyRoot) {
+      throw new UserError(`refusing rollback ${manifest.id}: backup manifest references a path outside configured skills roots \u2014 ${file.path}`);
+    }
+  }
+}
+function assertNoSymlinkLeaves(manifest) {
+  for (const file of manifest.files) {
+    let lst;
+    try {
+      lst = lstatSync3(file.path);
+    } catch {
+      lst = void 0;
+    }
+    if (lst?.isSymbolicLink()) {
+      throw new UserError(`refusing rollback ${manifest.id}: backup manifest path is currently a symlink \u2014 refusing to follow or overwrite it: ${file.path}`);
+    }
+  }
+}
+function findLexicalRoot(filePath, config) {
+  const lexicalTarget = resolvePath11(filePath);
+  for (const root of config.skillsRoots) {
+    const rootLexical = resolveConfiguredRoot3(root);
+    const rel = relative3(rootLexical, lexicalTarget);
+    if (rel !== "" && (rel === ".." || rel.startsWith(`..${sep2}`) || isAbsolute3(rel))) continue;
+    let rootReal;
+    try {
+      rootReal = realpathSync7(rootLexical);
+    } catch {
+      rootReal = rootLexical;
+    }
+    return { rootLexical, rootReal };
+  }
+  throw new UserError(`refusing to operate on ${filePath}: does not resolve lexically under any configured skills root`);
+}
+function walkRealComponents(filePath, config, createMissing) {
+  const { rootLexical, rootReal } = findLexicalRoot(filePath, config);
+  const relPath = relative3(rootLexical, resolvePath11(filePath));
+  const components = relPath.split(sep2).filter((c) => c.length > 0);
+  if (components.length === 0) {
+    throw new UserError(`refusing to operate on ${filePath}: resolves to the skills root itself`);
+  }
+  const leafComponent = components[components.length - 1];
+  const dirComponents = components.slice(0, -1);
+  let current = rootReal;
+  for (const component of dirComponents) {
+    if (current === void 0) break;
+    const next = join25(current, component);
+    let lst;
+    try {
+      lst = lstatSync3(next);
+    } catch {
+      lst = void 0;
+    }
+    if (lst === void 0) {
+      if (!createMissing) {
+        current = void 0;
+        continue;
+      }
+      mkdirSync9(next);
+      current = next;
+      continue;
+    }
+    if (lst.isSymbolicLink()) {
+      throw new UserError(`refusing to operate on ${filePath}: intermediate path component is a symlink \u2014 ${next}`);
+    }
+    if (!lst.isDirectory()) {
+      throw new UserError(`refusing to operate on ${filePath}: intermediate path component is not a directory \u2014 ${next}`);
+    }
+    current = next;
+  }
+  return { parentReal: current, leafComponent, rootReal };
+}
+function safeRestoreWrite(filePath, contentBuffer, mode, config) {
+  const { parentReal, leafComponent, rootReal } = walkRealComponents(filePath, config, true);
+  if (parentReal === void 0) {
+    throw new UserError(`refusing to restore ${filePath}: could not establish a real parent directory`);
+  }
+  const finalPath = join25(parentReal, leafComponent);
+  if (!isUnderRoot3(finalPath, rootReal)) {
+    throw new UserError(`refusing to restore ${filePath}: resolves outside root ${rootReal}`);
+  }
+  let leafLst;
+  try {
+    leafLst = lstatSync3(finalPath);
+  } catch {
+    leafLst = void 0;
+  }
+  if (leafLst?.isSymbolicLink()) {
+    throw new UserError(`refusing to restore ${filePath}: it is now a symlink \u2014 refusing to follow or overwrite it.`);
+  }
+  const tempPath = `${finalPath}.tmp-${randomUUID4()}`;
+  try {
+    writeFileSync9(tempPath, contentBuffer);
+    chmodSync(tempPath, mode);
+    renameSync5(tempPath, finalPath);
+  } catch (err) {
+    rmSync7(tempPath, { force: true });
+    throw err;
+  }
+}
+function safeDeleteTombstone(filePath, config) {
+  const { parentReal, leafComponent, rootReal } = walkRealComponents(filePath, config, false);
+  if (parentReal === void 0) return;
+  const finalPath = join25(parentReal, leafComponent);
+  if (!isUnderRoot3(finalPath, rootReal)) {
+    throw new UserError(`refusing to delete ${filePath}: resolves outside root ${rootReal}`);
+  }
+  let leafLst;
+  try {
+    leafLst = lstatSync3(finalPath);
+  } catch {
+    leafLst = void 0;
+  }
+  if (leafLst === void 0) return;
+  if (leafLst.isSymbolicLink()) {
+    throw new UserError(`refusing to delete ${filePath}: it is now a symlink \u2014 refusing to follow or overwrite it.`);
+  }
+  rmSync7(finalPath, { force: true });
+}
+async function refineRollbackCommand(backupId, options = {}) {
+  requireProFeature2();
+  if (!backupId) throw new UserError("a backup id is required: skill-forge refine rollback <backup-id>");
+  if (!isValidBackupId(backupId)) {
+    throw new UserError(`invalid backup id "${backupId}" \u2014 expected the format produced by \`skill-forge refine promote\` (e.g. 20260720T142305Z-a1b2)`);
+  }
+  assertBackupDirContained(backupId);
+  const manifest = readBackupManifest(backupId);
+  const config = loadConfig();
+  assertManifestPathsWithinRoots(manifest, config);
+  assertNoSymlinkLeaves(manifest);
+  const warnings = [];
+  const sidecar = readPostWriteSidecar(backupId);
+  if (sidecar.status !== "ok") {
+    const reason = sidecar.status;
+    if (!options.force) {
+      throw new UserError(
+        `refusing rollback ${backupId}: post-write verification data (post.json) is ${reason} \u2014 cannot confirm the current file state matches what was promoted. Pass --force to override.`
+      );
+    }
+    warnings.push(`post-write verification data for backup ${backupId} is ${reason} \u2014 restoring without hash verification (--force).`);
+  }
+  const mismatches = [];
+  for (const file of manifest.files) {
+    const expected = sidecar.hashes.get(file.path);
+    if (expected === void 0) continue;
+    const currentSha256 = existsSync20(file.path) ? createHash3("sha256").update(readFileSync15(file.path)).digest("hex") : null;
+    if (currentSha256 !== expected) mismatches.push(file.path);
+  }
+  if (mismatches.length > 0 && !options.force) {
+    throw new UserError(
+      `refusing rollback ${backupId}: current file(s) differ from the state recorded right after promote \u2014 ${mismatches.join(", ")} (pass --force to override)`
+    );
+  }
+  const fileList = manifest.files.map((file) => `  ${file.existed ? "restore" : "delete"} ${file.path}`).join("\n");
+  if (!options.json) {
+    console.log(`[skill-forge] refine rollback ${backupId} \u2014 restoring ${manifest.files.length} file(s):`);
+    console.log(fileList);
+    for (const w of warnings) console.log(`[skill-forge] warning: ${w}`);
+  }
+  const proceed = await confirmWrite(options.yes, options.json, `
+Roll back backup ${backupId}? Affected files:
+${fileList}
+[y/N] `);
+  if (!proceed) {
+    emit(options.json, { rolledBack: false, cancelled: true, backupId }, () => {
+      console.log("[skill-forge] rollback cancelled \u2014 nothing restored.");
+    });
+    return;
+  }
+  const restored = [];
+  for (const file of manifest.files) {
+    try {
+      if (!file.existed) {
+        safeDeleteTombstone(file.path, config);
+      } else {
+        safeRestoreWrite(file.path, Buffer.from(file.contentBase64 ?? "", "base64"), file.mode ?? 420, config);
+      }
+      restored.push(file.path);
+    } catch (err) {
+      const remaining = manifest.files.slice(restored.length + 1).map((f) => f.path);
+      throw new UserError(
+        `rollback ${backupId} failed partway through: restored ${restored.length} of ${manifest.files.length} file(s) (${restored.join(", ") || "(none)"}), then failed on ${file.path}: ${err.message}. NOT restored: ${[file.path, ...remaining].join(", ")}.`
+      );
+    }
+  }
+  const patternsStore = readPatternsStore();
+  const pattern = patternsStore.records.find((p) => p.generalizedBackupId === backupId);
+  if (pattern) {
+    pattern.status = "ready";
+    pattern.generalizedAt = void 0;
+    pattern.generalizedBackupId = void 0;
+    writePatternsStore(patternsStore);
+  }
+  emit(options.json, { rolledBack: true, backupId, patternReset: pattern?.id, warnings }, () => {
+    console.log(`[skill-forge] rollback complete for ${backupId}${pattern ? ` (pattern ${pattern.id} reset to ready)` : ""}`);
+    for (const w of warnings) console.log(`[skill-forge] warning: ${w}`);
+  });
+}
+
+// src/cli.ts
+var require2 = createRequire(import.meta.url);
+var pkg = require2("../package.json");
+function parseArtifact(value) {
+  if (value !== "skill" && value !== "mcp") {
+    throw new UserError(`--artifact must be "skill" or "mcp" (got "${value}")`);
+  }
+  return value;
+}
+function parseLookbackHours(value) {
+  const n = Number(value);
+  if (value.trim() === "" || !Number.isFinite(n) || n < 0) {
+    throw new UserError(`--lookback-hours must be a non-negative number (got "${value}")`);
+  }
+  return n;
+}
+function parseLimit(value) {
+  const n = Number(value);
+  if (value.trim() === "" || !Number.isInteger(n) || n < 1 || n > 50) {
+    throw new UserError(`--limit must be an integer between 1 and 50 (got "${value}")`);
   }
   return n;
 }
@@ -4001,6 +6556,21 @@ program.command("list").description("List skills currently in quarantine").actio
 program.command("status").description("Show skill-forge configuration and quarantine status").action(status);
 program.command("evolve <target-skill-dir>").description("Self-evolve a skill via SkillOpt-Sleep, re-gate the proposal, then promote/hold/reject (Pro)").option("--project <dir>", "project dir passed to SkillOpt-Sleep as --project (defaults to cwd)").option("--dry-run", "SkillOpt-Sleep dry-run: report only, nothing staged").option("--backend <name>", "SkillOpt-Sleep backend (default: mock, offline \u2014 a real backend requires --yes or interactive confirmation)").option("--lookback-hours <n>", "hours of session history for SkillOpt-Sleep to harvest", parseLookbackHours).option("-y, --yes", "skip interactive prompts; honor the re-gate verdict automatically").option("--json", "print the re-gate result as JSON instead of the terminal report").option("--force", "allow re-adopting a staging dir whose proposed content already matches the live skill").action(evolveCommand);
 program.command("audit").alias("doctor").description("Doctor-style health check over the configured skill/MCP set: inventory, hygiene findings, and consolidation/refinement opportunities").option("--json", "print the audit report as JSON instead of the terminal summary (non-interactive: skips the business-profile prompt)").option("-y, --yes", "skip interactive prompts (business profile, foundation, handoff); never implies --foundation or --handoff").option("--report <file>", "write the report to this path instead of the default ~/.skill-forge/reports/audit-<timestamp>.md (refuses an existing path)").option("--foundation", "authorizes exactly one skills-root write: scaffold a business-foundation skill from the captured business profile").option("--handoff", "authorizes launching the configured agent with the bundled curation prompt against the written report").action(auditCommand);
+program.command("organize").description("Build the set-level capability registry + dependency graph across configured skills roots (Pro)").option("--json", "print the registry+graph report as JSON instead of the terminal summary").option("--out <file>", "write the full report JSON to this path (refuses an existing path)").option("--usage-snapshot <file>", "join per-skill usage counts from a skill-monitor snapshot JSON").action(organizeCommand);
+program.command("find [query]").description("Discover skills via skills.sh and check partner security audits (requires VERCEL_OIDC_TOKEN)").option("--limit <n>", "max search results (default 10)", parseLimit).option("--audit <id>", "show partner audit verdicts (Socket/Snyk/\u2026) for a skills.sh id").option("--get <id>", "show detail + file tree for a skills.sh id").option("--curated", "list skills.sh curated skills").option("--json", "print the raw API payload as JSON").action(find);
+program.command("watch").description("Drift check across every SOURCES.md provenance ledger: which ingested upstreams have moved (Pro)").option("--offline", "skip all network checks; list entries for manual comparison only").option("--json", "print the drift report as JSON instead of the terminal summary").action(watchCommand);
+program.command("ingest").description(
+  "Hand the pending-ingestion queue to the configured coding agent for the decide/absorb pass (Pro). For a single new source, use `skill-forge add <source> --ingest` instead."
+).option("--list", "print pending queue entries and exit \u2014 no handoff").option("--json", "with --list: print pending entries as JSON").action(ingest);
+var queue = program.command("queue").description("Manage the pending-ingestion queue (Pro)");
+queue.command("close <id>").description("Close a queue entry after the decide pass \u2014 agents use this instead of hand-editing queue.json").requiredOption("--status <status>", 'final status: "ingested" or "dismissed"').action(queueClose);
+var refine = program.command("refine").description("Capture, apply, and generalize improvements to installed skills from usage feedback (Pro)");
+refine.command("capture", { isDefault: true }).description("Record a refinement and write a project-scope override artifact (never touches the base skill)").option("--skill <name>", "target skill name").option("--category <cat>", "trigger|content|hook|tool|pattern|config|new").option("--target <section>", 'heading path or file the refinement targets, e.g. "Hooks > duplicate-check"').option("--override-type <type>", "patch|extend|config|full|hook|script|new").option("--action <action>", "patch action: append|prepend|replace-section|insert-after|insert-before|delete-section").option("--marker <text>", "marker text for insert-* / replace-section / delete-section (filename for full|hook|script)").option("--content <text>", "override content inline").option("--content-file <file>", "read override content from a file").option("--expected <text>", "expected behavior").option("--actual <text>", "actual observed behavior").option("--example <text>", "concrete example of the gap").option("--outcome <text>", "desired outcome").option("--root-cause <text>", "root cause per the gap analysis").option("--pattern-id <id>", "join an existing pattern (PAT-xxxx) instead of fingerprint matching").option("--scope <scope>", 'where to write the artifact: "local" (.claude/skills, default) or "shared" (./skills)').option("--dry-run", "preview the artifact diff; write nothing").option("--json", "print the result as JSON").option("-y, --yes", "skip the interactive confirm; never implies --handoff").option("--handoff", "authorizes launching the configured agent with the bundled refine prompt").action(refineCaptureCommand);
+refine.command("list").description("Show refinement history from the user-scope store").option("--status <status>", "filter by refinement status").option("--skill <name>", "filter by skill").option("--project <name>", "filter by project").option("--json", "print records as JSON").action(refineListCommand);
+refine.command("patterns").description("Review tracked patterns and the generalization queue").option("--status <status>", "filter: tracking|ready|generalized|dismissed").option("--skill <name>", "filter by affected skill").option("--project <name>", "filter by project").option("--json", "print patterns as JSON").action(refinePatternsCommand);
+refine.command("which <skill>").description("Print override-scope resolution order and which override files exist at each scope").option("--user-root <dir>", "explicit user-scope skills root").option("--json", "print the resolution as JSON").action(refineWhichCommand);
+refine.command("promote <pattern-id>").description("Materialize a READY pattern into the user-scope skill default (backup + manifest first)").option("--force", "promote a pattern that is not READY").option("--dry-run", "preview the user-scope diff; write nothing").option("--user-root <dir>", "explicit user-scope skills root").option("--json", "print the result as JSON").option("-y, --yes", "skip the interactive confirm").action(refinePromoteCommand);
+refine.command("rollback <backup-id>").description("Restore a promotion backup (refuses if files changed since promotion unless --force)").option("--force", "restore even if current files differ from the post-promotion state").option("--json", "print the result as JSON").option("-y, --yes", "skip the interactive confirm").action(refineRollbackCommand);
 program.command("init").description("Detect installed agents and set gate targets, default promotion target, and handoff agent").option("--defaults", "non-interactive: use all detected agents as gate targets, the first as the default target").option("--list", "print detected agent skill roots and exit \u2014 no writes").action(init);
 try {
   await program.parseAsync();