@rhize/skill-forge 0.16.0 → 0.17.0

package/dist/cli.js

@@ -5,7 +5,7 @@ import { Command } from "commander";
 import { createRequire } from "module";
 
 // src/commands/add.ts
-import { join as join21 } from "path";
+import { join as join24 } from "path";
 
 // src/config.ts
 import { chmodSync, existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
@@ -166,6 +166,57 @@ function looksHighEntropy(value) {
   const uniqueChars = new Set(value).size;
   return varietyCount >= 2 && uniqueChars / value.length > 0.4;
 }
+var STACK_TOKENS = /* @__PURE__ */ new Set([
+  "django",
+  "laravel",
+  "springboot",
+  "spring",
+  "quarkus",
+  "csharp",
+  "fsharp",
+  "golang",
+  "go",
+  "kotlin",
+  "python",
+  "perl",
+  "dotnet",
+  "rust",
+  "swift",
+  "react",
+  "vue",
+  "angular",
+  "svelte",
+  "nextjs",
+  "nuxt",
+  "flutter",
+  "dart",
+  "java",
+  "typescript",
+  "php",
+  "ruby",
+  "rails",
+  "fastapi",
+  "nestjs",
+  "express",
+  "node",
+  "deno",
+  "bun",
+  "ios",
+  "android"
+]);
+function isStackSiblingPair(a, b) {
+  const tokensA = a.split("-");
+  const tokensB = b.split("-");
+  if (tokensA.length !== tokensB.length) return false;
+  let diffCount = 0;
+  for (let i = 0; i < tokensA.length; i++) {
+    if (tokensA[i] === tokensB[i]) continue;
+    diffCount++;
+    if (diffCount > 1) return false;
+    if (!STACK_TOKENS.has(tokensA[i]) || !STACK_TOKENS.has(tokensB[i])) return false;
+  }
+  return diffCount === 1;
+}
 
 // src/preferences.ts
 function markAccepted(value) {
@@ -410,7 +461,9 @@ function loadConfig() {
     // Both are repaired on read (invalid/secret-shaped entries dropped) — config.json is a plain
     // file anything can edit, and these render straight into a terminal. See src/preferences.ts.
     preferences: normalizePreferences(parsed.preferences) ?? defaults.preferences,
-    proposedPreferences: normalizeProposals(parsed.proposedPreferences) ?? defaults.proposedPreferences
+    proposedPreferences: normalizeProposals(parsed.proposedPreferences) ?? defaults.proposedPreferences,
+    claudePlugins: parsed.claudePlugins ?? defaults.claudePlugins,
+    usageSnapshotPath: parsed.usageSnapshotPath ?? defaults.usageSnapshotPath
   };
 }
 function saveConfig(config) {
@@ -1099,16 +1152,16 @@ import {
   statSync as statSync6,
   writeFileSync as writeFileSync5
 } from "fs";
-import { basename as basename6, delimiter as delimiter3, extname as extname3, join as join12, resolve as resolvePath2 } from "path";
+import { basename as basename6, delimiter as delimiter3, extname as extname4, join as join12, resolve as resolvePath2, sep as sep2 } from "path";
 
 // src/gate/safety.ts
 import { statSync as statSync4 } from "fs";
 import { execFile } from "child_process";
-import { delimiter as delimiter2, join as join9 } from "path";
+import { delimiter as delimiter2, extname as extname2, join as join9 } from "path";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
 var RM_RF_TARGET_RE = /\brm\s+(?:-[a-z]+\s+)+("[^"]*"|'[^']*'|[^\s;|&)"'`]+)/i;
-function refineRmRf(line) {
+function refineRmRf(line, _ctx) {
   const match = line.match(RM_RF_TARGET_RE);
   if (!match) {
     return { severity: "HIGH", message: "recursive force-delete (rm -rf) with an unparseable target \u2014 verify the path is scoped" };
@@ -1138,12 +1191,41 @@ function refineRmRf(line) {
   }
   return null;
 }
+var DOC_CUE_RE = /\b(never|not|don't|do not|must not|reject|refuse|attack|dangerous|unsafe|avoid|warning)\b/i;
+var DOC_EXTENSIONS = /* @__PURE__ */ new Set([".md", ".mdx", ".markdown"]);
+var NO_FENCES = [];
+function refineCurlPipeShell(line, ctx) {
+  const base = { severity: "CRITICAL", message: "downloads a remote script and pipes it directly into a shell" };
+  if (ctx.inFence) return base;
+  if (!DOC_EXTENSIONS.has(extname2(ctx.file).toLowerCase())) return base;
+  if (!DOC_CUE_RE.test(line)) return base;
+  return { ...base, classification: "documentation-example" };
+}
+function computeFenceFlags(lines) {
+  const flags = new Array(lines.length).fill(false);
+  let closeRe = null;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].replace(/\r$/, "");
+    if (closeRe === null) {
+      const open = line.match(/^\s{0,3}(`{3,}|~{3,})/);
+      if (open) {
+        closeRe = new RegExp(`^\\s{0,3}${open[1][0]}{${open[1].length},}\\s*$`);
+        flags[i] = true;
+      }
+      continue;
+    }
+    flags[i] = true;
+    if (closeRe.test(line)) closeRe = null;
+  }
+  return flags;
+}
 var DENY_RULES = [
   {
     rule: "curl-pipe-shell",
     severity: "CRITICAL",
     pattern: /\b(curl|wget)\b[^\n|]*\|\s*(sudo\s+)?(bash|sh|zsh)\b/i,
-    message: "downloads a remote script and pipes it directly into a shell"
+    message: "downloads a remote script and pipes it directly into a shell",
+    refine: refineCurlPipeShell
   },
   {
     rule: "base64-obfuscated-exec",
@@ -1214,17 +1296,19 @@ function scanStaticRules(targetPath) {
     const content = readTextFile(file);
     if (content === void 0) continue;
     const lines = content.split("\n");
+    const fenceFlags = DOC_EXTENSIONS.has(extname2(file).toLowerCase()) ? computeFenceFlags(lines) : NO_FENCES;
     for (const rule of DENY_RULES) {
       for (let i = 0; i < lines.length; i++) {
         if (rule.pattern.test(lines[i])) {
-          const refined = rule.refine ? rule.refine(lines[i]) : { severity: rule.severity, message: rule.message };
+          const refined = rule.refine ? rule.refine(lines[i], { inFence: fenceFlags[i], file }) : { severity: rule.severity, message: rule.message };
           if (!refined) continue;
           findings.push({
             severity: refined.severity,
             rule: rule.rule,
             file,
             detail: `line ${i + 1}: ${refined.message}`,
-            context: lines[i].trim()
+            context: lines[i].trim(),
+            ...refined.classification ? { classification: refined.classification } : {}
           });
         }
       }
@@ -1279,7 +1363,7 @@ async function scanSafety(targetPath, strictness = DEFAULT_STRICTNESS) {
 
 // src/gate/mcpSafety.ts
 import { statSync as statSync5 } from "fs";
-import { basename as basename4, extname as extname2 } from "path";
+import { basename as basename4, extname as extname3 } from "path";
 function isConfigOrExampleFile(file) {
   const base = basename4(file).toLowerCase();
   if (base.startsWith(".env")) return true;
@@ -1485,7 +1569,7 @@ function scanTextFile(file, content, allowCredentialCheck) {
 function scanFileForMcpFindings(file) {
   const content = readTextFile(file);
   if (content === void 0) return [];
-  if (extname2(file).toLowerCase() === ".json") {
+  if (extname3(file).toLowerCase() === ".json") {
     const parsed = tryParseJson(content);
     if (parsed !== void 0) return scanJsonConfig(file, parsed);
   }
@@ -1523,14 +1607,14 @@ skill skills user claude code based comprehensive enhanced practical including i
 `.split(/\s+/).filter(Boolean)
 );
 var DEFAULT_SET_THRESHOLD = 0.45;
-function splitLimited(text, sep7, maxSplit) {
+function splitLimited(text, sep9, maxSplit) {
   const parts = [];
   let rest = text;
   for (let i = 0; i < maxSplit; i++) {
-    const idx = rest.indexOf(sep7);
+    const idx = rest.indexOf(sep9);
     if (idx === -1) break;
     parts.push(rest.slice(0, idx));
-    rest = rest.slice(idx + sep7.length);
+    rest = rest.slice(idx + sep9.length);
   }
   parts.push(rest);
   return parts;
@@ -1882,7 +1966,14 @@ function proFeatureStatus(feature, betaFree = BETA_FREE) {
 // src/audit.ts
 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, context: f.context }));
+  return source.map((f) => ({
+    severity: f.severity,
+    rule: f.rule,
+    target: f.file,
+    detail: f.detail,
+    context: f.context,
+    ...f.classification ? { classification: f.classification } : {}
+  }));
 }
 function activeVerdictFor(findings, strictness) {
   return verdictFor(
@@ -2034,13 +2125,14 @@ function parseStrictFrontmatter(text) {
 function estimateTokens(text) {
   return Math.ceil(Buffer.byteLength(text, "utf-8") / 4);
 }
-function profileAuditedSkill(group, findings, unreadableSkillMdPaths) {
+function profileAuditedSkill(group, findings, unreadableSkillMdPaths, pluginId) {
   const skillMdPath = join12(group.canonicalPath, "SKILL.md");
   const base = {
     path: group.canonicalPath,
     skillMdPath,
     root: group.root,
-    aliasPaths: group.aliasPaths
+    aliasPaths: group.aliasPaths,
+    pluginId
   };
   let text;
   let sizeBytes;
@@ -2101,7 +2193,7 @@ function enumerateMcpServers(parsed) {
 }
 function auditMcpTarget(targetPath, notices) {
   const findings = [];
-  const isToml = extname3(targetPath).toLowerCase() === ".toml";
+  const isToml = extname4(targetPath).toLowerCase() === ".toml";
   const format = isToml ? "toml" : "json";
   if (!existsSync9(targetPath)) {
     findings.push({
@@ -2209,6 +2301,122 @@ function toClusterMembers(members) {
   }
   return sorted;
 }
+function annotateSiblingClusters(clusters, nameByPath) {
+  return clusters.map((cluster) => {
+    const names = cluster.members.map((p) => nameByPath.get(p) ?? basename6(p));
+    let allSiblings = true;
+    outer: for (let i = 0; i < names.length && allSiblings; i++) {
+      for (let j = i + 1; j < names.length; j++) {
+        if (!isStackSiblingPair(names[i], names[j])) {
+          allSiblings = false;
+          break outer;
+        }
+      }
+    }
+    return allSiblings ? { ...cluster, siblingVariants: true, suggestedVerb: "DEFER" } : cluster;
+  });
+}
+function profilePluginSkills(pluginRoots, findings, unreadableSkillMdPaths) {
+  const skills = [];
+  for (const pr of pluginRoots) {
+    for (const dir of pr.skillDirs) {
+      const group = { realPath: dir, canonicalPath: dir, root: pr.installPath, aliasPaths: [] };
+      skills.push(profileAuditedSkill(group, findings, unreadableSkillMdPaths, pr.pluginId));
+    }
+  }
+  return skills;
+}
+function attachContentHashes(skills) {
+  for (const skill of skills) {
+    try {
+      skill.contentHash = fingerprintTree(skill.path).digest;
+    } catch {
+      skill.contentHash = void 0;
+    }
+  }
+}
+function collapseIdenticalContent(skills, configuredRootOrder) {
+  const byHash = /* @__PURE__ */ new Map();
+  for (const skill of skills) {
+    if (skill.pluginId !== void 0 || skill.contentHash === void 0) continue;
+    const group = byHash.get(skill.contentHash) ?? [];
+    group.push(skill);
+    byHash.set(skill.contentHash, group);
+  }
+  const toRemove = /* @__PURE__ */ new Set();
+  let collapsedCount = 0;
+  for (const group of byHash.values()) {
+    if (group.length < 2) continue;
+    const sorted = [...group].sort((a, b) => {
+      const ai = configuredRootOrder.indexOf(a.root);
+      const bi = configuredRootOrder.indexOf(b.root);
+      if (ai !== bi) return ai - bi;
+      return a.path.localeCompare(b.path);
+    });
+    const canonical = sorted[0];
+    for (const duplicate of sorted.slice(1)) {
+      if (!canonical.aliasPaths.includes(duplicate.path)) canonical.aliasPaths.push(duplicate.path);
+      toRemove.add(duplicate);
+      collapsedCount++;
+    }
+  }
+  return { skills: skills.filter((s) => !toRemove.has(s)), collapsedCount };
+}
+function matchUsage(skill, usage, notices) {
+  if (usage.has(skill.name)) return usage.get(skill.name);
+  if (skill.pluginId) {
+    const composite = `${skill.pluginId.split("@")[0]}:${skill.name}`;
+    if (usage.has(composite)) return usage.get(composite);
+  }
+  const bareMatches = [...usage.keys()].filter((k) => (k.includes(":") ? k.slice(k.lastIndexOf(":") + 1) : k) === skill.name);
+  if (bareMatches.length === 1) return usage.get(bareMatches[0]);
+  if (bareMatches.length > 1) {
+    notices.push(`usage snapshot: ambiguous bare name "${skill.name}" matches ${bareMatches.length} entries \u2014 skipping attribution`);
+  }
+  return void 0;
+}
+function isUnderInstallPath(target, installPath) {
+  return target === installPath || target.startsWith(installPath + sep2);
+}
+function computePluginSummaries(pluginRoots, activeFindings, skills, usage) {
+  return pluginRoots.map((pr) => {
+    const findingCounts = { LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 0 };
+    for (const f of activeFindings) {
+      if (isUnderInstallPath(f.target, pr.installPath)) findingCounts[f.severity]++;
+    }
+    const skillCount = pr.skillDirs.length;
+    const hasUsage = usage !== void 0;
+    const exhaustive = usage?.exhaustive ?? false;
+    const windowDays = usage?.windowDays;
+    const observedSkillCount = hasUsage ? skills.filter((s) => s.pluginId === pr.pluginId && (s.usage ?? 0) > 0).length : void 0;
+    let recommendation;
+    const reasons = [];
+    if (findingCounts.HIGH > 0 || findingCounts.CRITICAL > 0) {
+      recommendation = "review";
+    } else if (exhaustive && windowDays !== void 0 && windowDays >= 28 && skillCount > 0 && observedSkillCount === 0) {
+      recommendation = "unobserved";
+    } else if (exhaustive && (observedSkillCount ?? 0) >= 1) {
+      recommendation = "keep";
+    } else {
+      recommendation = "unknown";
+      if (skillCount === 0) reasons.push("no skills to observe");
+      if (!hasUsage) reasons.push("no usage telemetry");
+      else if (!exhaustive) reasons.push("usage snapshot is not exhaustive (top-50 only)");
+      else if (windowDays === void 0 || windowDays < 28) reasons.push(`window ${windowDays ?? "unknown"} < 28 days`);
+      if (reasons.length === 0) reasons.push("no usage telemetry");
+    }
+    return {
+      pluginId: pr.pluginId,
+      version: pr.version,
+      installPath: pr.installPath,
+      skillCount,
+      findingCounts,
+      observedSkillCount,
+      recommendation,
+      reasons: [...new Set(reasons)].sort()
+    };
+  }).sort((a, b) => a.pluginId.localeCompare(b.pluginId));
+}
 function defaultWhich(cmd) {
   const pathEnv = process.env.PATH ?? "";
   const dirs = pathEnv.split(delimiter3).filter(Boolean);
@@ -2253,10 +2461,16 @@ async function auditConfiguredSet(config, options = {}) {
   const oversizedThreshold = options.oversizedSkillTokens ?? OVERSIZED_SKILL_EST_TOKENS;
   const findings = [];
   const notices = [];
+  const pluginRoots = options.pluginRoots ?? [];
   const { candidates, rootMeta } = collectSkillCandidates(config.skillsRoots);
   const groups = dedupeSkillCandidates(candidates, findings);
   const unreadableSkillMdPaths = /* @__PURE__ */ new Set();
-  const skills = groups.map((g) => profileAuditedSkill(g, findings, unreadableSkillMdPaths));
+  const configuredSkills = groups.map((g) => profileAuditedSkill(g, findings, unreadableSkillMdPaths));
+  const pluginSkills = profilePluginSkills(pluginRoots, findings, unreadableSkillMdPaths);
+  let skills = [...configuredSkills, ...pluginSkills];
+  attachContentHashes(skills);
+  const collapsed = collapseIdenticalContent(skills, config.skillsRoots);
+  skills = collapsed.skills;
   const skillRoots = config.skillsRoots.map((root) => {
     const meta = rootMeta.get(root) ?? { exists: false };
     if (!meta.exists) {
@@ -2273,9 +2487,20 @@ async function auditConfiguredSet(config, options = {}) {
       root,
       realPath: meta.realPath ?? resolveConfiguredRoot(root),
       exists: meta.exists,
-      skillCount: skills.filter((s) => s.root === root).length
+      skillCount: skills.filter((s) => s.root === root).length,
+      origin: "configured"
     };
   });
+  for (const pr of pluginRoots) {
+    skillRoots.push({
+      root: pr.installPath,
+      realPath: pr.installPath,
+      exists: isDir(pr.installPath),
+      skillCount: pr.skillDirs.length,
+      origin: "plugin",
+      pluginId: pr.pluginId
+    });
+  }
   const byName = /* @__PURE__ */ new Map();
   for (const skill of skills) {
     const arr = byName.get(skill.name) ?? [];
@@ -2284,13 +2509,15 @@ async function auditConfiguredSet(config, options = {}) {
   }
   for (const [name, group] of byName) {
     if (group.length > 1) {
+      const isIdenticalPluginPair = group.length === 2 && group.every((s) => s.pluginId !== void 0) && group[0].contentHash !== void 0 && group[0].contentHash === group[1].contentHash;
+      const severity = isIdenticalPluginPair ? "LOW" : "MEDIUM";
       for (const skill of group) {
         const otherPaths = group.filter((g) => g.path !== skill.path).map((g) => g.path);
         findings.push({
-          severity: "MEDIUM",
+          severity,
           rule: "duplicate-skill-name",
           target: skill.path,
-          detail: `name "${name}" is duplicated \u2014 also found at ${otherPaths.join(", ")}`
+          detail: isIdenticalPluginPair ? `identical content shipped by two enabled plugins \u2014 also found at ${otherPaths.join(", ")}` : `name "${name}" is duplicated \u2014 also found at ${otherPaths.join(", ")}`
         });
       }
     }
@@ -2340,9 +2567,10 @@ async function auditConfiguredSet(config, options = {}) {
   if (overlapStatus.enabled) {
     if (overlapStatus.notice) notices.push(overlapStatus.notice);
     try {
-      const readableSkillMdPaths = skills.map((s) => s.skillMdPath).filter((p) => !unreadableSkillMdPaths.has(p));
+      const readableSkillMdPaths = skills.filter((s) => s.pluginId === void 0).map((s) => s.skillMdPath).filter((p) => !unreadableSkillMdPaths.has(p));
       const pairs = scanOverlapPaths(readableSkillMdPaths, options.overlapThreshold);
-      overlapClusters = clusterOverlapPairs(pairs);
+      const nameByPath = new Map(skills.map((s) => [s.skillMdPath, s.name]));
+      overlapClusters = annotateSiblingClusters(clusterOverlapPairs(pairs), nameByPath);
     } catch (err) {
       findings.push({
         severity: "MEDIUM",
@@ -2381,7 +2609,7 @@ async function auditConfiguredSet(config, options = {}) {
   }
   const activeFindingSet = new Set(activeFindings);
   const evolveEligible = skills.filter((s) => {
-    if (!s.validFrontmatter || skillScanFailed.has(s.path)) return false;
+    if (!s.validFrontmatter || skillScanFailed.has(s.path) || s.pluginId !== void 0) return false;
     const skillFindings = perSkillFindings.get(s.path) ?? [];
     const activeSkillFindings = skillFindings.filter((f) => activeFindingSet.has(f));
     return activeVerdictFor(activeSkillFindings, config.strictness) === "pass";
@@ -2394,6 +2622,18 @@ async function auditConfiguredSet(config, options = {}) {
     available: true,
     message: "no business-foundation skill yet \u2014 `skill-forge audit --foundation` can scaffold one to ground future skills in your business profile"
   };
+  const usage = options.usage;
+  if (usage) {
+    for (const skill of skills) {
+      const matched = matchUsage(skill, usage.usage, notices);
+      if (matched !== void 0) skill.usage = matched;
+    }
+  }
+  const usageJoined = usage ? skills.filter((s) => s.usage !== void 0).length : void 0;
+  if (usage && usageJoined === 0) {
+    notices.push(`usage snapshot (${usage.sourcePath}) joined 0 of ${skills.length} skill(s)`);
+  }
+  const unobservedInWindow = usage && usage.exhaustive ? skills.filter((s) => (s.usage ?? 0) === 0).map((s) => ({ name: s.name, path: s.path, pluginId: s.pluginId })) : [];
   const findingCounts = { LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 0 };
   for (const f of activeFindings) findingCounts[f.severity]++;
   const summary = {
@@ -2403,8 +2643,12 @@ async function auditConfiguredSet(config, options = {}) {
     findingCounts,
     overlapClusterCount: overlapClusters.length,
     evolveEligibleCount: evolveEligible.length,
-    acceptedCount: acceptedEntries.length
+    acceptedCount: acceptedEntries.length,
+    collapsedDuplicateCount: collapsed.collapsedCount,
+    documentationExampleCount: activeFindings.filter((f) => f.classification === "documentation-example").length,
+    ...usage ? { usageJoined, usageExhaustive: usage.exhaustive, usageWindowDays: usage.windowDays } : {}
   };
+  const plugins = options.pluginRoots ? computePluginSummaries(pluginRoots, activeFindings, skills, usage) : void 0;
   const tooling = checkTooling(options.which ?? defaultWhich, options.env ?? process.env);
   return {
     schemaVersion: 1,
@@ -2412,10 +2656,11 @@ async function auditConfiguredSet(config, options = {}) {
     inventory: { skillRoots, skills, mcpTargets },
     hygiene: activeFindings,
     accepted: acceptedEntries,
-    opportunities: { overlapClusters, evolveEligible, foundation, overlapLocked: !overlapStatus.enabled },
+    opportunities: { overlapClusters, evolveEligible, foundation, overlapLocked: !overlapStatus.enabled, unobservedInWindow },
     tooling,
     notices,
-    summary
+    summary,
+    plugins
   };
 }
 function bulletList(items, emptyPlaceholder) {
@@ -2432,7 +2677,9 @@ function renderRootsSection(roots) {
     "### Skill roots",
     "",
     ...bulletList(
-      roots.map((r) => `${r.root}${r.exists ? "" : " (MISSING)"} \u2014 ${r.skillCount} skill${r.skillCount === 1 ? "" : "s"}`),
+      roots.map(
+        (r) => `${r.root}${r.exists ? "" : " (MISSING)"} \u2014 ${r.skillCount} skill${r.skillCount === 1 ? "" : "s"}` + (r.origin === "plugin" ? ` (plugin ${sanitizeForMarkdown(r.pluginId ?? "")})` : "")
+      ),
       "(none configured)"
     )
   ];
@@ -2476,17 +2723,17 @@ function renderMcpTargetsSection(targets) {
 function displayFingerprint(f) {
   return f.fingerprint ? f.fingerprint.slice(0, FINGERPRINT_DISPLAY_LENGTH) : "unknown";
 }
+function renderFindingLine(f) {
+  return `[${f.severity}] ${f.rule} \u2014 ${sanitizeForMarkdown(f.target)}: ${sanitizeForMarkdown(f.detail)} (fp ${displayFingerprint(f)})`;
+}
 function renderFindingsSection(findings) {
-  return [
-    "## Hygiene findings",
-    "",
-    ...bulletList(
-      findings.map(
-        (f) => `[${f.severity}] ${f.rule} \u2014 ${sanitizeForMarkdown(f.target)}: ${sanitizeForMarkdown(f.detail)} (fp ${displayFingerprint(f)})`
-      ),
-      "(none \u2014 clean)"
-    )
-  ];
+  const live = findings.filter((f) => f.classification !== "documentation-example");
+  const docExamples = findings.filter((f) => f.classification === "documentation-example");
+  const lines = ["## Hygiene findings", "", ...bulletList(live.map(renderFindingLine), "(none \u2014 clean)")];
+  if (docExamples.length > 0) {
+    lines.push("", "### Probable documentation examples (still CRITICAL \u2014 review)", "", ...bulletList(docExamples.map(renderFindingLine), ""));
+  }
+  return lines;
 }
 function renderAcceptedFindingsSection(entries) {
   return [
@@ -2508,7 +2755,9 @@ function renderOpportunitiesSection(report) {
     "### Overlap clusters",
     "",
     ...bulletList(
-      overlapClusters.map((c) => `top score ${c.topScore} \u2014 ${c.suggestedVerb} \u2014 ${c.members.join(", ")}`),
+      overlapClusters.map(
+        (c) => `top score ${c.topScore} \u2014 ${c.suggestedVerb} \u2014 ${c.members.join(", ")}` + (c.siblingVariants ? " (stack variants \u2014 deliberate siblings, not duplicates)" : "")
+      ),
       "(none \u2014 either no cross-root overlap found, or the Pro feature is locked, see Notices)"
     ),
     "",
@@ -2524,6 +2773,39 @@ function renderOpportunitiesSection(report) {
     `- ${foundation.message}`
   ];
 }
+function renderUsageSection(report) {
+  const { summary } = report;
+  const lines = ["## Usage", ""];
+  lines.push(`- Matched: ${summary.usageJoined ?? 0} of ${summary.skillCount} skill(s)`);
+  lines.push(`- Window: ${summary.usageWindowDays !== void 0 ? `${summary.usageWindowDays} day(s)` : "unknown"}`);
+  if (summary.usageExhaustive) {
+    lines.push("- Coverage: exhaustive (every skill counted this window)");
+  } else {
+    lines.push("- Coverage: top-50 only; absence is not zero usage");
+  }
+  if (report.opportunities.unobservedInWindow.length > 0) {
+    lines.push("", "### Unobserved this window", "");
+    for (const s of report.opportunities.unobservedInWindow) {
+      lines.push(`- ${sanitizeForMarkdown(s.name)} \u2014 ${s.path}${s.pluginId ? ` (plugin ${sanitizeForMarkdown(s.pluginId)})` : ""}`);
+    }
+  }
+  return lines;
+}
+function renderPluginsSection(plugins) {
+  return [
+    "## Plugins",
+    "",
+    ...bulletList(
+      plugins.map((p) => {
+        const findingsPart = `${p.findingCounts.CRITICAL} CRITICAL, ${p.findingCounts.HIGH} HIGH, ${p.findingCounts.MEDIUM} MEDIUM, ${p.findingCounts.LOW} LOW`;
+        const observedPart = p.observedSkillCount !== void 0 ? `, observed ${p.observedSkillCount}` : "";
+        const reasonsPart = p.reasons.length > 0 ? ` (${p.reasons.join("; ")})` : "";
+        return `${sanitizeForMarkdown(p.pluginId)} @ ${sanitizeForMarkdown(p.version)} \u2014 ${sanitizeForMarkdown(p.installPath)} \u2014 ${p.skillCount} skill(s)${observedPart} \u2014 findings: ${findingsPart} \u2014 **${p.recommendation}**${reasonsPart}`;
+      }),
+      "(no enabled plugins)"
+    )
+  ];
+}
 function renderToolingSection(tooling) {
   const lines = ["## Tooling", ""];
   if (!tooling) {
@@ -2560,6 +2842,7 @@ function renderAuditMarkdown(report) {
     `- Accepted: ${summary.acceptedCount} (suppressed from the counts above; see the Accepted findings section)`,
     `- Overlap clusters: ${summary.overlapClusterCount}`,
     `- Evolve-eligible skills: ${summary.evolveEligibleCount}`,
+    `- Collapsed duplicates: ${summary.collapsedDuplicateCount}`,
     "",
     "## Inventory",
     "",
@@ -2575,12 +2858,11 @@ function renderAuditMarkdown(report) {
     "",
     ...renderOpportunitiesSection(report),
     "",
-    ...renderToolingSection(report.tooling),
-    "",
-    "## Notices",
-    "",
-    ...bulletList(report.notices, "(none)")
+    ...renderToolingSection(report.tooling)
   ];
+  if (summary.usageJoined !== void 0) lines.push("", ...renderUsageSection(report));
+  if (report.plugins) lines.push("", ...renderPluginsSection(report.plugins));
+  lines.push("", "## Notices", "", ...bulletList(report.notices, "(none)"));
   return lines.join("\n") + "\n";
 }
 function renderFoundationSkillMd(profile) {
@@ -2811,11 +3093,11 @@ import {
   statSync as statSync7
 } from "fs";
 import { tmpdir } from "os";
-import { basename as basename8, dirname as dirname6, extname as extname5, join as join15, resolve as resolve3 } from "path";
+import { basename as basename8, dirname as dirname6, extname as extname6, join as join15, resolve as resolve3 } from "path";
 
 // src/gate/mcpCapabilities.ts
 import { existsSync as existsSync11, readFileSync as readFileSync11 } from "fs";
-import { extname as extname4, join as join14 } from "path";
+import { extname as extname5, join as join14 } from "path";
 var SOURCE_EXT = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 var MAX_ITEMS_PER_CATEGORY = 200;
 function readJsonSafe(file) {
@@ -2940,7 +3222,7 @@ function extractMcpCapabilities(packageDir) {
   let sawHttpTransport = false;
   let sawMcpSdkImport = false;
   for (const file of walk(packageDir)) {
-    if (!SOURCE_EXT.has(extname4(file))) continue;
+    if (!SOURCE_EXT.has(extname5(file))) continue;
     const text = readTextFile(file);
     if (text === void 0) continue;
     captureRegistrations(text, buckets);
@@ -3078,7 +3360,7 @@ function resolveSkillMd(inputPath) {
   let currentPath = inputPath;
   let tmpDir;
   const initialStat = statSync7(currentPath);
-  if (extname5(currentPath) === ".skill" || initialStat.isFile() && isZipFile(currentPath)) {
+  if (extname6(currentPath) === ".skill" || initialStat.isFile() && isZipFile(currentPath)) {
     tmpDir = mkdtempSync2(join15(tmpdir(), "forge_"));
     extractZip(currentPath, tmpDir);
     currentPath = tmpDir;
@@ -3641,14 +3923,14 @@ function renderSafetyLine(safety) {
   const withDetail = detail ? `${safety.verdict} (${detail})` : safety.verdict;
   return safety.recommendation ? `${withDetail} \u2014 ${safety.recommendation}` : withDetail;
 }
-function renderFindingLine(finding2) {
+function renderFindingLine2(finding2) {
   const severity = finding2.severity ?? "UNKNOWN";
   const rule = finding2.rule ?? "unknown-rule";
   return `  - [${severity}] ${rule}${finding2.message ? `: ${finding2.message}` : ""}`;
 }
 function renderFindingsLines(findings) {
   if (!findings?.length) return [];
-  return [`${padLabel("Findings")}:`, ...findings.map(renderFindingLine)];
+  return [`${padLabel("Findings")}:`, ...findings.map(renderFindingLine2)];
 }
 function profileHeaderFields(profile) {
   if (profile.kind === "mcp") {
@@ -3967,8 +4249,9 @@ function runHandoff(config, installedPath, options = {}) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync17 } from "fs";
-import { homedir as homedir4 } from "os";
+import { existsSync as existsSync18 } from "fs";
+import { homedir as homedir5 } from "os";
+import { join as join23 } from "path";
 import { createInterface as createInterface3 } from "readline/promises";
 
 // src/agents.ts
@@ -4218,12 +4501,12 @@ var AGENTS = [
 ].map(makeAgent);
 
 // src/gitPreflight.ts
-import { relative as relative2, sep as sep2 } from "path";
+import { relative as relative2, sep as sep3 } from "path";
 function splitNulTerminated(output) {
   return output.split("\0").filter((s) => s.length > 0);
 }
 function toPosixPath(p) {
-  return p.split(sep2).join("/");
+  return p.split(sep3).join("/");
 }
 var missingResult = (root) => ({
   root,
@@ -4348,8 +4631,8 @@ function describeGitPreflight(result) {
 }
 
 // src/commands/audit.ts
-import { existsSync as existsSync16 } from "fs";
-import { join as join20, resolve as resolvePath3 } from "path";
+import { existsSync as existsSync17 } from "fs";
+import { join as join22, resolve as resolvePath5 } from "path";
 import { createInterface as createInterface2 } from "readline/promises";
 
 // src/decision.ts
@@ -4381,8 +4664,325 @@ ${prompt}`);
   }
 }
 
+// src/pluginRoots.ts
+import { existsSync as existsSync16, readFileSync as readFileSync16, readdirSync as readdirSync8, realpathSync as realpathSync3 } from "fs";
+import { homedir as homedir4 } from "os";
+import { isAbsolute as isAbsolute3, join as join20, relative as relative3, resolve as resolvePath3, sep as sep4 } from "path";
+function readJsonFileSafe(path) {
+  let raw;
+  try {
+    raw = readFileSync16(path, "utf-8");
+  } catch (err) {
+    return { problem: err.code === "ENOENT" ? "missing" : "unreadable" };
+  }
+  try {
+    return { data: JSON.parse(raw) };
+  } catch {
+    return { problem: "malformed" };
+  }
+}
+function describeProblem(problem, path) {
+  const verb = problem === "missing" ? "not found" : problem === "unreadable" ? "unreadable" : "malformed (invalid JSON)";
+  return `${path} ${verb}`;
+}
+function extractEnabledMap(data) {
+  if (typeof data !== "object" || data === null) return {};
+  const raw = data.enabledPlugins;
+  if (typeof raw !== "object" || raw === null) return {};
+  const out = {};
+  for (const [id, value] of Object.entries(raw)) {
+    if (typeof value === "boolean") out[id] = value;
+  }
+  return out;
+}
+function extractRegistry(data) {
+  if (typeof data !== "object" || data === null) return {};
+  const pluginsRaw = data.plugins;
+  if (typeof pluginsRaw !== "object" || pluginsRaw === null) return {};
+  const out = {};
+  for (const [id, entriesRaw] of Object.entries(pluginsRaw)) {
+    if (!Array.isArray(entriesRaw)) continue;
+    const entries = [];
+    for (const raw of entriesRaw) {
+      if (typeof raw !== "object" || raw === null) continue;
+      const rec = raw;
+      const scope = rec.scope;
+      const installPath = rec.installPath;
+      const version = rec.version;
+      if ((scope === "user" || scope === "project" || scope === "local") && typeof installPath === "string" && typeof version === "string") {
+        entries.push({
+          scope,
+          projectPath: typeof rec.projectPath === "string" ? rec.projectPath : void 0,
+          installPath,
+          version
+        });
+      }
+    }
+    if (entries.length > 0) out[id] = entries;
+  }
+  return out;
+}
+function splitPluginId(id) {
+  const idx = id.lastIndexOf("@");
+  if (idx === -1) return { plugin: id, marketplace: "" };
+  return { plugin: id.slice(0, idx), marketplace: id.slice(idx + 1) };
+}
+function safeRealpath(p) {
+  try {
+    return realpathSync3(p);
+  } catch {
+    return void 0;
+  }
+}
+function parseSemver(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
+  if (!m) return void 0;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function compareVersionsDesc(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (pa && pb) {
+    for (let i = 0; i < 3; i++) {
+      if (pa[i] !== pb[i]) return pb[i] - pa[i];
+    }
+    return b.localeCompare(a);
+  }
+  if (pa && !pb) return -1;
+  if (!pa && pb) return 1;
+  return b.localeCompare(a);
+}
+function selectInstallEntry(entries, cwd) {
+  const userEntry = entries.find((e) => e.scope === "user");
+  if (userEntry) return userEntry;
+  const cwdReal = safeRealpath(cwd);
+  if (cwdReal) {
+    const projectEntry = entries.find((e) => e.scope === "project" && e.projectPath && safeRealpath(e.projectPath) === cwdReal);
+    if (projectEntry) return projectEntry;
+  }
+  return [...entries].sort((a, b) => compareVersionsDesc(a.version, b.version))[0];
+}
+function isInside2(child, root) {
+  if (child === root) return true;
+  const rel = relative3(root, child);
+  return rel !== "" && !rel.startsWith(".." + sep4) && rel !== ".." && !isAbsolute3(rel);
+}
+var DEFAULT_SKILL_LAYOUT = { paths: ["./skills/"], explicit: false };
+function normalizeDeclaredSkillsField(manifest, pluginId, notices) {
+  if (typeof manifest !== "object" || manifest === null) return DEFAULT_SKILL_LAYOUT;
+  const skillsField = manifest.skills;
+  if (skillsField === void 0) return DEFAULT_SKILL_LAYOUT;
+  if (typeof skillsField === "string") return { paths: [skillsField], explicit: true };
+  if (Array.isArray(skillsField) && skillsField.every((s) => typeof s === "string")) return { paths: skillsField, explicit: true };
+  notices.push(`plugin ${pluginId}: manifest "skills" field has an unrecognized shape \u2014 using default skill layout`);
+  return DEFAULT_SKILL_LAYOUT;
+}
+function resolveDeclaredPath(installPath, realInstall, declaredPath, explicit, pluginId, notices) {
+  const joined = resolvePath3(installPath, declaredPath);
+  let real;
+  try {
+    real = realpathSync3(joined);
+  } catch {
+    if (explicit) notices.push(`plugin ${pluginId}: declared skill path does not exist, skipping: ${declaredPath}`);
+    return [];
+  }
+  if (!realInstall || !isInside2(real, realInstall)) {
+    notices.push(`plugin ${pluginId}: declared skill path escapes the install root, skipping: ${declaredPath}`);
+    return [];
+  }
+  if (existsSync16(join20(real, "SKILL.md"))) return [real];
+  let entries;
+  try {
+    entries = readdirSync8(real, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const found = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const childPath = join20(real, entry.name);
+    if (existsSync16(join20(childPath, "SKILL.md"))) found.push(childPath);
+  }
+  return found;
+}
+function resolveSkillDirs(installPath, pluginId) {
+  const notices = [];
+  const manifestPath = join20(installPath, ".claude-plugin", "plugin.json");
+  const manifestResult = readJsonFileSafe(manifestPath);
+  if (manifestResult.problem) {
+    notices.push(`plugin ${pluginId}: ${manifestResult.problem} manifest at ${manifestPath} \u2014 using default skill layout`);
+  }
+  const declared = manifestResult.problem ? DEFAULT_SKILL_LAYOUT : normalizeDeclaredSkillsField(manifestResult.data, pluginId, notices);
+  const realInstall = safeRealpath(installPath);
+  const skillDirs = /* @__PURE__ */ new Set();
+  for (const declaredPath of declared.paths) {
+    for (const dir of resolveDeclaredPath(installPath, realInstall, declaredPath, declared.explicit, pluginId, notices)) {
+      skillDirs.add(dir);
+    }
+  }
+  return { skillDirs: Array.from(skillDirs).sort(), notices };
+}
+function discoverClaudePluginRoots(options = {}) {
+  const homeDir = options.homeDir ?? homedir4();
+  const cwd = options.cwd ?? process.cwd();
+  const settingsPath = options.settingsPath ?? join20(homeDir, ".claude", "settings.json");
+  const localSettingsPath = options.localSettingsPath ?? join20(cwd, ".claude", "settings.local.json");
+  const installedPluginsPath = options.installedPluginsPath ?? join20(homeDir, ".claude", "plugins", "installed_plugins.json");
+  const notices = [];
+  const settingsResult = readJsonFileSafe(settingsPath);
+  if (settingsResult.problem) {
+    notices.push(`Claude Code settings ${describeProblem(settingsResult.problem, settingsPath)} \u2014 skipping Claude plugin discovery`);
+    return { roots: [], notices };
+  }
+  const registryResult = readJsonFileSafe(installedPluginsPath);
+  if (registryResult.problem) {
+    notices.push(`Claude Code plugin registry ${describeProblem(registryResult.problem, installedPluginsPath)} \u2014 skipping Claude plugin discovery`);
+    return { roots: [], notices };
+  }
+  const globalEnabled = extractEnabledMap(settingsResult.data);
+  let localEnabled = {};
+  if (existsSync16(localSettingsPath)) {
+    const localResult = readJsonFileSafe(localSettingsPath);
+    if (localResult.problem) {
+      notices.push(`local settings ${describeProblem(localResult.problem, localSettingsPath)} \u2014 ignoring local plugin overrides`);
+    } else {
+      localEnabled = extractEnabledMap(localResult.data);
+    }
+  }
+  const merged = { ...globalEnabled, ...localEnabled };
+  const enabledIds = Object.keys(merged).filter((id) => merged[id] === true).sort();
+  const registry = extractRegistry(registryResult.data);
+  const roots = [];
+  for (const id of enabledIds) {
+    const entries = registry[id];
+    if (!entries || entries.length === 0) {
+      notices.push(`plugin ${id} is enabled but has no installed_plugins.json entry \u2014 skipping`);
+      continue;
+    }
+    const entry = selectInstallEntry(entries, cwd);
+    const { plugin, marketplace } = splitPluginId(id);
+    const { skillDirs, notices: manifestNotices } = resolveSkillDirs(entry.installPath, id);
+    notices.push(...manifestNotices);
+    roots.push({ pluginId: id, marketplace, plugin, version: entry.version, installPath: entry.installPath, skillDirs });
+  }
+  roots.sort((a, b) => a.pluginId.localeCompare(b.pluginId));
+  return { roots, notices };
+}
+
+// src/usageSnapshot.ts
+import { readFileSync as readFileSync17, readdirSync as readdirSync9 } from "fs";
+import { extname as extname7, join as join21, resolve as resolvePath4 } from "path";
+function emptySnapshot(sourcePath, warning) {
+  return { usage: /* @__PURE__ */ new Map(), exhaustive: false, sourcePath, warning };
+}
+function parseSnapshotFile(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { error: `could not parse usage snapshot (${err.message})` };
+  }
+  const outer = parsed && typeof parsed === "object" ? parsed : void 0;
+  const report = outer && typeof outer.report === "object" && outer.report !== null ? outer.report : void 0;
+  if (!report) return { error: 'usage snapshot has no "report" object' };
+  const generatedAt = typeof report.generated_at === "string" ? report.generated_at : void 0;
+  const windowDays = typeof report.window_days === "number" ? report.window_days : void 0;
+  const uniqueSkillsUsed = typeof report.unique_skills_used === "number" ? report.unique_skills_used : void 0;
+  const skillTotals = report.skill_totals && typeof report.skill_totals === "object" ? report.skill_totals : void 0;
+  const topSkills = Array.isArray(report.top_skills) ? report.top_skills : void 0;
+  const usage = /* @__PURE__ */ new Map();
+  if (skillTotals) {
+    for (const [name, count] of Object.entries(skillTotals)) {
+      if (typeof count === "number") usage.set(name, count);
+    }
+  } else if (topSkills) {
+    for (const row of topSkills) {
+      if (Array.isArray(row) && row.length === 2 && typeof row[0] === "string" && typeof row[1] === "number") {
+        usage.set(row[0], row[1]);
+      }
+    }
+  }
+  const exhaustive = Boolean(skillTotals) || topSkills !== void 0 && uniqueSkillsUsed !== void 0 && topSkills.length === uniqueSkillsUsed;
+  return { usage, exhaustive, windowDays, generatedAt };
+}
+function pickLatest(candidates) {
+  return candidates.reduce((best, cur) => {
+    if (!best) return cur;
+    if (cur.generatedAt === void 0 && best.generatedAt === void 0) return cur.path > best.path ? cur : best;
+    if (cur.generatedAt === void 0) return best;
+    if (best.generatedAt === void 0) return cur;
+    if (cur.generatedAt === best.generatedAt) return cur.path > best.path ? cur : best;
+    return cur.generatedAt > best.generatedAt ? cur : best;
+  }, void 0);
+}
+function loadUsageSnapshot(pathOrDir, opts = {}) {
+  const resolved = resolvePath4(expandHome(pathOrDir));
+  if (isDir(resolved)) {
+    let entries;
+    try {
+      entries = readdirSync9(resolved).filter((f) => extname7(f).toLowerCase() === ".json");
+    } catch (err) {
+      return emptySnapshot(resolved, `could not read usage snapshot directory (${err.message})`);
+    }
+    if (entries.length === 0) {
+      return emptySnapshot(resolved, `no *.json snapshot files found in ${resolved}`);
+    }
+    const candidates = [];
+    for (const name of entries) {
+      const filePath = join21(resolved, name);
+      let raw3;
+      try {
+        raw3 = readFileSync17(filePath, "utf-8");
+      } catch {
+        continue;
+      }
+      const parsed3 = parseSnapshotFile(raw3);
+      if ("error" in parsed3) continue;
+      if (opts.windowDays !== void 0 && parsed3.windowDays !== opts.windowDays) continue;
+      candidates.push({ path: filePath, generatedAt: parsed3.generatedAt });
+    }
+    const picked = pickLatest(candidates);
+    if (!picked) {
+      return emptySnapshot(
+        resolved,
+        opts.windowDays !== void 0 ? `no usage snapshot in ${resolved} matches --usage-window ${opts.windowDays}` : `no readable usage snapshot found in ${resolved}`
+      );
+    }
+    const raw2 = readFileSync17(picked.path, "utf-8");
+    const parsed2 = parseSnapshotFile(raw2);
+    if ("error" in parsed2) return emptySnapshot(picked.path, parsed2.error);
+    return { usage: parsed2.usage, exhaustive: parsed2.exhaustive, windowDays: parsed2.windowDays, generatedAt: parsed2.generatedAt, sourcePath: picked.path };
+  }
+  let raw;
+  try {
+    raw = readFileSync17(resolved, "utf-8");
+  } catch (err) {
+    return emptySnapshot(resolved, `could not read usage snapshot (${err.message})`);
+  }
+  const parsed = parseSnapshotFile(raw);
+  if ("error" in parsed) return emptySnapshot(resolved, parsed.error);
+  return { usage: parsed.usage, exhaustive: parsed.exhaustive, windowDays: parsed.windowDays, generatedAt: parsed.generatedAt, sourcePath: resolved };
+}
+
 // src/commands/audit.ts
 var CURATION_PROMPT_ASSET = "curation-prompt.md";
+function resolvePluginAndUsageContext(config, options, deps = {}) {
+  if (options.usageWindow !== void 0 && (!Number.isInteger(options.usageWindow) || options.usageWindow < 1)) {
+    throw new UserError(`--usage-window must be a positive integer (got "${options.usageWindow}")`);
+  }
+  const wantPlugins = options.claudePlugins ?? config.claudePlugins ?? false;
+  let pluginRoots;
+  const notices = [];
+  if (wantPlugins) {
+    const discovered = discoverClaudePluginRoots(deps);
+    pluginRoots = discovered.roots;
+    notices.push(...discovered.notices);
+  }
+  const usageSnapshotPath = options.usageSnapshot ?? config.usageSnapshotPath;
+  const usage = usageSnapshotPath ? loadUsageSnapshot(usageSnapshotPath, { windowDays: options.usageWindow }) : void 0;
+  if (usage?.warning) notices.push(usage.warning);
+  return { pluginRoots, usage, notices };
+}
 function splitCsv(s) {
   return s.split(",").map((x) => x.trim()).filter(Boolean);
 }
@@ -4415,11 +5015,16 @@ async function captureBusinessProfile(rl, existing) {
   return profile;
 }
 function resolveReportPath(reportOption) {
-  if (reportOption) return resolvePath3(reportOption);
+  if (reportOption) return resolvePath5(reportOption);
   const iso = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  return join20(getHomeDir(), "reports", `audit-${iso}.md`);
+  return join22(getHomeDir(), "reports", `audit-${iso}.md`);
 }
-function printTerminalSummary(report, reportPath) {
+function summarizePluginRecommendations(plugins) {
+  const counts = { keep: 0, review: 0, unobserved: 0, unknown: 0 };
+  for (const p of plugins) counts[p.recommendation]++;
+  return `plugins: ${plugins.length} (review ${counts.review}, unobserved ${counts.unobserved}, unknown ${counts.unknown})`;
+}
+function printTerminalSummary(report, reportPath, usage) {
   const { summary } = report;
   console.log("[skill-forge] audit complete");
   console.log(`  skill roots: ${summary.rootCount}  skills: ${summary.skillCount}  MCP targets: ${summary.mcpTargetCount}`);
@@ -4428,6 +5033,12 @@ function printTerminalSummary(report, reportPath) {
   );
   console.log(`  accepted: ${summary.acceptedCount} (suppressed from counts; see report)`);
   console.log(`  overlap clusters: ${summary.overlapClusterCount}  evolve-eligible: ${summary.evolveEligibleCount}`);
+  if (report.plugins) console.log(`  ${summarizePluginRecommendations(report.plugins)}`);
+  if (usage) {
+    console.log(
+      `  usage: ${usage.sourcePath} (window ${usage.windowDays !== void 0 ? `${usage.windowDays} day(s)` : "unknown"}, ${usage.exhaustive ? "exhaustive" : "top-50 only"})`
+    );
+  }
   console.log(`  report -> ${reportPath}`);
   for (const notice of report.notices) console.log(`  [notice] ${notice}`);
   console.log(
@@ -4465,9 +5076,9 @@ async function maybeHandoff(config, reportPath, options, rl) {
   if (!wantHandoff) return;
   runHandoff(config, reportPath, { promptAsset: CURATION_PROMPT_ASSET, log: options.json ? console.error : console.log });
 }
-async function auditCommand(options = {}) {
+async function auditCommand(options = {}, deps = {}) {
   await maybeOfferInit({ json: options.json, yes: options.yes, suppressAuditOffer: true });
-  if (!existsSync16(getConfigPath())) {
+  if (!existsSync17(getConfigPath())) {
     throw new UserError(
       "no skill-forge config found \u2014 run `skill-forge init` first (audit requires a configured skill/MCP set; it never audits an invented default)."
     );
@@ -4483,9 +5094,11 @@ async function auditCommand(options = {}) {
         saveConfig(config);
       }
     }
+    const { pluginRoots, usage, notices: pluginUsageNotices } = resolvePluginAndUsageContext(config, options, deps);
     const { records: accepted, notices: storeNotices } = readAcceptedFindings();
-    const report = await auditConfiguredSet(config, { accepted });
-    if (storeNotices.length > 0) report.notices = [...report.notices, ...storeNotices];
+    const report = await auditConfiguredSet(config, { accepted, pluginRoots, usage });
+    const extraNotices = [...storeNotices, ...pluginUsageNotices];
+    if (extraNotices.length > 0) report.notices = [...report.notices, ...extraNotices];
     const reportPath = resolveReportPath(options.report);
     writeNewFile(reportPath, renderAuditMarkdown(report), "--report");
     try {
@@ -4496,7 +5109,7 @@ async function auditCommand(options = {}) {
     if (options.json) {
       console.log(JSON.stringify(report, null, 2));
     } else {
-      printTerminalSummary(report, reportPath);
+      printTerminalSummary(report, reportPath, usage);
     }
     config = await maybeScaffoldFoundation(config, report, options, rl);
     await maybeHandoff(config, reportPath, options, rl);
@@ -4613,7 +5226,7 @@ function printMcpDetectionResults(detectedMcp) {
 function handoffTemplateFor(agent) {
   return agent.defaultHandoffTemplate ?? [agent.id, "-p", HANDOFF_INSTRUCTION];
 }
-function buildConfig(selected, defaultTargetEntry, handoffAgent, selectedMcp = []) {
+function buildConfig(selected, defaultTargetEntry, handoffAgent, selectedMcp = [], claudePlugins) {
   const existing = loadConfig();
   return {
     ...existing,
@@ -4625,7 +5238,8 @@ function buildConfig(selected, defaultTargetEntry, handoffAgent, selectedMcp = [
     agents: selected.length > 0 ? selected.flatMap((s) => s.members.map((m) => ({ id: m.agent.id, skillsRoot: s.root }))) : existing.agents,
     defaultTarget: defaultTargetEntry?.root ?? existing.defaultTarget,
     handoffCommand: handoffAgent ? handoffTemplateFor(handoffAgent) : existing.handoffCommand,
-    mcpTargets: selectedMcp.length > 0 ? selectedMcp.map((m) => m.path) : existing.mcpTargets
+    mcpTargets: selectedMcp.length > 0 ? selectedMcp.map((m) => m.path) : existing.mcpTargets,
+    claudePlugins: claudePlugins !== void 0 ? claudePlugins : existing.claudePlugins
   };
 }
 async function printSummary(config, deps = {}) {
@@ -4790,7 +5404,7 @@ async function init(options = {}, deps = {}) {
   const runAudit = deps.runAudit ?? auditCommand;
   const gitDeps = deps.gitExec ? { exec: deps.gitExec } : {};
   const cwd = options.cwd ?? process.cwd();
-  const home = options.home ?? homedir4();
+  const home = options.home ?? homedir5();
   const detected = detectAgents(cwd, home, options.pathEnv);
   const detectedMcp = detectMcpTargets(cwd, home, options.pathEnv);
   if (options.list) {
@@ -4813,10 +5427,18 @@ async function init(options = {}, deps = {}) {
       "[skill-forge] No detected agent CLI was found on PATH \u2014 keeping every detected target selected."
     );
   }
+  const installedPluginsPath = options.installedPluginsPath ?? join23(home, ".claude", "plugins", "installed_plugins.json");
+  const claudePluginsRegistryExists = existsSync18(installedPluginsPath);
   if (options.defaults) {
     const selectedRoots = narrow ? rootGroups.filter(hasInstalledMember) : rootGroups;
     const selectedMcpTargets = narrow ? mcpGroups.filter(hasInstalledMember) : mcpGroups;
-    const config = buildConfig(selectedRoots, selectedRoots[0], void 0, selectedMcpTargets);
+    const config = buildConfig(
+      selectedRoots,
+      selectedRoots[0],
+      void 0,
+      selectedMcpTargets,
+      claudePluginsRegistryExists ? true : void 0
+    );
     saveConfig(config);
     await printSummary(config, gitDeps);
     await runAudit({ yes: true });
@@ -4840,7 +5462,12 @@ async function init(options = {}, deps = {}) {
     const target = selected.length > 0 ? await promptDefaultTarget(rl, selected) : void 0;
     const handoffAgent = detected.length > 0 ? await promptHandoffAgent(rl, detected, narrow) : void 0;
     await promptGitPreflight(rl, selected, gitDeps);
-    const config = buildConfig(selected, target, handoffAgent, selectedMcp);
+    let claudePluginsAnswer;
+    if (claudePluginsRegistryExists) {
+      const answer = (await rl.question("\nInclude enabled Claude Code plugins in audits? [Y/n] ")).trim().toLowerCase();
+      claudePluginsAnswer = answer === "" || answer === "y" || answer === "yes";
+    }
+    const config = buildConfig(selected, target, handoffAgent, selectedMcp, claudePluginsAnswer);
     saveConfig(config);
     await printSummary(config, gitDeps);
     if (options.offerAudit !== false) {
@@ -4860,7 +5487,7 @@ async function init(options = {}, deps = {}) {
 }
 async function maybeOfferInit(options = {}) {
   if (options.json || options.yes || !process.stdin.isTTY) return;
-  if (existsSync17(getConfigPath())) return;
+  if (existsSync18(getConfigPath())) return;
   console.log(
     "[skill-forge] No config found \u2014 run `skill-forge init` to detect your agents and set gate targets (init finishes with a `skill-forge audit` health check over what it just configured)."
   );
@@ -5011,7 +5638,7 @@ async function addMcp(source, config, options) {
       envVars: detail.env ? Object.keys(detail.env) : void 0,
       candidateEntry: detail.command ? { command: detail.command, args: detail.args, env: detail.env } : void 0
     };
-    const mcpTargetPath = options.mcpTarget ?? config.mcpTargets?.[0] ?? join21(process.cwd(), ".mcp.json");
+    const mcpTargetPath = options.mcpTarget ?? config.mcpTargets?.[0] ?? join24(process.cwd(), ".mcp.json");
     const result = promoteMcp(entry, serverProfile, mcpTargetPath, { force: options.force });
     reject(entry);
     logOutcome(`[skill-forge] promoted -> ${result.target} (server "${result.serverName}")`, options.json);
@@ -5107,7 +5734,7 @@ async function scan(source, options = {}) {
 }
 
 // src/commands/list.ts
-import { join as join22 } from "path";
+import { join as join25 } from "path";
 async function list() {
   await maybeOfferInit();
   const config = loadConfig();
@@ -5120,14 +5747,14 @@ async function list() {
   }
   console.log(`[skill-forge] ${ids.length} held in quarantine (${quarantineDir}):`);
   for (const id of ids) {
-    const skillDirs = findSkillDirs(join22(quarantineDir, id));
+    const skillDirs = findSkillDirs(join25(quarantineDir, id));
     if (skillDirs.length === 0) {
       console.log(`  ${id}  (no SKILL.md found)`);
       continue;
     }
     const names = skillDirs.map((dir) => {
       try {
-        return readFrontmatter(join22(dir, "SKILL.md")).name;
+        return readFrontmatter(join25(dir, "SKILL.md")).name;
       } catch {
         return dir;
       }
@@ -5137,23 +5764,23 @@ async function list() {
 }
 
 // src/commands/guide.ts
-import { existsSync as existsSync19 } from "fs";
+import { existsSync as existsSync20 } from "fs";
 
 // src/commands/held.ts
-import { existsSync as existsSync18, realpathSync as realpathSync3 } from "fs";
-import { basename as basename9, join as join23, resolve as resolvePath4, sep as sep3 } from "path";
+import { existsSync as existsSync19, realpathSync as realpathSync4 } from "fs";
+import { basename as basename9, join as join26, resolve as resolvePath6, sep as sep5 } from "path";
 var PRO_FEATURE_LABEL2 = "overlap analysis, the provenance ledger, and the pending-ingestion queue";
 function resolveHeldPath(quarantineDir, id) {
   if (id === "" || id !== basename9(id) || id === "." || id === "..") {
     throw new UserError(`invalid quarantine id "${id}" \u2014 pass a single id exactly as printed by \`skill-forge list\``);
   }
-  const candidate = join23(quarantineDir, id);
-  if (!existsSync18(candidate)) {
+  const candidate = join26(quarantineDir, id);
+  if (!existsSync19(candidate)) {
     throw new UserError(`no held entry with id "${id}" \u2014 run \`skill-forge list\` to see what is in quarantine`);
   }
-  const realRoot = realpathSync3(resolvePath4(quarantineDir));
-  const realCandidate = realpathSync3(candidate);
-  if (!realCandidate.startsWith(realRoot + sep3)) {
+  const realRoot = realpathSync4(resolvePath6(quarantineDir));
+  const realCandidate = realpathSync4(candidate);
+  if (!realCandidate.startsWith(realRoot + sep5)) {
     throw new UserError(`refusing to act on "${id}": it resolves outside the quarantine dir (${realRoot})`);
   }
   return realCandidate;
@@ -5176,7 +5803,7 @@ function resolveTargetRoot(config, target) {
 function heldSkillNames(skillDirs) {
   return skillDirs.map((dir) => {
     try {
-      return readFrontmatter(join23(dir, "SKILL.md")).name;
+      return readFrontmatter(join26(dir, "SKILL.md")).name;
     } catch {
       return basename9(dir);
     }
@@ -5184,7 +5811,7 @@ function heldSkillNames(skillDirs) {
 }
 function looksLikeMcpSandbox(quarantinePath) {
   const candidate = resolveMcpCandidatePath({ quarantinePath });
-  return [".mcp.json", "mcp.json", "package.json"].some((f) => existsSync18(join23(candidate, f)));
+  return [".mcp.json", "mcp.json", "package.json"].some((f) => existsSync19(join26(candidate, f)));
 }
 async function promoteHeldMcp(id, entry, config, options) {
   const candidatePath = resolveMcpCandidatePath(entry);
@@ -5218,7 +5845,7 @@ async function promoteHeldMcp(id, entry, config, options) {
     envVars: detail.env ? Object.keys(detail.env) : void 0,
     candidateEntry: detail.command ? { command: detail.command, args: detail.args, env: detail.env } : void 0
   };
-  const mcpTargetPath = options.mcpTarget ?? config.mcpTargets?.[0] ?? join23(process.cwd(), ".mcp.json");
+  const mcpTargetPath = options.mcpTarget ?? config.mcpTargets?.[0] ?? join26(process.cwd(), ".mcp.json");
   const result = promoteMcp(entry, serverProfile, mcpTargetPath, { force: options.force });
   reject(entry);
   logOutcome(`[skill-forge] promoted -> ${result.target} (server "${result.serverName}")`, options.json);
@@ -5463,7 +6090,7 @@ var TOPICS = [
 ];
 function readState() {
   const configPath = getConfigPath();
-  const configured = existsSync19(configPath);
+  const configured = existsSync20(configPath);
   const base = {
     configured,
     configPath,
@@ -5697,17 +6324,17 @@ async function status() {
 // src/evolve.ts
 import { createInterface as createInterface5 } from "readline/promises";
 import { createHash as createHash3 } from "crypto";
-import { cpSync as cpSync3, existsSync as existsSync20, lstatSync as lstatSync4, mkdtempSync as mkdtempSync3, readFileSync as readFileSync16, rmSync as rmSync6 } from "fs";
+import { cpSync as cpSync3, existsSync as existsSync21, lstatSync as lstatSync4, mkdtempSync as mkdtempSync3, readFileSync as readFileSync18, rmSync as rmSync6 } from "fs";
 import { tmpdir as tmpdir2 } from "os";
-import { basename as basename10, dirname as dirname9, join as join24, resolve as resolvePath5, sep as sep4 } from "path";
+import { basename as basename10, dirname as dirname9, join as join27, resolve as resolvePath7, sep as sep6 } from "path";
 var SKILLOPT_BIN = "skillopt-sleep";
 var PRO_FEATURE_LABEL3 = "self-evolution via SkillOpt-Sleep (evolve) \u2014 re-gating, provenance, and the pending-ingestion queue";
 async function evolve(targetSkillDir, options = {}, deps = {}) {
   const exec = deps.exec ?? defaultExec;
   const json = options.json;
-  const resolvedTargetDir = resolvePath5(targetSkillDir);
-  const skillMdPath = join24(resolvedTargetDir, "SKILL.md");
-  if (!existsSync20(skillMdPath)) {
+  const resolvedTargetDir = resolvePath7(targetSkillDir);
+  const skillMdPath = join27(resolvedTargetDir, "SKILL.md");
+  if (!existsSync21(skillMdPath)) {
     throw new UserError(`no SKILL.md found at ${skillMdPath} \u2014 evolve requires an existing, installed skill directory`);
   }
   const proStatus = proFeatureStatus(PRO_FEATURE_LABEL3);
@@ -5734,7 +6361,7 @@ async function evolve(targetSkillDir, options = {}, deps = {}) {
   } else {
     notices.push('using the offline "mock" backend \u2014 deterministic, no network calls, no session data leaves this machine.');
   }
-  const project = resolvePath5(options.project ?? process.cwd());
+  const project = resolvePath7(options.project ?? process.cwd());
   const present = await detectSkillopt(exec, project);
   if (!present) {
     throw new UserError(
@@ -5765,33 +6392,33 @@ async function evolve(targetSkillDir, options = {}, deps = {}) {
     }
     return;
   }
-  const stagingRoot = join24(project, ".skillopt-sleep", "staging");
-  const stagingDir = resolvePath5(parsed.staging_dir);
-  if (stagingDir !== stagingRoot && !stagingDir.startsWith(stagingRoot + sep4)) {
+  const stagingRoot = join27(project, ".skillopt-sleep", "staging");
+  const stagingDir = resolvePath7(parsed.staging_dir);
+  if (stagingDir !== stagingRoot && !stagingDir.startsWith(stagingRoot + sep6)) {
     throw new UserError(
       `skillopt-sleep reported a staging_dir outside the expected sandbox (${stagingRoot}): ${stagingDir} \u2014 refusing to use it`
     );
   }
-  const proposedSkillMd = join24(stagingDir, "proposed_SKILL.md");
-  const proposedClaudeMd = join24(stagingDir, "proposed_CLAUDE.md");
-  const reportMdPath = join24(stagingDir, "report.md");
-  if (!existsSync20(proposedSkillMd)) {
+  const proposedSkillMd = join27(stagingDir, "proposed_SKILL.md");
+  const proposedClaudeMd = join27(stagingDir, "proposed_CLAUDE.md");
+  const reportMdPath = join27(stagingDir, "report.md");
+  if (!existsSync21(proposedSkillMd)) {
     throw new UserError(`skillopt-sleep reported an accepted proposal but ${proposedSkillMd} is missing`);
   }
-  if (existsSync20(reportMdPath)) {
+  if (existsSync21(reportMdPath)) {
     notices.push(`SkillOpt-Sleep's full report: ${reportMdPath}`);
   }
   assertNotSymlink(proposedSkillMd, "proposed_SKILL.md");
   assertNotSymlink(proposedClaudeMd, "proposed_CLAUDE.md");
   const scannedSkillHash = sha256File(proposedSkillMd);
   const scannedClaudeHash = sha256File(proposedClaudeMd);
-  const tempDir = mkdtempSync3(join24(tmpdir2(), "skill-forge-evolve-"));
+  const tempDir = mkdtempSync3(join27(tmpdir2(), "skill-forge-evolve-"));
   let profile;
   let safety;
   try {
-    cpSync3(proposedSkillMd, join24(tempDir, "SKILL.md"));
-    if (existsSync20(proposedClaudeMd)) {
-      cpSync3(proposedClaudeMd, join24(tempDir, "CLAUDE.md"));
+    cpSync3(proposedSkillMd, join27(tempDir, "SKILL.md"));
+    if (existsSync21(proposedClaudeMd)) {
+      cpSync3(proposedClaudeMd, join27(tempDir, "CLAUDE.md"));
     }
     profile = asSkillProfile(profileSkill(tempDir), "for the evolved proposal");
     const strictness = loadConfig().strictness;
@@ -5890,7 +6517,7 @@ async function evolve(targetSkillDir, options = {}, deps = {}) {
     if (safetyVerdict === "block") process.exitCode = 1;
   } else {
     logOutcome(`[skill-forge] held \u2014 staging dir left in place -> ${stagingDir}`, json);
-    if (existsSync20(reportMdPath)) {
+    if (existsSync21(reportMdPath)) {
       logOutcome(`[skill-forge] see ${reportMdPath} for the full evidence report`, json);
     }
   }
@@ -5932,10 +6559,10 @@ function validateRunOutput(raw) {
   return { accepted: Boolean(obj.accepted), staging_dir: stagingDirRaw ?? null };
 }
 function readManifest(stagingDir) {
-  const manifestPath = join24(stagingDir, "manifest.json");
+  const manifestPath = join27(stagingDir, "manifest.json");
   let raw;
   try {
-    raw = readFileSync16(manifestPath, "utf-8");
+    raw = readFileSync18(manifestPath, "utf-8");
   } catch (err) {
     throw new UserError(`could not read staging manifest ${manifestPath}: ${err.message}`);
   }
@@ -5969,18 +6596,18 @@ function validateManifest(raw, manifestPath) {
   };
 }
 function filesIdentical(a, b) {
-  if (!existsSync20(a) || !existsSync20(b)) return false;
-  return readFileSync16(a).equals(readFileSync16(b));
+  if (!existsSync21(a) || !existsSync21(b)) return false;
+  return readFileSync18(a).equals(readFileSync18(b));
 }
 function isAlreadyAdopted(stagingDir, manifest) {
-  const proposedSkillMd = join24(stagingDir, "proposed_SKILL.md");
-  const proposedClaudeMd = join24(stagingDir, "proposed_CLAUDE.md");
+  const proposedSkillMd = join27(stagingDir, "proposed_SKILL.md");
+  const proposedClaudeMd = join27(stagingDir, "proposed_CLAUDE.md");
   let sawComparison = false;
-  if (existsSync20(proposedSkillMd)) {
+  if (existsSync21(proposedSkillMd)) {
     sawComparison = true;
     if (!filesIdentical(proposedSkillMd, manifest.live_skill_path)) return false;
   }
-  if (existsSync20(proposedClaudeMd) && manifest.live_memory_path) {
+  if (existsSync21(proposedClaudeMd) && manifest.live_memory_path) {
     sawComparison = true;
     if (!filesIdentical(proposedClaudeMd, manifest.live_memory_path)) return false;
   }
@@ -5998,8 +6625,8 @@ function assertNotSymlink(path, label2) {
   }
 }
 function sha256File(path) {
-  if (!existsSync20(path)) return null;
-  return createHash3("sha256").update(readFileSync16(path)).digest("hex");
+  if (!existsSync21(path)) return null;
+  return createHash3("sha256").update(readFileSync18(path)).digest("hex");
 }
 
 // src/commands/evolve.ts
@@ -6008,9 +6635,9 @@ async function evolveCommand(targetSkillDir, options = {}) {
 }
 
 // src/commands/finding.ts
-import { existsSync as existsSync21 } from "fs";
+import { existsSync as existsSync22 } from "fs";
 function requireSavedConfig() {
-  if (!existsSync21(getConfigPath())) {
+  if (!existsSync22(getConfigPath())) {
     throw new UserError(
       "no skill-forge config found \u2014 run `skill-forge init` first (`finding accept` re-runs the audit engine to resolve a live finding, and audit never runs against an invented default)."
     );
@@ -6096,7 +6723,7 @@ async function findingRevokeCommand(prefix, options = {}) {
 async function findingListCommand(options = {}) {
   const { records, notices } = readAcceptedFindings();
   for (const notice of notices) console.error(`[skill-forge] ${notice}`);
-  const rows = options.stale ? records.filter((r) => !existsSync21(r.target)) : records;
+  const rows = options.stale ? records.filter((r) => !existsSync22(r.target)) : records;
   if (options.json) {
     console.log(JSON.stringify(rows, null, 2));
     return;
@@ -6114,24 +6741,24 @@ async function findingListCommand(options = {}) {
 }
 
 // src/commands/organize.ts
-import { resolve as resolvePath7 } from "path";
+import { resolve as resolvePath9 } from "path";
 
 // src/organize.ts
-import { existsSync as existsSync22, readFileSync as readFileSync17, readdirSync as readdirSync8, realpathSync as realpathSync4, statSync as statSync9 } from "fs";
-import { basename as basename11, join as join25, resolve as resolvePath6 } from "path";
+import { existsSync as existsSync23, readFileSync as readFileSync19, readdirSync as readdirSync10, realpathSync as realpathSync5, statSync as statSync9 } from "fs";
+import { basename as basename11, join as join28, resolve as resolvePath8 } from "path";
 var PRO_FEATURE_LABEL4 = "set-level organizer reports";
 var TIERS = /* @__PURE__ */ new Set(["resource", "custom"]);
-var MATURITIES = /* @__PURE__ */ new Set(["seedling", "stable", "deprecated"]);
+var MATURITIES = /* @__PURE__ */ new Set(["seedling", "stable", "deprecated", "experimental"]);
 function listSubdirs2(dir) {
   let entries;
   try {
-    entries = readdirSync8(dir, { withFileTypes: true });
+    entries = readdirSync10(dir, { withFileTypes: true });
   } catch {
     return [];
   }
   const out = [];
   for (const entry of entries) {
-    const full = join25(dir, entry.name);
+    const full = join28(dir, entry.name);
     if (entry.isDirectory()) {
       out.push(full);
       continue;
@@ -6149,14 +6776,14 @@ function findSkillDirsUnderRoot2(root) {
   const found = /* @__PURE__ */ new Set();
   const topDirs = listSubdirs2(root);
   for (const dir of topDirs) {
-    if (existsSync22(join25(dir, "SKILL.md"))) found.add(dir);
+    if (existsSync23(join28(dir, "SKILL.md"))) found.add(dir);
   }
-  for (const dir of listSubdirs2(join25(root, "skills"))) {
-    if (existsSync22(join25(dir, "SKILL.md"))) found.add(dir);
+  for (const dir of listSubdirs2(join28(root, "skills"))) {
+    if (existsSync23(join28(dir, "SKILL.md"))) found.add(dir);
   }
   for (const topDir of topDirs) {
-    for (const dir of listSubdirs2(join25(topDir, "skills"))) {
-      if (existsSync22(join25(dir, "SKILL.md"))) found.add(dir);
+    for (const dir of listSubdirs2(join28(topDir, "skills"))) {
+      if (existsSync23(join28(dir, "SKILL.md"))) found.add(dir);
     }
   }
   return Array.from(found).filter((p) => !p.includes("/.git/"));
@@ -6164,7 +6791,7 @@ function findSkillDirsUnderRoot2(root) {
 function collectCandidates(roots) {
   const out = [];
   for (const root of roots) {
-    const resolvedRoot = resolvePath6(expandHome(root));
+    const resolvedRoot = resolvePath8(expandHome(root));
     if (!isDir(resolvedRoot)) continue;
     for (const dirPath of findSkillDirsUnderRoot2(resolvedRoot)) {
       out.push({ dirPath, root });
@@ -6201,57 +6828,85 @@ function extractFrontmatterBlock(text) {
   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 };
+function indentOf(line) {
+  const m = line.match(/^ */);
+  return m ? m[0].length : 0;
+}
+function extractIndentedBlock(lines, key, parentIndent) {
+  const keyRe = new RegExp(`^${" ".repeat(parentIndent)}${key}:\\s*$`);
+  const startIdx = lines.findIndex((l) => keyRe.test(l));
+  if (startIdx === -1) return null;
+  const block = [];
+  for (const line of lines.slice(startIdx + 1)) {
+    if (line.trim() === "") {
+      block.push(line);
+      continue;
+    }
+    if (indentOf(line) <= parentIndent) break;
+    block.push(line);
   }
+  return block;
+}
+function dedent(lines) {
+  const nonBlank = lines.filter((l) => l.trim() !== "");
+  if (nonBlank.length === 0) return "";
+  const minIndent = Math.min(...nonBlank.map(indentOf));
+  return lines.map((l) => l.trim() === "" ? "" : l.slice(minIndent)).join("\n");
+}
+function extractFlatFields(text, keys) {
   const fields = {};
-  for (const key of ["name", "tier", "domain", "provenance", "maturity"]) {
-    const m = block.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+  for (const key of keys) {
+    const m = text.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
     if (m) fields[key] = stripQuotes(m[1].trim());
   }
+  return fields;
+}
+function parseNestedRhizeMetadata(block) {
+  const lines = block.split(/\r\n|\r|\n/);
+  const metaBlock = extractIndentedBlock(lines, "metadata", 0);
+  if (metaBlock === null) return null;
+  const rhizeLine = metaBlock.find((l) => /^\s*rhize:\s*$/.test(l));
+  if (!rhizeLine) return null;
+  const rhizeBlock = extractIndentedBlock(metaBlock, "rhize", indentOf(rhizeLine));
+  if (rhizeBlock === null) return null;
+  const dedented = dedent(rhizeBlock);
+  const fields = extractFlatFields(dedented, ["tier", "domain", "provenance", "maturity"]);
   return {
-    name: fields.name ?? fallbackName,
     tier: fields.tier,
     domain: fields.domain,
     provenance: fields.provenance,
     maturity: fields.maturity,
-    consumes: parseYamlList(block, "consumes"),
-    validFrontmatter: true
+    consumes: parseYamlList(dedented, "consumes")
   };
 }
-function loadUsageSnapshot(snapshotPath) {
-  const resolvedPath = resolvePath6(expandHome(snapshotPath));
-  let raw;
-  try {
-    raw = readFileSync17(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 };
+function contributesAnyField(f) {
+  return f.tier !== void 0 || f.domain !== void 0 || f.provenance !== void 0 || f.maturity !== void 0 || Boolean(f.consumes && f.consumes.length > 0);
+}
+function parseCapabilityFrontmatter(text, fallbackName) {
+  const block = extractFrontmatterBlock(text);
+  if (block === null) {
+    return { name: fallbackName, consumes: [], validFrontmatter: false, tagSource: "none" };
+  }
+  const fields = extractFlatFields(block, ["name", "tier", "domain", "provenance", "maturity"]);
+  const flatConsumes = parseYamlList(block, "consumes");
+  const nested = parseNestedRhizeMetadata(block);
+  const flatContributed = contributesAnyField({ ...fields, consumes: flatConsumes });
+  const nestedContributed = nested !== null && contributesAnyField(nested);
+  let tagSource;
+  if (flatContributed && nestedContributed) tagSource = "mixed";
+  else if (flatContributed) tagSource = "flat";
+  else if (nestedContributed) tagSource = "metadata.rhize";
+  else tagSource = "none";
+  return {
+    name: fields.name ?? fallbackName,
+    tier: fields.tier ?? nested?.tier,
+    domain: fields.domain ?? nested?.domain,
+    provenance: fields.provenance ?? nested?.provenance,
+    maturity: fields.maturity ?? nested?.maturity,
+    consumes: flatConsumes.length > 0 ? flatConsumes : nested?.consumes ?? [],
+    validFrontmatter: true,
+    tagSource
+  };
 }
 var WHITE = 0;
 var GRAY = 1;
@@ -6324,17 +6979,17 @@ function buildRegistryEntries(candidates, warnings) {
   for (const candidate of candidates) {
     let realPath;
     try {
-      realPath = realpathSync4(candidate.dirPath);
+      realPath = realpathSync5(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 = join25(realPath, "SKILL.md");
+    const skillMdPath = join28(realPath, "SKILL.md");
     let text;
     try {
-      text = readFileSync17(skillMdPath, "utf-8");
+      text = readFileSync19(skillMdPath, "utf-8");
     } catch (err) {
       warnings.push(`could not read ${skillMdPath}: ${err.message}`);
       continue;
@@ -6357,7 +7012,8 @@ function buildRegistryEntries(candidates, warnings) {
       consumes: fm.consumes,
       provenance: fm.provenance,
       maturity: fm.maturity,
-      validFrontmatter: fm.validFrontmatter
+      validFrontmatter: fm.validFrontmatter,
+      tagSource: fm.tagSource
     });
   }
   return entries;
@@ -6446,7 +7102,7 @@ function buildOrganizeReport(config, options = {}) {
 
 // src/commands/organize.ts
 function writeReport(outPath, contents) {
-  const resolved = resolvePath7(outPath);
+  const resolved = resolvePath9(outPath);
   writeNewFile(resolved, contents, "--out");
   return resolved;
 }
@@ -6739,13 +7395,13 @@ async function find(query, options = {}, deps = {}) {
 }
 
 // src/commands/watch.ts
-import { realpathSync as realpathSync5 } from "fs";
-import { join as join26, resolve as resolvePath8 } from "path";
+import { realpathSync as realpathSync6 } from "fs";
+import { join as join29, resolve as resolvePath10 } from "path";
 
 // src/gate/skillMapDrift.ts
 import { createHash as createHash4 } from "crypto";
-import { readFileSync as readFileSync18, existsSync as existsSync23 } from "fs";
-import { dirname as dirname10, isAbsolute as isAbsolute3, resolve as resolve7 } from "path";
+import { readFileSync as readFileSync20, existsSync as existsSync24 } from "fs";
+import { dirname as dirname10, isAbsolute as isAbsolute4, resolve as resolve7 } from "path";
 function sha256(text) {
   return createHash4("sha256").update(text, "utf-8").digest("hex");
 }
@@ -6778,22 +7434,22 @@ function threeWayVerdict(localNormalized, upstreamHash, baselineHash) {
 }
 function resolveLocalPath(path, mapDir) {
   const expanded = expandHome(path);
-  if (isAbsolute3(expanded)) return resolve7(expanded);
+  if (isAbsolute4(expanded)) return resolve7(expanded);
   const candidates = [resolve7(expanded)];
   if (mapDir) {
     candidates.push(resolve7(mapDir, expanded));
     candidates.push(resolve7(mapDir, "..", expanded));
   }
   for (const candidate of candidates) {
-    if (existsSync23(candidate)) return candidate;
+    if (existsSync24(candidate)) return candidate;
   }
   return candidates[0];
 }
 function defaultReadLocalFile(path, mapDir) {
   const resolved = resolveLocalPath(path, mapDir);
-  if (!existsSync23(resolved)) return void 0;
+  if (!existsSync24(resolved)) return void 0;
   try {
-    return readFileSync18(resolved, "utf-8");
+    return readFileSync20(resolved, "utf-8");
   } catch {
     return void 0;
   }
@@ -6834,7 +7490,7 @@ async function computeMapDrift(map, deps = {}) {
       continue;
     }
     const localResolved = resolveLocalPath(localNode.path, mapDir);
-    if (!existsSync23(localResolved)) {
+    if (!existsSync24(localResolved)) {
       rows.push({
         skill: skillLabel,
         upstream,
@@ -6940,12 +7596,12 @@ async function runWatch(config, options = {}, deps = {}) {
   const warnings = [];
   const seenRealPaths = /* @__PURE__ */ new Set();
   for (const root of config.skillsRoots) {
-    const resolvedRoot = resolvePath8(expandHome(root));
+    const resolvedRoot = resolvePath10(expandHome(root));
     const exists = isDir(resolvedRoot);
     let realPath = resolvedRoot;
     if (exists) {
       try {
-        realPath = realpathSync5(resolvedRoot);
+        realPath = realpathSync6(resolvedRoot);
       } catch {
         realPath = resolvedRoot;
       }
@@ -6957,7 +7613,7 @@ async function runWatch(config, options = {}, deps = {}) {
       ledger = readProvenanceLedger(resolvedRoot);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      const ledgerPath = join26(resolvedRoot, "SOURCES.md");
+      const ledgerPath = join29(resolvedRoot, "SOURCES.md");
       roots.push({ root, realPath, exists, ledgerPath, ledgerExists: false });
       warnings.push(`${ledgerPath}: could not read ledger: ${message}`);
       continue;
@@ -7067,8 +7723,8 @@ async function watchCommand(options = {}) {
 }
 
 // src/commands/routine.ts
-import { existsSync as existsSync24, rmSync as rmSync7, statSync as statSync10 } from "fs";
-import { join as join27 } from "path";
+import { existsSync as existsSync25, rmSync as rmSync7, statSync as statSync10 } from "fs";
+import { join as join30 } from "path";
 var PRO_FEATURE_LABEL6 = "the scheduled maintenance routine";
 var SEVERITY_ORDER = ["LOW", "MEDIUM", "HIGH", "CRITICAL"];
 function parseFailOnFloor(failOn) {
@@ -7089,7 +7745,7 @@ function exceedsFloor(audit2, failOn) {
 }
 function resolveReportPath2(override, generatedAt) {
   if (override) return override;
-  return join27(getHomeDir(), "reports", `routine-${generatedAt.replace(/[:.]/g, "-")}.md`);
+  return join30(getHomeDir(), "reports", `routine-${generatedAt.replace(/[:.]/g, "-")}.md`);
 }
 function runHousekeeping(config, options) {
   const actions = [];
@@ -7098,7 +7754,7 @@ function runHousekeeping(config, options) {
   const pruneDays = options.pruneDays ?? 30;
   const cutoff = Date.now() - pruneDays * 864e5;
   for (const id of listQuarantineIds(config.quarantineDir)) {
-    const path = join27(config.quarantineDir, id);
+    const path = join30(config.quarantineDir, id);
     let mtime;
     try {
       mtime = statSync10(path).mtimeMs;
@@ -7136,7 +7792,7 @@ function runHousekeeping(config, options) {
   }
   for (const entry of entries) {
     if (entry.status !== "pending") continue;
-    if (!entry.installedPath || existsSync24(entry.installedPath)) continue;
+    if (!entry.installedPath || existsSync25(entry.installedPath)) continue;
     if (apply) {
       try {
         updateQueueEntry(entry.id, { status: "dismissed" });
@@ -7227,7 +7883,7 @@ function renderRoutineMarkdown(result, audit2, watch, organize) {
   lines.push("");
   return lines.join("\n");
 }
-async function routineCommand(options = {}) {
+async function routineCommand(options = {}, deps = {}) {
   const pro = proFeatureStatus(PRO_FEATURE_LABEL6);
   const log = options.json ? console.error : console.log;
   if (pro.notice) log(`[skill-forge] ${pro.notice}`);
@@ -7240,9 +7896,11 @@ async function routineCommand(options = {}) {
   }
   const config = loadConfig();
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const { pluginRoots, usage, notices: pluginUsageNotices } = resolvePluginAndUsageContext(config, options, deps);
   const { records: accepted, notices: storeNotices } = readAcceptedFindings();
-  for (const notice of storeNotices) log(`[skill-forge] ${notice}`);
-  const audit2 = await auditConfiguredSet(config, { accepted });
+  const notices = [...storeNotices, ...pluginUsageNotices];
+  for (const notice of notices) log(`[skill-forge] ${notice}`);
+  const audit2 = await auditConfiguredSet(config, { accepted, pluginRoots, usage });
   const auditState = summarizeAudit(audit2);
   const degraded = [];
   let watch;
@@ -7283,9 +7941,10 @@ async function routineCommand(options = {}) {
       notices: watch.notices
     } : void 0,
     organize: organize ? { skills: organize.registry.count, roots: organize.registry.skillsRoots.length, notices: organize.notices } : void 0,
+    plugins: audit2.plugins,
     pending: { queue: pending.count, quarantine: quarantine2.count },
     housekeeping,
-    notices: storeNotices,
+    notices,
     degraded
   };
   const failure = degraded.length > 0 ? `${degraded.length} step(s) did not complete: ${degraded.join("; ")}` : exceedsFloor(auditState, options.failOn ?? "none");
@@ -7307,6 +7966,7 @@ async function routineCommand(options = {}) {
     console.log(`  accepted: ${auditState.acceptedCount ?? 0} (suppressed from counts; see report)`);
     if (result.watch) console.log(`  drift: ${result.watch.moved} moved of ${result.watch.checked} tracked`);
     if (result.organize) console.log(`  registry: ${result.organize.skills} skill(s)`);
+    if (result.plugins) console.log(`  ${summarizePluginRecommendations(result.plugins)}`);
     console.log(`  pending: ${result.pending.queue} queue, ${result.pending.quarantine} quarantine`);
     for (const action of housekeeping) {
       const label2 = action.outcome === "applied" ? "housekeeping" : action.outcome === "failed" ? "FAILED" : "would do";
@@ -7328,8 +7988,8 @@ async function routineCommand(options = {}) {
 }
 
 // src/commands/ingest.ts
-import { realpathSync as realpathSync6 } from "fs";
-import { dirname as dirname12, isAbsolute as isAbsolute4, relative as relative3, resolve as resolvePath9 } from "path";
+import { realpathSync as realpathSync7 } from "fs";
+import { dirname as dirname12, isAbsolute as isAbsolute5, relative as relative4, resolve as resolvePath11 } from "path";
 var PRO_FEATURE_LABEL7 = "the pending-ingestion queue";
 var VALID_STATUSES = ["ingested", "dismissed"];
 function requireProFeature() {
@@ -7370,19 +8030,19 @@ function printPendingList(pending, json) {
 }
 function realpathOrNull(p) {
   try {
-    return realpathSync6(p);
+    return realpathSync7(p);
   } catch {
     return null;
   }
 }
 function isUnderRoot(candidate, root) {
-  const rel = relative3(root, candidate);
-  return rel === "" || !rel.startsWith("..") && !isAbsolute4(rel);
+  const rel = relative4(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute5(rel);
 }
 function validatePendingEntries(entries, config) {
-  const quarantineRoot = realpathOrNull(resolvePath9(config.quarantineDir));
-  const skillsRoots = config.skillsRoots.map((r) => realpathOrNull(resolvePath9(r))).filter((r) => r !== null);
-  const mcpTargetDirs = (config.mcpTargets ?? []).map((f) => realpathOrNull(dirname12(resolvePath9(f)))).filter((r) => r !== null);
+  const quarantineRoot = realpathOrNull(resolvePath11(config.quarantineDir));
+  const skillsRoots = config.skillsRoots.map((r) => realpathOrNull(resolvePath11(r))).filter((r) => r !== null);
+  const mcpTargetDirs = (config.mcpTargets ?? []).map((f) => realpathOrNull(dirname12(resolvePath11(f)))).filter((r) => r !== null);
   const allowedRoots = [quarantineRoot, ...skillsRoots, ...mcpTargetDirs].filter((r) => r !== null);
   const valid = [];
   const excluded = [];
@@ -7392,7 +8052,7 @@ function validatePendingEntries(entries, config) {
       excluded.push({ entry, reason: "no installedPath or quarantinePath recorded on the entry" });
       continue;
     }
-    const real = realpathOrNull(resolvePath9(effectivePath));
+    const real = realpathOrNull(resolvePath11(effectivePath));
     if (!real) {
       excluded.push({ entry, reason: `path does not exist or could not be resolved: ${effectivePath}` });
       continue;
@@ -7459,15 +8119,15 @@ import {
   chmodSync as chmodSync3,
   lstatSync as lstatSync6,
   mkdirSync as mkdirSync9,
-  readFileSync as readFileSync22,
+  readFileSync as readFileSync24,
   readSync as readSync3,
   writeFileSync as writeFileSync8
 } from "fs";
-import { dirname as dirname13, isAbsolute as isAbsolute6, join as join32, relative as relative5, resolve as resolvePath10 } from "path";
+import { dirname as dirname13, isAbsolute as isAbsolute7, join as join35, relative as relative6, resolve as resolvePath12 } from "path";
 
 // src/insights/inventory.ts
-import { readFileSync as readFileSync19 } from "fs";
-import { join as join28 } from "path";
+import { readFileSync as readFileSync21 } from "fs";
+import { join as join31 } from "path";
 
 // src/insights/models.ts
 import { createHash as createHash5 } from "crypto";
@@ -7581,7 +8241,7 @@ function declaredMapCoverage(path, claim) {
 }
 function fingerprintInstalledSkill(path) {
   try {
-    return { fingerprint: stableHash(readFileSync19(join28(path, "SKILL.md"), "utf-8")) };
+    return { fingerprint: stableHash(readFileSync21(join31(path, "SKILL.md"), "utf-8")) };
   } catch (error) {
     return { reason: `could not fingerprint SKILL.md: ${error.message}` };
   }
@@ -7731,12 +8391,12 @@ function buildInsightInventory(config, options = {}) {
 }
 
 // src/insights/jira.ts
-import { existsSync as existsSync26, readFileSync as readFileSync21 } from "fs";
-import { join as join31 } from "path";
+import { existsSync as existsSync27, readFileSync as readFileSync23 } from "fs";
+import { join as join34 } from "path";
 
 // src/insights/store.ts
-import { chmodSync as chmodSync2, existsSync as existsSync25, mkdirSync as mkdirSync8, readFileSync as readFileSync20 } from "fs";
-import { join as join30 } from "path";
+import { chmodSync as chmodSync2, existsSync as existsSync26, mkdirSync as mkdirSync8, readFileSync as readFileSync22 } from "fs";
+import { join as join33 } from "path";
 
 // src/insights/sources.ts
 import { createHash as createHash6 } from "crypto";
@@ -7747,11 +8407,11 @@ import {
   lstatSync as lstatSync5,
   openSync as openSync3,
   readSync as readSync2,
-  readdirSync as readdirSync9,
-  realpathSync as realpathSync7,
+  readdirSync as readdirSync11,
+  realpathSync as realpathSync8,
   statSync as statSync11
 } from "fs";
-import { basename as basename12, extname as extname6, isAbsolute as isAbsolute5, join as join29, relative as relative4, resolve as resolve8, sep as sep5 } from "path";
+import { basename as basename12, extname as extname8, isAbsolute as isAbsolute6, join as join32, relative as relative5, resolve as resolve8, sep as sep7 } from "path";
 var DEFAULT_MAX_SOURCE_FILE_BYTES = 5 * 1024 * 1024;
 var DEFAULT_MAX_SOURCE_TOTAL_BYTES = 25 * 1024 * 1024;
 var SKIP_DIRS4 = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "build", "coverage", ".next", "out", "__pycache__", ".venv", "venv"]);
@@ -7821,9 +8481,9 @@ function canonicalPublicUrl(raw, label2) {
   url.hash = "";
   return url.toString();
 }
-function isInside2(child, root) {
-  const rel = relative4(root, child);
-  return rel === "" || !rel.startsWith(`..${sep5}`) && rel !== ".." && !isAbsolute5(rel);
+function isInside3(child, root) {
+  const rel = relative5(root, child);
+  return rel === "" || !rel.startsWith(`..${sep7}`) && rel !== ".." && !isAbsolute6(rel);
 }
 function isHiddenName(name) {
   return name.startsWith(".") && name !== "." && name !== "..";
@@ -7832,7 +8492,7 @@ function hasCredentialShapedName(name) {
   return name === ".env" || name.startsWith(".env.") || CREDENTIAL_NAME.test(name);
 }
 function mediaTypeFor(path, declared) {
-  return declared ?? SUPPORTED_MEDIA_BY_EXTENSION[extname6(path).toLowerCase()];
+  return declared ?? SUPPORTED_MEDIA_BY_EXTENSION[extname8(path).toLowerCase()];
 }
 function suspiciousInstructionFlags(bytes, mediaType) {
   if (!mediaType.startsWith("text/")) return [];
@@ -7887,7 +8547,7 @@ function observeFile(path, relativePath, declaredMediaType, maxFileBytes, remain
   if (!bytes || !descriptorStat) throw new UserError(`source file could not be observed: ${relativePath}`);
   let realPath;
   try {
-    realPath = realpathSync7(path);
+    realPath = realpathSync8(path);
     const pathStat = statSync11(realPath);
     if (pathStat.dev !== descriptorStat.dev || pathStat.ino !== descriptorStat.ino) {
       throw new Error("path identity changed");
@@ -8069,7 +8729,7 @@ function normalizeDirectory(input, retrievedAt, maxFileBytes, remainingBytes) {
   }
   if (lexicalStat.isSymbolicLink()) throw new UserError(`source directory must not be a symlink: ${resolved}`);
   if (!lexicalStat.isDirectory()) throw new UserError(`source directory is not a directory: ${resolved}`);
-  const realRoot = realpathSync7(resolved);
+  const realRoot = realpathSync8(resolved);
   const observations = [];
   const skipped = [];
   const seenFiles = /* @__PURE__ */ new Set();
@@ -8078,12 +8738,12 @@ function normalizeDirectory(input, retrievedAt, maxFileBytes, remainingBytes) {
   const walk2 = (dir, logicalDir) => {
     let entries;
     try {
-      entries = readdirSync9(dir, { withFileTypes: true }).sort((a, b) => compareStrings2(a.name, b.name));
+      entries = readdirSync11(dir, { withFileTypes: true }).sort((a, b) => compareStrings2(a.name, b.name));
     } catch (err) {
       throw new UserError(`unable to enumerate source directory ${dir}: ${err.message}`);
     }
     for (const entry of entries) {
-      const full = join29(dir, entry.name);
+      const full = join32(dir, entry.name);
       const logicalPath = logicalDir ? `${logicalDir}/${entry.name}` : entry.name;
       if (entry.isDirectory() && SKIP_DIRS4.has(entry.name)) {
         skipped.push({ path: logicalPath, reason: "ignored-directory" });
@@ -8100,11 +8760,11 @@ function normalizeDirectory(input, retrievedAt, maxFileBytes, remainingBytes) {
       if (entry.isSymbolicLink()) {
         let realTarget;
         try {
-          realTarget = realpathSync7(full);
+          realTarget = realpathSync8(full);
         } catch {
           throw new UserError(`source directory contains an unreadable symlink: ${logicalPath}`);
         }
-        if (!isInside2(realTarget, realRoot)) {
+        if (!isInside3(realTarget, realRoot)) {
           throw new UserError(`source directory symlink escapes its root: ${logicalPath}`);
         }
         const targetStat = statSync11(realTarget);
@@ -8119,7 +8779,7 @@ function normalizeDirectory(input, retrievedAt, maxFileBytes, remainingBytes) {
           continue;
         }
       } else if (entry.isDirectory()) {
-        const realDir = realpathSync7(full);
+        const realDir = realpathSync8(full);
         if (seenDirs.has(realDir)) continue;
         seenDirs.add(realDir);
         walk2(full, logicalPath);
@@ -8128,8 +8788,8 @@ function normalizeDirectory(input, retrievedAt, maxFileBytes, remainingBytes) {
         skipped.push({ path: logicalPath, reason: "unsupported-media-type" });
         continue;
       }
-      const realFile = realpathSync7(full);
-      if (!isInside2(realFile, realRoot)) {
+      const realFile = realpathSync8(full);
+      if (!isInside3(realFile, realRoot)) {
         throw new UserError(`source directory entry escaped its root while being observed: ${logicalPath}`);
       }
       if (seenFiles.has(realFile)) {
@@ -8235,17 +8895,17 @@ function normalizeSources(inputs, options = {}) {
 // src/insights/store.ts
 var STUDY_ID = /^STUDY-[0-9a-f]{16}$/;
 function getInsightsDir() {
-  return join30(getHomeDir(), "insights");
+  return join33(getHomeDir(), "insights");
 }
 function getStudyDir(studyId) {
   assertStudyId(studyId);
-  return join30(getInsightsDir(), studyId);
+  return join33(getInsightsDir(), studyId);
 }
 function getStudyPath(studyId) {
-  return join30(getStudyDir(studyId), "study.json");
+  return join33(getStudyDir(studyId), "study.json");
 }
 function getStudyEventsPath(studyId) {
-  return join30(getStudyDir(studyId), "events.jsonl");
+  return join33(getStudyDir(studyId), "events.jsonl");
 }
 function createStudyId(sourceInventoryHash, createdAt) {
   return stableId("STUDY", { sourceInventoryHash, createdAt });
@@ -8376,7 +9036,7 @@ function validateStudyShape(value, path) {
 function parseStudy(path) {
   let raw;
   try {
-    raw = readFileSync20(path, "utf-8");
+    raw = readFileSync22(path, "utf-8");
   } catch (err) {
     throw new UserError(`unable to read insight study at ${path}: ${err.message}`);
   }
@@ -8410,7 +9070,7 @@ function createInsightStudy(input, options = {}) {
   const studyId = options.studyId ?? createStudyId(input.sourceInventoryHash, createdAt);
   assertStudyId(studyId);
   const path = getStudyPath(studyId);
-  if (existsSync25(path)) throw new UserError(`insight study already exists: ${studyId}`);
+  if (existsSync26(path)) throw new UserError(`insight study already exists: ${studyId}`);
   const study = {
     schemaVersion: INSIGHT_SCHEMA_VERSION,
     studyId,
@@ -8431,7 +9091,7 @@ function createInsightStudy(input, options = {}) {
 }
 function readInsightStudy(studyId) {
   const path = getStudyPath(studyId);
-  if (!existsSync25(path)) throw new UserError(`no insight study with id: ${studyId}`);
+  if (!existsSync26(path)) throw new UserError(`no insight study with id: ${studyId}`);
   const study = parseStudy(path);
   if (study.studyId !== studyId) {
     throw new UserError(`malformed insight study at ${path}: stored studyId does not match its directory`);
@@ -8441,7 +9101,7 @@ function readInsightStudy(studyId) {
 function writeInsightStudy(study, now = /* @__PURE__ */ new Date()) {
   assertStudyId(study.studyId);
   const path = getStudyPath(study.studyId);
-  if (!existsSync25(path)) throw new UserError(`no insight study with id: ${study.studyId}`);
+  if (!existsSync26(path)) throw new UserError(`no insight study with id: ${study.studyId}`);
   const existing = parseStudy(path);
   let next = { ...study, updatedAt: now.toISOString() };
   if (next.status === "dismissed" || next.status === "archived") {
@@ -9178,7 +9838,7 @@ function buildJiraManifest(study, projectKey, options = {}) {
   return manifest;
 }
 function getJiraReceiptsPath(studyId) {
-  return join31(getStudyDir(studyId), "jira-receipts.jsonl");
+  return join34(getStudyDir(studyId), "jira-receipts.jsonl");
 }
 function assertCurrentJiraManifest(study, value) {
   if (study.status !== "jira-manifested" || !study.jira) {
@@ -9310,10 +9970,10 @@ function appendJiraReceipt(studyId, manifest, input) {
 function readJiraReceipts(studyId, manifest) {
   const currentManifest = assertCurrentJiraManifest(readInsightStudy(studyId), manifest);
   const path = getJiraReceiptsPath(studyId);
-  if (!existsSync26(path)) return [];
+  if (!existsSync27(path)) return [];
   let text;
   try {
-    text = readFileSync21(path, "utf-8");
+    text = readFileSync23(path, "utf-8");
   } catch (error) {
     throw new UserError(`unable to read Jira receipts at ${path}: ${error.message}`);
   }
@@ -9452,10 +10112,10 @@ function nonEmptyString(value, label2) {
   return value;
 }
 function parseJsonFile(path, label2) {
-  const resolved = resolvePath10(path);
+  const resolved = resolvePath12(path);
   let raw;
   try {
-    raw = readFileSync22(resolved, "utf-8");
+    raw = readFileSync24(resolved, "utf-8");
   } catch (error) {
     throw new UserError(`unable to read ${label2} at ${resolved}: ${error.message}`);
   }
@@ -9510,7 +10170,7 @@ function assertCommonDescriptorFields(value, label2) {
 }
 function pathRelativeTo(baseDir, raw, label2) {
   const path = nonEmptyString(raw, label2);
-  return isAbsolute6(path) ? path : resolvePath10(baseDir, path);
+  return isAbsolute7(path) ? path : resolvePath12(baseDir, path);
 }
 function parseManifestDescriptor(value, index, baseDir) {
   const label2 = `source manifest entry ${index + 1}`;
@@ -9548,7 +10208,7 @@ function parseManifestDescriptor(value, index, baseDir) {
   throw new UserError(`${label2}.type must be url|file|directory|connector|stdin`);
 }
 function readManifest2(path) {
-  const resolved = resolvePath10(path);
+  const resolved = resolvePath12(path);
   const parsed = parseJsonFile(resolved, "source manifest");
   let values;
   if (Array.isArray(parsed)) {
@@ -9581,7 +10241,7 @@ function positionalSource(value) {
     if (process.stdin.isTTY) throw new UserError(`stdin source "-" requires piped input`);
     return { type: "stdin", content: readBoundedStdin() };
   }
-  const resolved = resolvePath10(value);
+  const resolved = resolvePath12(value);
   let stat;
   try {
     stat = lstatSync6(resolved);
@@ -9600,15 +10260,15 @@ function collectSourceInputs(sourceArgs, options) {
   return inputs;
 }
 function contextPath(studyId) {
-  return join32(getStudyDir(studyId), CONTEXT_FILENAME);
+  return join35(getStudyDir(studyId), CONTEXT_FILENAME);
 }
 function inventoryPath(studyId) {
-  return join32(getStudyDir(studyId), INVENTORY_FILENAME);
+  return join35(getStudyDir(studyId), INVENTORY_FILENAME);
 }
 function writeCommandContext(studyId, skillMapPath, skillMapCoverage, inventory) {
   const context = {
     schemaVersion: 1,
-    skillMapPath: skillMapPath ? resolvePath10(skillMapPath) : void 0,
+    skillMapPath: skillMapPath ? resolvePath12(skillMapPath) : void 0,
     skillMapCoverage
   };
   writeJsonAtomic(contextPath(studyId), context);
@@ -9617,7 +10277,7 @@ function writeCommandContext(studyId, skillMapPath, skillMapCoverage, inventory)
 function readCommandContext(studyId) {
   const path = contextPath(studyId);
   const parsed = parseJsonFile(path, "insight command context");
-  if (!isRecord5(parsed) || parsed.schemaVersion !== 1 || parsed.skillMapPath !== void 0 && (typeof parsed.skillMapPath !== "string" || !isAbsolute6(parsed.skillMapPath)) || parsed.skillMapCoverage !== void 0 && parsed.skillMapCoverage !== "static" && parsed.skillMapCoverage !== "resolved" || parsed.skillMapCoverage !== void 0 && parsed.skillMapPath === void 0 || Object.keys(parsed).some((key) => !["schemaVersion", "skillMapPath", "skillMapCoverage"].includes(key))) {
+  if (!isRecord5(parsed) || parsed.schemaVersion !== 1 || parsed.skillMapPath !== void 0 && (typeof parsed.skillMapPath !== "string" || !isAbsolute7(parsed.skillMapPath)) || parsed.skillMapCoverage !== void 0 && parsed.skillMapCoverage !== "static" && parsed.skillMapCoverage !== "resolved" || parsed.skillMapCoverage !== void 0 && parsed.skillMapPath === void 0 || Object.keys(parsed).some((key) => !["schemaVersion", "skillMapPath", "skillMapCoverage"].includes(key))) {
     throw new UserError(`malformed insight command context at ${path}`);
   }
   return parsed;
@@ -9640,19 +10300,19 @@ function readCurrentStudy(studyId) {
   return { study, inventory: currentInventory(study, config), config };
 }
 function retainedPath(root, relativePath) {
-  const candidate = resolvePath10(root, relativePath);
-  const rel = relative5(root, candidate);
-  if (rel.startsWith("..") || isAbsolute6(rel)) throw new UserError(`refusing retained source path outside the study`);
+  const candidate = resolvePath12(root, relativePath);
+  const rel = relative6(root, candidate);
+  if (rel.startsWith("..") || isAbsolute7(rel)) throw new UserError(`refusing retained source path outside the study`);
   return candidate;
 }
 function retainObservedSources(study, observedFiles) {
   if (observedFiles.length === 0) return study;
-  const root = join32(getStudyDir(study.studyId), "retained-sources");
+  const root = join35(getStudyDir(study.studyId), "retained-sources");
   mkdirSync9(root, { recursive: true, mode: 448 });
   chmodSync3(root, 448);
   const retainedSourceIds = /* @__PURE__ */ new Set();
   for (const file of observedFiles) {
-    const sourceRoot = join32(root, file.sourceId);
+    const sourceRoot = join35(root, file.sourceId);
     mkdirSync9(sourceRoot, { recursive: true, mode: 448 });
     chmodSync3(sourceRoot, 448);
     const destination = retainedPath(sourceRoot, file.relativePath);
@@ -9733,7 +10393,7 @@ async function insightAnalyze(sourceArgs = [], options = {}) {
   requireProFeature2();
   const config = loadConfig();
   const inputs = collectSourceInputs(sourceArgs, options);
-  const skillMapPath = options.skillMap ? resolvePath10(options.skillMap) : void 0;
+  const skillMapPath = options.skillMap ? resolvePath12(options.skillMap) : void 0;
   if (options.skillMapCoverage !== void 0 && skillMapPath === void 0) {
     throw new UserError("--skill-map-coverage requires --skill-map");
   }
@@ -9890,7 +10550,7 @@ async function insightJira(studyId, options) {
     throw new UserError(`study ${studyId} cannot generate a Jira manifest: ${validation.blockers.map((issue) => issue.message).join("; ")}`);
   }
   if (localMode) {
-    const privatePath2 = join32(getStudyDir(studyId), JIRA_MANIFEST_FILENAME);
+    const privatePath2 = join35(getStudyDir(studyId), JIRA_MANIFEST_FILENAME);
     const manifest2 = assertCurrentJiraManifest(study, parseJsonFile(privatePath2, "stored Jira manifest"));
     const receipt = options.receipt === void 0 ? void 0 : appendJiraReceipt(studyId, manifest2, parseJiraReceiptInput(parseJsonFile(options.receipt, "Jira receipt import")));
     const resume = buildJiraResumeState(manifest2, readJiraReceipts(studyId, manifest2));
@@ -9902,10 +10562,10 @@ async function insightJira(studyId, options) {
     return;
   }
   const manifest = buildJiraManifest(study, projectKey);
-  const privatePath = join32(getStudyDir(studyId), JIRA_MANIFEST_FILENAME);
+  const privatePath = join35(getStudyDir(studyId), JIRA_MANIFEST_FILENAME);
   writeJsonAtomic(privatePath, manifest);
   if (options.out) {
-    writeNewFile(resolvePath10(options.out), `${JSON.stringify(manifest, null, 2)}
+    writeNewFile(resolvePath12(options.out), `${JSON.stringify(manifest, null, 2)}
 `, "--out");
   }
   const generatedAt = manifest.generatedAt;
@@ -9923,7 +10583,7 @@ async function insightJira(studyId, options) {
   emit(options.json, manifest, () => {
     console.log(`[skill-forge] wrote Jira manifest for ${next.studyId}`);
     console.log(`  manifest: ${privatePath}`);
-    if (options.out) console.log(`  export:   ${resolvePath10(options.out)}`);
+    if (options.out) console.log(`  export:   ${resolvePath12(options.out)}`);
     console.log("  no Jira issues were created.");
   });
   if (options.handoff) {
@@ -9974,13 +10634,13 @@ async function insightClose(studyId, options) {
 
 // src/commands/refine.ts
 import { createHash as createHash8, randomUUID as randomUUID5 } from "crypto";
-import { chmodSync as chmodSync4, existsSync as existsSync29, lstatSync as lstatSync7, mkdirSync as mkdirSync11, readFileSync as readFileSync24, realpathSync as realpathSync10, renameSync as renameSync6, rmSync as rmSync9, writeFileSync as writeFileSync10 } from "fs";
-import { dirname as dirname15, isAbsolute as isAbsolute8, join as join35, relative as relative7, resolve as resolvePath13, sep as sep6 } from "path";
+import { chmodSync as chmodSync4, existsSync as existsSync30, lstatSync as lstatSync7, mkdirSync as mkdirSync11, readFileSync as readFileSync26, realpathSync as realpathSync11, renameSync as renameSync6, rmSync as rmSync9, writeFileSync as writeFileSync10 } from "fs";
+import { dirname as dirname15, isAbsolute as isAbsolute9, join as join38, relative as relative8, resolve as resolvePath15, sep as sep8 } from "path";
 import { createInterface as createInterface7 } from "readline/promises";
 
 // src/refine/context.ts
-import { existsSync as existsSync28, realpathSync as realpathSync9, statSync as statSync13 } from "fs";
-import { isAbsolute as isAbsolute7, join as join34, relative as relative6, resolve as resolvePath12 } from "path";
+import { existsSync as existsSync29, realpathSync as realpathSync10, statSync as statSync13 } from "fs";
+import { isAbsolute as isAbsolute8, join as join37, relative as relative7, resolve as resolvePath14 } from "path";
 
 // src/refine/models.ts
 import { randomBytes } from "crypto";
@@ -10050,26 +10710,26 @@ function contentSimilarity(a, b) {
 
 // src/refine/store.ts
 import { createHash as createHash7 } from "crypto";
-import { existsSync as existsSync27, readFileSync as readFileSync23, statSync as statSync12, realpathSync as realpathSync8 } from "fs";
-import { join as join33, resolve as resolvePath11 } from "path";
+import { existsSync as existsSync28, readFileSync as readFileSync25, statSync as statSync12, realpathSync as realpathSync9 } from "fs";
+import { join as join36, resolve as resolvePath13 } from "path";
 var SIMILARITY_JOIN_THRESHOLD = 0.7;
 var READY_THRESHOLD = 2;
 function getRefinementsDir() {
-  return join33(getHomeDir(), "refinements");
+  return join36(getHomeDir(), "refinements");
 }
 function getRefinementsPath() {
-  return join33(getRefinementsDir(), "refinements.json");
+  return join36(getRefinementsDir(), "refinements.json");
 }
 function getPatternsPath() {
-  return join33(getRefinementsDir(), "patterns.json");
+  return join36(getRefinementsDir(), "patterns.json");
 }
 function getBackupsDir() {
-  return join33(getRefinementsDir(), "backups");
+  return join36(getRefinementsDir(), "backups");
 }
 function readJsonFile(path, label2) {
   let raw;
   try {
-    raw = readFileSync23(path, "utf-8");
+    raw = readFileSync25(path, "utf-8");
   } catch (err) {
     throw new UserError(`unable to read ${label2} at ${path}: ${err.message}`);
   }
@@ -10080,7 +10740,7 @@ function readJsonFile(path, label2) {
   }
 }
 function readStore(path, label2, validateRecord) {
-  if (!existsSync27(path)) {
+  if (!existsSync28(path)) {
     return { schemaVersion: 1, records: [] };
   }
   const parsed = readJsonFile(path, label2);
@@ -10170,9 +10830,9 @@ function writePatternsStore(store) {
   writeJsonAtomic(getPatternsPath(), store);
 }
 function resolveProjectRealpath(projectRoot) {
-  const resolved = resolvePath11(projectRoot);
+  const resolved = resolvePath13(projectRoot);
   try {
-    return realpathSync8(resolved);
+    return realpathSync9(resolved);
   } catch {
     return resolved;
   }
@@ -10304,16 +10964,16 @@ function createBackup(filePaths, deps = {}) {
   const randomHex = deps.randomHex ?? defaultRandomHex;
   const id = `${formatBackupTimestamp(now)}-${randomHex()}`;
   const files = filePaths.map((path) => {
-    if (!existsSync27(path)) {
+    if (!existsSync28(path)) {
       return { path, existed: false, sha256: null, mode: null, contentBase64: null };
     }
-    const bytes = readFileSync23(path);
+    const bytes = readFileSync25(path);
     const mode = statSync12(path).mode & 511;
     const sha2562 = createHash7("sha256").update(bytes).digest("hex");
     return { path, existed: true, sha256: sha2562, mode, contentBase64: bytes.toString("base64") };
   });
   const manifest = { id, createdAt: now.toISOString(), files };
-  writeJsonAtomic(join33(getBackupsDir(), id, "manifest.json"), manifest);
+  writeJsonAtomic(join36(getBackupsDir(), id, "manifest.json"), manifest);
   return manifest;
 }
 function validateBackupManifestShape(value, path) {
@@ -10362,8 +11022,8 @@ 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 = join33(getBackupsDir(), id, "manifest.json");
-  if (!existsSync27(manifestPath)) {
+  const manifestPath = join36(getBackupsDir(), id, "manifest.json");
+  if (!existsSync28(manifestPath)) {
     throw new UserError(`no backup with id: ${id}`);
   }
   const parsed = readJsonFile(manifestPath, "backup manifest");
@@ -10373,7 +11033,7 @@ function readBackupManifest(id) {
 
 // src/refine/context.ts
 function resolveConfiguredRoot2(root) {
-  return resolvePath12(expandHome(root));
+  return resolvePath14(expandHome(root));
 }
 function assertPlainSkillName(name) {
   if (!name || name.trim().length === 0) {
@@ -10385,32 +11045,32 @@ function assertPlainSkillName(name) {
 }
 function realpathOrNull2(p) {
   try {
-    return realpathSync9(p);
+    return realpathSync10(p);
   } catch {
     return null;
   }
 }
 function isUnderRoot2(candidate, root) {
-  const rel = relative6(root, candidate);
-  return rel === "" || !rel.startsWith("..") && !isAbsolute7(rel);
+  const rel = relative7(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute8(rel);
 }
 function resolveScopes(config, cwd, skill, userRootFlag) {
   assertPlainSkillName(skill);
-  const resolvedCwd = resolvePath12(cwd);
-  const localDir = join34(resolvedCwd, ".claude", "skills", skill);
-  const sharedDir = join34(resolvedCwd, "skills", skill);
-  const local = { scope: "local", dir: localDir, exists: existsSync28(localDir) };
-  const shared = { scope: "shared", dir: sharedDir, exists: existsSync28(sharedDir) };
+  const resolvedCwd = resolvePath14(cwd);
+  const localDir = join37(resolvedCwd, ".claude", "skills", skill);
+  const sharedDir = join37(resolvedCwd, "skills", skill);
+  const local = { scope: "local", dir: localDir, exists: existsSync29(localDir) };
+  const shared = { scope: "shared", dir: sharedDir, exists: existsSync29(sharedDir) };
   const user = resolveUserScope(config, resolvedCwd, skill, userRootFlag);
   return { local, shared, user };
 }
 function resolveUserScope(config, resolvedCwd, skill, userRootFlag) {
   if (userRootFlag) {
-    const root = resolvePath12(userRootFlag);
-    return { resolved: true, dir: join34(root, skill), root: userRootFlag, reason: "flag" };
+    const root = resolvePath14(userRootFlag);
+    return { resolved: true, dir: join37(root, skill), root: userRootFlag, reason: "flag" };
   }
   const cwdReal = realpathOrNull2(resolvedCwd) ?? resolvedCwd;
-  const candidates = config.skillsRoots.map((root) => ({ root, dir: join34(resolveConfiguredRoot2(root), skill) }));
+  const candidates = config.skillsRoots.map((root) => ({ root, dir: join37(resolveConfiguredRoot2(root), skill) }));
   for (const candidate of candidates) {
     const skillReal = realpathOrNull2(candidate.dir);
     if (skillReal) {
@@ -10445,12 +11105,12 @@ function inventoryScopeDir(scope, dir) {
     scope,
     dir,
     dirExists: isDirectory(dir),
-    skillMd: isFile2(join34(dir, "SKILL.md")),
-    patchMd: isFile2(join34(dir, "SKILL.patch.md")),
-    extendMd: isFile2(join34(dir, "SKILL.extend.md")),
-    configJson: isFile2(join34(dir, "skill-config.json")),
-    hooksDir: isDirectory(join34(dir, "hooks")),
-    scriptsDir: isDirectory(join34(dir, "scripts"))
+    skillMd: isFile2(join37(dir, "SKILL.md")),
+    patchMd: isFile2(join37(dir, "SKILL.patch.md")),
+    extendMd: isFile2(join37(dir, "SKILL.extend.md")),
+    configJson: isFile2(join37(dir, "skill-config.json")),
+    hooksDir: isDirectory(join37(dir, "hooks")),
+    scriptsDir: isDirectory(join37(dir, "scripts"))
   };
 }
 function inventoryAllScopes(resolution) {
@@ -10719,18 +11379,18 @@ async function confirmWrite(yes, json, prompt) {
   }
 }
 function resolveConfiguredRoot3(root) {
-  return resolvePath13(expandHome(root));
+  return resolvePath15(expandHome(root));
 }
 function isUnderRoot3(candidate, root) {
-  const rel = relative7(root, candidate);
-  return rel === "" || !rel.startsWith("..") && !isAbsolute8(rel);
+  const rel = relative8(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute9(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 readFileSync24(resolvePath13(options.contentFile), "utf-8");
+  if (options.contentFile) return readFileSync26(resolvePath15(options.contentFile), "utf-8");
   return void 0;
 }
 function validateCaptureOptions(options) {
@@ -10865,10 +11525,10 @@ function ensureScopeDirSafe(scopeDir, resolvedCwd) {
   }
   mkdirSync11(scopeDir, { recursive: true });
   const real = resolveConfiguredRoot3(scopeDir);
-  const lexical = resolvePath13(scopeDir);
+  const lexical = resolvePath15(scopeDir);
   let realResolved;
   try {
-    realResolved = realpathSync10(scopeDir);
+    realResolved = realpathSync11(scopeDir);
   } catch {
     realResolved = real;
   }
@@ -10882,10 +11542,10 @@ function ensureScopeDirSafe(scopeDir, resolvedCwd) {
 }
 function writeOverrideFile(scopeDir, relPath, content, resolvedCwd) {
   const realScopeDir = ensureScopeDirSafe(scopeDir, resolvedCwd);
-  const destPath = join35(scopeDir, relPath);
+  const destPath = join38(scopeDir, relPath);
   const destDir = dirname15(destPath);
   mkdirSync11(destDir, { recursive: true });
-  const realDestDir = realpathSync10(destDir);
+  const realDestDir = realpathSync11(destDir);
   if (!isUnderRoot3(realDestDir, realScopeDir)) {
     throw new UserError(`refusing to write ${destPath}: resolves outside scope directory ${scopeDir}`);
   }
@@ -10978,12 +11638,12 @@ Write ${preview.destPath}? [y/N] `);
 }
 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 ? join35(scopeDir, probeRelPath) : void 0;
-  const existingContent = probePath && existsSync29(probePath) ? readFileSync24(probePath, "utf-8") : "";
+  const probePath = probeRelPath ? join38(scopeDir, probeRelPath) : void 0;
+  const existingContent = probePath && existsSync30(probePath) ? readFileSync26(probePath, "utf-8") : "";
   const rendered = renderCaptureArtifact(opts, content, refinementId, generatedAt, existingContent);
   const relPath = rendered.relPath;
-  const destPath = join35(scopeDir, relPath);
-  const before = existsSync29(destPath) ? readFileSync24(destPath, "utf-8") : "";
+  const destPath = join38(scopeDir, relPath);
+  const before = existsSync30(destPath) ? readFileSync26(destPath, "utf-8") : "";
   const diff = previewDiff(before, rendered.content, destPath);
   return { relPath, content: rendered.content, destPath, diff };
 }
@@ -10992,7 +11652,7 @@ async function refineListCommand(options = {}) {
   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 === resolvePath13(options.project));
+  if (options.project) rows = rows.filter((r) => r.project === options.project || r.projectRoot === resolvePath15(options.project));
   if (options.status) {
     if (!isRefinementStatus(options.status)) {
       throw new UserError("--status must be one of: pending, applied, generalized");
@@ -11029,7 +11689,7 @@ async function refinePatternsCommand(options = {}) {
   }
   if (options.skill) rows = rows.filter((p) => p.affectedSkills.includes(options.skill));
   if (options.project) {
-    const resolvedProject = resolvePath13(options.project);
+    const resolvedProject = resolvePath15(options.project);
     rows = rows.filter((p) => p.occurrences.some((o) => o.projectRealpath === resolvedProject));
   }
   const filtered = Boolean(options.skill || options.project || options.status);
@@ -11080,16 +11740,16 @@ async function refineWhichCommand(skill, options = {}) {
 }
 function writePostWriteSidecar(backupId, files) {
   const sidecar = { schemaVersion: 1, files };
-  const dir = join35(getBackupsDir(), backupId);
+  const dir = join38(getBackupsDir(), backupId);
   mkdirSync11(dir, { recursive: true });
-  writeFileSync10(join35(dir, "post.json"), JSON.stringify(sidecar, null, 2) + "\n", { mode: 384 });
+  writeFileSync10(join38(dir, "post.json"), JSON.stringify(sidecar, null, 2) + "\n", { mode: 384 });
 }
 function readPostWriteSidecar(backupId) {
-  const path = join35(getBackupsDir(), backupId, "post.json");
-  if (!existsSync29(path)) return { hashes: /* @__PURE__ */ new Map(), status: "missing" };
+  const path = join38(getBackupsDir(), backupId, "post.json");
+  if (!existsSync30(path)) return { hashes: /* @__PURE__ */ new Map(), status: "missing" };
   let raw;
   try {
-    raw = readFileSync24(path, "utf-8");
+    raw = readFileSync26(path, "utf-8");
   } catch {
     return { hashes: /* @__PURE__ */ new Map(), status: "unreadable" };
   }
@@ -11134,21 +11794,21 @@ async function refinePromoteCommand(patternId, options = {}) {
   const resolvedUserRoot = resolveConfiguredRoot3(scopes.user.root);
   let realUserRoot;
   try {
-    realUserRoot = realpathSync10(resolvedUserRoot);
+    realUserRoot = realpathSync11(resolvedUserRoot);
   } catch {
     realUserRoot = resolvedUserRoot;
   }
   let realSkillDir;
   try {
-    realSkillDir = realpathSync10(skillDir);
+    realSkillDir = realpathSync11(skillDir);
   } catch {
-    realSkillDir = resolvePath13(skillDir);
+    realSkillDir = resolvePath15(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 = join35(skillDir, "SKILL.md");
-  if (!existsSync29(skillMdPath)) {
+  const skillMdPath = join38(skillDir, "SKILL.md");
+  if (!existsSync30(skillMdPath)) {
     throw new UserError(`user-scope SKILL.md not found at ${skillMdPath} \u2014 refusing to promote against a missing base skill.`);
   }
   const refinementsStore = readRefinementsStore();
@@ -11165,7 +11825,7 @@ async function refinePromoteCommand(patternId, options = {}) {
       `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 = readFileSync24(skillMdPath, "utf-8");
+  const before = readFileSync26(skillMdPath, "utf-8");
   const after = applyPatchBlocks(before, [block]);
   const diff = previewDiff(before, after, skillMdPath);
   if (options.dryRun) {
@@ -11197,7 +11857,7 @@ Promote pattern ${patternId} into ${skillMdPath}? [y/N] `);
     throw err;
   }
   try {
-    const postSha256 = createHash8("sha256").update(readFileSync24(skillMdPath)).digest("hex");
+    const postSha256 = createHash8("sha256").update(readFileSync26(skillMdPath)).digest("hex");
     writePostWriteSidecar(backup.id, [{ path: skillMdPath, sha256: postSha256 }]);
     markGeneralized(patternId, backup.id);
     const skillsRoot = resolveConfiguredRoot3(scopes.user.root);
@@ -11223,25 +11883,25 @@ Promote pattern ${patternId} into ${skillMdPath}? [y/N] `);
 }
 function assertBackupDirContained(backupId) {
   const backupsDir = getBackupsDir();
-  if (!existsSync29(backupsDir)) return;
-  const realBackupsDir = realpathSync10(backupsDir);
-  const backupDir = join35(backupsDir, backupId);
-  if (!existsSync29(backupDir)) return;
-  const realBackupDir = realpathSync10(backupDir);
+  if (!existsSync30(backupsDir)) return;
+  const realBackupsDir = realpathSync11(backupsDir);
+  const backupDir = join38(backupsDir, backupId);
+  if (!existsSync30(backupDir)) return;
+  const realBackupDir = realpathSync11(backupDir);
   if (!isUnderRoot3(realBackupDir, realBackupsDir)) {
     throw new UserError(`refusing rollback: backup id "${backupId}" resolves outside the backups directory`);
   }
 }
 function resolveTargetRealPath(path) {
-  let lexicalAncestor = resolvePath13(path);
+  let lexicalAncestor = resolvePath15(path);
   while (true) {
     try {
-      const real = realpathSync10(lexicalAncestor);
-      const remainder = relative7(lexicalAncestor, resolvePath13(path));
-      return remainder === "" ? real : join35(real, remainder);
+      const real = realpathSync11(lexicalAncestor);
+      const remainder = relative8(lexicalAncestor, resolvePath15(path));
+      return remainder === "" ? real : join38(real, remainder);
     } catch {
       const parent = dirname15(lexicalAncestor);
-      if (parent === lexicalAncestor) return resolvePath13(path);
+      if (parent === lexicalAncestor) return resolvePath15(path);
       lexicalAncestor = parent;
     }
   }
@@ -11253,7 +11913,7 @@ function assertManifestPathsWithinRoots(manifest, config) {
   const roots = config.skillsRoots.map((root) => {
     const resolved = resolveConfiguredRoot3(root);
     try {
-      return realpathSync10(resolved);
+      return realpathSync11(resolved);
     } catch {
       return resolved;
     }
@@ -11280,14 +11940,14 @@ function assertNoSymlinkLeaves(manifest) {
   }
 }
 function findLexicalRoot(filePath, config) {
-  const lexicalTarget = resolvePath13(filePath);
+  const lexicalTarget = resolvePath15(filePath);
   for (const root of config.skillsRoots) {
     const rootLexical = resolveConfiguredRoot3(root);
-    const rel = relative7(rootLexical, lexicalTarget);
-    if (rel !== "" && (rel === ".." || rel.startsWith(`..${sep6}`) || isAbsolute8(rel))) continue;
+    const rel = relative8(rootLexical, lexicalTarget);
+    if (rel !== "" && (rel === ".." || rel.startsWith(`..${sep8}`) || isAbsolute9(rel))) continue;
     let rootReal;
     try {
-      rootReal = realpathSync10(rootLexical);
+      rootReal = realpathSync11(rootLexical);
     } catch {
       rootReal = rootLexical;
     }
@@ -11297,8 +11957,8 @@ function findLexicalRoot(filePath, config) {
 }
 function walkRealComponents(filePath, config, createMissing) {
   const { rootLexical, rootReal } = findLexicalRoot(filePath, config);
-  const relPath = relative7(rootLexical, resolvePath13(filePath));
-  const components = relPath.split(sep6).filter((c) => c.length > 0);
+  const relPath = relative8(rootLexical, resolvePath15(filePath));
+  const components = relPath.split(sep8).filter((c) => c.length > 0);
   if (components.length === 0) {
     throw new UserError(`refusing to operate on ${filePath}: resolves to the skills root itself`);
   }
@@ -11307,7 +11967,7 @@ function walkRealComponents(filePath, config, createMissing) {
   let current = rootReal;
   for (const component of dirComponents) {
     if (current === void 0) break;
-    const next = join35(current, component);
+    const next = join38(current, component);
     let lst;
     try {
       lst = lstatSync7(next);
@@ -11338,7 +11998,7 @@ function safeRestoreWrite(filePath, contentBuffer, mode, config) {
   if (parentReal === void 0) {
     throw new UserError(`refusing to restore ${filePath}: could not establish a real parent directory`);
   }
-  const finalPath = join35(parentReal, leafComponent);
+  const finalPath = join38(parentReal, leafComponent);
   if (!isUnderRoot3(finalPath, rootReal)) {
     throw new UserError(`refusing to restore ${filePath}: resolves outside root ${rootReal}`);
   }
@@ -11364,7 +12024,7 @@ function safeRestoreWrite(filePath, contentBuffer, mode, config) {
 function safeDeleteTombstone(filePath, config) {
   const { parentReal, leafComponent, rootReal } = walkRealComponents(filePath, config, false);
   if (parentReal === void 0) return;
-  const finalPath = join35(parentReal, leafComponent);
+  const finalPath = join38(parentReal, leafComponent);
   if (!isUnderRoot3(finalPath, rootReal)) {
     throw new UserError(`refusing to delete ${filePath}: resolves outside root ${rootReal}`);
   }
@@ -11406,7 +12066,7 @@ async function refineRollbackCommand(backupId, options = {}) {
   for (const file of manifest.files) {
     const expected = sidecar.hashes.get(file.path);
     if (expected === void 0) continue;
-    const currentSha256 = existsSync29(file.path) ? createHash8("sha256").update(readFileSync24(file.path)).digest("hex") : null;
+    const currentSha256 = existsSync30(file.path) ? createHash8("sha256").update(readFileSync26(file.path)).digest("hex") : null;
     if (currentSha256 !== expected) mismatches.push(file.path);
   }
   if (mismatches.length > 0 && !options.force) {
@@ -11497,6 +12157,13 @@ function parsePruneDays(value) {
   }
   return n;
 }
+function parseUsageWindow(value) {
+  const n = Number(value);
+  if (value.trim() === "" || !Number.isInteger(n) || n < 1) {
+    throw new UserError(`--usage-window must be a positive integer (got "${value}")`);
+  }
+  return n;
+}
 function parseInsightAnalysisMode(value) {
   if (value !== "independent" && value !== "single") {
     throw new UserError(`--analysis-mode must be "independent" or "single" (got "${value}")`);
@@ -11544,7 +12211,7 @@ configCmd.command("propose <key> <value>").description("Queue a preference for r
 configCmd.command("review").description("Review pending agent-proposed preferences one at a time").option("--accept-all", "accept every pending proposal without prompting").option("--reject-all", "reject every pending proposal without prompting").action(configReview);
 program.command("guide [topic]").description("What this tool does, what state you are in, and the next command to run").action(guide);
 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("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").option("--claude-plugins", "include enabled Claude Code plugins' declared skills in this audit (default: config.claudePlugins, else off)").option("--no-claude-plugins", "exclude enabled Claude Code plugins from this audit even when config.claudePlugins is on").option("--usage-snapshot <file>", "join per-skill usage counts from a skill-monitor snapshot JSON file or a directory of them (default: config.usageSnapshotPath)").option("--usage-window <days>", "restrict directory-input usage-snapshot selection to a snapshot with this window_days (integer)", parseUsageWindow).action(auditCommand);
 var finding = program.command("finding").description("Review and acknowledge audit findings \u2014 human-only, never a gate input (see docs/accepted-findings-schema.md)");
 finding.command("accept <fingerprint-prefix>").description("Accept a currently-active LOW/MEDIUM finding (no override for HIGH/CRITICAL); re-runs the audit engine to resolve it").requiredOption("--reason <text>", "why this finding is accepted (mandatory, 1-200 chars, no control characters)").option("--json", "print the accepted record as JSON").action(findingAcceptCommand);
 finding.command("revoke <fingerprint-prefix>").description("Remove a stored acceptance so the finding reports again").option("--json", "print the removed record as JSON").action(findingRevokeCommand);
@@ -11555,7 +12222,7 @@ program.command("watch").description("Drift check across every SOURCES.md proven
   "--skill-map <path>",
   "also drift-check every fork-of edge in a generated rhize-plugins skill map (contentHash compare against upstream)"
 ).action(watchCommand);
-program.command("routine").description("One scheduled maintenance pass: audit + drift + registry, one report, cron-friendly exit codes (Pro)").option("--json", "print the routine result as JSON instead of the terminal summary").option("--offline", "skip every network check (drift entries are reported unchecked)").option("--skip-watch", "skip the drift check").option("--skip-organize", "skip the capability registry").option("--fail-on <level>", "exit 1 when a finding at or above this severity exists: none|low|medium|high|critical|any (default none)", parseFailOn).option("--housekeeping", "opt in to bounded writes: prune expired quarantine sandboxes, close orphaned queue entries").option("--prune-days <n>", "quarantine age threshold in days for --housekeeping (default 30)", parsePruneDays).option("--dry-run", "with --housekeeping: report what would change, change nothing").option("--handoff", "hand the written report to the configured agent (curation prompt)").option("--report <file>", "write the report here instead of ~/.skill-forge/reports/routine-<timestamp>.md (refuses an existing path)").action(routineCommand);
+program.command("routine").description("One scheduled maintenance pass: audit + drift + registry, one report, cron-friendly exit codes (Pro)").option("--json", "print the routine result as JSON instead of the terminal summary").option("--offline", "skip every network check (drift entries are reported unchecked)").option("--skip-watch", "skip the drift check").option("--skip-organize", "skip the capability registry").option("--fail-on <level>", "exit 1 when a finding at or above this severity exists: none|low|medium|high|critical|any (default none)", parseFailOn).option("--housekeeping", "opt in to bounded writes: prune expired quarantine sandboxes, close orphaned queue entries").option("--prune-days <n>", "quarantine age threshold in days for --housekeeping (default 30)", parsePruneDays).option("--dry-run", "with --housekeeping: report what would change, change nothing").option("--handoff", "hand the written report to the configured agent (curation prompt)").option("--report <file>", "write the report here instead of ~/.skill-forge/reports/routine-<timestamp>.md (refuses an existing path)").option("--claude-plugins", "include enabled Claude Code plugins' declared skills in the audit step (default: config.claudePlugins, else off)").option("--no-claude-plugins", "exclude enabled Claude Code plugins from the audit step even when config.claudePlugins is on").option("--usage-snapshot <file>", "join per-skill usage counts from a skill-monitor snapshot JSON file or a directory of them (default: config.usageSnapshotPath)").option("--usage-window <days>", "restrict directory-input usage-snapshot selection to a snapshot with this window_days (integer)", parseUsageWindow).action(routineCommand);
 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);