@rhize/skill-forge 0.17.1 → 0.20.0

package/dist/cli.js

@@ -1,15 +1,5 @@
 #!/usr/bin/env node
 
-// src/cli.ts
-import { Command } from "commander";
-import { createRequire } from "module";
-
-// src/commands/add.ts
-import { join as join24 } from "path";
-
-// src/config.ts
-import { chmodSync, existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
-
 // src/errors.ts
 var UserError = class extends Error {
   constructor(message) {
@@ -18,6 +8,13 @@ var UserError = class extends Error {
   }
 };
 
+// src/pluginDecisions.ts
+import { existsSync as existsSync2, readFileSync as readFileSync3, realpathSync } from "fs";
+import { isAbsolute, join as join4, resolve } from "path";
+
+// src/config.ts
+import { chmodSync, existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+
 // src/gate/scanShared.ts
 import { readFileSync, readdirSync, statSync } from "fs";
 import { extname, join } from "path";
@@ -476,9 +473,6 @@ function saveConfig(config) {
   chmodSync(path, 384);
 }
 
-// src/install/resolve.ts
-import { existsSync as existsSync2 } from "fs";
-
 // src/util.ts
 import {
   accessSync,
@@ -596,11 +590,83 @@ function appendPrivateJsonLine(path, value) {
   }
 }
 
+// src/pluginDecisions.ts
+function projectIdentity(path) {
+  return realpathSync(resolve(path));
+}
+function validatePluginDecision(value) {
+  const d = value;
+  if (!d || !["claude", "codex"].includes(d.host) || typeof d.pluginId !== "string" || !/^[\w.-]+@[\w.-]+$/.test(d.pluginId) || !["essential", "project-specific", "intentionally-infrequent"].includes(d.category) || typeof d.reason !== "string" || !d.reason.trim() || d.reason.length > 2e3 || /[\x00-\x1f\x7f-\x9f\u200b-\u200f\u202a-\u202e\u2066-\u2069]/.test(d.reason) || d.project !== void 0 && (typeof d.project !== "string" || !isAbsolute(d.project)) || d.category === "project-specific" && !d.project || typeof d.updatedAt !== "string" || !Number.isFinite(Date.parse(d.updatedAt))) {
+    throw new UserError("Invalid plugin keep decision: require host, plugin@marketplace, category, reason, date, and a project for project-specific decisions.");
+  }
+  return { host: d.host, pluginId: d.pluginId, category: d.category, reason: d.reason.trim(), project: d.project, updatedAt: d.updatedAt };
+}
+function decisionKey(d) {
+  return JSON.stringify([d.host, d.pluginId, d.project ?? null]);
+}
+function readPluginDecisions() {
+  const path = join4(getHomeDir(), "plugin-decisions.json");
+  if (!existsSync2(path)) return [];
+  const store = JSON.parse(readFileSync3(path, "utf8"));
+  if (store.schemaVersion !== 1 || !Array.isArray(store.records)) throw new UserError("Invalid plugin-decisions.json schema.");
+  const records = store.records.map(validatePluginDecision);
+  if (new Set(records.map(decisionKey)).size !== records.length) throw new UserError("Duplicate plugin keep decisions.");
+  return records;
+}
+function writePluginDecisions(records) {
+  writeJsonAtomic(join4(getHomeDir(), "plugin-decisions.json"), { schemaVersion: 1, records: records.map(validatePluginDecision) });
+}
+function applyPluginDecisions(report, cwd = process.cwd()) {
+  try {
+    const records = readPluginDecisions();
+    const project = projectIdentity(cwd);
+    for (const plugin of report.plugins ?? []) {
+      const matches = records.filter((d) => d.host === (plugin.host ?? "claude") && d.pluginId === plugin.pluginId);
+      const decision = matches.find((d) => d.project === project) ?? matches.find((d) => !d.project);
+      if (!decision) continue;
+      plugin.keepDecision = decision;
+      if (plugin.recommendation !== "review") plugin.recommendation = "keep";
+    }
+  } catch (error) {
+    report.notices.push(`Plugin keep decisions unavailable; retention advice unchanged: ${error.message}`);
+  }
+}
+
+// src/commands/plugins.ts
+function pluginsKeepCommand(pluginId, options) {
+  const decision = validatePluginDecision({ ...options, pluginId, project: options.project ? projectIdentity(options.project) : void 0, updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
+  const records = readPluginDecisions().filter((d) => decisionKey(d) !== decisionKey(decision));
+  records.push(decision);
+  writePluginDecisions(records);
+  console.log(options.json ? JSON.stringify(decision, null, 2) : `Keep decision recorded for ${decision.host}:${pluginId}. Safety findings remain active.`);
+}
+function pluginsListCommand(options) {
+  const records = readPluginDecisions();
+  console.log(options.json ? JSON.stringify({ schemaVersion: 1, records }, null, 2) : records.map((d) => `${d.host}:${d.pluginId} \u2014 ${d.category}${d.project ? ` (${d.project})` : ""}: ${d.reason}`).join("\n") || "No explicit plugin keep decisions.");
+}
+function pluginsForgetCommand(pluginId, options) {
+  if (!["claude", "codex"].includes(options.host ?? "")) throw new UserError("--host claude|codex is required.");
+  const key = decisionKey({ host: options.host, pluginId, project: options.project ? projectIdentity(options.project) : void 0 });
+  const records = readPluginDecisions();
+  const remaining = records.filter((d) => decisionKey(d) !== key);
+  if (remaining.length === records.length) throw new UserError("No matching keep decision for that host, plugin and project.");
+  writePluginDecisions(remaining);
+  console.log(options.json ? JSON.stringify({ removed: true, pluginId }) : `Keep decision removed for ${options.host}:${pluginId}.`);
+}
+
+// src/cli.ts
+import { Command } from "commander";
+import { createRequire } from "module";
+
+// src/commands/add.ts
+import { join as join26 } from "path";
+
 // src/install/resolve.ts
+import { existsSync as existsSync3 } from "fs";
 var GIT_URL_PATTERN = /^(git@|https?:\/\/|ssh:\/\/)/;
 var LOCAL_PATH_PATTERN = /^(\.{1,2}\/|\/|~\/|~$)/;
 var NPM_SCOPED_PATTERN = /^@[^/]+\/[^/]+$/;
-function resolve(source, artifact = "skill") {
+function resolve2(source, artifact = "skill") {
   const value = source.trim();
   if (value.startsWith("-")) {
     throw new UserError(`skill source cannot start with "-" (looks like a flag, not a source): ${value}`);
@@ -609,7 +675,7 @@ function resolve(source, artifact = "skill") {
     return { type: "git", value };
   }
   const localCandidate = expandHome(value);
-  if (existsSync2(localCandidate) || LOCAL_PATH_PATTERN.test(value)) {
+  if (existsSync3(localCandidate) || LOCAL_PATH_PATTERN.test(value)) {
     return { type: "local", value: localCandidate };
   }
   if (artifact === "mcp" && (NPM_SCOPED_PATTERN.test(value) || !value.includes("/"))) {
@@ -621,14 +687,14 @@ function resolve(source, artifact = "skill") {
 // src/install/quarantine.ts
 import { randomUUID as randomUUID2 } from "crypto";
 import { spawn } from "child_process";
-import { cpSync, existsSync as existsSync3, mkdirSync as mkdirSync3, readdirSync as readdirSync2 } from "fs";
-import { basename as basename2, join as join4, resolve as resolvePath } from "path";
+import { cpSync, existsSync as existsSync4, mkdirSync as mkdirSync3, readdirSync as readdirSync2 } from "fs";
+import { basename as basename2, join as join5, resolve as resolvePath } from "path";
 var SKILL_MANIFEST = "SKILL.md";
 var SKIP_DIRS2 = /* @__PURE__ */ new Set([".git", "node_modules"]);
 async function quarantine(source, quarantineDir, deps = {}) {
   const exec = deps.exec ?? defaultExec;
   const id = randomUUID2();
-  const quarantinePath = join4(quarantineDir, id);
+  const quarantinePath = join5(quarantineDir, id);
   mkdirSync3(quarantinePath, { recursive: true });
   let packageDir;
   switch (source.type) {
@@ -644,7 +710,7 @@ async function quarantine(source, quarantineDir, deps = {}) {
       break;
     }
     case "git": {
-      const clonePath = join4(quarantinePath, deriveGitDirName(source.value));
+      const clonePath = join5(quarantinePath, deriveGitDirName(source.value));
       const result = await exec("git", ["clone", "--depth", "1", "--", source.value, clonePath], {
         cwd: quarantinePath
       });
@@ -656,11 +722,11 @@ async function quarantine(source, quarantineDir, deps = {}) {
       break;
     }
     case "local": {
-      if (!existsSync3(source.value)) {
+      if (!existsSync4(source.value)) {
         throw new UserError(`local path not found: ${source.value}`);
       }
       const dirName = basename2(resolvePath(source.value));
-      cpSync(source.value, join4(quarantinePath, dirName), { recursive: true });
+      cpSync(source.value, join5(quarantinePath, dirName), { recursive: true });
       break;
     }
     case "npm": {
@@ -674,7 +740,7 @@ async function quarantine(source, quarantineDir, deps = {}) {
           `npm pack failed for "${source.value}" (exit ${packResult.code}): ${packResult.stderr || packResult.stdout}`
         );
       }
-      const tarballPath = join4(quarantinePath, findTarball(quarantinePath, source.value));
+      const tarballPath = join5(quarantinePath, findTarball(quarantinePath, source.value));
       const listResult = await exec("tar", ["-tzf", tarballPath], { cwd: quarantinePath });
       if (listResult.code !== 0) {
         throw new UserError(
@@ -690,8 +756,8 @@ async function quarantine(source, quarantineDir, deps = {}) {
           `tarball extraction failed for "${source.value}" (exit ${extractResult.code}): ${extractResult.stderr || extractResult.stdout}`
         );
       }
-      packageDir = join4(quarantinePath, "package");
-      if (!existsSync3(packageDir)) {
+      packageDir = join5(quarantinePath, "package");
+      if (!existsSync4(packageDir)) {
         throw new UserError(
           `npm pack for "${source.value}" did not produce the expected package/ dir after extraction`
         );
@@ -705,7 +771,7 @@ async function quarantine(source, quarantineDir, deps = {}) {
   return { id, quarantinePath, skillDirs: findSkillDirs(quarantinePath), packageDir, source };
 }
 function listQuarantineIds(quarantineDir) {
-  if (!existsSync3(quarantineDir)) return [];
+  if (!existsSync4(quarantineDir)) return [];
   return readdirSync2(quarantineDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
 }
 function findSkillDirs(root) {
@@ -722,7 +788,7 @@ function findSkillDirs(root) {
     }
     for (const entry of entries) {
       if (entry.isDirectory() && !SKIP_DIRS2.has(entry.name)) {
-        walk2(join4(dir, entry.name));
+        walk2(join5(dir, entry.name));
       }
     }
   }
@@ -765,27 +831,27 @@ function defaultExec(command, args, options) {
 }
 
 // src/install/promote.ts
-import { cpSync as cpSync2, existsSync as existsSync4, mkdirSync as mkdirSync4, renameSync as renameSync2, rmSync as rmSync2 } from "fs";
-import { basename as basename3, join as join6 } from "path";
+import { cpSync as cpSync2, existsSync as existsSync5, mkdirSync as mkdirSync4, renameSync as renameSync2, rmSync as rmSync2 } from "fs";
+import { basename as basename3, join as join7 } from "path";
 
 // src/install/fingerprint.ts
 import { createHash } from "crypto";
-import { lstatSync as lstatSync2, readFileSync as readFileSync3, readdirSync as readdirSync3, readlinkSync, realpathSync } from "fs";
-import { isAbsolute, join as join5, relative, sep } from "path";
+import { lstatSync as lstatSync2, readFileSync as readFileSync4, readdirSync as readdirSync3, readlinkSync, realpathSync as realpathSync2 } from "fs";
+import { isAbsolute as isAbsolute2, join as join6, relative, sep } from "path";
 var SKIP_DIRS3 = /* @__PURE__ */ new Set([".git", "node_modules"]);
 function isInside(child, root) {
   const rel = relative(root, child);
-  return rel === "" || !rel.startsWith(".." + sep) && rel !== ".." && !isAbsolute(rel);
+  return rel === "" || !rel.startsWith(".." + sep) && rel !== ".." && !isAbsolute2(rel);
 }
 function fingerprintTree(root) {
   const hash = createHash("sha256");
   const symlinks = [];
   const escaping = [];
-  const realRoot = realpathSync(root);
+  const realRoot = realpathSync2(root);
   function walk2(dir) {
     const entries = readdirSync3(dir, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
     for (const entry of entries) {
-      const full = join5(dir, entry.name);
+      const full = join6(dir, entry.name);
       const rel = relative(root, full);
       if (entry.isSymbolicLink()) {
         const target = readlinkSync(full);
@@ -793,7 +859,7 @@ function fingerprintTree(root) {
         hash.update(`L	${rel}	${target}
 `);
         try {
-          if (!isInside(realpathSync(full), realRoot)) escaping.push(rel);
+          if (!isInside(realpathSync2(full), realRoot)) escaping.push(rel);
         } catch {
           escaping.push(rel);
         }
@@ -807,7 +873,7 @@ function fingerprintTree(root) {
         continue;
       }
       if (entry.isFile()) {
-        const contentHash = createHash("sha256").update(readFileSync3(full)).digest("hex");
+        const contentHash = createHash("sha256").update(readFileSync4(full)).digest("hex");
         hash.update(`F	${rel}	${contentHash}
 `);
         continue;
@@ -856,8 +922,8 @@ function promote(entry, targetSkillsRoot, options = {}) {
         `refusing to promote ${skillDir}: it is no longer a real directory (a symlink or a deleted path) \u2014 re-run the gate on this candidate`
       );
     }
-    const dest = join6(targetSkillsRoot, basename3(skillDir));
-    if (existsSync4(dest) && !force) {
+    const dest = join7(targetSkillsRoot, basename3(skillDir));
+    if (existsSync5(dest) && !force) {
       throw new Error(`Refusing to overwrite existing skill dir: ${dest} (pass force to override)`);
     }
   }
@@ -876,8 +942,8 @@ function promote(entry, targetSkillsRoot, options = {}) {
   mkdirSync4(targetSkillsRoot, { recursive: true });
   const promoted = [];
   for (const skillDir of entry.skillDirs) {
-    const dest = join6(targetSkillsRoot, basename3(skillDir));
-    if (existsSync4(dest)) {
+    const dest = join7(targetSkillsRoot, basename3(skillDir));
+    if (existsSync5(dest)) {
       rmSync2(dest, { recursive: true, force: true });
     }
     moveDir(skillDir, dest);
@@ -905,7 +971,7 @@ function moveDir(src, dest) {
 }
 
 // src/install/promoteMcp.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname2 } from "path";
 function promoteMcp(_entry, profile, targetConfigPath, options = {}) {
   const force = options.force ?? false;
@@ -913,8 +979,8 @@ function promoteMcp(_entry, profile, targetConfigPath, options = {}) {
   const { command, args, envVarsToFill, autoPinned } = deriveServerEntry(profile);
   let config = {};
   let rawExisting;
-  if (existsSync5(targetConfigPath)) {
-    rawExisting = readFileSync4(targetConfigPath, "utf-8");
+  if (existsSync6(targetConfigPath)) {
+    rawExisting = readFileSync5(targetConfigPath, "utf-8");
     try {
       config = JSON.parse(rawExisting);
     } catch (err) {
@@ -998,11 +1064,11 @@ function deriveServerEntry(profile) {
 }
 
 // src/install/mcpCandidate.ts
-import { readFileSync as readFileSync5 } from "fs";
-import { dirname as dirname3, join as join7 } from "path";
+import { readFileSync as readFileSync6 } from "fs";
+import { dirname as dirname3, join as join8 } from "path";
 function readPackageInfo(pkgPath) {
   try {
-    const pkg2 = JSON.parse(readFileSync5(pkgPath, "utf-8"));
+    const pkg2 = JSON.parse(readFileSync6(pkgPath, "utf-8"));
     return {
       name: typeof pkg2.name === "string" ? pkg2.name : void 0,
       version: typeof pkg2.version === "string" ? pkg2.version : void 0
@@ -1013,7 +1079,7 @@ function readPackageInfo(pkgPath) {
 }
 function readConfigEntry(configPath, name) {
   try {
-    const cfg = JSON.parse(readFileSync5(configPath, "utf-8"));
+    const cfg = JSON.parse(readFileSync6(configPath, "utf-8"));
     const servers = cfg.mcpServers ?? cfg.servers ?? {};
     const raw = servers[name] ?? {};
     return {
@@ -1031,7 +1097,7 @@ function resolveMcpCandidateDetail(profile) {
     return { name, version: readPackageInfo(profile.config).version };
   }
   const entry = readConfigEntry(profile.config, name);
-  const sidecar = readPackageInfo(join7(dirname3(profile.config), "package.json"));
+  const sidecar = readPackageInfo(join8(dirname3(profile.config), "package.json"));
   return {
     name,
     command: entry?.command,
@@ -1043,8 +1109,8 @@ function resolveMcpCandidateDetail(profile) {
 }
 
 // src/provenance.ts
-import { appendFileSync, existsSync as existsSync6, readFileSync as readFileSync6, statSync as statSync3, writeFileSync as writeFileSync4 } from "fs";
-import { join as join8 } from "path";
+import { appendFileSync, existsSync as existsSync7, readFileSync as readFileSync7, statSync as statSync3, writeFileSync as writeFileSync4 } from "fs";
+import { join as join9 } from "path";
 var FORGE_VERBS = ["DEFER", "ABSORB", "FORK", "REJECT", "WATCH"];
 var LEDGER_HEADER = "# Skill Forge \u2014 Provenance Ledger\n\nOne entry per external-skill ingestion decision.\n";
 function todayLocalIsoDate() {
@@ -1058,7 +1124,7 @@ function appendProvenance(entry, skillsRoot) {
   if (!FORGE_VERBS.includes(entry.verb)) {
     throw new Error(`verb must be one of ${FORGE_VERBS.join(", ")}`);
   }
-  if (!existsSync6(skillsRoot) || !statSync3(skillsRoot).isDirectory()) {
+  if (!existsSync7(skillsRoot) || !statSync3(skillsRoot).isDirectory()) {
     throw new Error(`skills-root not a directory: ${skillsRoot}`);
   }
   const today = todayLocalIsoDate();
@@ -1075,8 +1141,8 @@ function appendProvenance(entry, skillsRoot) {
 - **Drift check:** \`${driftCheck}\`
 - **Notes:** ${entry.notes ?? ""}
 `;
-  const ledgerPath = join8(skillsRoot, "SOURCES.md");
-  if (!existsSync6(ledgerPath)) {
+  const ledgerPath = join9(skillsRoot, "SOURCES.md");
+  if (!existsSync7(ledgerPath)) {
     writeFileSync4(ledgerPath, LEDGER_HEADER, "utf-8");
   }
   appendFileSync(ledgerPath, block, "utf-8");
@@ -1123,11 +1189,11 @@ function parseProvenanceLedger(text) {
   return { entries, warnings };
 }
 function readProvenanceLedger(skillsRoot) {
-  const ledgerPath = join8(skillsRoot, "SOURCES.md");
-  if (!existsSync6(ledgerPath)) {
+  const ledgerPath = join9(skillsRoot, "SOURCES.md");
+  if (!existsSync7(ledgerPath)) {
     return { ledgerPath, exists: false, entries: [], warnings: [] };
   }
-  const text = readFileSync6(ledgerPath, "utf-8");
+  const text = readFileSync7(ledgerPath, "utf-8");
   const parsed = parseProvenanceLedger(text);
   return { ledgerPath, exists: true, ...parsed };
 }
@@ -1136,28 +1202,134 @@ function readProvenanceLedger(skillsRoot) {
 import { readdirSync as readdirSync7 } from "fs";
 
 // src/auditState.ts
-import { existsSync as existsSync10, readFileSync as readFileSync10 } from "fs";
-import { basename as basename7, dirname as dirname5, join as join13 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync12 } from "fs";
+import { basename as basename7, dirname as dirname5, join as join14 } from "path";
+
+// src/auditComparison.ts
+import { readFileSync as readFileSync8 } from "fs";
+import { relative as relative2, sep as sep2 } from "path";
+function targetIdentity(report, target) {
+  for (const p of report.plugins ?? []) {
+    const rel = relative2(p.installPath, target);
+    if (rel !== ".." && !rel.startsWith(".." + sep2) && !rel.startsWith(sep2)) return `${p.host ?? "claude"}:${p.pluginId}/${rel}`;
+  }
+  return target;
+}
+function scope(report) {
+  return JSON.stringify({
+    host: report.hostInventory?.host ?? (report.plugins ? "claude" : "configured"),
+    roots: report.inventory.skillRoots.filter((r) => r.origin !== "plugin").map((r) => r.root).sort(),
+    skills: report.inventory.skills.map((s) => targetIdentity(report, s.path)).sort(),
+    mcp: report.inventory.mcpTargets.map((m) => m.path).sort(),
+    plugins: report.plugins?.map((p) => p.pluginId).sort()
+  });
+}
+function incomplete(report) {
+  return report.hostInventory?.complete === false || report.hygiene.some((f) => /unreadable|missing|symlink|parse|invalid/.test(f.rule));
+}
+function compareAudits(current, previous) {
+  const result = { baselineAt: previous?.generatedAt, comparable: false, added: [], changed: [], resolved: [], unchanged: 0 };
+  if (!previous || previous.schemaVersion !== 1 || !previous.inventory || !Array.isArray(previous.hygiene) || !Array.isArray(previous.inventory.skills) || !Array.isArray(previous.inventory.skillRoots) || !Array.isArray(previous.inventory.mcpTargets)) {
+    return { ...result, reason: "Baseline must be a full schema-v1 audit JSON, not a routine/audit-state summary." };
+  }
+  if (!Number.isFinite(Date.parse(previous.generatedAt)) || Date.parse(previous.generatedAt) > Date.parse(current.generatedAt)) return { ...result, reason: "Baseline timestamp is invalid or newer than the current audit." };
+  if (incomplete(current) || incomplete(previous) || scope(current) !== scope(previous)) {
+    return { ...result, reason: "Inventory scope changed or a scan is incomplete; no resolution claims can be made. Review the full findings." };
+  }
+  const groups = (report) => {
+    const map = /* @__PURE__ */ new Map();
+    for (const f of report.hygiene) {
+      const key = JSON.stringify([targetIdentity(report, f.target), f.rule]);
+      map.set(key, [...map.get(key) ?? [], f]);
+    }
+    return map;
+  };
+  const old = groups(previous), next = groups(current);
+  const content = (f) => JSON.stringify([f.severity, f.context ?? f.detail, f.classification ?? null]);
+  for (const key of /* @__PURE__ */ new Set([...old.keys(), ...next.keys()])) {
+    const before = [...old.get(key) ?? []];
+    const after = [...next.get(key) ?? []];
+    for (let i = after.length - 1; i >= 0; i--) {
+      const match = before.findIndex((f) => content(f) === content(after[i]));
+      if (match >= 0) {
+        before.splice(match, 1);
+        after.splice(i, 1);
+        result.unchanged++;
+      }
+    }
+    for (let i = after.length - 1; i >= 0; i--) {
+      const identity = after[i].context ?? after[i].detail;
+      const matches = before.map((f, n) => (f.context ?? f.detail) === identity ? n : -1).filter((n) => n >= 0);
+      if (matches.length === 1 && after.filter((f) => (f.context ?? f.detail) === identity).length === 1) {
+        result.changed.push({ before: before.splice(matches[0], 1)[0], after: after.splice(i, 1)[0] });
+      }
+    }
+    if (before.length === 1 && after.length === 1) result.changed.push({ before: before[0], after: after[0] });
+    else {
+      result.added.push(...after);
+      result.resolved.push(...before);
+    }
+  }
+  result.comparable = true;
+  const previousSkills = new Map(previous.inventory.skills.map((skill) => [skill.path, skill]));
+  let coveredSkills = 0;
+  let descriptionCodePointDelta = 0;
+  let entrypointCodePointDelta = 0;
+  for (const skill of current.inventory.skills) {
+    const prior = previousSkills.get(skill.path);
+    const currentDiagnostics = skill.instructionDiagnostics;
+    const priorDiagnostics = prior?.instructionDiagnostics;
+    if (!prior || !currentDiagnostics || !priorDiagnostics) continue;
+    coveredSkills++;
+    descriptionCodePointDelta += (currentDiagnostics.discovery.description?.unicodeCodePoints ?? 0) - (priorDiagnostics.discovery.description?.unicodeCodePoints ?? 0);
+    entrypointCodePointDelta += currentDiagnostics.entrypoint.unicodeCodePoints - priorDiagnostics.entrypoint.unicodeCodePoints;
+  }
+  result.instructionDiagnostics = coveredSkills > 0 ? { comparable: true, hostLoad: "unknown", coveredSkills, descriptionCodePointDelta, entrypointCodePointDelta } : { comparable: false, hostLoad: "unknown", reason: "Instruction diagnostics are unavailable in one or both report inventories.", coveredSkills: 0 };
+  return result;
+}
+function loadAuditComparison(current, path) {
+  try {
+    return compareAudits(current, JSON.parse(readFileSync8(path, "utf8")));
+  } catch (error) {
+    return { comparable: false, reason: `Baseline unusable: ${error.message}`, added: [], changed: [], resolved: [], unchanged: 0 };
+  }
+}
+function renderAuditComparison(comparison) {
+  const c = comparison;
+  return ["## Changes since prior audit", "", ...c.comparable ? [
+    `${c.added.length} new \xB7 ${c.changed.length} changed \xB7 ${c.resolved.length} no longer active \xB7 ${c.unchanged} unchanged.`,
+    ...c.instructionDiagnostics?.comparable ? [`Instruction diagnostics: ${c.instructionDiagnostics.coveredSkills} shared skill(s); description ${signed(c.instructionDiagnostics.descriptionCodePointDelta ?? 0)} code points, entrypoint ${signed(c.instructionDiagnostics.entrypointCodePointDelta ?? 0)} code points.`] : c.instructionDiagnostics ? [`Instruction diagnostics unavailable: ${c.instructionDiagnostics.reason}`] : [],
+    "No longer active can include accepted findings; it does not prove a security fix.",
+    "",
+    ...c.added.map((f) => `- NEW ${f.severity} [${sanitizeForMarkdown(f.rule)}] ${sanitizeForMarkdown(f.target)}`),
+    ...c.changed.map((f) => `- CHANGED ${f.before.severity} \u2192 ${f.after.severity} [${sanitizeForMarkdown(f.after.rule)}] ${sanitizeForMarkdown(f.after.target)}`),
+    ...c.resolved.map((f) => `- NO LONGER ACTIVE [${sanitizeForMarkdown(f.rule)}] ${sanitizeForMarkdown(f.target)}`)
+  ] : [sanitizeForMarkdown(c.reason ?? "Comparison unavailable.")], ""];
+}
+function signed(value) {
+  return value >= 0 ? `+${value}` : String(value);
+}
 
 // src/audit.ts
 import {
-  existsSync as existsSync9,
+  existsSync as existsSync10,
   lstatSync as lstatSync3,
   mkdtempSync,
-  readFileSync as readFileSync9,
+  opendirSync,
+  readFileSync as readFileSync11,
   readdirSync as readdirSync5,
-  realpathSync as realpathSync2,
+  realpathSync as realpathSync3,
   renameSync as renameSync3,
   rmSync as rmSync3,
   statSync as statSync6,
   writeFileSync as writeFileSync5
 } from "fs";
-import { basename as basename6, delimiter as delimiter3, extname as extname4, join as join12, resolve as resolvePath2, sep as sep2 } from "path";
+import { basename as basename6, delimiter as delimiter3, extname as extname4, join as join13, resolve as resolvePath2, sep as sep3 } from "path";
 
 // src/gate/safety.ts
 import { statSync as statSync4 } from "fs";
 import { execFile } from "child_process";
-import { delimiter as delimiter2, extname as extname2, join as join9 } from "path";
+import { delimiter as delimiter2, extname as extname2, join as join10 } from "path";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
 var RM_RF_TARGET_RE = /\brm\s+(?:-[a-z]+\s+)+("[^"]*"|'[^']*'|[^\s;|&)"'`]+)/i;
@@ -1203,6 +1375,10 @@ function hasUnnegatedInstallCue(line) {
 }
 function refineCurlPipeShell(line, ctx) {
   const base = { severity: "CRITICAL", message: "downloads a remote script and pipes it directly into a shell" };
+  const pipelines = [...line.matchAll(/\b(?:curl|wget)\b[^\n|]*\|\s*(?:sudo\s+)?(?:bash|sh|zsh)\b([^|;\n]*)/gi)];
+  if (!/\$\(|`/.test(line) && pipelines.length && pipelines.every((m) => /^\s+(?:\.\/)?(?:[a-zA-Z0-9_-]+\/)*[a-zA-Z0-9_-]+\.sh(?:\s|$)/.test(m[1]))) {
+    return { ...base, message: "passes downloaded data to a named local shell script; inspect that script for evaluation of stdin before use", classification: "local-script-input" };
+  }
   if (ctx.inFence) return base;
   if (!DOC_EXTENSIONS.has(extname2(ctx.file).toLowerCase())) return base;
   if (!DOC_CUE_RE.test(line)) return base;
@@ -1291,7 +1467,7 @@ var DENY_RULES = [
     message: "invokes sudo \u2014 review for unnecessary privilege escalation"
   }
 ];
-function scanStaticRules(targetPath) {
+function scanStaticRules(targetPath, capturedFiles) {
   const findings = [];
   let root;
   try {
@@ -1300,8 +1476,8 @@ function scanStaticRules(targetPath) {
     return findings;
   }
   const files = root.isDirectory() ? Array.from(walk(targetPath)) : [targetPath];
-  for (const file of files) {
-    const content = readTextFile(file);
+  const sources = capturedFiles ?? files.map((file) => ({ file, content: readTextFile(file) }));
+  for (const { file, content } of sources) {
     if (content === void 0) continue;
     const lines = content.split("\n");
     const fenceFlags = DOC_EXTENSIONS.has(extname2(file).toLowerCase()) ? computeFenceFlags(lines) : void 0;
@@ -1330,7 +1506,7 @@ function which(cmd) {
   const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
   for (const dir of dirs) {
     for (const ext of exts) {
-      const candidate = join9(dir, cmd + ext);
+      const candidate = join10(dir, cmd + ext);
       try {
         if (statSync4(candidate).isFile()) return candidate;
       } catch {
@@ -1364,8 +1540,8 @@ async function scanWithSkillSpector(targetPath) {
     return [];
   }
 }
-async function scanSafety(targetPath, strictness = DEFAULT_STRICTNESS) {
-  const findings = [...scanStaticRules(targetPath), ...await scanWithSkillSpector(targetPath)];
+async function scanSafety(targetPath, strictness = DEFAULT_STRICTNESS, capturedFiles) {
+  const findings = [...scanStaticRules(targetPath, capturedFiles), ...await scanWithSkillSpector(targetPath)];
   return { findings, verdict: verdictFor(findings, strictness) };
 }
 
@@ -1605,8 +1781,8 @@ async function mcpScan(targetPath, strictness = DEFAULT_STRICTNESS) {
 }
 
 // src/gate/overlap.ts
-import { existsSync as existsSync7, readFileSync as readFileSync7, readdirSync as readdirSync4 } from "fs";
-import { basename as basename5, dirname as dirname4, join as join10, resolve as resolve2 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync9, readdirSync as readdirSync4 } from "fs";
+import { basename as basename5, dirname as dirname4, join as join11, resolve as resolve3 } from "path";
 var STOPWORDS = new Set(
   `
 a an the and or of to for in on with use used using when whether this that these those is are be
@@ -1615,20 +1791,20 @@ skill skills user claude code based comprehensive enhanced practical including i
 `.split(/\s+/).filter(Boolean)
 );
 var DEFAULT_SET_THRESHOLD = 0.45;
-function splitLimited(text, sep9, maxSplit) {
+function splitLimited(text, sep11, maxSplit) {
   const parts = [];
   let rest = text;
   for (let i = 0; i < maxSplit; i++) {
-    const idx = rest.indexOf(sep9);
+    const idx = rest.indexOf(sep11);
     if (idx === -1) break;
     parts.push(rest.slice(0, idx));
-    rest = rest.slice(idx + sep9.length);
+    rest = rest.slice(idx + sep11.length);
   }
   parts.push(rest);
   return parts;
 }
 function readFrontmatter(skillMdPath) {
-  const text = readFileSync7(skillMdPath, "utf-8");
+  const text = readFileSync9(skillMdPath, "utf-8");
   const meta = { name: basename5(dirname4(skillMdPath)), description: "" };
   if (text.startsWith("---\n")) {
     const block = splitLimited(text, "---", 2)[1] ?? "";
@@ -1723,47 +1899,47 @@ function suggestVerbCode(topScore) {
   return verbTier(topScore).verb;
 }
 function listSubdirs(dir) {
-  if (!existsSync7(dir)) return [];
+  if (!existsSync8(dir)) return [];
   let entries;
   try {
     entries = readdirSync4(dir, { withFileTypes: true });
   } catch {
     return [];
   }
-  return entries.filter((e) => e.isDirectory()).map((e) => join10(dir, e.name));
+  return entries.filter((e) => e.isDirectory()).map((e) => join11(dir, e.name));
 }
 function findSkillMdFiles(root) {
   const found = /* @__PURE__ */ new Set();
   for (const dir of listSubdirs(root)) {
-    const candidate = join10(dir, "SKILL.md");
-    if (existsSync7(candidate)) found.add(resolve2(candidate));
+    const candidate = join11(dir, "SKILL.md");
+    if (existsSync8(candidate)) found.add(resolve3(candidate));
   }
-  for (const dir of listSubdirs(join10(root, "skills"))) {
-    const candidate = join10(dir, "SKILL.md");
-    if (existsSync7(candidate)) found.add(resolve2(candidate));
+  for (const dir of listSubdirs(join11(root, "skills"))) {
+    const candidate = join11(dir, "SKILL.md");
+    if (existsSync8(candidate)) found.add(resolve3(candidate));
   }
   for (const topDir of listSubdirs(root)) {
-    for (const dir of listSubdirs(join10(topDir, "skills"))) {
-      const candidate = join10(dir, "SKILL.md");
-      if (existsSync7(candidate)) found.add(resolve2(candidate));
+    for (const dir of listSubdirs(join11(topDir, "skills"))) {
+      const candidate = join11(dir, "SKILL.md");
+      if (existsSync8(candidate)) found.add(resolve3(candidate));
     }
   }
   return Array.from(found).filter((p) => !p.includes("/.git/")).sort();
 }
 function scanOverlap(candidatePath, skillsRoot) {
-  const root = resolve2(expandHome(skillsRoot));
+  const root = resolve3(expandHome(skillsRoot));
   if (!isDir(root)) {
     throw new Error(`skills-root not a directory: ${root}`);
   }
-  let cpath = resolve2(expandHome(candidatePath));
+  let cpath = resolve3(expandHome(candidatePath));
   if (isDir(cpath)) {
-    cpath = join10(cpath, "SKILL.md");
+    cpath = join11(cpath, "SKILL.md");
   }
-  if (!existsSync7(cpath)) {
+  if (!existsSync8(cpath)) {
     throw new Error(`candidate SKILL.md not found: ${cpath}`);
   }
   const cand = readFrontmatter(cpath);
-  const existing = findSkillMdFiles(root).filter((p) => p !== resolve2(cpath));
+  const existing = findSkillMdFiles(root).filter((p) => p !== resolve3(cpath));
   if (existing.length === 0) {
     throw new Error(`no existing skills found under ${root}`);
   }
@@ -1804,8 +1980,8 @@ function scanOverlapPaths(skillMdPaths, threshold = DEFAULT_SET_THRESHOLD) {
 
 // src/findings.ts
 import { createHash as createHash2 } from "crypto";
-import { existsSync as existsSync8, readFileSync as readFileSync8 } from "fs";
-import { join as join11 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync10 } from "fs";
+import { join as join12 } from "path";
 var FINGERPRINT_DISPLAY_LENGTH = 12;
 var MIN_FINGERPRINT_PREFIX_LENGTH = 8;
 var FINGERPRINT_HEX_RE = /^[0-9a-f]{64}$/;
@@ -1818,7 +1994,7 @@ function fingerprintFinding(f) {
   return createHash2("sha256").update(`${f.severity}\0${f.rule}\0${f.target}\0${f.context}`).digest("hex");
 }
 function getAcceptedFindingsPath() {
-  return join11(getHomeDir(), "accepted-findings.json");
+  return join12(getHomeDir(), "accepted-findings.json");
 }
 function invalidRecordReason(record) {
   if (typeof record !== "object" || record === null) return "not an object";
@@ -1838,10 +2014,10 @@ function invalidRecordReason(record) {
 }
 function readAcceptedFindings() {
   const path = getAcceptedFindingsPath();
-  if (!existsSync8(path)) return { records: [], notices: [] };
+  if (!existsSync9(path)) return { records: [], notices: [] };
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync8(path, "utf-8"));
+    parsed = JSON.parse(readFileSync10(path, "utf-8"));
   } catch {
     return { records: [], notices: ["accepted-findings store unreadable (corrupt JSON) \u2014 nothing suppressed this run"] };
   }
@@ -1971,6 +2147,43 @@ function proFeatureStatus(feature, betaFree = BETA_FREE) {
   };
 }
 
+// src/instructionDiagnostics.ts
+function instructionTextMetrics(text) {
+  const utf8Bytes = Buffer.byteLength(text, "utf8");
+  return { utf8Bytes, unicodeCodePoints: Array.from(text).length, words: text.match(/\S+/gu)?.length ?? 0, estimatedTokens: Math.ceil(utf8Bytes / 4) };
+}
+function skillEntrypointBody(text) {
+  const opening = text.match(/^---[ \t]*\r?\n/);
+  if (!opening) return text;
+  const closing = /^---[ \t]*(?:\r?\n|$)/gm;
+  closing.lastIndex = opening[0].length;
+  const match = closing.exec(text);
+  return match ? text.slice(match.index + match[0].length) : text;
+}
+function diagnoseInstructions(name, description, entrypoint, resources) {
+  const inputs = Array.isArray(resources) ? resources : Object.entries(resources).map(([directory, files]) => ({ directory, files }));
+  const inventory = [...inputs].sort((a, b) => a.directory.localeCompare(b.directory)).map(({ directory, files, unavailableReason }) => ({
+    directory,
+    ...unavailableReason ? { status: "unavailable", reason: unavailableReason } : { status: "available", files: files ?? 0 },
+    routedFromEntrypoint: new RegExp(`(?:^|[^A-Za-z0-9_-])${escapeRegExp(directory)}/`, "m").test(entrypoint)
+  }));
+  const advice = [];
+  if (description && instructionTextMetrics(description).unicodeCodePoints > 500) advice.push({ kind: "long-description", detail: "description exceeds the advisory 500-code-point review bucket" });
+  if (description && /\b(?:always|any|every|all)\b[^.\n]{0,90}\b(?:request|task|work|question)\b/i.test(description)) advice.push({ kind: "broad-trigger-wording", detail: "description contains broad/catchall trigger wording; review selection scope" });
+  const entrypointMetrics = instructionTextMetrics(entrypoint);
+  const entrypointLines = entrypoint === "" ? 0 : entrypoint.split(/\r\n|\r|\n/).length;
+  if (entrypointLines > 500 || entrypointMetrics.words > 4e3) advice.push({ kind: "dense-entrypoint", detail: `entrypoint has ${entrypointLines} lines and ${entrypointMetrics.words} words; review routing before moving content` });
+  const unavailable = inventory.filter((resource) => resource.status === "unavailable");
+  if (unavailable.length > 0) advice.push({ kind: "resource-inventory-unavailable", detail: `resource inventory unavailable for ${unavailable.map((resource) => resource.directory).join(", ")}; no file count was inferred` });
+  const unrouted = inventory.filter((resource) => resource.status === "available" && !resource.routedFromEntrypoint);
+  if (unrouted.length > 0) advice.push({ kind: "unrouted-resources", detail: `entrypoint does not name ${unrouted.map((resource) => resource.directory).join(", ")}; confirm conditional routing or document it` });
+  if (/\b(?:always|must)\s+(?:read|load)\b[^\n]*(?:references|reference|assets|templates|scripts|commands|hooks)\//i.test(entrypoint)) advice.push({ kind: "unconditional-resource-routing", detail: "entrypoint appears to require resource loading unconditionally; review whether a narrower trigger is possible" });
+  return { hostLoad: "unknown", discovery: { ...name ? { name: instructionTextMetrics(name) } : {}, ...description ? { description: instructionTextMetrics(description) } : {} }, entrypoint: entrypointMetrics, resources: inventory, advice };
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 // src/audit.ts
 var OVERSIZED_SKILL_EST_TOKENS = 5e3;
 function toAuditFindings(source) {
@@ -2011,7 +2224,7 @@ function listSubdirsFollowingSymlinks(dir) {
   }
   const out = [];
   for (const entry of entries) {
-    const full = join12(dir, entry.name);
+    const full = join13(dir, entry.name);
     if (entry.isDirectory() || entry.isSymbolicLink() && isDirFollowingSymlink(full)) {
       out.push(full);
     }
@@ -2025,20 +2238,20 @@ function listSubdirsNoSymlinks(dir) {
   } catch {
     return [];
   }
-  return entries.filter((e) => e.isDirectory()).map((e) => join12(dir, e.name));
+  return entries.filter((e) => e.isDirectory()).map((e) => join13(dir, e.name));
 }
 function findSkillDirsUnderRoot(root) {
   const found = /* @__PURE__ */ new Set();
   const rootSubdirs = listSubdirsFollowingSymlinks(root);
   for (const dir of rootSubdirs) {
-    if (existsSync9(join12(dir, "SKILL.md"))) found.add(dir);
+    if (existsSync10(join13(dir, "SKILL.md"))) found.add(dir);
   }
-  for (const dir of listSubdirsFollowingSymlinks(join12(root, "skills"))) {
-    if (existsSync9(join12(dir, "SKILL.md"))) found.add(dir);
+  for (const dir of listSubdirsFollowingSymlinks(join13(root, "skills"))) {
+    if (existsSync10(join13(dir, "SKILL.md"))) found.add(dir);
   }
   for (const topDir of rootSubdirs) {
-    for (const dir of listSubdirsNoSymlinks(join12(topDir, "skills"))) {
-      if (existsSync9(join12(dir, "SKILL.md"))) found.add(dir);
+    for (const dir of listSubdirsNoSymlinks(join13(topDir, "skills"))) {
+      if (existsSync10(join13(dir, "SKILL.md"))) found.add(dir);
     }
   }
   return Array.from(found).filter((p) => !p.includes("/.git/"));
@@ -2052,7 +2265,7 @@ function collectSkillCandidates(roots) {
     let realPath;
     if (exists) {
       try {
-        realPath = realpathSync2(resolvedRoot);
+        realPath = realpathSync3(resolvedRoot);
       } catch {
         realPath = void 0;
       }
@@ -2071,7 +2284,7 @@ function dedupeSkillCandidates(candidates, findings) {
   for (const candidate of candidates) {
     let realPath;
     try {
-      realPath = realpathSync2(candidate.configuredPath);
+      realPath = realpathSync3(candidate.configuredPath);
     } catch (err) {
       findings.push({
         severity: "MEDIUM",
@@ -2134,7 +2347,7 @@ function estimateTokens(text) {
   return Math.ceil(Buffer.byteLength(text, "utf-8") / 4);
 }
 function profileAuditedSkill(group, findings, unreadableSkillMdPaths, pluginId) {
-  const skillMdPath = join12(group.canonicalPath, "SKILL.md");
+  const skillMdPath = join13(group.canonicalPath, "SKILL.md");
   const base = {
     path: group.canonicalPath,
     skillMdPath,
@@ -2146,7 +2359,7 @@ function profileAuditedSkill(group, findings, unreadableSkillMdPaths, pluginId)
   let sizeBytes;
   try {
     sizeBytes = statSync6(skillMdPath).size;
-    text = readFileSync9(skillMdPath, "utf-8");
+    text = readFileSync11(skillMdPath, "utf-8");
   } catch (err) {
     findings.push({
       severity: "MEDIUM",
@@ -2169,9 +2382,88 @@ function profileAuditedSkill(group, findings, unreadableSkillMdPaths, pluginId)
     validFrontmatter: fm.valid,
     description: fm.description,
     sizeBytes,
-    estTokens: estimateTokens(text)
+    estTokens: estimateTokens(text),
+    instructionDiagnostics: diagnoseInstructions(fm.name, fm.description, skillEntrypointBody(text), countSkillResources(group.canonicalPath))
   };
 }
+var RESOURCE_INVENTORY_SKIP_DIRS = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "build", "__pycache__", ".venv", "venv"]);
+var MAX_RESOURCE_INVENTORY_ENTRIES = 1e4;
+var MAX_RESOURCE_INVENTORY_DEPTH = 32;
+function countSkillResources(root) {
+  const resourceDirs = ["scripts", "references", "reference", "commands", "hooks", "assets", "templates", "sub-skills"];
+  const inventory = [];
+  for (const directory of resourceDirs) {
+    const resourceRoot = join13(root, directory);
+    let rootStat;
+    try {
+      rootStat = lstatSync3(resourceRoot);
+    } catch (error) {
+      if (error.code !== "ENOENT") inventory.push({ directory, unavailableReason: `could not inspect resource directory: ${error.message}` });
+      continue;
+    }
+    if (rootStat.isSymbolicLink()) {
+      inventory.push({ directory, unavailableReason: "resource directory is a symlink and was not followed" });
+      continue;
+    }
+    if (!rootStat.isDirectory()) continue;
+    const pending = [{ path: resourceRoot, depth: 0 }];
+    let files = 0;
+    let entries = 0;
+    let unavailableReason;
+    while (pending.length > 0 && !unavailableReason) {
+      const current = pending.pop();
+      let handle;
+      try {
+        handle = opendirSync(current.path);
+      } catch (error) {
+        unavailableReason = `could not read resource subtree: ${error.message}`;
+        break;
+      }
+      try {
+        let entry;
+        while ((entry = handle.readSync()) !== null) {
+          if (++entries > MAX_RESOURCE_INVENTORY_ENTRIES) {
+            unavailableReason = `resource inventory exceeded ${MAX_RESOURCE_INVENTORY_ENTRIES} entries`;
+            break;
+          }
+          const path = join13(current.path, entry.name);
+          let stat;
+          try {
+            stat = lstatSync3(path);
+          } catch (error) {
+            unavailableReason = `could not inspect resource entry: ${error.message}`;
+            break;
+          }
+          if (stat.isSymbolicLink()) {
+            unavailableReason = `resource subtree contains a symlink that was not followed: ${entry.name}`;
+            break;
+          }
+          if (stat.isDirectory()) {
+            if (RESOURCE_INVENTORY_SKIP_DIRS.has(entry.name)) {
+              unavailableReason = `resource subtree contains skipped directory: ${entry.name}`;
+              break;
+            }
+            if (current.depth >= MAX_RESOURCE_INVENTORY_DEPTH) {
+              unavailableReason = `resource inventory exceeded depth ${MAX_RESOURCE_INVENTORY_DEPTH}`;
+              break;
+            }
+            pending.push({ path, depth: current.depth + 1 });
+          } else if (stat.isFile()) files++;
+        }
+      } catch (error) {
+        unavailableReason = `could not read resource subtree: ${error.message}`;
+      } finally {
+        try {
+          handle.closeSync();
+        } catch (error) {
+          if (!unavailableReason) unavailableReason = `could not close resource subtree: ${error.message}`;
+        }
+      }
+    }
+    inventory.push(unavailableReason ? { directory, unavailableReason } : { directory, files });
+  }
+  return inventory;
+}
 function hasRecognizedMcpShape(parsed) {
   if (typeof parsed !== "object" || parsed === null) return false;
   const obj = parsed;
@@ -2203,7 +2495,7 @@ function auditMcpTarget(targetPath, notices) {
   const findings = [];
   const isToml = extname4(targetPath).toLowerCase() === ".toml";
   const format = isToml ? "toml" : "json";
-  if (!existsSync9(targetPath)) {
+  if (!existsSync10(targetPath)) {
     findings.push({
       severity: "LOW",
       rule: "missing-mcp-target",
@@ -2224,7 +2516,7 @@ function auditMcpTarget(targetPath, notices) {
   }
   if (isToml) {
     try {
-      readFileSync9(targetPath, "utf-8");
+      readFileSync11(targetPath, "utf-8");
     } catch (err) {
       findings.push({
         severity: "MEDIUM",
@@ -2239,7 +2531,7 @@ function auditMcpTarget(targetPath, notices) {
   }
   let raw;
   try {
-    raw = readFileSync9(targetPath, "utf-8");
+    raw = readFileSync11(targetPath, "utf-8");
   } catch (err) {
     findings.push({
       severity: "MEDIUM",
@@ -2373,18 +2665,32 @@ function buildUsageJoinIndex(usage, skills) {
   }
   const inventoryNameCounts = /* @__PURE__ */ new Map();
   for (const skill of skills) inventoryNameCounts.set(skill.name, (inventoryNameCounts.get(skill.name) ?? 0) + 1);
-  return { bareKeys, inventoryNameCounts, noticed: /* @__PURE__ */ new Set() };
+  const compositeCounts = /* @__PURE__ */ new Map();
+  for (const skill of skills) {
+    if (!skill.pluginId) continue;
+    const key = `${skill.pluginId.split("@")[0]}:${skill.name}`;
+    compositeCounts.set(key, (compositeCounts.get(key) ?? 0) + 1);
+  }
+  return { bareKeys, inventoryNameCounts, compositeCounts, noticed: /* @__PURE__ */ new Set(), uncertainPaths: /* @__PURE__ */ new Set() };
 }
 function matchUsage(skill, usage, index, 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);
+    if (usage.has(composite) && index.compositeCounts.get(composite) === 1) {
+      if (usage.get(composite) === 0 && (usage.get(skill.name) ?? 0) > 0) {
+        index.uncertainPaths.add(skill.path);
+        notices.push(`usage snapshot: conflicting zero and positive aliases for "${skill.name}" \u2014 skipping attribution`);
+        return void 0;
+      }
+      return usage.get(composite);
+    }
   }
   const bareMatches = index.bareKeys.get(skill.name) ?? [];
   if (bareMatches.length === 0) return void 0;
   const installedWithName = index.inventoryNameCounts.get(skill.name) ?? 0;
-  if (bareMatches.length === 1 && installedWithName === 1) return usage.get(bareMatches[0]);
+  if (installedWithName === 1 && usage.has(skill.name)) return usage.get(skill.name);
+  if (bareMatches.length === 1 && installedWithName === 1 && !skill.pluginId) return usage.get(bareMatches[0]);
+  index.uncertainPaths.add(skill.path);
   if (!index.noticed.has(skill.name)) {
     index.noticed.add(skill.name);
     notices.push(
@@ -2394,9 +2700,9 @@ function matchUsage(skill, usage, index, notices) {
   return void 0;
 }
 function isUnderInstallPath(target, installPath) {
-  return target === installPath || target.startsWith(installPath + sep2);
+  return target === installPath || target.startsWith(installPath + sep3);
 }
-function computePluginSummaries(pluginRoots, activeFindings, skills, usage, usageJoined) {
+function computePluginSummaries(pluginRoots, activeFindings, skills, usage, usageJoined, uncertainPaths, positiveJoined) {
   return pluginRoots.map((pr) => {
     const findingCounts = { LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 0 };
     for (const f of activeFindings) {
@@ -2410,9 +2716,10 @@ function computePluginSummaries(pluginRoots, activeFindings, skills, usage, usag
     let recommendation;
     const reasons = [];
     const longWindow = windowDays !== void 0 && windowDays >= 28;
+    const ambiguousUsage = skills.some((s) => s.pluginId === pr.pluginId && uncertainPaths.has(s.path));
     if (findingCounts.HIGH > 0 || findingCounts.CRITICAL > 0) {
       recommendation = "review";
-    } else if (exhaustive && longWindow && skillCount > 0 && observedSkillCount === 0 && (usageJoined ?? 0) > 0) {
+    } else if (!ambiguousUsage && exhaustive && longWindow && skillCount > 0 && observedSkillCount === 0 && positiveJoined > 0) {
       recommendation = "unobserved";
     } else if (exhaustive && (observedSkillCount ?? 0) >= 1) {
       recommendation = "keep";
@@ -2421,9 +2728,11 @@ function computePluginSummaries(pluginRoots, activeFindings, skills, usage, usag
       if (skillCount === 0) reasons.push("no skills to observe");
       if (!hasUsage) reasons.push("no usage telemetry");
       else if (usage.usage.size === 0) reasons.push("usage snapshot is empty or unreadable (see notices)");
-      else if (!exhaustive) reasons.push("usage snapshot is not exhaustive (top-50 only)");
+      else if (!exhaustive) reasons.push("usage snapshot is not exhaustive (top-50 only or invalid counts)");
+      else if (ambiguousUsage) reasons.push("ambiguous usage identity \u2014 absence is not zero usage");
       else if (!longWindow) reasons.push(`window ${windowDays ?? "unknown"} < 28 days`);
       else if ((usageJoined ?? 0) === 0) reasons.push("usage snapshot joined 0 installed skills");
+      else if (positiveJoined === 0) reasons.push("usage snapshot joined no positive installed-skill usage");
     }
     return {
       pluginId: pr.pluginId,
@@ -2443,7 +2752,7 @@ function defaultWhich(cmd) {
   const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
   for (const dir of dirs) {
     for (const ext of exts) {
-      const candidate = join12(dir, cmd + ext);
+      const candidate = join13(dir, cmd + ext);
       try {
         if (statSync6(candidate).isFile()) return candidate;
       } catch {
@@ -2643,18 +2952,21 @@ async function auditConfiguredSet(config, options = {}) {
     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;
+  const uncertainPaths = /* @__PURE__ */ new Set();
   if (usage) {
     const index = buildUsageJoinIndex(usage.usage, skills);
     for (const skill of skills) {
       const matched = matchUsage(skill, usage.usage, index, notices);
       if (matched !== void 0) skill.usage = matched;
+      if (index.uncertainPaths.has(skill.path)) uncertainPaths.add(skill.path);
     }
   }
+  const positiveJoined = skills.filter((s) => (s.usage ?? 0) > 0).length;
   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 && usage.windowDays !== void 0 && usage.windowDays >= 28 && (usageJoined ?? 0) > 0 ? skills.filter((s) => (s.usage ?? 0) === 0).map((s) => ({ name: s.name, path: s.path, pluginId: s.pluginId })) : [];
+  const unobservedInWindow = usage && usage.exhaustive && usage.windowDays !== void 0 && usage.windowDays >= 28 && positiveJoined > 0 ? skills.filter((s) => (s.usage ?? 0) === 0 && !uncertainPaths.has(s.path)).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 = {
@@ -2669,7 +2981,7 @@ async function auditConfiguredSet(config, options = {}) {
     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, usageJoined) : void 0;
+  const plugins2 = options.pluginRoots ? computePluginSummaries(pluginRoots, activeFindings, skills, usage, usageJoined, uncertainPaths, positiveJoined) : void 0;
   const tooling = checkTooling(options.which ?? defaultWhich, options.env ?? process.env);
   return {
     schemaVersion: 1,
@@ -2681,7 +2993,7 @@ async function auditConfiguredSet(config, options = {}) {
     tooling,
     notices,
     summary,
-    plugins
+    plugins: plugins2
   };
 }
 function bulletList(items, emptyPlaceholder) {
@@ -2721,6 +3033,17 @@ function renderSkillsSection(skills) {
     )
   ];
 }
+function renderInstructionDiagnosticsSection(skills) {
+  const lines = ["## Instruction diagnostics (advisory)", "", "- Static measurements only. Actual host loading and truncation are unknown; estimated tokens use ceil(UTF-8 bytes / 4) and are not observed usage."];
+  for (const skill of skills) {
+    const diagnostics = skill.instructionDiagnostics;
+    if (!diagnostics) continue;
+    const description = diagnostics.discovery.description;
+    lines.push(`- ${sanitizeForMarkdown(skill.name)} \u2014 description: ${description ? `${description.utf8Bytes} UTF-8 bytes, ${description.unicodeCodePoints} Unicode code points, ${description.words} words, est. ${description.estimatedTokens} tokens` : "unavailable"}; entrypoint: ${diagnostics.entrypoint.utf8Bytes} UTF-8 bytes, ${diagnostics.entrypoint.unicodeCodePoints} Unicode code points, ${diagnostics.entrypoint.words} words, est. ${diagnostics.entrypoint.estimatedTokens} tokens; host load: unknown`);
+    for (const advice of diagnostics.advice) lines.push(`  - advisory ${advice.kind}: ${sanitizeForMarkdown(advice.detail)}`);
+  }
+  return lines;
+}
 function renderMcpTargetsSection(targets) {
   const lines = ["### MCP targets", ""];
   if (targets.length === 0) {
@@ -2816,16 +3139,17 @@ function renderUsageSection(report) {
   }
   return lines;
 }
-function renderPluginsSection(plugins) {
+function renderPluginsSection(plugins2) {
   return [
     "## Plugins",
     "",
     ...bulletList(
-      plugins.map((p) => {
+      plugins2.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}`;
+        const reasonsPart = p.reasons.length > 0 ? ` (${p.reasons.map(sanitizeForMarkdown).join("; ")})` : "";
+        const action = p.recommendation === "review" ? " \u2014 next: inspect finding context, update or fix the owning source; do not edit an installed cache" : p.recommendation === "unobserved" ? " \u2014 next: check hooks, commands and occasional use; record a keep rationale or explicitly review disabling" : p.recommendation === "unknown" ? " \u2014 next: resolve the listed evidence gaps before a retention decision" : "";
+        return `${sanitizeForMarkdown(p.pluginId)} @ ${sanitizeForMarkdown(p.version)} \u2014 ${sanitizeForMarkdown(p.installPath)} \u2014 ${p.skillCount} skill(s)${observedPart} \u2014 findings: ${findingsPart} \u2014 **${p.recommendation}**${reasonsPart}` + (p.keepDecision ? ` \u2014 explicit keep (${p.keepDecision.category}): ${sanitizeForMarkdown(p.keepDecision.reason)}` : "") + action;
       }),
       "(no enabled plugins)"
     )
@@ -2858,6 +3182,7 @@ function renderAuditMarkdown(report) {
   const lines = [
     `# skill-forge audit \u2014 ${report.generatedAt}`,
     "",
+    ...report.comparison ? renderAuditComparison(report.comparison) : [],
     "## Summary",
     "",
     `- Skill roots: ${summary.rootCount}`,
@@ -2876,6 +3201,8 @@ function renderAuditMarkdown(report) {
     "",
     ...renderSkillsSection(report.inventory.skills),
     "",
+    ...renderInstructionDiagnosticsSection(report.inventory.skills),
+    "",
     ...renderMcpTargetsSection(report.inventory.mcpTargets),
     "",
     ...renderFindingsSection(report.hygiene),
@@ -2933,7 +3260,7 @@ async function scaffoldFoundationSkill(config, profile, targetRoot) {
   if (!isDir(resolvedRoot)) {
     throw new UserError(`skills root does not exist: ${resolvedRoot}`);
   }
-  const destDir = join12(resolvedRoot, "business-foundation");
+  const destDir = join13(resolvedRoot, "business-foundation");
   let destLstat;
   try {
     destLstat = lstatSync3(destDir);
@@ -2947,9 +3274,9 @@ async function scaffoldFoundationSkill(config, profile, targetRoot) {
     throw new UserError(`refusing to scaffold a foundation skill at ${destDir}: already exists`);
   }
   const content = renderFoundationSkillMd(profile);
-  const tempDir = mkdtempSync(join12(resolvedRoot, ".business-foundation-"));
+  const tempDir = mkdtempSync(join13(resolvedRoot, ".business-foundation-"));
   try {
-    writeFileSync5(join12(tempDir, "SKILL.md"), content, { flag: "wx", mode: 384 });
+    writeFileSync5(join13(tempDir, "SKILL.md"), content, { flag: "wx", mode: 384 });
     const safety = await scanSafety(tempDir, config.strictness);
     if (safety.verdict === "block") {
       throw new UserError(
@@ -2983,7 +3310,7 @@ async function scaffoldFoundationSkill(config, profile, targetRoot) {
 
 // src/auditState.ts
 function getAuditStatePath() {
-  return join13(getHomeDir(), "audit-state.json");
+  return join14(getHomeDir(), "audit-state.json");
 }
 function emptyCounts() {
   return { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
@@ -3046,9 +3373,9 @@ function writeAuditState(state) {
 }
 function readAuditState() {
   const path = getAuditStatePath();
-  if (!existsSync10(path)) return void 0;
+  if (!existsSync11(path)) return void 0;
   try {
-    const parsed = JSON.parse(readFileSync10(path, "utf-8"));
+    const parsed = JSON.parse(readFileSync12(path, "utf-8"));
     if (parsed.schemaVersion !== 1 || typeof parsed.lastRunAt !== "string") return void 0;
     return {
       schemaVersion: 1,
@@ -3110,32 +3437,32 @@ function formatAuditAdvisory(state, options = {}) {
 }
 
 // src/commands/gatePipeline.ts
-import { join as join16 } from "path";
+import { join as join17 } from "path";
 
 // src/gate/profile.ts
 import { execFileSync } from "child_process";
 import {
   closeSync as closeSync2,
-  existsSync as existsSync12,
+  existsSync as existsSync13,
   mkdtempSync as mkdtempSync2,
   openSync as openSync2,
-  readFileSync as readFileSync12,
+  readFileSync as readFileSync14,
   readdirSync as readdirSync6,
   readSync,
   rmSync as rmSync4,
   statSync as statSync7
 } from "fs";
 import { tmpdir } from "os";
-import { basename as basename8, dirname as dirname6, extname as extname6, join as join15, resolve as resolve3 } from "path";
+import { basename as basename8, dirname as dirname6, extname as extname6, join as join16, resolve as resolve4 } from "path";
 
 // src/gate/mcpCapabilities.ts
-import { existsSync as existsSync11, readFileSync as readFileSync11 } from "fs";
-import { extname as extname5, join as join14 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync13 } from "fs";
+import { extname as extname5, join as join15 } from "path";
 var SOURCE_EXT = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 var MAX_ITEMS_PER_CATEGORY = 200;
 function readJsonSafe(file) {
   try {
-    return JSON.parse(readFileSync11(file, "utf-8"));
+    return JSON.parse(readFileSync13(file, "utf-8"));
   } catch {
     return void 0;
   }
@@ -3236,16 +3563,16 @@ var MCP_SDK_IMPORT_RE = /@modelcontextprotocol\/sdk/;
 function extractMcpCapabilities(packageDir) {
   const buckets = { tools: /* @__PURE__ */ new Set(), resources: /* @__PURE__ */ new Set(), prompts: /* @__PURE__ */ new Set() };
   let hasPackageJsonMarker = false;
-  const pkgPath = join14(packageDir, "package.json");
-  if (existsSync11(pkgPath)) {
+  const pkgPath = join15(packageDir, "package.json");
+  if (existsSync12(pkgPath)) {
     const pkg2 = readJsonSafe(pkgPath);
     if (pkg2 && typeof pkg2 === "object" && !Array.isArray(pkg2)) {
       hasPackageJsonMarker = hasPackageJsonMcpMarkers(pkg2);
     }
   }
   for (const manifestName of [".mcp.json", "mcp.json"]) {
-    const manifestPath = join14(packageDir, manifestName);
-    if (!existsSync11(manifestPath)) continue;
+    const manifestPath = join15(packageDir, manifestName);
+    if (!existsSync12(manifestPath)) continue;
     const parsed = readJsonSafe(manifestPath);
     if (parsed !== void 0) {
       collectDeclaredFromManifest(parsed, buckets);
@@ -3321,8 +3648,8 @@ var PYTHON_STDLIB = /* @__PURE__ */ new Set([
   "__future__"
 ]);
 function profileSkill(inputPath) {
-  const p = resolve3(expandHome(inputPath));
-  if (!existsSync12(p)) {
+  const p = resolve4(expandHome(inputPath));
+  if (!existsSync13(p)) {
     throw new Error(`path does not exist: ${p}`);
   }
   const stat = statSync7(p);
@@ -3352,7 +3679,7 @@ function asProfile(candidatePath, artifact) {
   return asSkillProfile(profile, `at ${candidatePath}`);
 }
 function classifyInput(p) {
-  if (existsSync12(join15(p, ".claude-plugin", "plugin.json"))) return "plugin";
+  if (existsSync13(join16(p, ".claude-plugin", "plugin.json"))) return "plugin";
   if (detectArtifactType(p) === "mcp") return "mcp";
   return "skill";
 }
@@ -3360,10 +3687,10 @@ var MCP_SDK_DEP2 = "@modelcontextprotocol/sdk";
 var MCP_KEYWORD2 = "mcp-server";
 var MCP_BIN_PREFIX2 = /^mcp-/i;
 function readPackageJsonSafe(root) {
-  const pkgPath = join15(root, "package.json");
-  if (!existsSync12(pkgPath)) return void 0;
+  const pkgPath = join16(root, "package.json");
+  if (!existsSync13(pkgPath)) return void 0;
   try {
-    return JSON.parse(readFileSync12(pkgPath, "utf-8"));
+    return JSON.parse(readFileSync14(pkgPath, "utf-8"));
   } catch {
     return void 0;
   }
@@ -3384,7 +3711,7 @@ function hasMcpPackageMarkers(pkg2) {
   return false;
 }
 function detectArtifactType(root) {
-  if (existsSync12(join15(root, ".mcp.json")) || existsSync12(join15(root, "mcp.json"))) return "mcp";
+  if (existsSync13(join16(root, ".mcp.json")) || existsSync13(join16(root, "mcp.json"))) return "mcp";
   const pkg2 = readPackageJsonSafe(root);
   if (pkg2 && hasMcpPackageMarkers(pkg2)) return "mcp";
   return "skill";
@@ -3394,7 +3721,7 @@ function resolveSkillMd(inputPath) {
   let tmpDir;
   const initialStat = statSync7(currentPath);
   if (extname6(currentPath) === ".skill" || initialStat.isFile() && isZipFile(currentPath)) {
-    tmpDir = mkdtempSync2(join15(tmpdir(), "forge_"));
+    tmpDir = mkdtempSync2(join16(tmpdir(), "forge_"));
     extractZip(currentPath, tmpDir);
     currentPath = tmpDir;
   }
@@ -3403,8 +3730,8 @@ function resolveSkillMd(inputPath) {
     return { skillMd: currentPath, root: dirname6(currentPath), tmpDir };
   }
   if (stat.isDirectory()) {
-    const direct = join15(currentPath, "SKILL.md");
-    if (existsSync12(direct)) {
+    const direct = join16(currentPath, "SKILL.md");
+    if (existsSync13(direct)) {
       return { skillMd: direct, root: currentPath, tmpDir };
     }
     const matches = findSkillMdOneLevelDown(currentPath);
@@ -3429,16 +3756,16 @@ function findSkillMdOneLevelDown(dir) {
   const matches = /* @__PURE__ */ new Set();
   for (const entry of readdirSync6(dir, { withFileTypes: true })) {
     if (entry.isDirectory()) {
-      const candidate = join15(dir, entry.name, "SKILL.md");
-      if (existsSync12(candidate)) matches.add(candidate);
+      const candidate = join16(dir, entry.name, "SKILL.md");
+      if (existsSync13(candidate)) matches.add(candidate);
     }
   }
-  const skillsDir = join15(dir, "skills");
+  const skillsDir = join16(dir, "skills");
   if (isDir(skillsDir)) {
     for (const entry of readdirSync6(skillsDir, { withFileTypes: true })) {
       if (entry.isDirectory()) {
-        const candidate = join15(skillsDir, entry.name, "SKILL.md");
-        if (existsSync12(candidate)) matches.add(candidate);
+        const candidate = join16(skillsDir, entry.name, "SKILL.md");
+        if (existsSync13(candidate)) matches.add(candidate);
       }
     }
   }
@@ -3549,9 +3876,9 @@ function detectLicense(root, fm) {
   if (fm.license) return fm.license;
   const names = ["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING", "license"];
   for (const name of names) {
-    const p = join15(root, name);
-    if (existsSync12(p) && statSync7(p).isFile()) {
-      const head = readFileSync12(p, "utf-8").slice(0, 2e3).toLowerCase();
+    const p = join16(root, name);
+    if (existsSync13(p) && statSync7(p).isFile()) {
+      const head = readFileSync14(p, "utf-8").slice(0, 2e3).toLowerCase();
       for (const [hint, label2] of Object.entries(SPDX_HINTS)) {
         if (head.includes(hint)) return label2;
       }
@@ -3563,7 +3890,7 @@ function detectLicense(root, fm) {
 function walkFiles(dir) {
   const out = [];
   for (const entry of readdirSync6(dir, { withFileTypes: true })) {
-    const full = join15(dir, entry.name);
+    const full = join16(dir, entry.name);
     if (entry.isDirectory()) {
       out.push(...walkFiles(full));
     } else if (entry.isFile()) {
@@ -3575,7 +3902,7 @@ function walkFiles(dir) {
 function countResources(root) {
   const resources = {};
   for (const d of RESOURCE_DIRS) {
-    const dp = join15(root, d);
+    const dp = join16(root, d);
     if (isDir(dp)) {
       resources[d] = walkFiles(dp).length;
     }
@@ -3586,11 +3913,11 @@ function scanMcpAndImports(text, root) {
   const mcpRefRe = /mcp__[a-zA-Z0-9_]+/g;
   const mcpRefs = new Set(text.match(mcpRefRe) ?? []);
   const imports = /* @__PURE__ */ new Set();
-  const scriptsDir = join15(root, "scripts");
+  const scriptsDir = join16(root, "scripts");
   if (isDir(scriptsDir)) {
     for (const f of walkFiles(scriptsDir)) {
       if (!f.endsWith(".py")) continue;
-      const ft = readFileSync12(f, "utf-8");
+      const ft = readFileSync14(f, "utf-8");
       for (const m2 of ft.match(mcpRefRe) ?? []) mcpRefs.add(m2);
       const importRe = /^\s*(?:import|from)\s+([a-zA-Z0-9_]+)/gm;
       let m;
@@ -3607,7 +3934,7 @@ function scanMcpAndImports(text, root) {
 function profileSkillDir(inputPath) {
   const { skillMd, root, tmpDir } = resolveSkillMd(inputPath);
   try {
-    const text = readFileSync12(skillMd, "utf-8");
+    const text = readFileSync14(skillMd, "utf-8");
     const fm = parseFrontmatter(text);
     const bodyLines = (text.match(/\n/g)?.length ?? 0) + 1;
     const headers = Array.from(text.matchAll(/^#{1,3}\s+(.+)$/gm)).map((m) => m[1]);
@@ -3628,6 +3955,7 @@ function profileSkillDir(inputPath) {
       resources,
       mcpDependencies: mcpDeps,
       externalPythonDeps: externalDeps,
+      instructionDiagnostics: diagnoseInstructions(fm.name, fm.description, skillEntrypointBody(text), resources),
       artifactType: detectArtifactType(root),
       extends: fm.extends ?? []
     };
@@ -3636,19 +3964,19 @@ function profileSkillDir(inputPath) {
   }
 }
 function profilePlugin(p) {
-  const manifestPath = join15(p, ".claude-plugin", "plugin.json");
+  const manifestPath = join16(p, ".claude-plugin", "plugin.json");
   let manifest;
   try {
-    manifest = JSON.parse(readFileSync12(manifestPath, "utf-8"));
+    manifest = JSON.parse(readFileSync14(manifestPath, "utf-8"));
   } catch (err) {
     throw new Error(`could not parse plugin.json under ${p}: ${err.message}`);
   }
-  const skillsDir = join15(p, "skills");
+  const skillsDir = join16(p, "skills");
   let skills = [];
   if (isDir(skillsDir)) {
-    skills = readdirSync6(skillsDir, { withFileTypes: true }).filter((d) => d.isDirectory() && existsSync12(join15(skillsDir, d.name, "SKILL.md"))).map((d) => d.name).sort();
+    skills = readdirSync6(skillsDir, { withFileTypes: true }).filter((d) => d.isDirectory() && existsSync13(join16(skillsDir, d.name, "SKILL.md"))).map((d) => d.name).sort();
   }
-  const commandsDir = join15(p, "commands");
+  const commandsDir = join16(p, "commands");
   const commands = isDir(commandsDir) ? readdirSync6(commandsDir).filter((f) => f.endsWith(".md")).length : 0;
   const mc = manifest.mcpServers ?? manifest.mcp_servers ?? {};
   const mcpServers = typeof mc === "object" && mc !== null ? Object.keys(mc).sort() : [];
@@ -3666,11 +3994,11 @@ function profilePlugin(p) {
   };
 }
 function profileMcp(p) {
-  const explicitConfig = existsSync12(join15(p, ".mcp.json")) ? join15(p, ".mcp.json") : existsSync12(join15(p, "mcp.json")) ? join15(p, "mcp.json") : void 0;
+  const explicitConfig = existsSync13(join16(p, ".mcp.json")) ? join16(p, ".mcp.json") : existsSync13(join16(p, "mcp.json")) ? join16(p, "mcp.json") : void 0;
   if (explicitConfig) {
     let cfg;
     try {
-      cfg = JSON.parse(readFileSync12(explicitConfig, "utf-8"));
+      cfg = JSON.parse(readFileSync14(explicitConfig, "utf-8"));
     } catch (err) {
       throw new Error(`could not parse MCP config ${explicitConfig}: ${err.message}`);
     }
@@ -3686,10 +4014,10 @@ function profileMcp(p) {
       capabilities: extractMcpCapabilities(p)
     };
   }
-  const pkgPath = join15(p, "package.json");
+  const pkgPath = join16(p, "package.json");
   let pkg2;
   try {
-    pkg2 = JSON.parse(readFileSync12(pkgPath, "utf-8"));
+    pkg2 = JSON.parse(readFileSync14(pkgPath, "utf-8"));
   } catch (err) {
     throw new Error(`could not parse package.json ${pkgPath}: ${err.message}`);
   }
@@ -3706,14 +4034,14 @@ function profileMcp(p) {
 }
 
 // src/gate/mcpOverlap.ts
-import { existsSync as existsSync13, readFileSync as readFileSync13 } from "fs";
-import { resolve as resolve4 } from "path";
+import { existsSync as existsSync14, readFileSync as readFileSync15 } from "fs";
+import { resolve as resolve5 } from "path";
 function readTargetServers(targetPath) {
-  const path = resolve4(expandHome(targetPath));
-  if (!existsSync13(path)) return [];
+  const path = resolve5(expandHome(targetPath));
+  if (!existsSync14(path)) return [];
   let cfg;
   try {
-    cfg = JSON.parse(readFileSync13(path, "utf-8"));
+    cfg = JSON.parse(readFileSync15(path, "utf-8"));
   } catch {
     return [];
   }
@@ -3769,7 +4097,7 @@ function score2(candidate, target) {
 function scanMcpOverlap(candidate, mcpTargetPaths) {
   const ranking = [];
   for (const targetPath of mcpTargetPaths) {
-    const resolvedPath = resolve4(expandHome(targetPath));
+    const resolvedPath = resolve5(expandHome(targetPath));
     for (const target of readTargetServers(targetPath)) {
       ranking.push({ skill: target.name, path: resolvedPath, score: score2(candidate, target) });
     }
@@ -3786,13 +4114,13 @@ function scanMcpOverlap(candidate, mcpTargetPaths) {
 }
 
 // src/gate/skillMap.ts
-import { readFileSync as readFileSync14 } from "fs";
-import { resolve as resolve5 } from "path";
+import { readFileSync as readFileSync16 } from "fs";
+import { resolve as resolve6 } from "path";
 function loadSkillMap(path) {
-  const resolved = resolve5(expandHome(path));
+  const resolved = resolve6(expandHome(path));
   let text;
   try {
-    text = readFileSync14(resolved, "utf-8");
+    text = readFileSync16(resolved, "utf-8");
   } catch (err) {
     throw new Error(`could not read skill map at ${resolved}: ${err.message}`);
   }
@@ -4092,7 +4420,7 @@ function resolveMcpCandidatePath(entry) {
     children = readdirSync7(entry.quarantinePath, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
   } catch {
   }
-  return children.length === 1 ? join16(entry.quarantinePath, children[0]) : entry.quarantinePath;
+  return children.length === 1 ? join17(entry.quarantinePath, children[0]) : entry.quarantinePath;
 }
 async function runGate(candidatePath, skillsRoot, {
   proFeatureLabel = "overlap analysis",
@@ -4141,17 +4469,17 @@ async function runGate(candidatePath, skillsRoot, {
 
 // src/queue.ts
 import { randomUUID as randomUUID3 } from "crypto";
-import { existsSync as existsSync14, mkdirSync as mkdirSync6, readFileSync as readFileSync15, renameSync as renameSync4, rmSync as rmSync5, writeFileSync as writeFileSync6 } from "fs";
-import { join as join17 } from "path";
+import { existsSync as existsSync15, mkdirSync as mkdirSync6, readFileSync as readFileSync17, renameSync as renameSync4, rmSync as rmSync5, writeFileSync as writeFileSync6 } from "fs";
+import { join as join18 } from "path";
 function getQueuePath() {
-  return join17(getHomeDir(), "queue.json");
+  return join18(getHomeDir(), "queue.json");
 }
 function readQueue() {
   const path = getQueuePath();
-  if (!existsSync14(path)) {
+  if (!existsSync15(path)) {
     return { version: 1, entries: [] };
   }
-  const raw = readFileSync15(path, "utf-8");
+  const raw = readFileSync17(path, "utf-8");
   const parsed = JSON.parse(raw);
   return { version: 1, entries: parsed.entries ?? [] };
 }
@@ -4159,7 +4487,7 @@ function writeQueue(queue2) {
   const home = getHomeDir();
   mkdirSync6(home, { recursive: true });
   const finalPath = getQueuePath();
-  const tempPath = join17(home, `.queue.json.tmp-${randomUUID3()}`);
+  const tempPath = join18(home, `.queue.json.tmp-${randomUUID3()}`);
   try {
     writeFileSync6(tempPath, JSON.stringify(queue2, null, 2) + "\n", "utf-8");
     renameSync4(tempPath, finalPath);
@@ -4208,19 +4536,19 @@ function generateId(existingIds) {
 
 // src/handoff.ts
 import { spawnSync } from "child_process";
-import { existsSync as existsSync15 } from "fs";
-import { dirname as dirname7, isAbsolute as isAbsolute2, join as join18, win32 } from "path";
+import { existsSync as existsSync16 } from "fs";
+import { dirname as dirname7, isAbsolute as isAbsolute3, join as join19, win32 } from "path";
 import { fileURLToPath } from "url";
 var KNOWN_AGENT_BINARIES = ["claude", "codex", "cursor-agent", "windsurf", "opencode", "gemini"];
 var HANDOFF_INSTRUCTION = "Read {prompt} and follow its instructions for the skill installed at {path}";
 function resolvePromptPath(assetName = "ingest-prompt.md") {
-  if (assetName.length === 0 || assetName.includes("\0") || isAbsolute2(assetName) || win32.isAbsolute(assetName) || assetName.split(/[\\/]/).includes("..")) {
+  if (assetName.length === 0 || assetName.includes("\0") || isAbsolute3(assetName) || win32.isAbsolute(assetName) || assetName.split(/[\\/]/).includes("..")) {
     throw new UserError(`Invalid handoff prompt asset path: ${assetName}`);
   }
   const here = dirname7(fileURLToPath(import.meta.url));
-  const builtCandidate = join18(here, assetName);
-  if (existsSync15(builtCandidate)) return builtCandidate;
-  return join18(here, "..", "assets", assetName);
+  const builtCandidate = join19(here, assetName);
+  if (existsSync16(builtCandidate)) return builtCandidate;
+  return join19(here, "..", "assets", assetName);
 }
 function defaultIsOnPath(bin) {
   const finder = process.platform === "win32" ? "where" : "which";
@@ -4282,15 +4610,15 @@ function runHandoff(config, installedPath, options = {}) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync18 } from "fs";
+import { existsSync as existsSync19 } from "fs";
 import { homedir as homedir5 } from "os";
-import { join as join23 } from "path";
+import { join as join25 } from "path";
 import { createInterface as createInterface3 } from "readline/promises";
 
 // src/agents.ts
 import { statSync as statSync8 } from "fs";
 import { homedir as homedir3 } from "os";
-import { join as join19, resolve as resolve6 } from "path";
+import { join as join20, resolve as resolve7 } from "path";
 function isFile(p) {
   try {
     return statSync8(p).isFile();
@@ -4299,12 +4627,12 @@ function isFile(p) {
   }
 }
 function projectPath(root, cwd) {
-  return root ? resolve6(cwd, root) : void 0;
+  return root ? resolve7(cwd, root) : void 0;
 }
 function globalPath(root, home) {
   if (!root) return void 0;
   if (root === "~") return home;
-  if (root.startsWith("~/")) return join19(home, root.slice(2));
+  if (root.startsWith("~/")) return join20(home, root.slice(2));
   return root;
 }
 function makeAgent(spec) {
@@ -4321,30 +4649,30 @@ function makeAgent(spec) {
   };
   return agent;
 }
-function resolveAgentRoot(agent, scope, cwd = process.cwd(), home = homedir3()) {
-  return scope === "project" ? projectPath(agent.projectRoot, cwd) : globalPath(agent.globalRoot, home);
+function resolveAgentRoot(agent, scope2, cwd = process.cwd(), home = homedir3()) {
+  return scope2 === "project" ? projectPath(agent.projectRoot, cwd) : globalPath(agent.globalRoot, home);
 }
 function agentCliPresence(agent, pathEnv = process.env.PATH) {
   if (!agent.cliBinaries || agent.cliBinaries.length === 0) return "unknown";
   return agent.cliBinaries.some((bin) => resolveBinaryOnPath(bin, pathEnv) !== void 0) ? "installed" : "absent";
 }
 function detectAgentRoot(agent, cwd = process.cwd(), home = homedir3()) {
-  for (const scope of ["project", "global"]) {
-    const root = resolveAgentRoot(agent, scope, cwd, home);
-    if (root && isDir(root)) return { scope, root };
+  for (const scope2 of ["project", "global"]) {
+    const root = resolveAgentRoot(agent, scope2, cwd, home);
+    if (root && isDir(root)) return { scope: scope2, root };
   }
   return void 0;
 }
-function resolveMcpConfigPath(agent, scope, cwd = process.cwd(), home = homedir3()) {
+function resolveMcpConfigPath(agent, scope2, cwd = process.cwd(), home = homedir3()) {
   if (!agent.mcpConfig) return void 0;
-  return scope === "project" ? projectPath(agent.mcpConfig.project, cwd) : globalPath(agent.mcpConfig.global, home);
+  return scope2 === "project" ? projectPath(agent.mcpConfig.project, cwd) : globalPath(agent.mcpConfig.global, home);
 }
 function detectMcpConfigFiles(agent, cwd = process.cwd(), home = homedir3()) {
   if (!agent.mcpConfig) return [];
   const found = [];
-  for (const scope of ["project", "global"]) {
-    const path = resolveMcpConfigPath(agent, scope, cwd, home);
-    if (path && isFile(path)) found.push({ scope, path });
+  for (const scope2 of ["project", "global"]) {
+    const path = resolveMcpConfigPath(agent, scope2, cwd, home);
+    if (path && isFile(path)) found.push({ scope: scope2, path });
   }
   return found;
 }
@@ -4534,12 +4862,12 @@ var AGENTS = [
 ].map(makeAgent);
 
 // src/gitPreflight.ts
-import { relative as relative2, sep as sep3 } from "path";
+import { relative as relative3, sep as sep4 } from "path";
 function splitNulTerminated(output) {
   return output.split("\0").filter((s) => s.length > 0);
 }
 function toPosixPath(p) {
-  return p.split(sep3).join("/");
+  return p.split(sep4).join("/");
 }
 var missingResult = (root) => ({
   root,
@@ -4569,7 +4897,7 @@ async function evaluateGitPreflight(root, deps = {}) {
   if (toplevel.code !== 0) return notInRepoResult(root);
   const repoRoot = toplevel.stdout.trim();
   if (!repoRoot) return notInRepoResult(root);
-  const rel = toPosixPath(relative2(repoRoot, root));
+  const rel = toPosixPath(relative3(repoRoot, root));
   const pathspec = rel === "" ? "." : rel;
   const tracked = await exec("git", ["--literal-pathspecs", "-C", repoRoot, "ls-files", "-z", "--", pathspec], { cwd: repoRoot });
   const untracked = await exec(
@@ -4640,7 +4968,7 @@ function untrackedAddCommitCommands(root, repoRoot) {
   ];
 }
 function ignoredUnignoreSuggestions(root, repoRoot) {
-  const rel = toPosixPath(relative2(repoRoot, root));
+  const rel = toPosixPath(relative3(repoRoot, root));
   return [`!${rel}/`, `!${rel}/**`];
 }
 async function runGitCommands(commands, deps = {}) {
@@ -4663,9 +4991,52 @@ function describeGitPreflight(result) {
   return parts.join(", ");
 }
 
+// src/pluginInventory.ts
+import { readFileSync as readFileSync18, realpathSync as realpathSync4, statSync as statSync9 } from "fs";
+import { isAbsolute as isAbsolute4, join as join21, relative as relative4, sep as sep5 } from "path";
+function readPluginInventory(path) {
+  const data = JSON.parse(readFileSync18(path, "utf8"));
+  if (data.schemaVersion !== 1 || data.kind !== "skill-forge-host-inventory" || !["claude", "codex"].includes(data.host) || !Array.isArray(data.plugins) || typeof data.complete !== "boolean" || typeof data.generatedAt !== "string" || !Number.isFinite(Date.parse(data.generatedAt))) throw new UserError("Invalid host inventory export.");
+  const roots = [];
+  const notices = ["Imported host inventory is static evidence; runtime discovery/invocation is unverified."];
+  if (Array.isArray(data.notices)) notices.push(...data.notices.filter((n) => typeof n === "string"));
+  const ids = /* @__PURE__ */ new Set();
+  let complete = data.complete;
+  for (const row of data.plugins) {
+    if (!row || row.host !== data.host || typeof row.pluginId !== "string" || !/^[\w.-]+@[\w.-]+$/.test(row.pluginId) || ids.has(row.pluginId)) {
+      throw new UserError("Invalid or duplicate host inventory plugin identity.");
+    }
+    ids.add(row.pluginId);
+    if (row.enabled === false && row.status === "disabled") continue;
+    if (row.enabled !== true || row.status !== "installed") {
+      complete = false;
+      notices.push(`${row.pluginId}: installed skills unavailable (${typeof row.reason === "string" ? row.reason : "unknown state"}).`);
+      continue;
+    }
+    if (typeof row.installPath !== "string" || !isAbsolute4(row.installPath) || typeof row.version !== "string" || !Array.isArray(row.skillDirs) || row.skillDirs.some((p) => typeof p !== "string" || !isAbsolute4(p))) {
+      throw new UserError("Invalid host inventory install paths/version.");
+    }
+    const installPath = realpathSync4(row.installPath);
+    const skillDirs = [...new Set(row.skillDirs.map((dir) => {
+      const real = realpathSync4(dir);
+      for (const target of [real, realpathSync4(join21(real, "SKILL.md"))]) {
+        const rel = relative4(installPath, target);
+        if (rel === ".." || rel.startsWith(".." + sep5) || isAbsolute4(rel)) throw new UserError("Imported skill escapes its plugin install.");
+      }
+      if (!statSync9(join21(real, "SKILL.md")).isFile()) throw new UserError("Imported SKILL.md is not a file.");
+      return real;
+    }))].sort();
+    const [plugin, marketplace] = row.pluginId.split("@");
+    roots.push({ pluginId: row.pluginId, plugin, marketplace, version: row.version, installPath, skillDirs });
+  }
+  if (!complete) notices.push("Host inventory coverage is incomplete; missing plugins are not evidence of removal.");
+  if (Date.now() - Date.parse(data.generatedAt) > 24 * 60 * 60 * 1e3) notices.push("Host inventory export is older than 24 hours; refresh it before making retention decisions.");
+  return { host: data.host, roots, notices, complete, generatedAt: data.generatedAt };
+}
+
 // src/commands/audit.ts
-import { existsSync as existsSync17 } from "fs";
-import { join as join22, resolve as resolvePath5 } from "path";
+import { existsSync as existsSync18 } from "fs";
+import { join as join24, resolve as resolvePath5 } from "path";
 import { createInterface as createInterface2 } from "readline/promises";
 
 // src/decision.ts
@@ -4698,13 +5069,13 @@ ${prompt}`);
 }
 
 // src/pluginRoots.ts
-import { existsSync as existsSync16, readFileSync as readFileSync16, readdirSync as readdirSync8, realpathSync as realpathSync3 } from "fs";
+import { existsSync as existsSync17, readFileSync as readFileSync19, readdirSync as readdirSync8, realpathSync as realpathSync5 } 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";
+import { isAbsolute as isAbsolute5, join as join22, relative as relative5, resolve as resolvePath3, sep as sep6 } from "path";
 function readJsonFileSafe(path) {
   let raw;
   try {
-    raw = readFileSync16(path, "utf-8");
+    raw = readFileSync19(path, "utf-8");
   } catch (err) {
     return { problem: err.code === "ENOENT" ? "missing" : "unreadable" };
   }
@@ -4740,12 +5111,12 @@ function extractRegistry(data) {
     const entries = [];
     for (const raw of entriesRaw) {
       const rec = typeof raw === "object" && raw !== null ? raw : {};
-      const scope = rec.scope;
+      const scope2 = rec.scope;
       const installPath = rec.installPath;
       const version = rec.version;
-      if ((scope === "user" || scope === "project" || scope === "local") && typeof installPath === "string" && typeof version === "string") {
+      if ((scope2 === "user" || scope2 === "project" || scope2 === "local") && typeof installPath === "string" && typeof version === "string") {
         entries.push({
-          scope,
+          scope: scope2,
           projectPath: typeof rec.projectPath === "string" ? rec.projectPath : void 0,
           installPath,
           version
@@ -4765,7 +5136,7 @@ function splitPluginId(id) {
 }
 function safeRealpath(p) {
   try {
-    return realpathSync3(p);
+    return realpathSync5(p);
   } catch {
     return void 0;
   }
@@ -4800,8 +5171,8 @@ function selectInstallEntry(entries, cwd) {
 }
 function isInside2(child, root) {
   if (child === root) return true;
-  const rel = relative3(root, child);
-  return rel !== "" && !rel.startsWith(".." + sep4) && rel !== ".." && !isAbsolute3(rel);
+  const rel = relative5(root, child);
+  return rel !== "" && !rel.startsWith(".." + sep6) && rel !== ".." && !isAbsolute5(rel);
 }
 var DEFAULT_SKILL_LAYOUT = { paths: ["./skills/"], explicit: false };
 function normalizeDeclaredSkillsField(manifest, pluginId, notices) {
@@ -4817,7 +5188,7 @@ function resolveDeclaredPath(installPath, realInstall, declaredPath, explicit, p
   const joined = resolvePath3(installPath, declaredPath);
   let real;
   try {
-    real = realpathSync3(joined);
+    real = realpathSync5(joined);
   } catch {
     if (explicit) notices.push(`plugin ${pluginId}: declared skill path does not exist, skipping: ${declaredPath}`);
     return [];
@@ -4826,7 +5197,7 @@ function resolveDeclaredPath(installPath, realInstall, declaredPath, explicit, p
     notices.push(`plugin ${pluginId}: declared skill path escapes the install root, skipping: ${declaredPath}`);
     return [];
   }
-  if (existsSync16(join20(real, "SKILL.md"))) return [real];
+  if (existsSync17(join22(real, "SKILL.md"))) return [real];
   let entries;
   try {
     entries = readdirSync8(real, { withFileTypes: true });
@@ -4835,24 +5206,24 @@ function resolveDeclaredPath(installPath, realInstall, declaredPath, explicit, p
   }
   const found = [];
   for (const entry of entries) {
-    let childPath = join20(real, entry.name);
+    let childPath = join22(real, entry.name);
     if (entry.isSymbolicLink()) {
       const target = safeRealpath(childPath);
       if (!target || !isInside2(target, realInstall)) {
-        notices.push(`plugin ${pluginId}: skill dir symlink escapes the install root, skipping: ${join20(declaredPath, entry.name)}`);
+        notices.push(`plugin ${pluginId}: skill dir symlink escapes the install root, skipping: ${join22(declaredPath, entry.name)}`);
         continue;
       }
       childPath = target;
     } else if (!entry.isDirectory()) {
       continue;
     }
-    if (existsSync16(join20(childPath, "SKILL.md"))) found.push(childPath);
+    if (existsSync17(join22(childPath, "SKILL.md"))) found.push(childPath);
   }
   return found;
 }
 function resolveSkillDirs(installPath, pluginId) {
   const notices = [];
-  const manifestPath = join20(installPath, ".claude-plugin", "plugin.json");
+  const manifestPath = join22(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`);
@@ -4870,9 +5241,9 @@ function resolveSkillDirs(installPath, pluginId) {
 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 settingsPath = options.settingsPath ?? join22(homeDir, ".claude", "settings.json");
+  const localSettingsPath = options.localSettingsPath ?? join22(cwd, ".claude", "settings.local.json");
+  const installedPluginsPath = options.installedPluginsPath ?? join22(homeDir, ".claude", "plugins", "installed_plugins.json");
   const notices = [];
   const settingsResult = readJsonFileSafe(settingsPath);
   if (settingsResult.problem) {
@@ -4886,7 +5257,7 @@ function discoverClaudePluginRoots(options = {}) {
   }
   const globalEnabled = extractEnabledMap(settingsResult.data);
   let localEnabled = {};
-  if (existsSync16(localSettingsPath)) {
+  if (existsSync17(localSettingsPath)) {
     const localResult = readJsonFileSafe(localSettingsPath);
     if (localResult.problem) {
       notices.push(`local settings ${describeProblem(localResult.problem, localSettingsPath)} \u2014 ignoring local plugin overrides`);
@@ -4919,10 +5290,10 @@ function discoverClaudePluginRoots(options = {}) {
 }
 
 // src/usageSnapshot.ts
-import { readFileSync as readFileSync17, readdirSync as readdirSync9 } from "fs";
-import { extname as extname7, join as join21, resolve as resolvePath4 } from "path";
+import { readFileSync as readFileSync20, readdirSync as readdirSync9 } from "fs";
+import { extname as extname7, join as join23, resolve as resolvePath4 } from "path";
 function isValidCount(value) {
-  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
 }
 function toSnapshot(parsed, sourcePath) {
   return {
@@ -4949,24 +5320,28 @@ function parseSnapshotFile(raw) {
   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 uniqueSkillsUsed = report.unique_skills_used;
   const skillTotalsRaw = report.skill_totals;
   const skillTotals = skillTotalsRaw && typeof skillTotalsRaw === "object" && !Array.isArray(skillTotalsRaw) ? skillTotalsRaw : void 0;
-  const warning = skillTotalsRaw !== void 0 && skillTotals === void 0 ? 'usage snapshot: "skill_totals" is not an object \u2014 ignoring it' : void 0;
+  let warning = skillTotalsRaw !== void 0 && skillTotals === void 0 ? 'usage snapshot: "skill_totals" is not an object \u2014 ignoring it' : 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 (isValidCount(count)) usage.set(name, count);
-    }
-  } else if (topSkills) {
-    for (const row of topSkills) {
-      if (Array.isArray(row) && row.length === 2 && typeof row[0] === "string" && isValidCount(row[1])) {
-        usage.set(row[0], row[1]);
-      }
+  let invalidRows = false;
+  const rows = skillTotals ? Object.entries(skillTotals) : topSkills ?? [];
+  for (const row of rows) {
+    if (!Array.isArray(row) || row.length !== 2 || typeof row[0] !== "string" || !row[0].trim() || !isValidCount(row[1]) || usage.has(row[0])) {
+      invalidRows = true;
+      continue;
     }
+    usage.set(row[0], row[1]);
+  }
+  const observed = [...usage.values()].filter((count) => count > 0).length;
+  const validUniqueCount = isValidCount(uniqueSkillsUsed);
+  const inconsistentTotal = uniqueSkillsUsed !== void 0 && (!validUniqueCount || (skillTotals ? observed !== uniqueSkillsUsed : observed > uniqueSkillsUsed));
+  const exhaustive = !invalidRows && !inconsistentTotal && (Boolean(skillTotals) || topSkills !== void 0 && validUniqueCount && observed === uniqueSkillsUsed);
+  if (invalidRows || inconsistentTotal) {
+    warning = [warning, "usage snapshot contains invalid, duplicate, or inconsistent counts \u2014 coverage is not exhaustive"].filter(Boolean).join("; ");
   }
-  const exhaustive = Boolean(skillTotals) || topSkills !== void 0 && uniqueSkillsUsed !== void 0 && topSkills.length === uniqueSkillsUsed;
   return { usage, exhaustive, windowDays, generatedAt, warning };
 }
 function pickLatest(candidates) {
@@ -4995,10 +5370,10 @@ function loadUsageSnapshot(pathOrDir, opts = {}) {
     }
     const candidates = [];
     for (const name of entries) {
-      const filePath = join21(resolved, name);
+      const filePath = join23(resolved, name);
       let raw2;
       try {
-        raw2 = readFileSync17(filePath, "utf-8");
+        raw2 = readFileSync20(filePath, "utf-8");
       } catch {
         continue;
       }
@@ -5018,7 +5393,7 @@ function loadUsageSnapshot(pathOrDir, opts = {}) {
   }
   let raw;
   try {
-    raw = readFileSync17(resolved, "utf-8");
+    raw = readFileSync20(resolved, "utf-8");
   } catch (err) {
     return emptySnapshot(resolved, `could not read usage snapshot (${err.message})`);
   }
@@ -5033,18 +5408,21 @@ 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 (options.pluginInventory && options.claudePlugins === true) throw new UserError("--plugin-inventory and --claude-plugins cannot be combined. Audit each host separately.");
+  const importedInventory = options.pluginInventory ? readPluginInventory(options.pluginInventory) : void 0;
+  const wantPlugins = !importedInventory && (options.claudePlugins ?? config.claudePlugins ?? false);
+  let pluginRoots = importedInventory?.roots;
+  const notices = [...importedInventory?.notices ?? []];
   if (wantPlugins) {
     const discovered = discoverClaudePluginRoots(deps);
     pluginRoots = discovered.roots;
     notices.push(...discovered.notices);
   }
-  const usageSnapshotPath = options.usageSnapshot ?? config.usageSnapshotPath;
+  if (importedInventory?.host === "codex" && options.usageSnapshot) throw new UserError("Claude skill-monitor snapshots cannot be joined to Codex inventory.");
+  const usageSnapshotPath = importedInventory?.host === "codex" ? void 0 : 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 };
+  return { pluginRoots, usage, notices, importedInventory };
 }
 function splitCsv(s) {
   return s.split(",").map((x) => x.trim()).filter(Boolean);
@@ -5080,12 +5458,12 @@ async function captureBusinessProfile(rl, existing) {
 function resolveReportPath(reportOption) {
   if (reportOption) return resolvePath5(reportOption);
   const iso = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  return join22(getHomeDir(), "reports", `audit-${iso}.md`);
+  return join24(getHomeDir(), "reports", `audit-${iso}.md`);
 }
-function summarizePluginRecommendations(plugins) {
+function summarizePluginRecommendations(plugins2) {
   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})`;
+  for (const p of plugins2) counts[p.recommendation]++;
+  return `plugins: ${plugins2.length} (review ${counts.review}, unobserved ${counts.unobserved}, unknown ${counts.unknown})`;
 }
 function printTerminalSummary(report, reportPath, usage) {
   const { summary } = report;
@@ -5141,7 +5519,7 @@ async function maybeHandoff(config, reportPath, options, rl) {
 }
 async function auditCommand(options = {}, deps = {}) {
   await maybeOfferInit({ json: options.json, yes: options.yes, suppressAuditOffer: true });
-  if (!existsSync17(getConfigPath())) {
+  if (!existsSync18(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)."
     );
@@ -5157,11 +5535,17 @@ async function auditCommand(options = {}, deps = {}) {
         saveConfig(config);
       }
     }
-    const { pluginRoots, usage, notices: pluginUsageNotices } = resolvePluginAndUsageContext(config, options, deps);
+    const { pluginRoots, usage, importedInventory, notices: pluginUsageNotices } = resolvePluginAndUsageContext(config, options, deps);
     const { records: accepted, notices: storeNotices } = readAcceptedFindings();
     const report = await auditConfiguredSet(config, { accepted, pluginRoots, usage });
+    if (importedInventory) {
+      report.hostInventory = { host: importedInventory.host, complete: importedInventory.complete, generatedAt: importedInventory.generatedAt };
+      for (const plugin of report.plugins ?? []) plugin.host = importedInventory.host;
+    }
+    applyPluginDecisions(report, deps.cwd);
     const extraNotices = [...storeNotices, ...pluginUsageNotices];
     if (extraNotices.length > 0) report.notices = [...report.notices, ...extraNotices];
+    if (options.compare) report.comparison = loadAuditComparison(report, options.compare);
     const reportPath = resolveReportPath(options.report);
     writeNewFile(reportPath, renderAuditMarkdown(report), "--report");
     try {
@@ -5212,19 +5596,19 @@ function hasInstalledMember(group) {
   return group.members.some((m) => m.presence === "installed");
 }
 function describeGroup(members, scopes) {
-  const scope = [...scopes].join("+");
+  const scope2 = [...scopes].join("+");
   const installed = members.filter((m) => m.presence === "installed").map((m) => m.agent.displayName);
   const others = members.length - installed.length;
   if (installed.length > 0) {
     const share = others > 0 ? ` (+${others} other agent${others === 1 ? "" : "s"} share this path)` : "";
-    return `on PATH: ${installed.join(", ")} (${scope})${share}`;
+    return `on PATH: ${installed.join(", ")} (${scope2})${share}`;
   }
   const names = members.map((m) => m.agent.displayName);
   const shown = names.slice(0, 3).join(", ");
   const more = names.length > 3 ? `, +${names.length - 3} more` : "";
   const suffix = members.every((m) => m.presence === "absent") ? "CLI not on PATH" : "no verified CLI name to check";
   const who = names.length === 1 ? names[0] : `${names.length} agents: ${shown}${more}`;
-  return `${who} (${scope}) \u2014 ${suffix}`;
+  return `${who} (${scope2}) \u2014 ${suffix}`;
 }
 function detectAgents(cwd, home, pathEnv) {
   const found = [];
@@ -5490,8 +5874,8 @@ 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);
+  const installedPluginsPath = options.installedPluginsPath ?? join25(home, ".claude", "plugins", "installed_plugins.json");
+  const claudePluginsRegistryExists = existsSync19(installedPluginsPath);
   if (options.defaults) {
     const selectedRoots = narrow ? rootGroups.filter(hasInstalledMember) : rootGroups;
     const selectedMcpTargets = narrow ? mcpGroups.filter(hasInstalledMember) : mcpGroups;
@@ -5550,7 +5934,7 @@ async function init(options = {}, deps = {}) {
 }
 async function maybeOfferInit(options = {}) {
   if (options.json || options.yes || !process.stdin.isTTY) return;
-  if (existsSync18(getConfigPath())) return;
+  if (existsSync19(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)."
   );
@@ -5581,7 +5965,7 @@ async function add(source, options = {}) {
   if (!targetRoot) {
     throw new Error("no target skills root configured; pass --target <dir> or set skillsRoots in the config");
   }
-  const resolved = resolve(source, artifact);
+  const resolved = resolve2(source, artifact);
   const entry = await quarantine(resolved, config.quarantineDir);
   const gatedFingerprint = fingerprintDirs(entry.skillDirs).digest;
   if (entry.skillDirs.length === 0) {
@@ -5665,7 +6049,7 @@ async function add(source, options = {}) {
   }
 }
 async function addMcp(source, config, options) {
-  const resolved = resolve(source, "mcp");
+  const resolved = resolve2(source, "mcp");
   const entry = await quarantine(resolved, config.quarantineDir);
   const candidatePath = resolveMcpCandidatePath(entry);
   const { safety, gateResult, proEnabled } = await runGate(candidatePath, "", {
@@ -5701,7 +6085,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] ?? join24(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);
@@ -5756,7 +6140,7 @@ async function scan(source, options = {}) {
   if (artifact === "skill" && !skillsRoot) {
     throw new Error("no skills root configured; set skillsRoots in the config");
   }
-  const resolved = resolve(source, artifact);
+  const resolved = resolve2(source, artifact);
   const entry = await quarantine(resolved, config.quarantineDir);
   try {
     let candidatePath;
@@ -5797,7 +6181,7 @@ async function scan(source, options = {}) {
 }
 
 // src/commands/list.ts
-import { join as join25 } from "path";
+import { join as join27 } from "path";
 async function list() {
   await maybeOfferInit();
   const config = loadConfig();
@@ -5810,14 +6194,14 @@ async function list() {
   }
   console.log(`[skill-forge] ${ids.length} held in quarantine (${quarantineDir}):`);
   for (const id of ids) {
-    const skillDirs = findSkillDirs(join25(quarantineDir, id));
+    const skillDirs = findSkillDirs(join27(quarantineDir, id));
     if (skillDirs.length === 0) {
       console.log(`  ${id}  (no SKILL.md found)`);
       continue;
     }
     const names = skillDirs.map((dir) => {
       try {
-        return readFrontmatter(join25(dir, "SKILL.md")).name;
+        return readFrontmatter(join27(dir, "SKILL.md")).name;
       } catch {
         return dir;
       }
@@ -5827,23 +6211,23 @@ async function list() {
 }
 
 // src/commands/guide.ts
-import { existsSync as existsSync20 } from "fs";
+import { existsSync as existsSync21 } from "fs";
 
 // src/commands/held.ts
-import { existsSync as existsSync19, realpathSync as realpathSync4 } from "fs";
-import { basename as basename9, join as join26, resolve as resolvePath6, sep as sep5 } from "path";
+import { existsSync as existsSync20, realpathSync as realpathSync6 } from "fs";
+import { basename as basename9, join as join28, resolve as resolvePath6, sep as sep7 } 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 = join26(quarantineDir, id);
-  if (!existsSync19(candidate)) {
+  const candidate = join28(quarantineDir, id);
+  if (!existsSync20(candidate)) {
     throw new UserError(`no held entry with id "${id}" \u2014 run \`skill-forge list\` to see what is in quarantine`);
   }
-  const realRoot = realpathSync4(resolvePath6(quarantineDir));
-  const realCandidate = realpathSync4(candidate);
-  if (!realCandidate.startsWith(realRoot + sep5)) {
+  const realRoot = realpathSync6(resolvePath6(quarantineDir));
+  const realCandidate = realpathSync6(candidate);
+  if (!realCandidate.startsWith(realRoot + sep7)) {
     throw new UserError(`refusing to act on "${id}": it resolves outside the quarantine dir (${realRoot})`);
   }
   return realCandidate;
@@ -5866,7 +6250,7 @@ function resolveTargetRoot(config, target) {
 function heldSkillNames(skillDirs) {
   return skillDirs.map((dir) => {
     try {
-      return readFrontmatter(join26(dir, "SKILL.md")).name;
+      return readFrontmatter(join28(dir, "SKILL.md")).name;
     } catch {
       return basename9(dir);
     }
@@ -5874,7 +6258,7 @@ function heldSkillNames(skillDirs) {
 }
 function looksLikeMcpSandbox(quarantinePath) {
   const candidate = resolveMcpCandidatePath({ quarantinePath });
-  return [".mcp.json", "mcp.json", "package.json"].some((f) => existsSync19(join26(candidate, f)));
+  return [".mcp.json", "mcp.json", "package.json"].some((f) => existsSync20(join28(candidate, f)));
 }
 async function promoteHeldMcp(id, entry, config, options) {
   const candidatePath = resolveMcpCandidatePath(entry);
@@ -5908,7 +6292,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] ?? join26(process.cwd(), ".mcp.json");
+  const mcpTargetPath = options.mcpTarget ?? config.mcpTargets?.[0] ?? join28(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);
@@ -6153,7 +6537,7 @@ var TOPICS = [
 ];
 function readState() {
   const configPath = getConfigPath();
-  const configured = existsSync20(configPath);
+  const configured = existsSync21(configPath);
   const base = {
     configured,
     configPath,
@@ -6387,17 +6771,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 existsSync21, lstatSync as lstatSync4, mkdtempSync as mkdtempSync3, readFileSync as readFileSync18, rmSync as rmSync6 } from "fs";
+import { cpSync as cpSync3, existsSync as existsSync22, lstatSync as lstatSync4, mkdtempSync as mkdtempSync3, readFileSync as readFileSync21, rmSync as rmSync6 } from "fs";
 import { tmpdir as tmpdir2 } from "os";
-import { basename as basename10, dirname as dirname9, join as join27, resolve as resolvePath7, sep as sep6 } from "path";
+import { basename as basename10, dirname as dirname9, join as join29, resolve as resolvePath7, sep as sep8 } 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 = resolvePath7(targetSkillDir);
-  const skillMdPath = join27(resolvedTargetDir, "SKILL.md");
-  if (!existsSync21(skillMdPath)) {
+  const skillMdPath = join29(resolvedTargetDir, "SKILL.md");
+  if (!existsSync22(skillMdPath)) {
     throw new UserError(`no SKILL.md found at ${skillMdPath} \u2014 evolve requires an existing, installed skill directory`);
   }
   const proStatus = proFeatureStatus(PRO_FEATURE_LABEL3);
@@ -6455,33 +6839,33 @@ async function evolve(targetSkillDir, options = {}, deps = {}) {
     }
     return;
   }
-  const stagingRoot = join27(project, ".skillopt-sleep", "staging");
+  const stagingRoot = join29(project, ".skillopt-sleep", "staging");
   const stagingDir = resolvePath7(parsed.staging_dir);
-  if (stagingDir !== stagingRoot && !stagingDir.startsWith(stagingRoot + sep6)) {
+  if (stagingDir !== stagingRoot && !stagingDir.startsWith(stagingRoot + sep8)) {
     throw new UserError(
       `skillopt-sleep reported a staging_dir outside the expected sandbox (${stagingRoot}): ${stagingDir} \u2014 refusing to use it`
     );
   }
-  const proposedSkillMd = join27(stagingDir, "proposed_SKILL.md");
-  const proposedClaudeMd = join27(stagingDir, "proposed_CLAUDE.md");
-  const reportMdPath = join27(stagingDir, "report.md");
-  if (!existsSync21(proposedSkillMd)) {
+  const proposedSkillMd = join29(stagingDir, "proposed_SKILL.md");
+  const proposedClaudeMd = join29(stagingDir, "proposed_CLAUDE.md");
+  const reportMdPath = join29(stagingDir, "report.md");
+  if (!existsSync22(proposedSkillMd)) {
     throw new UserError(`skillopt-sleep reported an accepted proposal but ${proposedSkillMd} is missing`);
   }
-  if (existsSync21(reportMdPath)) {
+  if (existsSync22(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(join27(tmpdir2(), "skill-forge-evolve-"));
+  const tempDir = mkdtempSync3(join29(tmpdir2(), "skill-forge-evolve-"));
   let profile;
   let safety;
   try {
-    cpSync3(proposedSkillMd, join27(tempDir, "SKILL.md"));
-    if (existsSync21(proposedClaudeMd)) {
-      cpSync3(proposedClaudeMd, join27(tempDir, "CLAUDE.md"));
+    cpSync3(proposedSkillMd, join29(tempDir, "SKILL.md"));
+    if (existsSync22(proposedClaudeMd)) {
+      cpSync3(proposedClaudeMd, join29(tempDir, "CLAUDE.md"));
     }
     profile = asSkillProfile(profileSkill(tempDir), "for the evolved proposal");
     const strictness = loadConfig().strictness;
@@ -6580,7 +6964,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 (existsSync21(reportMdPath)) {
+    if (existsSync22(reportMdPath)) {
       logOutcome(`[skill-forge] see ${reportMdPath} for the full evidence report`, json);
     }
   }
@@ -6622,10 +7006,10 @@ function validateRunOutput(raw) {
   return { accepted: Boolean(obj.accepted), staging_dir: stagingDirRaw ?? null };
 }
 function readManifest(stagingDir) {
-  const manifestPath = join27(stagingDir, "manifest.json");
+  const manifestPath = join29(stagingDir, "manifest.json");
   let raw;
   try {
-    raw = readFileSync18(manifestPath, "utf-8");
+    raw = readFileSync21(manifestPath, "utf-8");
   } catch (err) {
     throw new UserError(`could not read staging manifest ${manifestPath}: ${err.message}`);
   }
@@ -6659,18 +7043,18 @@ function validateManifest(raw, manifestPath) {
   };
 }
 function filesIdentical(a, b) {
-  if (!existsSync21(a) || !existsSync21(b)) return false;
-  return readFileSync18(a).equals(readFileSync18(b));
+  if (!existsSync22(a) || !existsSync22(b)) return false;
+  return readFileSync21(a).equals(readFileSync21(b));
 }
 function isAlreadyAdopted(stagingDir, manifest) {
-  const proposedSkillMd = join27(stagingDir, "proposed_SKILL.md");
-  const proposedClaudeMd = join27(stagingDir, "proposed_CLAUDE.md");
+  const proposedSkillMd = join29(stagingDir, "proposed_SKILL.md");
+  const proposedClaudeMd = join29(stagingDir, "proposed_CLAUDE.md");
   let sawComparison = false;
-  if (existsSync21(proposedSkillMd)) {
+  if (existsSync22(proposedSkillMd)) {
     sawComparison = true;
     if (!filesIdentical(proposedSkillMd, manifest.live_skill_path)) return false;
   }
-  if (existsSync21(proposedClaudeMd) && manifest.live_memory_path) {
+  if (existsSync22(proposedClaudeMd) && manifest.live_memory_path) {
     sawComparison = true;
     if (!filesIdentical(proposedClaudeMd, manifest.live_memory_path)) return false;
   }
@@ -6688,8 +7072,8 @@ function assertNotSymlink(path, label2) {
   }
 }
 function sha256File(path) {
-  if (!existsSync21(path)) return null;
-  return createHash3("sha256").update(readFileSync18(path)).digest("hex");
+  if (!existsSync22(path)) return null;
+  return createHash3("sha256").update(readFileSync21(path)).digest("hex");
 }
 
 // src/commands/evolve.ts
@@ -6698,9 +7082,9 @@ async function evolveCommand(targetSkillDir, options = {}) {
 }
 
 // src/commands/finding.ts
-import { existsSync as existsSync22 } from "fs";
+import { existsSync as existsSync23 } from "fs";
 function requireSavedConfig() {
-  if (!existsSync22(getConfigPath())) {
+  if (!existsSync23(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)."
     );
@@ -6786,7 +7170,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) => !existsSync22(r.target)) : records;
+  const rows = options.stale ? records.filter((r) => !existsSync23(r.target)) : records;
   if (options.json) {
     console.log(JSON.stringify(rows, null, 2));
     return;
@@ -6807,8 +7191,8 @@ async function findingListCommand(options = {}) {
 import { resolve as resolvePath9 } from "path";
 
 // src/organize.ts
-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";
+import { existsSync as existsSync24, readFileSync as readFileSync22, readdirSync as readdirSync10, realpathSync as realpathSync7, statSync as statSync10 } from "fs";
+import { basename as basename11, join as join30, 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", "experimental"]);
@@ -6821,14 +7205,14 @@ function listSubdirs2(dir) {
   }
   const out = [];
   for (const entry of entries) {
-    const full = join28(dir, entry.name);
+    const full = join30(dir, entry.name);
     if (entry.isDirectory()) {
       out.push(full);
       continue;
     }
     if (entry.isSymbolicLink()) {
       try {
-        if (statSync9(full).isDirectory()) out.push(full);
+        if (statSync10(full).isDirectory()) out.push(full);
       } catch {
       }
     }
@@ -6839,14 +7223,14 @@ function findSkillDirsUnderRoot2(root) {
   const found = /* @__PURE__ */ new Set();
   const topDirs = listSubdirs2(root);
   for (const dir of topDirs) {
-    if (existsSync23(join28(dir, "SKILL.md"))) found.add(dir);
+    if (existsSync24(join30(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 dir of listSubdirs2(join30(root, "skills"))) {
+    if (existsSync24(join30(dir, "SKILL.md"))) found.add(dir);
   }
   for (const topDir of topDirs) {
-    for (const dir of listSubdirs2(join28(topDir, "skills"))) {
-      if (existsSync23(join28(dir, "SKILL.md"))) found.add(dir);
+    for (const dir of listSubdirs2(join30(topDir, "skills"))) {
+      if (existsSync24(join30(dir, "SKILL.md"))) found.add(dir);
     }
   }
   return Array.from(found).filter((p) => !p.includes("/.git/"));
@@ -7042,17 +7426,17 @@ function buildRegistryEntries(candidates, warnings) {
   for (const candidate of candidates) {
     let realPath;
     try {
-      realPath = realpathSync5(candidate.dirPath);
+      realPath = realpathSync7(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 = join28(realPath, "SKILL.md");
+    const skillMdPath = join30(realPath, "SKILL.md");
     let text;
     try {
-      text = readFileSync19(skillMdPath, "utf-8");
+      text = readFileSync22(skillMdPath, "utf-8");
     } catch (err) {
       warnings.push(`could not read ${skillMdPath}: ${err.message}`);
       continue;
@@ -7458,13 +7842,13 @@ async function find(query, options = {}, deps = {}) {
 }
 
 // src/commands/watch.ts
-import { realpathSync as realpathSync6 } from "fs";
-import { join as join29, resolve as resolvePath10 } from "path";
+import { realpathSync as realpathSync8 } from "fs";
+import { join as join31, resolve as resolvePath10 } from "path";
 
 // src/gate/skillMapDrift.ts
 import { createHash as createHash4 } from "crypto";
-import { readFileSync as readFileSync20, existsSync as existsSync24 } from "fs";
-import { dirname as dirname10, isAbsolute as isAbsolute4, resolve as resolve7 } from "path";
+import { readFileSync as readFileSync23, existsSync as existsSync25 } from "fs";
+import { dirname as dirname10, isAbsolute as isAbsolute6, resolve as resolve8 } from "path";
 function sha256(text) {
   return createHash4("sha256").update(text, "utf-8").digest("hex");
 }
@@ -7497,22 +7881,22 @@ function threeWayVerdict(localNormalized, upstreamHash, baselineHash) {
 }
 function resolveLocalPath(path, mapDir) {
   const expanded = expandHome(path);
-  if (isAbsolute4(expanded)) return resolve7(expanded);
-  const candidates = [resolve7(expanded)];
+  if (isAbsolute6(expanded)) return resolve8(expanded);
+  const candidates = [resolve8(expanded)];
   if (mapDir) {
-    candidates.push(resolve7(mapDir, expanded));
-    candidates.push(resolve7(mapDir, "..", expanded));
+    candidates.push(resolve8(mapDir, expanded));
+    candidates.push(resolve8(mapDir, "..", expanded));
   }
   for (const candidate of candidates) {
-    if (existsSync24(candidate)) return candidate;
+    if (existsSync25(candidate)) return candidate;
   }
   return candidates[0];
 }
 function defaultReadLocalFile(path, mapDir) {
   const resolved = resolveLocalPath(path, mapDir);
-  if (!existsSync24(resolved)) return void 0;
+  if (!existsSync25(resolved)) return void 0;
   try {
-    return readFileSync20(resolved, "utf-8");
+    return readFileSync23(resolved, "utf-8");
   } catch {
     return void 0;
   }
@@ -7533,7 +7917,7 @@ function upstreamLabel(node, edge) {
   return node?.url ?? node?.path ?? node?.name ?? node?.id ?? edge.to;
 }
 async function computeMapDrift(map, deps = {}) {
-  const mapDir = deps.mapPath ? dirname10(resolve7(expandHome(deps.mapPath))) : void 0;
+  const mapDir = deps.mapPath ? dirname10(resolve8(expandHome(deps.mapPath))) : void 0;
   const readLocalFile = deps.readLocalFile ?? ((path) => defaultReadLocalFile(path, mapDir));
   const fetchUpstream = deps.fetchUpstream ?? defaultFetchUpstream;
   const rows = [];
@@ -7553,7 +7937,7 @@ async function computeMapDrift(map, deps = {}) {
       continue;
     }
     const localResolved = resolveLocalPath(localNode.path, mapDir);
-    if (!existsSync24(localResolved)) {
+    if (!existsSync25(localResolved)) {
       rows.push({
         skill: skillLabel,
         upstream,
@@ -7664,7 +8048,7 @@ async function runWatch(config, options = {}, deps = {}) {
     let realPath = resolvedRoot;
     if (exists) {
       try {
-        realPath = realpathSync6(resolvedRoot);
+        realPath = realpathSync8(resolvedRoot);
       } catch {
         realPath = resolvedRoot;
       }
@@ -7676,7 +8060,7 @@ async function runWatch(config, options = {}, deps = {}) {
       ledger = readProvenanceLedger(resolvedRoot);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      const ledgerPath = join29(resolvedRoot, "SOURCES.md");
+      const ledgerPath = join31(resolvedRoot, "SOURCES.md");
       roots.push({ root, realPath, exists, ledgerPath, ledgerExists: false });
       warnings.push(`${ledgerPath}: could not read ledger: ${message}`);
       continue;
@@ -7786,8 +8170,8 @@ async function watchCommand(options = {}) {
 }
 
 // src/commands/routine.ts
-import { existsSync as existsSync25, rmSync as rmSync7, statSync as statSync10 } from "fs";
-import { join as join30 } from "path";
+import { existsSync as existsSync26, rmSync as rmSync7, statSync as statSync11 } from "fs";
+import { join as join32 } from "path";
 var PRO_FEATURE_LABEL6 = "the scheduled maintenance routine";
 var SEVERITY_ORDER = ["LOW", "MEDIUM", "HIGH", "CRITICAL"];
 function parseFailOnFloor(failOn) {
@@ -7795,20 +8179,20 @@ function parseFailOnFloor(failOn) {
   if (failOn === "any") return "LOW";
   return failOn.toUpperCase();
 }
-function exceedsFloor(audit2, failOn) {
+function exceedsFloor(findings, failOn) {
   const floor = parseFailOnFloor(failOn);
   if (!floor) return void 0;
   const floorIndex = SEVERITY_ORDER.indexOf(floor);
   for (let i = SEVERITY_ORDER.length - 1; i >= floorIndex; i--) {
     const severity = SEVERITY_ORDER[i];
-    const count = audit2.findings[severity] ?? 0;
+    const count = findings[severity] ?? 0;
     if (count > 0) return `${count} ${severity} finding(s) at or above --fail-on ${failOn}`;
   }
   return void 0;
 }
 function resolveReportPath2(override, generatedAt) {
   if (override) return override;
-  return join30(getHomeDir(), "reports", `routine-${generatedAt.replace(/[:.]/g, "-")}.md`);
+  return join32(getHomeDir(), "reports", `routine-${generatedAt.replace(/[:.]/g, "-")}.md`);
 }
 function runHousekeeping(config, options) {
   const actions = [];
@@ -7817,10 +8201,10 @@ function runHousekeeping(config, options) {
   const pruneDays = options.pruneDays ?? 30;
   const cutoff = Date.now() - pruneDays * 864e5;
   for (const id of listQuarantineIds(config.quarantineDir)) {
-    const path = join30(config.quarantineDir, id);
+    const path = join32(config.quarantineDir, id);
     let mtime;
     try {
-      mtime = statSync10(path).mtimeMs;
+      mtime = statSync11(path).mtimeMs;
     } catch {
       continue;
     }
@@ -7855,7 +8239,7 @@ function runHousekeeping(config, options) {
   }
   for (const entry of entries) {
     if (entry.status !== "pending") continue;
-    if (!entry.installedPath || existsSync25(entry.installedPath)) continue;
+    if (!entry.installedPath || existsSync26(entry.installedPath)) continue;
     if (apply) {
       try {
         updateQueueEntry(entry.id, { status: "dismissed" });
@@ -7888,6 +8272,7 @@ function renderRoutineMarkdown(result, audit2, watch, organize) {
     "",
     `- Skills: ${result.audit.skillCount} across ${audit2.summary.rootCount} configured root(s)`,
     `- Findings: ${audit2.summary.findingCounts.CRITICAL ?? 0} critical, ${audit2.summary.findingCounts.HIGH ?? 0} high, ${audit2.summary.findingCounts.MEDIUM ?? 0} medium, ${audit2.summary.findingCounts.LOW ?? 0} low`,
+    `- Failure scope: ${result.failScope} (configured excludes plugin-origin findings; all includes them)`,
     `- Accepted: ${audit2.summary.acceptedCount} (suppressed from the counts above; see Accepted findings)`,
     `- Overlap clusters: ${result.audit.overlapClusters.length}${result.audit.overlapLocked ? ' (overlap analysis was locked \u2014 not "none found")' : ""}`,
     `- Pending queue entries: ${result.pending.queue}`,
@@ -7957,15 +8342,23 @@ async function routineCommand(options = {}, deps = {}) {
   if (options.dryRun && !options.housekeeping) {
     throw new UserError("--dry-run only applies to --housekeeping; without it `routine` already writes nothing but its own report");
   }
+  const failScope = options.failScope ?? "configured";
+  if (failScope !== "configured" && failScope !== "all") throw new UserError("--fail-scope must be configured or all");
   const config = loadConfig();
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const { pluginRoots, usage, notices: pluginUsageNotices } = resolvePluginAndUsageContext(config, options, deps);
+  const { pluginRoots, usage, importedInventory, notices: pluginUsageNotices } = resolvePluginAndUsageContext(config, options, deps);
   const { records: accepted, notices: storeNotices } = readAcceptedFindings();
   const notices = [...storeNotices, ...pluginUsageNotices];
   for (const notice of notices) log(`[skill-forge] ${notice}`);
   const audit2 = await auditConfiguredSet(config, { accepted, pluginRoots, usage });
+  if (importedInventory) {
+    audit2.hostInventory = { host: importedInventory.host, complete: importedInventory.complete, generatedAt: importedInventory.generatedAt };
+    for (const plugin of audit2.plugins ?? []) plugin.host = importedInventory.host;
+  }
+  applyPluginDecisions(audit2, deps.cwd);
+  notices.push(...audit2.notices);
   const auditState = summarizeAudit(audit2);
-  if (audit2.plugins) {
+  if (audit2.plugins && failScope === "configured") {
     const critical = audit2.plugins.reduce((n, p) => n + p.findingCounts.CRITICAL, 0);
     const high = audit2.plugins.reduce((n, p) => n + p.findingCounts.HIGH, 0);
     if (critical + high > 0) {
@@ -8001,7 +8394,11 @@ async function routineCommand(options = {}, deps = {}) {
   }
   const quarantine2 = heldCount(config.quarantineDir);
   if (!quarantine2.readable) degraded.push("quarantine dir could not be listed \u2014 held count is not trustworthy");
+  const failureCounts = failScope === "all" ? audit2.summary.findingCounts : auditState.findings;
   const result = {
+    schemaVersion: 1,
+    failScope,
+    failureCounts,
     generatedAt,
     reportPath: resolveReportPath2(options.report, generatedAt),
     audit: auditState,
@@ -8019,7 +8416,7 @@ async function routineCommand(options = {}, deps = {}) {
     notices,
     degraded
   };
-  const failure = degraded.length > 0 ? `${degraded.length} step(s) did not complete: ${degraded.join("; ")}` : exceedsFloor(auditState, options.failOn ?? "none");
+  const failure = degraded.length > 0 ? `${degraded.length} step(s) did not complete: ${degraded.join("; ")}` : exceedsFloor(failureCounts, options.failOn ?? "none");
   if (failure) result.failure = failure;
   writeNewFile(result.reportPath, renderRoutineMarkdown(result, audit2, watch, organize), "--report");
   try {
@@ -8031,6 +8428,7 @@ async function routineCommand(options = {}, deps = {}) {
     console.log(JSON.stringify(result, null, 2));
   } else {
     console.log("[skill-forge] routine");
+    console.log(`  failure scope: ${failScope}`);
     console.log(`  skills: ${auditState.skillCount}`);
     console.log(
       `  findings: ${auditState.findings.CRITICAL ?? 0} critical / ${auditState.findings.HIGH ?? 0} high / ${auditState.findings.MEDIUM ?? 0} medium / ${auditState.findings.LOW ?? 0} low`
@@ -8060,8 +8458,8 @@ async function routineCommand(options = {}, deps = {}) {
 }
 
 // src/commands/ingest.ts
-import { realpathSync as realpathSync7 } from "fs";
-import { dirname as dirname12, isAbsolute as isAbsolute5, relative as relative4, resolve as resolvePath11 } from "path";
+import { realpathSync as realpathSync9 } from "fs";
+import { dirname as dirname12, isAbsolute as isAbsolute7, relative as relative6, resolve as resolvePath11 } from "path";
 var PRO_FEATURE_LABEL7 = "the pending-ingestion queue";
 var VALID_STATUSES = ["ingested", "dismissed"];
 function requireProFeature() {
@@ -8102,14 +8500,14 @@ function printPendingList(pending, json) {
 }
 function realpathOrNull(p) {
   try {
-    return realpathSync7(p);
+    return realpathSync9(p);
   } catch {
     return null;
   }
 }
 function isUnderRoot(candidate, root) {
-  const rel = relative4(root, candidate);
-  return rel === "" || !rel.startsWith("..") && !isAbsolute5(rel);
+  const rel = relative6(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute7(rel);
 }
 function validatePendingEntries(entries, config) {
   const quarantineRoot = realpathOrNull(resolvePath11(config.quarantineDir));
@@ -8191,15 +8589,15 @@ import {
   chmodSync as chmodSync3,
   lstatSync as lstatSync6,
   mkdirSync as mkdirSync9,
-  readFileSync as readFileSync24,
+  readFileSync as readFileSync27,
   readSync as readSync3,
   writeFileSync as writeFileSync8
 } from "fs";
-import { dirname as dirname13, isAbsolute as isAbsolute7, join as join35, relative as relative6, resolve as resolvePath12 } from "path";
+import { dirname as dirname13, isAbsolute as isAbsolute9, join as join37, relative as relative8, resolve as resolvePath12 } from "path";
 
 // src/insights/inventory.ts
-import { readFileSync as readFileSync21 } from "fs";
-import { join as join31 } from "path";
+import { readFileSync as readFileSync24 } from "fs";
+import { join as join33 } from "path";
 
 // src/insights/models.ts
 import { createHash as createHash5 } from "crypto";
@@ -8313,7 +8711,7 @@ function declaredMapCoverage(path, claim) {
 }
 function fingerprintInstalledSkill(path) {
   try {
-    return { fingerprint: stableHash(readFileSync21(join31(path, "SKILL.md"), "utf-8")) };
+    return { fingerprint: stableHash(readFileSync24(join33(path, "SKILL.md"), "utf-8")) };
   } catch (error) {
     return { reason: `could not fingerprint SKILL.md: ${error.message}` };
   }
@@ -8463,12 +8861,12 @@ function buildInsightInventory(config, options = {}) {
 }
 
 // src/insights/jira.ts
-import { existsSync as existsSync27, readFileSync as readFileSync23 } from "fs";
-import { join as join34 } from "path";
+import { existsSync as existsSync28, readFileSync as readFileSync26 } from "fs";
+import { join as join36 } from "path";
 
 // src/insights/store.ts
-import { chmodSync as chmodSync2, existsSync as existsSync26, mkdirSync as mkdirSync8, readFileSync as readFileSync22 } from "fs";
-import { join as join33 } from "path";
+import { chmodSync as chmodSync2, existsSync as existsSync27, mkdirSync as mkdirSync8, readFileSync as readFileSync25 } from "fs";
+import { join as join35 } from "path";
 
 // src/insights/sources.ts
 import { createHash as createHash6 } from "crypto";
@@ -8480,10 +8878,10 @@ import {
   openSync as openSync3,
   readSync as readSync2,
   readdirSync as readdirSync11,
-  realpathSync as realpathSync8,
-  statSync as statSync11
+  realpathSync as realpathSync10,
+  statSync as statSync12
 } from "fs";
-import { basename as basename12, extname as extname8, isAbsolute as isAbsolute6, join as join32, relative as relative5, resolve as resolve8, sep as sep7 } from "path";
+import { basename as basename12, extname as extname8, isAbsolute as isAbsolute8, join as join34, relative as relative7, resolve as resolve9, sep as sep9 } 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"]);
@@ -8554,8 +8952,8 @@ function canonicalPublicUrl(raw, label2) {
   return url.toString();
 }
 function isInside3(child, root) {
-  const rel = relative5(root, child);
-  return rel === "" || !rel.startsWith(`..${sep7}`) && rel !== ".." && !isAbsolute6(rel);
+  const rel = relative7(root, child);
+  return rel === "" || !rel.startsWith(`..${sep9}`) && rel !== ".." && !isAbsolute8(rel);
 }
 function isHiddenName(name) {
   return name.startsWith(".") && name !== "." && name !== "..";
@@ -8619,8 +9017,8 @@ function observeFile(path, relativePath, declaredMediaType, maxFileBytes, remain
   if (!bytes || !descriptorStat) throw new UserError(`source file could not be observed: ${relativePath}`);
   let realPath;
   try {
-    realPath = realpathSync8(path);
-    const pathStat = statSync11(realPath);
+    realPath = realpathSync10(path);
+    const pathStat = statSync12(realPath);
     if (pathStat.dev !== descriptorStat.dev || pathStat.ino !== descriptorStat.ino) {
       throw new Error("path identity changed");
     }
@@ -8741,7 +9139,7 @@ function normalizeStdin(input, retrievedAt, maxFileBytes, remainingBytes) {
   };
 }
 function normalizeFile(input, retrievedAt, maxFileBytes, remainingBytes) {
-  const resolved = resolve8(input.path);
+  const resolved = resolve9(input.path);
   let lexicalStat;
   try {
     lexicalStat = lstatSync5(resolved);
@@ -8792,7 +9190,7 @@ function normalizeFile(input, retrievedAt, maxFileBytes, remainingBytes) {
   };
 }
 function normalizeDirectory(input, retrievedAt, maxFileBytes, remainingBytes) {
-  const resolved = resolve8(input.path);
+  const resolved = resolve9(input.path);
   let lexicalStat;
   try {
     lexicalStat = lstatSync5(resolved);
@@ -8801,7 +9199,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 = realpathSync8(resolved);
+  const realRoot = realpathSync10(resolved);
   const observations = [];
   const skipped = [];
   const seenFiles = /* @__PURE__ */ new Set();
@@ -8815,7 +9213,7 @@ function normalizeDirectory(input, retrievedAt, maxFileBytes, remainingBytes) {
       throw new UserError(`unable to enumerate source directory ${dir}: ${err.message}`);
     }
     for (const entry of entries) {
-      const full = join32(dir, entry.name);
+      const full = join34(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" });
@@ -8832,14 +9230,14 @@ function normalizeDirectory(input, retrievedAt, maxFileBytes, remainingBytes) {
       if (entry.isSymbolicLink()) {
         let realTarget;
         try {
-          realTarget = realpathSync8(full);
+          realTarget = realpathSync10(full);
         } catch {
           throw new UserError(`source directory contains an unreadable symlink: ${logicalPath}`);
         }
         if (!isInside3(realTarget, realRoot)) {
           throw new UserError(`source directory symlink escapes its root: ${logicalPath}`);
         }
-        const targetStat = statSync11(realTarget);
+        const targetStat = statSync12(realTarget);
         if (targetStat.isDirectory()) {
           if (seenDirs.has(realTarget)) continue;
           seenDirs.add(realTarget);
@@ -8851,7 +9249,7 @@ function normalizeDirectory(input, retrievedAt, maxFileBytes, remainingBytes) {
           continue;
         }
       } else if (entry.isDirectory()) {
-        const realDir = realpathSync8(full);
+        const realDir = realpathSync10(full);
         if (seenDirs.has(realDir)) continue;
         seenDirs.add(realDir);
         walk2(full, logicalPath);
@@ -8860,7 +9258,7 @@ function normalizeDirectory(input, retrievedAt, maxFileBytes, remainingBytes) {
         skipped.push({ path: logicalPath, reason: "unsupported-media-type" });
         continue;
       }
-      const realFile = realpathSync8(full);
+      const realFile = realpathSync10(full);
       if (!isInside3(realFile, realRoot)) {
         throw new UserError(`source directory entry escaped its root while being observed: ${logicalPath}`);
       }
@@ -8967,17 +9365,17 @@ function normalizeSources(inputs, options = {}) {
 // src/insights/store.ts
 var STUDY_ID = /^STUDY-[0-9a-f]{16}$/;
 function getInsightsDir() {
-  return join33(getHomeDir(), "insights");
+  return join35(getHomeDir(), "insights");
 }
 function getStudyDir(studyId) {
   assertStudyId(studyId);
-  return join33(getInsightsDir(), studyId);
+  return join35(getInsightsDir(), studyId);
 }
 function getStudyPath(studyId) {
-  return join33(getStudyDir(studyId), "study.json");
+  return join35(getStudyDir(studyId), "study.json");
 }
 function getStudyEventsPath(studyId) {
-  return join33(getStudyDir(studyId), "events.jsonl");
+  return join35(getStudyDir(studyId), "events.jsonl");
 }
 function createStudyId(sourceInventoryHash, createdAt) {
   return stableId("STUDY", { sourceInventoryHash, createdAt });
@@ -9108,7 +9506,7 @@ function validateStudyShape(value, path) {
 function parseStudy(path) {
   let raw;
   try {
-    raw = readFileSync22(path, "utf-8");
+    raw = readFileSync25(path, "utf-8");
   } catch (err) {
     throw new UserError(`unable to read insight study at ${path}: ${err.message}`);
   }
@@ -9142,7 +9540,7 @@ function createInsightStudy(input, options = {}) {
   const studyId = options.studyId ?? createStudyId(input.sourceInventoryHash, createdAt);
   assertStudyId(studyId);
   const path = getStudyPath(studyId);
-  if (existsSync26(path)) throw new UserError(`insight study already exists: ${studyId}`);
+  if (existsSync27(path)) throw new UserError(`insight study already exists: ${studyId}`);
   const study = {
     schemaVersion: INSIGHT_SCHEMA_VERSION,
     studyId,
@@ -9163,7 +9561,7 @@ function createInsightStudy(input, options = {}) {
 }
 function readInsightStudy(studyId) {
   const path = getStudyPath(studyId);
-  if (!existsSync26(path)) throw new UserError(`no insight study with id: ${studyId}`);
+  if (!existsSync27(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`);
@@ -9173,7 +9571,7 @@ function readInsightStudy(studyId) {
 function writeInsightStudy(study, now = /* @__PURE__ */ new Date()) {
   assertStudyId(study.studyId);
   const path = getStudyPath(study.studyId);
-  if (!existsSync26(path)) throw new UserError(`no insight study with id: ${study.studyId}`);
+  if (!existsSync27(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") {
@@ -9910,7 +10308,7 @@ function buildJiraManifest(study, projectKey, options = {}) {
   return manifest;
 }
 function getJiraReceiptsPath(studyId) {
-  return join34(getStudyDir(studyId), "jira-receipts.jsonl");
+  return join36(getStudyDir(studyId), "jira-receipts.jsonl");
 }
 function assertCurrentJiraManifest(study, value) {
   if (study.status !== "jira-manifested" || !study.jira) {
@@ -10042,10 +10440,10 @@ function appendJiraReceipt(studyId, manifest, input) {
 function readJiraReceipts(studyId, manifest) {
   const currentManifest = assertCurrentJiraManifest(readInsightStudy(studyId), manifest);
   const path = getJiraReceiptsPath(studyId);
-  if (!existsSync27(path)) return [];
+  if (!existsSync28(path)) return [];
   let text;
   try {
-    text = readFileSync23(path, "utf-8");
+    text = readFileSync26(path, "utf-8");
   } catch (error) {
     throw new UserError(`unable to read Jira receipts at ${path}: ${error.message}`);
   }
@@ -10187,7 +10585,7 @@ function parseJsonFile(path, label2) {
   const resolved = resolvePath12(path);
   let raw;
   try {
-    raw = readFileSync24(resolved, "utf-8");
+    raw = readFileSync27(resolved, "utf-8");
   } catch (error) {
     throw new UserError(`unable to read ${label2} at ${resolved}: ${error.message}`);
   }
@@ -10242,7 +10640,7 @@ function assertCommonDescriptorFields(value, label2) {
 }
 function pathRelativeTo(baseDir, raw, label2) {
   const path = nonEmptyString(raw, label2);
-  return isAbsolute7(path) ? path : resolvePath12(baseDir, path);
+  return isAbsolute9(path) ? path : resolvePath12(baseDir, path);
 }
 function parseManifestDescriptor(value, index, baseDir) {
   const label2 = `source manifest entry ${index + 1}`;
@@ -10332,10 +10730,10 @@ function collectSourceInputs(sourceArgs, options) {
   return inputs;
 }
 function contextPath(studyId) {
-  return join35(getStudyDir(studyId), CONTEXT_FILENAME);
+  return join37(getStudyDir(studyId), CONTEXT_FILENAME);
 }
 function inventoryPath(studyId) {
-  return join35(getStudyDir(studyId), INVENTORY_FILENAME);
+  return join37(getStudyDir(studyId), INVENTORY_FILENAME);
 }
 function writeCommandContext(studyId, skillMapPath, skillMapCoverage, inventory) {
   const context = {
@@ -10349,7 +10747,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" || !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))) {
+  if (!isRecord5(parsed) || parsed.schemaVersion !== 1 || parsed.skillMapPath !== void 0 && (typeof parsed.skillMapPath !== "string" || !isAbsolute9(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;
@@ -10373,18 +10771,18 @@ function readCurrentStudy(studyId) {
 }
 function retainedPath(root, relativePath) {
   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`);
+  const rel = relative8(root, candidate);
+  if (rel.startsWith("..") || isAbsolute9(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 = join35(getStudyDir(study.studyId), "retained-sources");
+  const root = join37(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 = join35(root, file.sourceId);
+    const sourceRoot = join37(root, file.sourceId);
     mkdirSync9(sourceRoot, { recursive: true, mode: 448 });
     chmodSync3(sourceRoot, 448);
     const destination = retainedPath(sourceRoot, file.relativePath);
@@ -10622,7 +11020,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 = join35(getStudyDir(studyId), JIRA_MANIFEST_FILENAME);
+    const privatePath2 = join37(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));
@@ -10634,7 +11032,7 @@ async function insightJira(studyId, options) {
     return;
   }
   const manifest = buildJiraManifest(study, projectKey);
-  const privatePath = join35(getStudyDir(studyId), JIRA_MANIFEST_FILENAME);
+  const privatePath = join37(getStudyDir(studyId), JIRA_MANIFEST_FILENAME);
   writeJsonAtomic(privatePath, manifest);
   if (options.out) {
     writeNewFile(resolvePath12(options.out), `${JSON.stringify(manifest, null, 2)}
@@ -10705,14 +11103,11 @@ async function insightClose(studyId, options) {
 }
 
 // src/commands/refine.ts
-import { createHash as createHash8, randomUUID as randomUUID5 } from "crypto";
-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";
+import { tmpdir as tmpdir3 } from "os";
 
-// src/refine/context.ts
-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/activation.ts
+import { lstatSync as lstatSync7, readFileSync as readFileSync28, readdirSync as readdirSync12, realpathSync as realpathSync11 } from "fs";
+import { join as join38 } from "path";
 
 // src/refine/models.ts
 import { randomBytes } from "crypto";
@@ -10780,52 +11175,413 @@ function contentSimilarity(a, b) {
   return unionSize3 === 0 ? 0 : intersectionSize / unionSize3;
 }
 
-// src/refine/store.ts
-import { createHash as createHash7 } from "crypto";
-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 join36(getHomeDir(), "refinements");
+// src/refine/patch.ts
+var FENCE_RE = /^\s*(```|~~~)/;
+var HEADING_RE = /^(#{1,6})\s+(.*)$/;
+var ACTION_RE = /^<!--\s*ACTION:\s*([a-zA-Z-]+)(?:\s+"([^"]*)")?\s*-->\s*$/;
+var TARGET_RE = /^<!--\s*TARGET:\s*(.+?)\s*-->\s*$/;
+var ACTIONS_REQUIRING_MARKER = /* @__PURE__ */ new Set(["replace-section", "insert-after", "insert-before", "delete-section"]);
+function parsePatchFile(source) {
+  const lines = source.split("\n");
+  const blocks = [];
+  let inFence = false;
+  let current = null;
+  const finalizeCurrent = () => {
+    if (!current) return;
+    const contentLines = current.contentLines;
+    while (contentLines.length > 0 && contentLines[0].trim() === "") contentLines.shift();
+    while (contentLines.length > 0 && contentLines[contentLines.length - 1].trim() === "") contentLines.pop();
+    blocks.push({
+      action: current.action,
+      marker: current.marker,
+      target: current.target,
+      content: contentLines.join("\n")
+    });
+    current = null;
+  };
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      if (current) current.contentLines.push(line);
+      i++;
+      continue;
+    }
+    if (!inFence) {
+      const trimmed = line.trim();
+      const actionMatch = ACTION_RE.exec(trimmed);
+      if (actionMatch) {
+        finalizeCurrent();
+        const action = actionMatch[1];
+        if (!isPatchAction(action)) {
+          throw new UserError(`Unknown patch action "${action}" (valid: append, prepend, replace-section, insert-after, insert-before, delete-section)`);
+        }
+        const marker = actionMatch[2];
+        if (ACTIONS_REQUIRING_MARKER.has(action) && (!marker || marker.trim().length === 0)) {
+          throw new UserError(`Action "${action}" requires a quoted marker argument, e.g. <!-- ACTION: ${action} "marker text" -->`);
+        }
+        current = { action, marker: marker || void 0, contentLines: [] };
+        i++;
+        let peek = i;
+        while (peek < lines.length && lines[peek].trim() === "") peek++;
+        if (peek < lines.length) {
+          const targetMatch = TARGET_RE.exec(lines[peek].trim());
+          if (targetMatch) {
+            current.target = targetMatch[1];
+            i = peek + 1;
+          }
+        }
+        continue;
+      }
+    }
+    if (current) current.contentLines.push(line);
+    i++;
+  }
+  finalizeCurrent();
+  if (blocks.length === 0) {
+    throw new UserError("No ACTION blocks found in patch source");
+  }
+  return blocks;
 }
-function getRefinementsPath() {
-  return join36(getRefinementsDir(), "refinements.json");
+function frontmatterOffset(lines) {
+  if (lines[0] !== "---") return 0;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") return i + 1;
+  }
+  return 0;
 }
-function getPatternsPath() {
-  return join36(getRefinementsDir(), "patterns.json");
+function buildHeadingTree(lines, bodyOffset) {
+  const flat = [];
+  let inFence = false;
+  for (let i = bodyOffset; i < lines.length; i++) {
+    const line = lines[i];
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const m = HEADING_RE.exec(line);
+    if (m) flat.push({ level: m[1].length, text: m[2].trim(), line: i });
+  }
+  const root = { level: 0, heading: "", headingLine: bodyOffset - 1, bodyStart: bodyOffset, bodyEnd: lines.length, children: [] };
+  const stack = [root];
+  for (const h of flat) {
+    while (stack.length > 1 && stack[stack.length - 1].level >= h.level) {
+      const done = stack.pop();
+      if (done) done.bodyEnd = h.line;
+    }
+    const node = { level: h.level, heading: h.text, headingLine: h.line, bodyStart: h.line + 1, bodyEnd: lines.length, children: [] };
+    stack[stack.length - 1].children.push(node);
+    stack.push(node);
+  }
+  return root;
 }
-function getBackupsDir() {
-  return join36(getRefinementsDir(), "backups");
+function normalizeText(s) {
+  return s.trim().replace(/\s+/g, " ");
 }
-function readJsonFile(path, label2) {
-  let raw;
-  try {
-    raw = readFileSync25(path, "utf-8");
-  } catch (err) {
-    throw new UserError(`unable to read ${label2} at ${path}: ${err.message}`);
+function splitHeadingPath(target) {
+  return target.split(">").map((segment) => segment.trim()).filter((segment) => segment.length > 0);
+}
+function collectDescendants(node, acc) {
+  acc.push(node);
+  for (const child of node.children) collectDescendants(child, acc);
+}
+function resolveHeadingPath(root, segments) {
+  if (segments.length === 0) return root;
+  const allNodes = [];
+  collectDescendants(root, allNodes);
+  const headingNodes = allNodes.filter((n) => n.level > 0);
+  const firstNorm = normalizeText(segments[0]);
+  let candidates = headingNodes.filter((n) => normalizeText(n.heading) === firstNorm);
+  if (candidates.length === 0) {
+    const available = headingNodes.map((n) => n.heading);
+    throw new UserError(`No section matching "${segments[0]}" found (available headings: ${available.length > 0 ? available.join(", ") : "none"})`);
   }
-  try {
-    return JSON.parse(raw);
-  } catch {
-    throw new UserError(`malformed ${label2} at ${path}: not valid JSON`);
+  for (let i = 1; i < segments.length; i++) {
+    const segment = segments[i];
+    const norm = normalizeText(segment);
+    const next = [];
+    for (const candidate of candidates) {
+      for (const child of candidate.children) {
+        if (normalizeText(child.heading) === norm) next.push(child);
+      }
+    }
+    if (next.length === 0) {
+      const available = [...new Set(candidates.flatMap((c) => c.children.map((child) => child.heading)))];
+      throw new UserError(`No section matching "${segment}" found (available headings: ${available.length > 0 ? available.join(", ") : "none"})`);
+    }
+    candidates = next;
+  }
+  if (candidates.length > 1) {
+    throw new UserError(`Target selector "${segments.join(" > ")}" matched ${candidates.length} sections; be more specific`);
   }
+  return candidates[0];
 }
-function readStore(path, label2, validateRecord) {
-  if (!existsSync28(path)) {
-    return { schemaVersion: 1, records: [] };
+function findMarkerLine(lines, start, end, marker) {
+  const norm = normalizeText(marker);
+  const matches = [];
+  for (let i = start; i < end; i++) {
+    if (normalizeText(lines[i]).includes(norm)) matches.push(i);
   }
-  const parsed = readJsonFile(path, label2);
-  if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.records)) {
-    throw new UserError(`malformed ${label2} at ${path}: expected an object with a "records" array`);
+  if (matches.length === 0) {
+    throw new UserError(`No line matching marker "${marker}" found in target section`);
   }
-  const records = parsed.records;
-  if (validateRecord) {
-    records.forEach((record, index) => validateRecord(record, index));
+  if (matches.length > 1) {
+    const preview = matches.map((i) => `line ${i + 1}: "${lines[i].trim()}"`).join("; ");
+    throw new UserError(`Marker "${marker}" matched ${matches.length} lines, expected exactly 1 (${preview})`);
   }
-  return { schemaVersion: 1, records };
+  return matches[0];
 }
-function validateRefinementRecordShape(record, index, path) {
+function findChildByMarker(target, marker) {
+  const norm = normalizeText(marker);
+  const matches = target.children.filter((c) => normalizeText(c.heading).includes(norm));
+  if (matches.length === 0) {
+    const available = target.children.map((c) => c.heading).join(", ") || "none";
+    throw new UserError(`No subsection matching "${marker}" found under target section (available: ${available})`);
+  }
+  if (matches.length > 1) {
+    throw new UserError(`Marker "${marker}" matched ${matches.length} subsections: ${matches.map((c) => c.heading).join(", ")}`);
+  }
+  return matches[0];
+}
+function requireMarker(block) {
+  if (!block.marker || block.marker.trim().length === 0) {
+    throw new UserError(`Action "${block.action}" requires a marker`);
+  }
+  return block.marker;
+}
+function applyOneAction(lines, target, block) {
+  const contentLines = block.content.length === 0 ? [""] : block.content.split("\n");
+  switch (block.action) {
+    case "append": {
+      lines.splice(target.bodyEnd, 0, ...contentLines);
+      return;
+    }
+    case "prepend": {
+      lines.splice(target.bodyStart, 0, ...contentLines);
+      return;
+    }
+    case "insert-after":
+    case "insert-before": {
+      const idx = findMarkerLine(lines, target.bodyStart, target.bodyEnd, requireMarker(block));
+      lines.splice(block.action === "insert-after" ? idx + 1 : idx, 0, ...contentLines);
+      return;
+    }
+    case "replace-section":
+    case "delete-section": {
+      const child = findChildByMarker(target, requireMarker(block));
+      const replacement = block.action === "replace-section" ? contentLines : [];
+      lines.splice(child.headingLine, child.bodyEnd - child.headingLine, ...replacement);
+      return;
+    }
+    default: {
+      const exhaustive = block.action;
+      throw new UserError(`Unknown patch action "${exhaustive}"`);
+    }
+  }
+}
+function applyPatchBlocks(skillMd, blocks) {
+  const lines = skillMd.split("\n");
+  for (const block of blocks) {
+    const bodyOffset = frontmatterOffset(lines);
+    const root = buildHeadingTree(lines, bodyOffset);
+    const segments = block.target ? splitHeadingPath(block.target) : [];
+    const target = resolveHeadingPath(root, segments);
+    applyOneAction(lines, target, block);
+  }
+  return lines.join("\n");
+}
+function renderExtendFile(meta) {
+  return [
+    "# SKILL.extend.md",
+    `# Extensions for: ${meta.skillName}`,
+    `# Generated: ${meta.generatedAt}`,
+    `# Refinement: ${meta.refinementId}`,
+    "",
+    `## EXTEND: ${meta.targetSection}`,
+    "<!-- ACTION: append -->",
+    meta.content,
+    ""
+  ].join("\n");
+}
+function renderConfigOverride(meta) {
+  const payload = {
+    skill: meta.skillName,
+    version: "1.0.0",
+    generated: meta.generatedAt,
+    config: meta.config
+  };
+  return `${JSON.stringify(payload, null, 2)}
+`;
+}
+function computeLcsDiff(a, b) {
+  const n = a.length;
+  const m = b.length;
+  const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i2 = n - 1; i2 >= 0; i2--) {
+    for (let j2 = m - 1; j2 >= 0; j2--) {
+      dp[i2][j2] = a[i2] === b[j2] ? dp[i2 + 1][j2 + 1] + 1 : Math.max(dp[i2 + 1][j2], dp[i2][j2 + 1]);
+    }
+  }
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ type: "context", line: a[i] });
+      i++;
+      j++;
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      ops.push({ type: "remove", line: a[i] });
+      i++;
+    } else {
+      ops.push({ type: "add", line: b[j] });
+      j++;
+    }
+  }
+  while (i < n) {
+    ops.push({ type: "remove", line: a[i] });
+    i++;
+  }
+  while (j < m) {
+    ops.push({ type: "add", line: b[j] });
+    j++;
+  }
+  return ops;
+}
+function previewDiff(before, after, path) {
+  const a = before.split("\n");
+  const b = after.split("\n");
+  const ops = computeLcsDiff(a, b);
+  const lines = [`--- ${path}`, `+++ ${path}`];
+  for (const op of ops) {
+    const prefix = op.type === "add" ? "+" : op.type === "remove" ? "-" : " ";
+    lines.push(`${prefix}${op.line}`);
+  }
+  return lines.join("\n");
+}
+
+// src/refine/activation.ts
+var OUTSIDE_RESOURCE = /\$\{?CLAUDE_PLUGIN_ROOT\b|(?:\]\(|["'\s])(?:\.\.\/)/;
+function activationFiles(baseDir, overrideDir, name) {
+  const files = [];
+  let total = 0;
+  function walk2(dir, prefix = "") {
+    for (const entry of readdirSync12(dir).sort()) {
+      if (entry === ".git" || entry === "node_modules") continue;
+      const path = join38(dir, entry), relativePath = prefix ? `${prefix}/${entry}` : entry;
+      const stat = lstatSync7(path);
+      if (stat.isSymbolicLink()) throw new UserError(`Activation refuses symlinks: ${path}`);
+      if (stat.isDirectory()) {
+        walk2(path, relativePath);
+        continue;
+      }
+      if (!stat.isFile() || stat.size > 2 * 1024 * 1024 || files.length >= 1e3 || (total += stat.size) > 16 * 1024 * 1024) {
+        throw new UserError("Activation source exceeds the bounded file limits (1000 files, 2 MiB/file, 16 MiB total) or contains a special file.");
+      }
+      const bytes = readFileSync28(path);
+      if (OUTSIDE_RESOURCE.test(bytes.toString("utf8"))) {
+        throw new UserError(`Activation needs a self-contained skill; ${relativePath} references its parent/plugin tree. Vendor the required resources first.`);
+      }
+      files.push({ relativePath, bytes, mode: stat.mode & 511 });
+    }
+  }
+  walk2(realpathSync11(baseDir));
+  const skill = files.find((f) => f.relativePath === "SKILL.md");
+  if (!skill) throw new UserError("The explicit base directory must contain SKILL.md.");
+  const artifacts = readdirSync12(overrideDir).sort();
+  if (!artifacts.length || artifacts.some((p) => !["SKILL.patch.md", "SKILL.extend.md"].includes(p))) {
+    throw new UserError("Activation supports a capture directory containing only SKILL.patch.md and/or SKILL.extend.md. Full/config/hook/script overrides require separate review.");
+  }
+  let content = skill.bytes.toString("utf8");
+  for (const artifact of artifacts) {
+    const path = join38(overrideDir, artifact);
+    const stat = lstatSync7(path);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new UserError("Override artifact must be a regular file, not a symlink.");
+    if (stat.size > 2 * 1024 * 1024) throw new UserError("Override artifact exceeds 2 MiB.");
+    const text = readFileSync28(path, "utf8");
+    if (artifact === "SKILL.patch.md") content = applyPatchBlocks(content, parsePatchFile(text));
+    else {
+      const chunks = text.split(/^# SKILL\.extend\.md\r?$/m).filter((c) => c.trim());
+      for (const chunk of chunks) {
+        const match = /^\n# Extensions for: [^\n]+\n# Generated: [^\n]+\n# Refinement: [^\n]+\n\n## EXTEND: ([^\n]+)\n<!-- ACTION: append -->\n([\s\S]*)$/.exec(chunk);
+        if (!match) throw new UserError("Unrecognized extend artifact; re-capture it or use an explicit patch.");
+        content = applyPatchBlocks(content, [{ action: "append", target: match[1], content: match[2].trim() }]);
+      }
+    }
+  }
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
+  if (!frontmatter) throw new UserError("Host activation requires SKILL.md YAML frontmatter.");
+  const header = frontmatter[1].replace(/^name:.*(?:\r?\n|$)/m, "");
+  content = `---
+name: ${name}
+${header}
+---
+${content.slice(frontmatter[0].length)}`;
+  if (OUTSIDE_RESOURCE.test(content)) {
+    throw new UserError("Activation needs a self-contained skill; captured content references its parent/plugin tree.");
+  }
+  skill.bytes = Buffer.from(content);
+  return files;
+}
+
+// src/commands/refine.ts
+import { createHash as createHash8, randomUUID as randomUUID5 } from "crypto";
+import { chmodSync as chmodSync4, existsSync as existsSync31, lstatSync as lstatSync8, mkdirSync as mkdirSync11, mkdtempSync as mkdtempSync4, rmdirSync, readFileSync as readFileSync30, realpathSync as realpathSync14, renameSync as renameSync6, rmSync as rmSync9, writeFileSync as writeFileSync10 } from "fs";
+import { dirname as dirname15, isAbsolute as isAbsolute11, join as join41, relative as relative10, resolve as resolvePath15, sep as sep10 } from "path";
+import { createInterface as createInterface7 } from "readline/promises";
+
+// src/refine/context.ts
+import { existsSync as existsSync30, realpathSync as realpathSync13, statSync as statSync14 } from "fs";
+import { isAbsolute as isAbsolute10, join as join40, relative as relative9, resolve as resolvePath14 } from "path";
+
+// src/refine/store.ts
+import { createHash as createHash7 } from "crypto";
+import { existsSync as existsSync29, readFileSync as readFileSync29, statSync as statSync13, realpathSync as realpathSync12 } from "fs";
+import { join as join39, resolve as resolvePath13 } from "path";
+var SIMILARITY_JOIN_THRESHOLD = 0.7;
+var READY_THRESHOLD = 2;
+function getRefinementsDir() {
+  return join39(getHomeDir(), "refinements");
+}
+function getRefinementsPath() {
+  return join39(getRefinementsDir(), "refinements.json");
+}
+function getPatternsPath() {
+  return join39(getRefinementsDir(), "patterns.json");
+}
+function getBackupsDir() {
+  return join39(getRefinementsDir(), "backups");
+}
+function readJsonFile(path, label2) {
+  let raw;
+  try {
+    raw = readFileSync29(path, "utf-8");
+  } catch (err) {
+    throw new UserError(`unable to read ${label2} at ${path}: ${err.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new UserError(`malformed ${label2} at ${path}: not valid JSON`);
+  }
+}
+function readStore(path, label2, validateRecord) {
+  if (!existsSync29(path)) {
+    return { schemaVersion: 1, records: [] };
+  }
+  const parsed = readJsonFile(path, label2);
+  if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.records)) {
+    throw new UserError(`malformed ${label2} at ${path}: expected an object with a "records" array`);
+  }
+  const records = parsed.records;
+  if (validateRecord) {
+    records.forEach((record, index) => validateRecord(record, index));
+  }
+  return { schemaVersion: 1, records };
+}
+function validateRefinementRecordShape(record, index, path) {
   if (typeof record !== "object" || record === null) {
     throw new UserError(`malformed refinements.json at ${path}: record[${index}] is not an object`);
   }
@@ -10904,7 +11660,7 @@ function writePatternsStore(store) {
 function resolveProjectRealpath(projectRoot) {
   const resolved = resolvePath13(projectRoot);
   try {
-    return realpathSync9(resolved);
+    return realpathSync12(resolved);
   } catch {
     return resolved;
   }
@@ -11036,16 +11792,16 @@ function createBackup(filePaths, deps = {}) {
   const randomHex = deps.randomHex ?? defaultRandomHex;
   const id = `${formatBackupTimestamp(now)}-${randomHex()}`;
   const files = filePaths.map((path) => {
-    if (!existsSync28(path)) {
+    if (!existsSync29(path)) {
       return { path, existed: false, sha256: null, mode: null, contentBase64: null };
     }
-    const bytes = readFileSync25(path);
-    const mode = statSync12(path).mode & 511;
+    const bytes = readFileSync29(path);
+    const mode = statSync13(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(join36(getBackupsDir(), id, "manifest.json"), manifest);
+  writeJsonAtomic(join39(getBackupsDir(), id, "manifest.json"), manifest);
   return manifest;
 }
 function validateBackupManifestShape(value, path) {
@@ -11094,8 +11850,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 = join36(getBackupsDir(), id, "manifest.json");
-  if (!existsSync28(manifestPath)) {
+  const manifestPath = join39(getBackupsDir(), id, "manifest.json");
+  if (!existsSync29(manifestPath)) {
     throw new UserError(`no backup with id: ${id}`);
   }
   const parsed = readJsonFile(manifestPath, "backup manifest");
@@ -11117,32 +11873,32 @@ function assertPlainSkillName(name) {
 }
 function realpathOrNull2(p) {
   try {
-    return realpathSync10(p);
+    return realpathSync13(p);
   } catch {
     return null;
   }
 }
 function isUnderRoot2(candidate, root) {
-  const rel = relative7(root, candidate);
-  return rel === "" || !rel.startsWith("..") && !isAbsolute8(rel);
+  const rel = relative9(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute10(rel);
 }
 function resolveScopes(config, cwd, skill, userRootFlag) {
   assertPlainSkillName(skill);
   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 localDir = join40(resolvedCwd, ".claude", "skills", skill);
+  const sharedDir = join40(resolvedCwd, "skills", skill);
+  const local = { scope: "local", dir: localDir, exists: existsSync30(localDir) };
+  const shared = { scope: "shared", dir: sharedDir, exists: existsSync30(sharedDir) };
   const user = resolveUserScope(config, resolvedCwd, skill, userRootFlag);
   return { local, shared, user };
 }
 function resolveUserScope(config, resolvedCwd, skill, userRootFlag) {
   if (userRootFlag) {
     const root = resolvePath14(userRootFlag);
-    return { resolved: true, dir: join37(root, skill), root: userRootFlag, reason: "flag" };
+    return { resolved: true, dir: join40(root, skill), root: userRootFlag, reason: "flag" };
   }
   const cwdReal = realpathOrNull2(resolvedCwd) ?? resolvedCwd;
-  const candidates = config.skillsRoots.map((root) => ({ root, dir: join37(resolveConfiguredRoot2(root), skill) }));
+  const candidates = config.skillsRoots.map((root) => ({ root, dir: join40(resolveConfiguredRoot2(root), skill) }));
   for (const candidate of candidates) {
     const skillReal = realpathOrNull2(candidate.dir);
     if (skillReal) {
@@ -11160,29 +11916,29 @@ function resolveUserScope(config, resolvedCwd, skill, userRootFlag) {
 }
 function isFile2(p) {
   try {
-    return statSync13(p).isFile();
+    return statSync14(p).isFile();
   } catch {
     return false;
   }
 }
 function isDirectory(p) {
   try {
-    return statSync13(p).isDirectory();
+    return statSync14(p).isDirectory();
   } catch {
     return false;
   }
 }
-function inventoryScopeDir(scope, dir) {
+function inventoryScopeDir(scope2, dir) {
   return {
-    scope,
+    scope: scope2,
     dir,
     dirExists: isDirectory(dir),
-    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"))
+    skillMd: isFile2(join40(dir, "SKILL.md")),
+    patchMd: isFile2(join40(dir, "SKILL.patch.md")),
+    extendMd: isFile2(join40(dir, "SKILL.extend.md")),
+    configJson: isFile2(join40(dir, "skill-config.json")),
+    hooksDir: isDirectory(join40(dir, "hooks")),
+    scriptsDir: isDirectory(join40(dir, "scripts"))
   };
 }
 function inventoryAllScopes(resolution) {
@@ -11193,230 +11949,10 @@ function inventoryAllScopes(resolution) {
   return rows;
 }
 
-// src/refine/patch.ts
-var FENCE_RE = /^\s*(```|~~~)/;
-var HEADING_RE = /^(#{1,6})\s+(.*)$/;
-function frontmatterOffset(lines) {
-  if (lines[0] !== "---") return 0;
-  for (let i = 1; i < lines.length; i++) {
-    if (lines[i] === "---") return i + 1;
-  }
-  return 0;
-}
-function buildHeadingTree(lines, bodyOffset) {
-  const flat = [];
-  let inFence = false;
-  for (let i = bodyOffset; i < lines.length; i++) {
-    const line = lines[i];
-    if (FENCE_RE.test(line)) {
-      inFence = !inFence;
-      continue;
-    }
-    if (inFence) continue;
-    const m = HEADING_RE.exec(line);
-    if (m) flat.push({ level: m[1].length, text: m[2].trim(), line: i });
-  }
-  const root = { level: 0, heading: "", headingLine: bodyOffset - 1, bodyStart: bodyOffset, bodyEnd: lines.length, children: [] };
-  const stack = [root];
-  for (const h of flat) {
-    while (stack.length > 1 && stack[stack.length - 1].level >= h.level) {
-      const done = stack.pop();
-      if (done) done.bodyEnd = h.line;
-    }
-    const node = { level: h.level, heading: h.text, headingLine: h.line, bodyStart: h.line + 1, bodyEnd: lines.length, children: [] };
-    stack[stack.length - 1].children.push(node);
-    stack.push(node);
-  }
-  return root;
-}
-function normalizeText(s) {
-  return s.trim().replace(/\s+/g, " ");
-}
-function splitHeadingPath(target) {
-  return target.split(">").map((segment) => segment.trim()).filter((segment) => segment.length > 0);
-}
-function collectDescendants(node, acc) {
-  acc.push(node);
-  for (const child of node.children) collectDescendants(child, acc);
-}
-function resolveHeadingPath(root, segments) {
-  if (segments.length === 0) return root;
-  const allNodes = [];
-  collectDescendants(root, allNodes);
-  const headingNodes = allNodes.filter((n) => n.level > 0);
-  const firstNorm = normalizeText(segments[0]);
-  let candidates = headingNodes.filter((n) => normalizeText(n.heading) === firstNorm);
-  if (candidates.length === 0) {
-    const available = headingNodes.map((n) => n.heading);
-    throw new UserError(`No section matching "${segments[0]}" found (available headings: ${available.length > 0 ? available.join(", ") : "none"})`);
-  }
-  for (let i = 1; i < segments.length; i++) {
-    const segment = segments[i];
-    const norm = normalizeText(segment);
-    const next = [];
-    for (const candidate of candidates) {
-      for (const child of candidate.children) {
-        if (normalizeText(child.heading) === norm) next.push(child);
-      }
-    }
-    if (next.length === 0) {
-      const available = [...new Set(candidates.flatMap((c) => c.children.map((child) => child.heading)))];
-      throw new UserError(`No section matching "${segment}" found (available headings: ${available.length > 0 ? available.join(", ") : "none"})`);
-    }
-    candidates = next;
-  }
-  if (candidates.length > 1) {
-    throw new UserError(`Target selector "${segments.join(" > ")}" matched ${candidates.length} sections; be more specific`);
-  }
-  return candidates[0];
-}
-function findMarkerLine(lines, start, end, marker) {
-  const norm = normalizeText(marker);
-  const matches = [];
-  for (let i = start; i < end; i++) {
-    if (normalizeText(lines[i]).includes(norm)) matches.push(i);
-  }
-  if (matches.length === 0) {
-    throw new UserError(`No line matching marker "${marker}" found in target section`);
-  }
-  if (matches.length > 1) {
-    const preview = matches.map((i) => `line ${i + 1}: "${lines[i].trim()}"`).join("; ");
-    throw new UserError(`Marker "${marker}" matched ${matches.length} lines, expected exactly 1 (${preview})`);
-  }
-  return matches[0];
-}
-function findChildByMarker(target, marker) {
-  const norm = normalizeText(marker);
-  const matches = target.children.filter((c) => normalizeText(c.heading).includes(norm));
-  if (matches.length === 0) {
-    const available = target.children.map((c) => c.heading).join(", ") || "none";
-    throw new UserError(`No subsection matching "${marker}" found under target section (available: ${available})`);
-  }
-  if (matches.length > 1) {
-    throw new UserError(`Marker "${marker}" matched ${matches.length} subsections: ${matches.map((c) => c.heading).join(", ")}`);
-  }
-  return matches[0];
-}
-function requireMarker(block) {
-  if (!block.marker || block.marker.trim().length === 0) {
-    throw new UserError(`Action "${block.action}" requires a marker`);
-  }
-  return block.marker;
-}
-function applyOneAction(lines, target, block) {
-  const contentLines = block.content.length === 0 ? [""] : block.content.split("\n");
-  switch (block.action) {
-    case "append": {
-      lines.splice(target.bodyEnd, 0, ...contentLines);
-      return;
-    }
-    case "prepend": {
-      lines.splice(target.bodyStart, 0, ...contentLines);
-      return;
-    }
-    case "insert-after":
-    case "insert-before": {
-      const idx = findMarkerLine(lines, target.bodyStart, target.bodyEnd, requireMarker(block));
-      lines.splice(block.action === "insert-after" ? idx + 1 : idx, 0, ...contentLines);
-      return;
-    }
-    case "replace-section":
-    case "delete-section": {
-      const child = findChildByMarker(target, requireMarker(block));
-      const replacement = block.action === "replace-section" ? contentLines : [];
-      lines.splice(child.headingLine, child.bodyEnd - child.headingLine, ...replacement);
-      return;
-    }
-    default: {
-      const exhaustive = block.action;
-      throw new UserError(`Unknown patch action "${exhaustive}"`);
-    }
-  }
-}
-function applyPatchBlocks(skillMd, blocks) {
-  const lines = skillMd.split("\n");
-  for (const block of blocks) {
-    const bodyOffset = frontmatterOffset(lines);
-    const root = buildHeadingTree(lines, bodyOffset);
-    const segments = block.target ? splitHeadingPath(block.target) : [];
-    const target = resolveHeadingPath(root, segments);
-    applyOneAction(lines, target, block);
-  }
-  return lines.join("\n");
-}
-function renderExtendFile(meta) {
-  return [
-    "# SKILL.extend.md",
-    `# Extensions for: ${meta.skillName}`,
-    `# Generated: ${meta.generatedAt}`,
-    `# Refinement: ${meta.refinementId}`,
-    "",
-    `## EXTEND: ${meta.targetSection}`,
-    "<!-- ACTION: append -->",
-    meta.content,
-    ""
-  ].join("\n");
-}
-function renderConfigOverride(meta) {
-  const payload = {
-    skill: meta.skillName,
-    version: "1.0.0",
-    generated: meta.generatedAt,
-    config: meta.config
-  };
-  return `${JSON.stringify(payload, null, 2)}
-`;
-}
-function computeLcsDiff(a, b) {
-  const n = a.length;
-  const m = b.length;
-  const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
-  for (let i2 = n - 1; i2 >= 0; i2--) {
-    for (let j2 = m - 1; j2 >= 0; j2--) {
-      dp[i2][j2] = a[i2] === b[j2] ? dp[i2 + 1][j2 + 1] + 1 : Math.max(dp[i2 + 1][j2], dp[i2][j2 + 1]);
-    }
-  }
-  const ops = [];
-  let i = 0;
-  let j = 0;
-  while (i < n && j < m) {
-    if (a[i] === b[j]) {
-      ops.push({ type: "context", line: a[i] });
-      i++;
-      j++;
-    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
-      ops.push({ type: "remove", line: a[i] });
-      i++;
-    } else {
-      ops.push({ type: "add", line: b[j] });
-      j++;
-    }
-  }
-  while (i < n) {
-    ops.push({ type: "remove", line: a[i] });
-    i++;
-  }
-  while (j < m) {
-    ops.push({ type: "add", line: b[j] });
-    j++;
-  }
-  return ops;
-}
-function previewDiff(before, after, path) {
-  const a = before.split("\n");
-  const b = after.split("\n");
-  const ops = computeLcsDiff(a, b);
-  const lines = [`--- ${path}`, `+++ ${path}`];
-  for (const op of ops) {
-    const prefix = op.type === "add" ? "+" : op.type === "remove" ? "-" : " ";
-    lines.push(`${prefix}${op.line}`);
-  }
-  return lines.join("\n");
-}
-
 // src/commands/refine.ts
 var PRO_FEATURE_LABEL9 = "skill refinement";
 var REFINE_PROMPT_ASSET = "refine-prompt.md";
+var PROJECT_SKILL_ROOTS = { claude: ".claude/skills", codex: ".agents/skills" };
 function requireProFeature3() {
   const status2 = proFeatureStatus(PRO_FEATURE_LABEL9);
   if (!status2.enabled) {
@@ -11454,15 +11990,15 @@ function resolveConfiguredRoot3(root) {
   return resolvePath15(expandHome(root));
 }
 function isUnderRoot3(candidate, root) {
-  const rel = relative8(root, candidate);
-  return rel === "" || !rel.startsWith("..") && !isAbsolute9(rel);
+  const rel = relative10(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute11(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 readFileSync26(resolvePath15(options.contentFile), "utf-8");
+  if (options.contentFile) return readFileSync30(resolvePath15(options.contentFile), "utf-8");
   return void 0;
 }
 function validateCaptureOptions(options) {
@@ -11588,7 +12124,7 @@ ${rendered}` : rendered;
 function ensureScopeDirSafe(scopeDir, resolvedCwd) {
   let lst;
   try {
-    lst = lstatSync7(scopeDir);
+    lst = lstatSync8(scopeDir);
   } catch {
     lst = void 0;
   }
@@ -11600,7 +12136,7 @@ function ensureScopeDirSafe(scopeDir, resolvedCwd) {
   const lexical = resolvePath15(scopeDir);
   let realResolved;
   try {
-    realResolved = realpathSync11(scopeDir);
+    realResolved = realpathSync14(scopeDir);
   } catch {
     realResolved = real;
   }
@@ -11614,16 +12150,16 @@ function ensureScopeDirSafe(scopeDir, resolvedCwd) {
 }
 function writeOverrideFile(scopeDir, relPath, content, resolvedCwd) {
   const realScopeDir = ensureScopeDirSafe(scopeDir, resolvedCwd);
-  const destPath = join38(scopeDir, relPath);
+  const destPath = join41(scopeDir, relPath);
   const destDir = dirname15(destPath);
   mkdirSync11(destDir, { recursive: true });
-  const realDestDir = realpathSync11(destDir);
+  const realDestDir = realpathSync14(destDir);
   if (!isUnderRoot3(realDestDir, realScopeDir)) {
     throw new UserError(`refusing to write ${destPath}: resolves outside scope directory ${scopeDir}`);
   }
   let destLst;
   try {
-    destLst = lstatSync7(destPath);
+    destLst = lstatSync8(destPath);
   } catch {
     destLst = void 0;
   }
@@ -11710,15 +12246,105 @@ 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 ? join38(scopeDir, probeRelPath) : void 0;
-  const existingContent = probePath && existsSync30(probePath) ? readFileSync26(probePath, "utf-8") : "";
+  const probePath = probeRelPath ? join41(scopeDir, probeRelPath) : void 0;
+  const existingContent = probePath && existsSync31(probePath) ? readFileSync30(probePath, "utf-8") : "";
   const rendered = renderCaptureArtifact(opts, content, refinementId, generatedAt, existingContent);
   const relPath = rendered.relPath;
-  const destPath = join38(scopeDir, relPath);
-  const before = existsSync30(destPath) ? readFileSync26(destPath, "utf-8") : "";
+  const destPath = join41(scopeDir, relPath);
+  const before = existsSync31(destPath) ? readFileSync30(destPath, "utf-8") : "";
   const diff = previewDiff(before, rendered.content, destPath);
   return { relPath, content: rendered.content, destPath, diff };
 }
+async function refineActivateCommand(options) {
+  requireProFeature3();
+  if (!options.skill || !options.base || !options.as || !["claude", "codex"].includes(options.host ?? "")) {
+    throw new UserError("activate requires --skill, --base, --as and --host claude|codex.");
+  }
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(options.as)) throw new UserError("--as must be a lowercase hyphenated skill name.");
+  if (options.scope && !["local", "shared"].includes(options.scope)) throw new UserError("--scope must be local|shared.");
+  const cwd = realpathSync14(process.cwd());
+  const scopes = resolveScopes(loadConfig(), cwd, options.skill);
+  const overrideDir = options.scope === "shared" ? scopes.shared.dir : scopes.local.dir;
+  if (realpathSync14(overrideDir) !== overrideDir) throw new UserError("Activation refuses a symlinked override directory.");
+  const hostRoot = join41(cwd, PROJECT_SKILL_ROOTS[options.host]);
+  const destination = join41(hostRoot, options.as);
+  if (existsSync31(destination) || resolveTargetRealPath(destination) !== destination) throw new UserError("Activation destination already exists or contains a symlink; choose a new --as name.");
+  const files = activationFiles(options.base, overrideDir, options.as);
+  const receiptName = ".skill-forge-activation.json";
+  if (files.some((f) => f.relativePath === receiptName)) throw new UserError("Base is already an activation; use its original source and capture.");
+  const provenance = {
+    schemaVersion: 1,
+    host: options.host,
+    skill: options.as,
+    capture: options.skill,
+    source: realpathSync14(options.base),
+    sourceSha256: createHash8("sha256").update(readFileSync30(join41(options.base, "SKILL.md"))).digest("hex"),
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    runtimeVerified: false
+  };
+  files.push({ relativePath: receiptName, mode: 384, bytes: Buffer.from(JSON.stringify(provenance, null, 2) + "\n") });
+  if (files.length > 1e3 || files.some((f) => f.bytes.length > 2 * 1024 * 1024) || files.reduce((n, f) => n + f.bytes.length, 0) > 16 * 1024 * 1024) {
+    throw new UserError("Composed activation exceeds file or total size limits.");
+  }
+  const stage = mkdtempSync4(join41(tmpdir3(), "skill-forge-activate-"));
+  try {
+    for (const file of files) {
+      const path = join41(stage, file.relativePath);
+      mkdirSync11(dirname15(path), { recursive: true });
+      writeFileSync10(path, file.bytes, { mode: file.mode });
+    }
+    const safety = await scanSafety(stage, "block-high", files.map((f) => ({ file: join41(stage, f.relativePath), content: f.bytes.toString("utf8") })));
+    safety.findings = safety.findings.map((f) => ({ ...f, file: join41(destination, relative10(stage, f.file)) }));
+    const preview = {
+      destination,
+      provenance,
+      host: options.host,
+      invocation: options.host === "claude" ? `/${options.as}` : `$${options.as}`,
+      source: realpathSync14(options.base),
+      files: files.map((f) => f.relativePath),
+      safety,
+      diff: previewDiff(readFileSync30(join41(options.base, "SKILL.md"), "utf8"), files.find((f) => f.relativePath === "SKILL.md").bytes.toString("utf8"), join41(destination, "SKILL.md"))
+    };
+    if (options.dryRun) {
+      emit2(options.json, { ...preview, dryRun: true, activated: false }, () => console.log(JSON.stringify(preview, null, 2)));
+      return;
+    }
+    if (safety.verdict === "block") throw new UserError(`Activation safety gate blocked the staged skill. Inspect --dry-run --json findings; nothing activated.`);
+    if (!options.json) console.log(sanitizeDiffForConsole(preview.diff));
+    if (!await confirmWrite(options.yes, options.json, `Activate ${destination}? [y/N] `)) {
+      emit2(options.json, { activated: false, cancelled: true }, () => console.log("Activation cancelled."));
+      return;
+    }
+    if (resolveTargetRealPath(destination) !== destination) throw new UserError("Activation destination became symlinked.");
+    ensureScopeDirSafe(hostRoot, cwd);
+    mkdirSync11(destination);
+    const backup = createBackup(files.map((f) => join41(destination, f.relativePath)));
+    const hashes = files.map((f) => ({ path: join41(destination, f.relativePath), sha256: createHash8("sha256").update(f.bytes).digest("hex") }));
+    writePostWriteSidecar(backup.id, hashes);
+    const projectConfig = { ...loadConfig(), skillsRoots: [hostRoot] };
+    try {
+      for (const file of files) safeRestoreWrite(join41(destination, file.relativePath), file.bytes, file.mode, projectConfig);
+      for (const file of hashes) {
+        if (createHash8("sha256").update(readFileSync30(file.path)).digest("hex") !== file.sha256) throw new UserError("Activation read-back hash mismatch.");
+      }
+    } catch (error) {
+      throw new UserError(`Activation write failed; backup ${backup.id} records recovery paths. Inspect before using rollback --project --force: ${error.message}`);
+    }
+    emit2(options.json, {
+      ...preview,
+      activated: true,
+      backupId: backup.id,
+      runtimeVerified: false,
+      verification: `Open a fresh ${options.host} task in this project, invoke ${preview.invocation}, and verify it reads ${join41(destination, "SKILL.md")}.`,
+      rollback: `skill-forge refine rollback ${backup.id} --project --yes`
+    }, () => {
+      console.log(`Activated ${destination}. Invoke ${preview.invocation} in a fresh ${options.host} task and verify the loaded file; runtime use is not yet observed.`);
+      console.log(`Rollback from this project: skill-forge refine rollback ${backup.id} --project --yes`);
+    });
+  } finally {
+    rmSync9(stage, { recursive: true, force: true });
+  }
+}
 async function refineListCommand(options = {}) {
   requireProFeature3();
   const { records } = readRefinementsStore();
@@ -11812,16 +12438,16 @@ async function refineWhichCommand(skill, options = {}) {
 }
 function writePostWriteSidecar(backupId, files) {
   const sidecar = { schemaVersion: 1, files };
-  const dir = join38(getBackupsDir(), backupId);
+  const dir = join41(getBackupsDir(), backupId);
   mkdirSync11(dir, { recursive: true });
-  writeFileSync10(join38(dir, "post.json"), JSON.stringify(sidecar, null, 2) + "\n", { mode: 384 });
+  writeFileSync10(join41(dir, "post.json"), JSON.stringify(sidecar, null, 2) + "\n", { mode: 384 });
 }
 function readPostWriteSidecar(backupId) {
-  const path = join38(getBackupsDir(), backupId, "post.json");
-  if (!existsSync30(path)) return { hashes: /* @__PURE__ */ new Map(), status: "missing" };
+  const path = join41(getBackupsDir(), backupId, "post.json");
+  if (!existsSync31(path)) return { hashes: /* @__PURE__ */ new Map(), status: "missing" };
   let raw;
   try {
-    raw = readFileSync26(path, "utf-8");
+    raw = readFileSync30(path, "utf-8");
   } catch {
     return { hashes: /* @__PURE__ */ new Map(), status: "unreadable" };
   }
@@ -11866,21 +12492,21 @@ async function refinePromoteCommand(patternId, options = {}) {
   const resolvedUserRoot = resolveConfiguredRoot3(scopes.user.root);
   let realUserRoot;
   try {
-    realUserRoot = realpathSync11(resolvedUserRoot);
+    realUserRoot = realpathSync14(resolvedUserRoot);
   } catch {
     realUserRoot = resolvedUserRoot;
   }
   let realSkillDir;
   try {
-    realSkillDir = realpathSync11(skillDir);
+    realSkillDir = realpathSync14(skillDir);
   } catch {
     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 = join38(skillDir, "SKILL.md");
-  if (!existsSync30(skillMdPath)) {
+  const skillMdPath = join41(skillDir, "SKILL.md");
+  if (!existsSync31(skillMdPath)) {
     throw new UserError(`user-scope SKILL.md not found at ${skillMdPath} \u2014 refusing to promote against a missing base skill.`);
   }
   const refinementsStore = readRefinementsStore();
@@ -11897,7 +12523,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 = readFileSync26(skillMdPath, "utf-8");
+  const before = readFileSync30(skillMdPath, "utf-8");
   const after = applyPatchBlocks(before, [block]);
   const diff = previewDiff(before, after, skillMdPath);
   if (options.dryRun) {
@@ -11929,7 +12555,7 @@ Promote pattern ${patternId} into ${skillMdPath}? [y/N] `);
     throw err;
   }
   try {
-    const postSha256 = createHash8("sha256").update(readFileSync26(skillMdPath)).digest("hex");
+    const postSha256 = createHash8("sha256").update(readFileSync30(skillMdPath)).digest("hex");
     writePostWriteSidecar(backup.id, [{ path: skillMdPath, sha256: postSha256 }]);
     markGeneralized(patternId, backup.id);
     const skillsRoot = resolveConfiguredRoot3(scopes.user.root);
@@ -11955,11 +12581,11 @@ Promote pattern ${patternId} into ${skillMdPath}? [y/N] `);
 }
 function assertBackupDirContained(backupId) {
   const backupsDir = getBackupsDir();
-  if (!existsSync30(backupsDir)) return;
-  const realBackupsDir = realpathSync11(backupsDir);
-  const backupDir = join38(backupsDir, backupId);
-  if (!existsSync30(backupDir)) return;
-  const realBackupDir = realpathSync11(backupDir);
+  if (!existsSync31(backupsDir)) return;
+  const realBackupsDir = realpathSync14(backupsDir);
+  const backupDir = join41(backupsDir, backupId);
+  if (!existsSync31(backupDir)) return;
+  const realBackupDir = realpathSync14(backupDir);
   if (!isUnderRoot3(realBackupDir, realBackupsDir)) {
     throw new UserError(`refusing rollback: backup id "${backupId}" resolves outside the backups directory`);
   }
@@ -11968,9 +12594,9 @@ function resolveTargetRealPath(path) {
   let lexicalAncestor = resolvePath15(path);
   while (true) {
     try {
-      const real = realpathSync11(lexicalAncestor);
-      const remainder = relative8(lexicalAncestor, resolvePath15(path));
-      return remainder === "" ? real : join38(real, remainder);
+      const real = realpathSync14(lexicalAncestor);
+      const remainder = relative10(lexicalAncestor, resolvePath15(path));
+      return remainder === "" ? real : join41(real, remainder);
     } catch {
       const parent = dirname15(lexicalAncestor);
       if (parent === lexicalAncestor) return resolvePath15(path);
@@ -11985,7 +12611,7 @@ function assertManifestPathsWithinRoots(manifest, config) {
   const roots = config.skillsRoots.map((root) => {
     const resolved = resolveConfiguredRoot3(root);
     try {
-      return realpathSync11(resolved);
+      return realpathSync14(resolved);
     } catch {
       return resolved;
     }
@@ -12002,7 +12628,7 @@ function assertNoSymlinkLeaves(manifest) {
   for (const file of manifest.files) {
     let lst;
     try {
-      lst = lstatSync7(file.path);
+      lst = lstatSync8(file.path);
     } catch {
       lst = void 0;
     }
@@ -12015,11 +12641,11 @@ function findLexicalRoot(filePath, config) {
   const lexicalTarget = resolvePath15(filePath);
   for (const root of config.skillsRoots) {
     const rootLexical = resolveConfiguredRoot3(root);
-    const rel = relative8(rootLexical, lexicalTarget);
-    if (rel !== "" && (rel === ".." || rel.startsWith(`..${sep8}`) || isAbsolute9(rel))) continue;
+    const rel = relative10(rootLexical, lexicalTarget);
+    if (rel !== "" && (rel === ".." || rel.startsWith(`..${sep10}`) || isAbsolute11(rel))) continue;
     let rootReal;
     try {
-      rootReal = realpathSync11(rootLexical);
+      rootReal = realpathSync14(rootLexical);
     } catch {
       rootReal = rootLexical;
     }
@@ -12029,8 +12655,8 @@ function findLexicalRoot(filePath, config) {
 }
 function walkRealComponents(filePath, config, createMissing) {
   const { rootLexical, rootReal } = findLexicalRoot(filePath, config);
-  const relPath = relative8(rootLexical, resolvePath15(filePath));
-  const components = relPath.split(sep8).filter((c) => c.length > 0);
+  const relPath = relative10(rootLexical, resolvePath15(filePath));
+  const components = relPath.split(sep10).filter((c) => c.length > 0);
   if (components.length === 0) {
     throw new UserError(`refusing to operate on ${filePath}: resolves to the skills root itself`);
   }
@@ -12039,10 +12665,10 @@ function walkRealComponents(filePath, config, createMissing) {
   let current = rootReal;
   for (const component of dirComponents) {
     if (current === void 0) break;
-    const next = join38(current, component);
+    const next = join41(current, component);
     let lst;
     try {
-      lst = lstatSync7(next);
+      lst = lstatSync8(next);
     } catch {
       lst = void 0;
     }
@@ -12070,13 +12696,13 @@ 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 = join38(parentReal, leafComponent);
+  const finalPath = join41(parentReal, leafComponent);
   if (!isUnderRoot3(finalPath, rootReal)) {
     throw new UserError(`refusing to restore ${filePath}: resolves outside root ${rootReal}`);
   }
   let leafLst;
   try {
-    leafLst = lstatSync7(finalPath);
+    leafLst = lstatSync8(finalPath);
   } catch {
     leafLst = void 0;
   }
@@ -12096,13 +12722,13 @@ 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 = join38(parentReal, leafComponent);
+  const finalPath = join41(parentReal, leafComponent);
   if (!isUnderRoot3(finalPath, rootReal)) {
     throw new UserError(`refusing to delete ${filePath}: resolves outside root ${rootReal}`);
   }
   let leafLst;
   try {
-    leafLst = lstatSync7(finalPath);
+    leafLst = lstatSync8(finalPath);
   } catch {
     leafLst = void 0;
   }
@@ -12121,6 +12747,13 @@ async function refineRollbackCommand(backupId, options = {}) {
   assertBackupDirContained(backupId);
   const manifest = readBackupManifest(backupId);
   const config = loadConfig();
+  if (options.project) config.skillsRoots = Object.values(PROJECT_SKILL_ROOTS).map((p) => join41(realpathSync14(process.cwd()), p));
+  const assertProjectRoots = () => {
+    if (options.project && config.skillsRoots.some((root) => resolveTargetRealPath(root) !== root)) {
+      throw new UserError("refusing project rollback: a project skill root or its ancestor is symlinked.");
+    }
+  };
+  assertProjectRoots();
   assertManifestPathsWithinRoots(manifest, config);
   assertNoSymlinkLeaves(manifest);
   const warnings = [];
@@ -12134,11 +12767,14 @@ async function refineRollbackCommand(backupId, options = {}) {
     }
     warnings.push(`post-write verification data for backup ${backupId} is ${reason} \u2014 restoring without hash verification (--force).`);
   }
+  if (sidecar.status === "ok" && manifest.files.some((f) => !sidecar.hashes.has(f.path)) && !options.force) {
+    throw new UserError("refusing rollback: post-write verification is incomplete for the backup manifest.");
+  }
   const mismatches = [];
   for (const file of manifest.files) {
     const expected = sidecar.hashes.get(file.path);
     if (expected === void 0) continue;
-    const currentSha256 = existsSync30(file.path) ? createHash8("sha256").update(readFileSync26(file.path)).digest("hex") : null;
+    const currentSha256 = existsSync31(file.path) ? createHash8("sha256").update(readFileSync30(file.path)).digest("hex") : null;
     if (currentSha256 !== expected) mismatches.push(file.path);
   }
   if (mismatches.length > 0 && !options.force) {
@@ -12165,6 +12801,7 @@ ${fileList}
   const restored = [];
   for (const file of manifest.files) {
     try {
+      assertProjectRoots();
       if (!file.existed) {
         safeDeleteTombstone(file.path, config);
       } else {
@@ -12178,6 +12815,18 @@ ${fileList}
       );
     }
   }
+  if (options.project) {
+    const roots = new Set(config.skillsRoots);
+    for (const file of manifest.files) {
+      for (let dir = dirname15(file.path); !roots.has(dir) && dirname15(dir) !== dir; dir = dirname15(dir)) {
+        try {
+          rmdirSync(dir);
+        } catch {
+          break;
+        }
+      }
+    }
+  }
   const patternsStore = readPatternsStore();
   const pattern = patternsStore.records.find((p) => p.generalizedBackupId === backupId);
   if (pattern) {
@@ -12283,7 +12932,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").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);
+program.command("audit").option("--compare <file>", "compare with a prior full audit JSON; preserve all current findings").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("--plugin-inventory <file>", "import a static host inventory JSON; audit one host at a time").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);
@@ -12294,7 +12943,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)").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("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("--fail-scope <scope>", "findings used by --fail-on: configured|all (default configured; all includes plugin findings)").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("--plugin-inventory <file>", "import a static host inventory JSON; audit one host at a time").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);
@@ -12308,13 +12957,18 @@ insight.command("approve <study-id>").description("Human-only TTY approval of th
 insight.command("jira <study-id>").description("Generate a Jira manifest or manage its private local receipts; never calls Jira").option("--project <key>", "destination Jira project key recorded in a new manifest").option("--out <file>", "write an additional export-safe manifest here (refuses an existing file)").option("--handoff", "launch the configured agent to present and confirm the backlog before Jira writes").option("--receipt <file>", "append one validated local receipt for the current manifest").option("--resume", "show local resume state for the current manifest").option("--json", "print the selected mode result as one JSON document").action(insightJira);
 insight.command("status <study-id>").description("Show private study lifecycle and evidence counts; read-only").option("--json", "print the status payload as one JSON document").action(insightStatus);
 insight.command("close <study-id>").description("Close a study while preserving its append-only receipts").requiredOption("--status <status>", "dismissed|archived", parseInsightCloseStatus).action(insightClose);
+var plugins = program.command("plugins").description("Explicit host-specific plugin retention decisions; never suppresses safety findings");
+plugins.command("keep <plugin-id>").requiredOption("--host <host>", "claude|codex").requiredOption("--category <category>", "essential|project-specific|intentionally-infrequent").requiredOption("--reason <text>", "why this capability should be retained").option("--project <path>", "bind the decision to an existing project").option("--json", "print JSON").action(pluginsKeepCommand);
+plugins.command("list").option("--json", "print JSON").action(pluginsListCommand);
+plugins.command("forget <plugin-id>").requiredOption("--host <host>", "claude|codex").option("--project <path>", "remove the decision for this project only").option("--json", "print JSON").action(pluginsForgetCommand);
 var refine = program.command("refine").description("Capture, apply, and generalize improvements to installed skills from usage feedback (Pro)");
 refine.command("capture", { isDefault: true }).description("Record a refinement and write a project-scope override artifact (never touches the base skill)").option("--skill <name>", "target skill name").option("--category <cat>", "trigger|content|hook|tool|pattern|config|new").option("--target <section>", 'heading path or file the refinement targets, e.g. "Hooks > duplicate-check"').option("--override-type <type>", "patch|extend|config|full|hook|script|new").option("--action <action>", "patch action: append|prepend|replace-section|insert-after|insert-before|delete-section").option("--marker <text>", "marker text for insert-* / replace-section / delete-section (filename for full|hook|script)").option("--content <text>", "override content inline").option("--content-file <file>", "read override content from a file").option("--expected <text>", "expected behavior").option("--actual <text>", "actual observed behavior").option("--example <text>", "concrete example of the gap").option("--outcome <text>", "desired outcome").option("--root-cause <text>", "root cause per the gap analysis").option("--pattern-id <id>", "join an existing pattern (PAT-xxxx) instead of fingerprint matching").option("--scope <scope>", 'where to write the artifact: "local" (.claude/skills, default) or "shared" (./skills)').option("--dry-run", "preview the artifact diff; write nothing").option("--json", "print the result as JSON").option("-y, --yes", "skip the interactive confirm; never implies --handoff").option("--handoff", "authorizes launching the configured agent with the bundled refine prompt").action(refineCaptureCommand);
 refine.command("list").description("Show refinement history from the user-scope store").option("--status <status>", "filter by refinement status").option("--skill <name>", "filter by skill").option("--project <name>", "filter by project").option("--json", "print records as JSON").action(refineListCommand);
 refine.command("patterns").description("Review tracked patterns and the generalization queue").option("--status <status>", "filter: tracking|ready|generalized|dismissed").option("--skill <name>", "filter by affected skill").option("--project <name>", "filter by project").option("--json", "print patterns as JSON").action(refinePatternsCommand);
+refine.command("activate").description("Materialize a captured patch as a new project skill; never edits a plugin cache").requiredOption("--skill <name>", "captured skill directory name").requiredOption("--base <dir>", "explicit base skill directory, read-only").requiredOption("--as <name>", "unique project skill name").requiredOption("--host <host>", "claude|codex").option("--scope <scope>", "capture source local|shared (default local)").option("--dry-run", "compose and safety-scan without activating").option("--json", "print one JSON result").option("-y, --yes", "confirm activation").action(refineActivateCommand);
 refine.command("which <skill>").description("Print override-scope resolution order and which override files exist at each scope").option("--user-root <dir>", "explicit user-scope skills root").option("--json", "print the resolution as JSON").action(refineWhichCommand);
 refine.command("promote <pattern-id>").description("Materialize a READY pattern into the user-scope skill default (backup + manifest first)").option("--force", "promote a pattern that is not READY").option("--dry-run", "preview the user-scope diff; write nothing").option("--user-root <dir>", "explicit user-scope skills root").option("--json", "print the result as JSON").option("-y, --yes", "skip the interactive confirm").action(refinePromoteCommand);
-refine.command("rollback <backup-id>").description("Restore a promotion backup (refuses if files changed since promotion unless --force)").option("--force", "restore even if current files differ from the post-promotion state").option("--json", "print the result as JSON").option("-y, --yes", "skip the interactive confirm").action(refineRollbackCommand);
+refine.command("rollback <backup-id>").option("--project", "restrict rollback to this project\u2019s .claude/skills and .agents/skills roots").description("Restore a promotion backup (refuses if files changed since promotion unless --force)").option("--force", "restore even if current files differ from the post-promotion state").option("--json", "print the result as JSON").option("-y, --yes", "skip the interactive confirm").action(refineRollbackCommand);
 program.command("init").description("Detect installed agents and set gate targets, default promotion target, and handoff agent").option("--defaults", "non-interactive: use all detected agents as gate targets, the first as the default target").option("--list", "print detected agent skill roots and exit \u2014 no writes").option("--all-agents", "pre-select every detected root, not just those of agents whose CLI is on PATH").action(init);
 try {
   await program.parseAsync();