@hasna/skills 0.10.73 → 0.10.75

package/dist/index.js

@@ -8566,8 +8566,8 @@ function ensureInstructionSkillFiles(skillPath, manifest) {
     displayName: manifest.displayName ?? displayName(manifest.name),
     category: manifest.category ?? "Development Tools",
     tags: manifest.tags?.length ? manifest.tags : ["custom", manifest.name],
-    inputs: [],
-    commands: []
+    inputs: Array.isArray(manifest.inputs) ? manifest.inputs : [],
+    commands: Array.isArray(manifest.commands) ? manifest.commands : []
   };
   if (!existsSync6(join6(skillPath, "SKILL.md"))) {
     writeFileSync2(join6(skillPath, "SKILL.md"), renderSkillMd(next));
@@ -15144,7 +15144,7 @@ import { basename as basename13, dirname as dirname24, isAbsolute as isAbsolute2
 import { homedir as homedir5 } from "os";
 import { isAbsolute as isAbsolute25, join as join36, resolve as resolve24 } from "path";
 // package.json
-var version = "0.10.73";
+var version = "0.10.75";
 var package_default = {
   name: "@hasna/skills",
   version,
@@ -20212,11 +20212,19 @@ function planAgentIntegration(options) {
     const executable2 = discoveryExecutable(agent) ?? (prior ? recordedDiscoveryExecutable(agent, prior) : null);
     executables.set(agent, executable2);
     const retainedReview = options.discoveryInputs === undefined && policy.bridge?.discovery?.[agent]?.method === "reviewed" ? { ...policy.bridge.discovery[agent], ...agent === "codex" ? { codexDisabledPluginSkills: policy.bridge.codexPluginSkills ?? [] } : {} } : undefined;
-    if (retainedReview) {
-      assertManagedAgentBridge(agent, { home, dataDir: dataDir2, projectDir: options.projectDir ?? home });
-      retainedAgents.push(agent);
+    try {
+      if (retainedReview) {
+        assertRetainedReviewState(agent, { home, dataDir: dataDir2, projectDir: options.projectDir ?? home });
+        retainedAgents.push(agent);
+      }
+      return resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, retainedReview, canonical: (path) => canonicalAgentPath(path, aliases), executable: executable2 });
+    } catch (error) {
+      if (isDiscoveryRootUnresolved(error) || error instanceof SumiPathResolverError || error instanceof NativeSkillCopiesDriftError)
+        throw error;
+      if (!retainedReview)
+        throw error;
+      throw new Error(`NATIVE_SKILL_DRIFT: ${error.message.replace(/^NATIVE_SKILL_DRIFT: /, "")}. This agent reuses a saved discovery review and that review no longer verifies, so a fresh explicit review is required: skills hook install --agent ${agent} --discovery-inputs <review> --apply.`);
     }
-    return resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, retainedReview, canonical: (path) => canonicalAgentPath(path, aliases), executable: executable2 });
   });
   const codexConfigBefore = options.agents.includes("codex") ? readOptional(canonicalAgentPath(join31(home, ".codex", "config.toml"), aliases)) : null;
   const codexConfig = Bun.TOML.parse(codexConfigBefore ?? "");
@@ -20970,7 +20978,7 @@ function applyAgentIntegrationUnlocked(plan, options = {}, assertCurrent) {
   assertCurrent();
   recheckRootAliases(aliases);
   for (const agent of plan.retainedReviewChecks?.agents ?? [])
-    assertManagedAgentBridge(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
+    assertRetainedReviewState(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
   if (plan.reviewArtifactMigration) {
     const verified = planReviewedArtifactMigration(plan.reviewArtifactMigration);
     if (JSON.stringify(verified.changes) !== JSON.stringify(plan.changes) || JSON.stringify(verified.discoveryAfter) !== JSON.stringify(plan.discoveryAfter))
@@ -21013,6 +21021,8 @@ function applyAgentIntegrationUnlocked(plan, options = {}, assertCurrent) {
   if (!plan.changes.length) {
     assertCurrent();
     recheckRootAliases(aliases);
+    for (const agent of plan.retainedReviewChecks?.agents ?? [])
+      assertManagedAgentBridge(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
     return { changed: [], backups, ...aliases.length ? { rootAliases: aliases } : {} };
   }
   assertSafePath(backupRoot);
@@ -21062,6 +21072,8 @@ function applyAgentIntegrationUnlocked(plan, options = {}, assertCurrent) {
     }
     for (const agent of plan.managedAgentChecks?.agents ?? [])
       assertManagedAgentBridge(agent, { home: plan.managedAgentChecks.home, dataDir: plan.dataDir, projectDir: plan.managedAgentChecks.projectDir ?? plan.managedAgentChecks.home });
+    for (const agent of plan.retainedReviewChecks?.agents ?? [])
+      assertManagedAgentBridge(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
     atomicWrite2(join31(backupRoot, "receipt.json"), JSON.stringify({ version: 1, changes: written.map((change) => ({ path: change.path, beforeHash: change.before === null ? null : sha4(change.before), afterHash: sha4(change.after) })), backups, ...plan.cacheWitnessUpgrade ? { cacheWitnessUpgrade: plan.cacheWitnessUpgrade } : {}, ...plan.retainedReviewArtifacts?.length ? { retainedReviewArtifacts: plan.retainedReviewArtifacts.map((item) => ({ path: item.path, ...item.artifact })) } : {}, ...aliases.length ? { rootAliases: aliases } : {} }) + `
 `);
   } catch (error) {
@@ -21393,7 +21405,7 @@ enabled = false
 function assertManagedAgentBridge(agent, options = {}) {
   return assertManagedAgentBridgeWithDiscovery(agent, options);
 }
-function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscovery) {
+function assertManagedBridgeCustody(agent, options = {}, provenDiscovery) {
   const home = resolve23(options.home ?? homedir2()), dataDir2 = options.dataDir ?? getDataDirReadOnly();
   assertSafePath(join31(dataDir2, "agent-policy.json"));
   const snapshot2 = readManagedSkillPolicySnapshot(dataDir2);
@@ -21410,7 +21422,6 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
   if (!isOwnedCliBridge(expected, [expected]))
     throw new Error("NATIVE_SKILL_DRIFT: the native Skills bridge is missing or modified; repair it before continuing");
   const roots = projectAncestorDirectories([options.projectDir ?? process.cwd(), ...options.projectDirs ?? [], ...agent === "hermes" && process.env.TERMINAL_CWD ? [process.cwd()] : []]);
-  const visible = (entry) => entry.agent === agent || ["codex", "gemini", "opencode", "hermes", "sumi"].includes(agent) && entry.path.includes(`${sep14}.agents${sep14}skills${sep14}`) || ["opencode", "sumi"].includes(agent) && entry.agent === "claude";
   const discovery = provenDiscovery ?? binding.discovery?.[agent];
   assertProjectDiscovery(agent, [...roots], home, (path) => canonicalAgentPath(path, aliases), discovery);
   for (const source of discovery?.sources ?? [])
@@ -21425,11 +21436,30 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
     throw new Error("NATIVE_SKILL_DRIFT: the native hook command/profile binding is missing");
   if (options.profileId !== undefined && options.profileId !== profile)
     throw new Error("NATIVE_SKILL_DRIFT: the hook selection profile differs from its managed binding; restart the native client after reviewing skills hook install");
+  return { home, dataDir: dataDir2, binding, aliases, expected, roots, discovery, configPath, config, command, profile };
+}
+function assertUnrepairableBridgeProtection(custody, agent) {
+  if (agent !== "hermes")
+    return;
+  const { home, dataDir: dataDir2, binding, config, command, profile } = custody;
+  const supervisor = binding.supervisors?.hermes;
+  if (supervisor?.path !== join31(dataDir2, "agent-hooks", "hermes.js") || supervisor?.sha256 !== sha4(renderHermesSupervisor(command, profile)))
+    throw new Error("NATIVE_SKILL_DRIFT: Hermes supervisor binding changed; run skills hook install");
+  assertHermesProtection(home, config, command, profile, supervisor);
+}
+function assertRetainedReviewState(agent, options) {
+  const custody = assertManagedBridgeCustody(agent, options);
+  assertUnrepairableBridgeProtection(custody, agent);
+  assertManagedNativeDiscovery(custody, agent, options);
+}
+
+class NativeSkillCopiesDriftError extends Error {
+}
+function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscovery) {
+  const custody = assertManagedBridgeCustody(agent, options, provenDiscovery);
+  const { home, aliases, expected, discovery, config, command, profile } = custody;
   if (agent === "hermes") {
-    const supervisor = binding.supervisors?.hermes;
-    if (supervisor?.path !== join31(dataDir2, "agent-hooks", "hermes.js") || supervisor?.sha256 !== sha4(renderHermesSupervisor(command, profile)))
-      throw new Error("NATIVE_SKILL_DRIFT: Hermes supervisor binding changed; run skills hook install");
-    assertHermesProtection(home, config, command, profile, supervisor);
+    assertUnrepairableBridgeProtection(custody, agent);
   } else if (agent === "sumi") {
     if (JSON.stringify(config.permissions?.filter((rule) => rule.action === "skill")) !== JSON.stringify(SUMI_SKILL_PERMISSIONS) || !isManagedSumiPlugin(readOptional(join31(sumiConfigDirectory(home, process.env, options.projectDir ?? process.cwd()), "plugins", "skills-cli.js")), command, profile))
       throw new Error("NATIVE_SKILL_DRIFT: Sumi bridge protection changed; run skills hook install");
@@ -21451,6 +21481,21 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
     if (agent === "gemini" && (config.hooksConfig?.enabled === false || config.skills?.enabled !== true || !["antigravity-support", "skill-creator"].every((name) => config.skills?.disabled?.includes(name)) || config.skills?.disabled?.includes(CLI_BRIDGE_NAME)))
       throw new Error("NATIVE_SKILL_DRIFT: Gemini bridge or bundled-skill protection changed; run skills hook install");
   }
+  if (agent === "codex") {
+    const codexConfig = Bun.TOML.parse(readOptional(canonicalAgentPath(join31(home, ".codex", "config.toml"), aliases)) ?? "");
+    if (codexConfig.skills?.bundled?.enabled !== false)
+      throw new Error("NATIVE_SKILL_DRIFT: Codex bundled skill reseeding is not disabled (skills.bundled.enabled); run skills hook install");
+    const setting = (path) => (codexConfig.skills?.config ?? []).filter((entry) => typeof entry.path === "string" && [path, join31(path, "SKILL.md")].includes(canonicalAgentPath(entry.path, aliases)));
+    if ([...setting(expected), ...(codexConfig.skills?.config ?? []).filter((entry) => typeof entry.name === "string" && entry.name.trim() === CLI_BRIDGE_NAME)].some((entry) => entry.enabled === false))
+      throw new Error("NATIVE_SKILL_DRIFT: the Codex CLI bridge is disabled; run skills hook install");
+  }
+  if (agent === "gemini" && discovery && !discovery.builtinNames?.every((name) => config.skills.disabled.includes(name)))
+    throw new Error("NATIVE_SKILL_DRIFT: an installed Gemini builtin is not disabled");
+  return assertManagedNativeDiscovery(custody, agent, options);
+}
+function assertManagedNativeDiscovery(custody, agent, options) {
+  const { home, dataDir: dataDir2, binding, aliases, expected, roots, discovery } = custody;
+  const visible = (entry) => entry.agent === agent || ["codex", "gemini", "opencode", "hermes", "sumi"].includes(agent) && entry.path.includes(`${sep14}.agents${sep14}skills${sep14}`) || ["opencode", "sumi"].includes(agent) && entry.agent === "claude";
   const codexPath = canonicalAgentPath(join31(home, ".codex", "config.toml"), aliases);
   const vendorCache = canonicalAgentPath(join31(home, ".codex", "plugins", "cache"), aliases);
   const witnessTolerance = agent === "codex" && options.codexPromptHook === true ? {
@@ -21461,11 +21506,6 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
   if (options.codexDiscoveryRecovery && (agent !== "codex" || options.codexDiscoveryRecovery.configPath !== codexPath))
     throw new Error("NATIVE_SKILL_DRIFT: Codex trust recovery names a different configuration root");
   const codexConfig = agent === "codex" ? Bun.TOML.parse(readOptional(codexPath) ?? "") : {};
-  if (agent === "codex" && codexConfig.skills?.bundled?.enabled !== false)
-    throw new Error("NATIVE_SKILL_DRIFT: Codex bundled skill reseeding is not disabled (skills.bundled.enabled); run skills hook install");
-  const setting = (path) => (codexConfig.skills?.config ?? []).filter((entry) => typeof entry.path === "string" && [path, join31(path, "SKILL.md")].includes(canonicalAgentPath(entry.path, aliases)));
-  if (agent === "codex" && [...setting(expected), ...(codexConfig.skills?.config ?? []).filter((entry) => typeof entry.name === "string" && entry.name.trim() === CLI_BRIDGE_NAME)].some((entry) => entry.enabled === false))
-    throw new Error("NATIVE_SKILL_DRIFT: the Codex CLI bridge is disabled; run skills hook install");
   if (agent === "codex" && !reviewedCodexPluginCapabilitiesUnchanged(canonicalAgentPath(join31(home, ".codex/plugins/cache"), aliases), binding.codexPluginSkills ?? [], (path) => new TextDecoder("utf-8", { fatal: true }).decode(readNativeBytes(path, 1024 * 1024)), codexConfig.skills?.config ?? []))
     throw new Error("NATIVE_SKILL_DRIFT: reviewed native plugin capability controls changed; run skills hook install with a fresh discovery review");
   const disabledPlugin = (entry) => {
@@ -21502,8 +21542,6 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
   };
   if (!discovery || discovery.agent !== agent)
     throw new Error("NATIVE_SKILL_DRIFT: native discovery coverage is missing; run skills hook install");
-  if (agent === "gemini" && !discovery.builtinNames?.every((name) => config.skills.disabled.includes(name)))
-    throw new Error("NATIVE_SKILL_DRIFT: an installed Gemini builtin is not disabled");
   try {
     verifyAgentDiscovery(agent === "codex" ? { ...discovery, codexDisabledPluginSkills: binding.codexPluginSkills ?? [] } : discovery, options.codexDiscoveryRecovery, aliases, witnessTolerance);
     if (agent === "sumi" && discovery.method === "reviewed")
@@ -21558,7 +21596,7 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
         return false;
       }
     }, read: (path) => new TextDecoder("utf-8", { fatal: true }).decode(readNativeBytes(path, 1024 * 1024)) });
-    throw new Error(`NATIVE_SKILL_DRIFT: ${blocking.length} unexpected native skill copies were found: ${nativeSkillPathList(blocking.map((entry) => entry.path))}. ${remediation}${adapterRefusal ? ` Native policy adapter refused: ${adapterRefusal}` : ""}`);
+    throw new NativeSkillCopiesDriftError(`NATIVE_SKILL_DRIFT: ${blocking.length} unexpected native skill copies were found: ${nativeSkillPathList(blocking.map((entry) => entry.path))}. ${remediation}${adapterRefusal ? ` Native policy adapter refused: ${adapterRefusal}` : ""}`);
   }
   recheckRootAliases(aliases);
   const discoveryChanges = (witnessTolerance?.changes ?? []).filter((change, index, all) => all.findIndex((other) => other.kind === change.kind && other.path === change.path) === index);
@@ -22689,6 +22727,115 @@ function readIfExists(path) {
   return null;
 }
 
+// src/lib/search.ts
+function editDistance(a, b) {
+  if (a === b)
+    return 0;
+  if (a.length === 0)
+    return b.length;
+  if (b.length === 0)
+    return a.length;
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  const curr = new Array(b.length + 1);
+  for (let i = 1;i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1;j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    prev.splice(0, prev.length, ...curr);
+  }
+  return prev[b.length];
+}
+function fuzzyMatchScore(word, target) {
+  if (target.includes(word))
+    return 1;
+  const tokens = target.split(/[\s\-_]+/).filter(Boolean);
+  for (const token of tokens) {
+    if (token.startsWith(word))
+      return 0.6;
+  }
+  if (word.length >= 3) {
+    const maxDist = word.length <= 3 ? 1 : 2;
+    for (const token of tokens) {
+      if (Math.abs(token.length - word.length) <= maxDist) {
+        const dist = editDistance(word, token);
+        if (dist <= maxDist)
+          return 0.4;
+      }
+    }
+  }
+  return 0;
+}
+function searchSkills(query, registry = loadRegistry()) {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (words.length === 0)
+    return [];
+  const scored = [];
+  for (const skill of registry) {
+    const nameLower = skill.name.toLowerCase();
+    const displayNameLower = skill.displayName.toLowerCase();
+    const descriptionLower = skill.description.toLowerCase();
+    const tagsLower = skill.tags.map((t2) => t2.toLowerCase());
+    const tagsCombined = tagsLower.join(" ");
+    let score = 0;
+    let allWordsMatch = true;
+    for (const word of words) {
+      let wordScore = 0;
+      const nameMatch = fuzzyMatchScore(word, nameLower);
+      if (nameMatch > 0)
+        wordScore += 10 * nameMatch;
+      const displayMatch = fuzzyMatchScore(word, displayNameLower);
+      if (displayMatch > 0)
+        wordScore += 7 * displayMatch;
+      const tagMatch = Math.max(...tagsLower.map((t2) => fuzzyMatchScore(word, t2)), fuzzyMatchScore(word, tagsCombined));
+      if (tagMatch > 0)
+        wordScore += 5 * tagMatch;
+      const descMatch = fuzzyMatchScore(word, descriptionLower);
+      if (descMatch > 0)
+        wordScore += 2 * descMatch;
+      if (wordScore === 0) {
+        allWordsMatch = false;
+        break;
+      }
+      score += wordScore;
+    }
+    if (allWordsMatch && score > 0) {
+      scored.push({ skill, score });
+    }
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.map((s) => s.skill);
+}
+function findCloseSkillNames(query, names, maxResults = 3) {
+  if (maxResults <= 0)
+    return [];
+  const q = query.trim().toLowerCase();
+  if (q.length === 0)
+    return [];
+  const tokens = q.split("-").filter(Boolean);
+  const ranked = [];
+  if (q.length >= 3) {
+    for (const name of names) {
+      const candidate = name.toLowerCase();
+      const rank = candidate === q ? 0 : candidate.endsWith(`-${q}`) || candidate.startsWith(`${q}-`) ? 1 : tokens.length > 1 && tokens.every((token) => candidate.split("-").includes(token)) ? 2 : undefined;
+      if (rank !== undefined)
+        ranked.push([name, rank]);
+    }
+  }
+  ranked.sort((a, b) => a[1] - b[1] || a[0].length - b[0].length || a[0].localeCompare(b[0]));
+  const found = ranked.slice(0, maxResults).map(([name]) => name);
+  if (found.length === maxResults)
+    return found;
+  const taken = new Set(found);
+  const threshold = Math.max(3, Math.floor(q.length / 2));
+  const byDistance = names.filter((name) => !taken.has(name)).map((name) => ({ name, distance: editDistance(q, name.toLowerCase()) })).filter((entry) => entry.distance <= threshold).sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name));
+  return [...found, ...byDistance.slice(0, maxResults - found.length).map((entry) => entry.name)];
+}
+function findSimilarSkills(query, maxResults = 3, registry = loadRegistry()) {
+  return findCloseSkillNames(query, registry.map((skill) => skill.name), maxResults);
+}
+
 // src/lib/selected-document.ts
 var DOCUMENT_PATHS = ["SKILL.md", "README.md", "CLAUDE.md"];
 function readSelectedDocument(entries, file) {
@@ -22805,11 +22952,31 @@ function exactProfileSelection(spec, profile) {
   const at = spec.lastIndexOf("@");
   const slug = at > 0 ? spec.slice(0, at) : spec;
   const version2 = at > 0 ? spec.slice(at + 1) : undefined;
-  const selection = profile.selections.find((entry) => (entry.slug === slug || entry.aliases?.includes(slug)) && (version2 === undefined || version2 === entry.version));
-  if (!selection || version2 === "")
-    throw new SkillSelectionError("SKILL_NOT_SELECTED", "The requested exact skill version is not selected by this profile or project lock.");
+  const named = profile.selections.filter((entry) => entry.slug === slug || entry.aliases?.includes(slug));
+  if (version2 === "")
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", emptyVersionRefusal(spec));
+  if (named.length === 0)
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", unknownNameRefusal(slug, profile));
+  const selection = version2 === undefined ? named[0] : named.find((entry) => entry.version === version2);
+  if (!selection)
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", wrongVersionRefusal(slug, version2, named));
   return selection;
 }
+var ACCEPTED_FORM = "Accepted form: '<slug>' or '<slug>@<version>'.";
+function emptyVersionRefusal(spec) {
+  return `The requested name '${spec}' has an empty version. ${ACCEPTED_FORM}`;
+}
+function wrongVersionRefusal(slug, version2, named) {
+  const versions = [...new Set(named.map((entry) => entry.version))].sort();
+  const canonical9 = named[0].slug;
+  return `Skill '${slug}' is selected at version '${versions.join("', '")}', but '${version2}' was requested. ` + `Accepted form: '${canonical9}@${versions[0]}'.`;
+}
+function unknownNameRefusal(slug, profile) {
+  const names = profile.selections.flatMap((entry) => [entry.slug, ...entry.aliases ?? []]);
+  const close = findCloseSkillNames(slug, names);
+  const hint = close.length > 0 ? ` Did you mean: ${close.join(", ")}?` : "";
+  return `Skill '${slug}' is not selected by this Skills profile or project lock.${hint} ` + `Read the accepted names with 'skills search <term>' or 'skills list --all --json'; accept one with 'skills pin <name>'. ${ACCEPTED_FORM}`;
+}
 
 // src/lib/selected-manifest.ts
 function jsonEntry(entries, path) {
@@ -24133,6 +24300,12 @@ function verifyAgentDiscovery(binding, codexRecovery, reviewedRootAliases, witne
 }
 var CLAUDE_CONTROL_WITNESS_MODES = new Set(["claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-settings-v4", "claude-marketplace-registry", "claude-marketplace-registry-v2", "claude-marketplace-entry-v1", "claude-plugin-registry"]);
 var CLAUDE_CONTROL_FILES = new Set(["settings.json", "settings.local.json", "installed_plugins.json", "known_marketplaces.json"]);
+function claudeControlSource(source) {
+  return CLAUDE_CONTROL_WITNESS_MODES.has(source.hashMode ?? "") || CLAUDE_CONTROL_FILES.has(basename15(source.path)) && !source.path.includes(`${sep15}.claude${sep15}plugins${sep15}cache${sep15}`);
+}
+function retainedAbsentClaudeRoot(absentRoots, source) {
+  return claudeControlSource(source) ? undefined : retainedAbsentRoot(absentRoots, source);
+}
 function codexInstallationRoots(binding) {
   const proof = binding.codexInstallationInputs;
   if (proof === undefined)
@@ -24542,7 +24715,10 @@ function resolveAgentDiscovery(options) {
     if (!review.sources.some((source) => source.path === canonical9(configPath)))
       throw new Error("Discovery review must include the agent configuration source");
     const reviewedSources = supersedesSettingsProjection(agent, review.sources, canonical9(configPath)) ? sources.filter((source) => !isSupersededSettingsProjection(agent, canonical9(configPath), source)) : sources;
+    const absentRoots = absentRetiredClaudeRoots(supplied);
     const reviewedSourcesWithManifestProjection = review.sources.map((source) => {
+      if (retainedAbsentClaudeRoot(absentRoots, source) !== undefined)
+        return source;
       if (agent === "claude" && source.format === undefined && source.fields === undefined && source.managedPlugins === undefined && source.reviewArtifact === undefined && [undefined, "bytes", "path-bytes"].includes(source.hashMode) && isClaudePluginCacheOrphanMarker(source.path)) {
         return { path: source.path, hashMode: CLAUDE_ORPHAN_MARKER_MODE, sha256: hashClaudePluginCacheOrphanMarker(source.path) };
       }
@@ -24575,6 +24751,11 @@ function resolveAgentDiscovery(options) {
     });
     if (agent === "claude")
       assertReviewedClaudeCacheClosures(home, config, review, canonical9);
+    for (const root2 of absentRoots) {
+      safe6(root2);
+      if (lstatSync32(root2, { throwIfNoEntry: false }))
+        throw new Error("Retired native materialization changed during discovery review");
+    }
     const combined = [...reviewedSources, ...reviewedSourcesWithManifestProjection];
     const unique = combined.filter((source, index) => combined.findIndex((candidate2) => isDeepStrictEqual9(candidate2, source)) === index);
     return { ...supplied, roots: [...new Set([...roots, ...supplied.roots])].sort(), sources: unique, ...agent === "gemini" ? { builtinNames } : {} };
@@ -25302,92 +25483,6 @@ var CATEGORIES = [
   "Event Management"
 ];
 var BASIC_SKILL_NAMES = [];
-
-// src/lib/search.ts
-function editDistance(a, b) {
-  if (a === b)
-    return 0;
-  if (a.length === 0)
-    return b.length;
-  if (b.length === 0)
-    return a.length;
-  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
-  const curr = new Array(b.length + 1);
-  for (let i = 1;i <= a.length; i++) {
-    curr[0] = i;
-    for (let j = 1;j <= b.length; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
-    }
-    prev.splice(0, prev.length, ...curr);
-  }
-  return prev[b.length];
-}
-function fuzzyMatchScore(word, target) {
-  if (target.includes(word))
-    return 1;
-  const tokens = target.split(/[\s\-_]+/).filter(Boolean);
-  for (const token of tokens) {
-    if (token.startsWith(word))
-      return 0.6;
-  }
-  if (word.length >= 3) {
-    const maxDist = word.length <= 3 ? 1 : 2;
-    for (const token of tokens) {
-      if (Math.abs(token.length - word.length) <= maxDist) {
-        const dist = editDistance(word, token);
-        if (dist <= maxDist)
-          return 0.4;
-      }
-    }
-  }
-  return 0;
-}
-function searchSkills(query, registry = loadRegistry()) {
-  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
-  if (words.length === 0)
-    return [];
-  const scored = [];
-  for (const skill of registry) {
-    const nameLower = skill.name.toLowerCase();
-    const displayNameLower = skill.displayName.toLowerCase();
-    const descriptionLower = skill.description.toLowerCase();
-    const tagsLower = skill.tags.map((t2) => t2.toLowerCase());
-    const tagsCombined = tagsLower.join(" ");
-    let score = 0;
-    let allWordsMatch = true;
-    for (const word of words) {
-      let wordScore = 0;
-      const nameMatch = fuzzyMatchScore(word, nameLower);
-      if (nameMatch > 0)
-        wordScore += 10 * nameMatch;
-      const displayMatch = fuzzyMatchScore(word, displayNameLower);
-      if (displayMatch > 0)
-        wordScore += 7 * displayMatch;
-      const tagMatch = Math.max(...tagsLower.map((t2) => fuzzyMatchScore(word, t2)), fuzzyMatchScore(word, tagsCombined));
-      if (tagMatch > 0)
-        wordScore += 5 * tagMatch;
-      const descMatch = fuzzyMatchScore(word, descriptionLower);
-      if (descMatch > 0)
-        wordScore += 2 * descMatch;
-      if (wordScore === 0) {
-        allWordsMatch = false;
-        break;
-      }
-      score += wordScore;
-    }
-    if (allWordsMatch && score > 0) {
-      scored.push({ skill, score });
-    }
-  }
-  scored.sort((a, b) => b.score - a.score);
-  return scored.map((s) => s.skill);
-}
-function findSimilarSkills(query, maxResults = 3, registry = loadRegistry()) {
-  const q = query.toLowerCase();
-  const scored = registry.map((s) => ({ name: s.name, dist: editDistance(q, s.name.toLowerCase()) })).filter((s) => s.dist <= Math.max(3, Math.floor(q.length / 2))).sort((a, b) => a.dist - b.dist);
-  return scored.slice(0, maxResults).map((s) => s.name);
-}
 // src/lib/registry.ts
 function isBasicSkillName(name) {
   return BASIC_SKILL_NAMES.includes(name);

package/dist/lib/portable-skills-files.d.ts

@@ -52,6 +52,16 @@ export declare function ensurePortableSkillFiles(skillPath: string, manifest: Po
  * locally, so `port` must never fabricate executable stubs (package.json, bin,
  * src/index.ts, tsconfig.json, AGENTS.md). Apart from aligning declared names
  * after an import rename, it preserves the copied prose and metadata.
+ *
+ * "Metadata" includes what the candidate declared in skill.json. An instruction
+ * skill may legitimately bundle a helper command (and inputs for it) — the
+ * validator permits a package.json bin on an instruction skill for exactly that
+ * reason — so declared `commands` and `inputs` are carried through verbatim and
+ * only an absent declaration becomes an explicit empty array. Forcing them to []
+ * here silently erased the declaration on disk: writeSkillJsonWithHash() merges
+ * the rebuilt manifest over the copied candidate skill.json, so the candidate's
+ * own array was destroyed and the manifest was left self-inconsistent
+ * (runtime.entrypoint still naming an entry no command declared).
  */
 export declare function ensureInstructionSkillFiles(skillPath: string, manifest: PortableSkillManifest): PortableSkillManifest;
 export declare function copySkillDirectory(source: string, destination: string): void;

package/dist/lib/search.d.ts

@@ -11,6 +11,24 @@ export declare function editDistance(a: string, b: string): number;
  * Search skills by name, description, and tags using fuzzy matching.
  */
 export declare function searchSkills(query: string, registry?: SkillMeta[]): SkillMeta[];
+/**
+ * Bounded close canonical names for a refused name, strongest evidence first:
+ *
+ *  0. the exact name;
+ *  1. a hyphen-delimited containment — the candidate owns the query as a whole
+ *     leading or trailing segment (`fleet-refresh` → `instructions-fleet-refresh`);
+ *  2. a multi-word token subset of the candidate;
+ *  3. the edit-distance rule that was the only signal before.
+ *
+ * Containment is what edit distance cannot see, and it is the case that cost
+ * real time: the canonical name that owns a shorter name as its trailing
+ * segment is 13 edits from the short name, so a caller naming the procedure by
+ * its last words was told the procedure did not exist (Agents Audit A27). The
+ * distance pass still runs and fills any slots containment leaves, so a
+ * distance-only miss — including every query under three characters — keeps the
+ * answer it has always had.
+ */
+export declare function findCloseSkillNames(query: string, names: readonly string[], maxResults?: number): string[];
 /**
  * Find skills with names similar to the given query (for "did you mean?" suggestions).
  */

package/dist/lib/selected-run.d.ts

@@ -13,6 +13,50 @@ export interface ResolvedSelectedRun {
     cacheDir: string;
 }
 export declare function resolveSelectedRun(spec: string, profileId: string, options?: SelectionResolverOptions): Promise<ResolvedSelectedRun>;
+/**
+ * The operation an instruction skill declares, if it declares one.
+ *
+ * An instruction skill is prose-first: agents follow SKILL.md, and `skills run`
+ * refuses it. Its manifest may still declare the one operation it ships — the
+ * first `commands` entry, naming the helper — together with an explicit runtime
+ * contract in `runtime` (`runtime` plus its `version`/`timeout` policy). Such a
+ * skill is runnable through that declared operation, and only through it: the
+ * executed file is exactly the entry the selected command declares, it must be a
+ * regular file in the selected bundle, and a `runtime.entrypoint` that disagrees
+ * with it is an inconsistent declaration that refuses (see
+ * {@link instructionEntrypointMismatch}) rather than quietly running the other
+ * file. An instruction skill that declares no operation — no command, a
+ * non-string or empty entry, or no runtime contract — keeps the prose-only
+ * refusal (`skills load`, never `skills run`), so an instruction bundle is never
+ * mistaken for a runnable stub.
+ */
+export declare function declaredOperation(manifest: Record<string, any>): {
+    entry: string;
+} | null;
+/**
+ * The entry the instruction skill's declared command names, when it names one.
+ * The first `commands` entry is the operation: nothing else in the manifest
+ * selects what an instruction skill runs.
+ */
+export declare function instructionCommandEntry(manifest: Record<string, any>): string | null;
+/**
+ * A declared `runtime.entrypoint` that disagrees with the declared command entry,
+ * for an instruction skill. The command entry is the authority, so a disagreement
+ * is an inconsistent declaration: it refuses, and the disagreeing file never runs.
+ */
+export declare function instructionEntrypointMismatch(manifest: Record<string, any>): string | null;
+/**
+ * Why an instruction skill cannot run locally, if it cannot. `isBundledFile` says
+ * whether a path is a regular file in the selected bundle, so a declared command
+ * entry that is not there is refused by name instead of being substituted. The
+ * CLI, the MCP tool and the local executor all ask this one function, so the
+ * reason and the code cannot drift between them. A runnable instruction skill
+ * (declared command, agreeing runtime, entry present in the bundle) returns null.
+ */
+export declare function instructionRunRefusal(manifest: Record<string, any>, isBundledFile: (path: string) => boolean): {
+    code: string;
+    message: string;
+} | null;
 export interface SelectedLocalRunOptions {
     args?: string[];
     input?: unknown;
@@ -54,6 +98,7 @@ export declare function executeSelectedLocal(selected: ResolvedSelectedRun, opti
     selection: ResolvedSkillSelection;
     target: "local";
     runtime: any;
+    entrypoint: string;
     inputDigest: string;
     runDirectory: string;
 }>;

package/dist/lib/selection-provenance.d.ts

@@ -0,0 +1,108 @@
+import { type SelectionCacheOptions } from "./selection-cache.js";
+/** Bounded so one receipt can never carry an unbounded drift list. */
+export declare const PROVENANCE_DRIFT_LIMIT = 200;
+export type SelectionProvenanceStatus = "current" | "behind" | "pinned" | "unverified";
+export type SelectionProvenanceSource = "local-receipt" | "authority-receipt" | "session-receipt";
+export type SelectionProvenanceReference = "authority" | "synced-snapshot" | "unavailable";
+/**
+ * The fixed diagnostic vocabulary. A reader's exception text is never carried,
+ * only one of these codes, so a foreign body or a credential inside an error
+ * string cannot reach a receipt that may be shared.
+ */
+export type SelectionProvenanceReason = "CURRENT_SCHEMA_MATCH" | "REVISION_BEHIND" | "PINNED_BY_DESIGN" | "IDENTITY_MISMATCH" | "INCOMPLETE_RECEIPT" | "DIFFERENT_PROFILE" | "NO_LOCAL_RECEIPT" | "NO_SESSION_NAMED" | "NO_SESSION_RECEIPT" | "NO_STATION_RECEIPT" | "READ_REFUSED" | "REFERENCE_FROM_AUTHORITY" | "REFERENCE_NOT_AUTHORITY" | "REFERENCE_UNAVAILABLE" | "NO_STATION_REPORTED";
+export interface SelectionProvenanceVersion {
+    slug: string;
+    version: string;
+    bundleDigest?: string;
+}
+export interface SelectionProvenanceConsumer {
+    kind: "station" | "session";
+    source: SelectionProvenanceSource;
+    /** The local host for a local receipt, the requested station only for the authority receipt. */
+    id: string;
+    /** Whether `id` names the host running this command or a station named on the command line. */
+    idKind: "local-host" | "requested-station";
+    profileId?: string;
+    profileRevision?: string;
+    /** Compared, never assumed: a matching revision under another identity is not current. */
+    authority?: string;
+    workspaceId?: string;
+    observedAt?: string;
+    selectionCount?: number;
+    /** Only for a session: how many of its selections it really loaded. */
+    loadedCount?: number;
+    /** Only for a session: the exact versions it really loaded. */
+    consumed?: SelectionProvenanceVersion[];
+    status: SelectionProvenanceStatus;
+    reasonCode: SelectionProvenanceReason;
+    reason: string;
+}
+export interface SelectionProvenanceDrift {
+    source: SelectionProvenanceSource;
+    id: string;
+    slug: string;
+    selectedVersion: string;
+    observedVersion: string;
+}
+export interface SelectionProvenanceReceipt {
+    schemaVersion: 1;
+    readOnly: true;
+    selectionProfile: string;
+    selected: {
+        profileId: string;
+        profileRevision?: string;
+        selectionCount?: number;
+        authority?: string;
+        workspaceId?: string;
+        source: SelectionProvenanceReference;
+        observedAt?: string;
+        reasonCode: SelectionProvenanceReason;
+        reason: string;
+    };
+    consumers: SelectionProvenanceConsumer[];
+    drift: SelectionProvenanceDrift[];
+    driftTruncated: boolean;
+    /**
+     * What this receipt deliberately does not attest. Version and digest evidence
+     * for published payloads, native discovery, native locks and live consumer
+     * adoption are outside this command and stay unverified here rather than being
+     * implied by a clean-looking result.
+     */
+    notAttested: string[];
+}
+export interface SelectionProvenanceInput {
+    profileId: string;
+    /** The station whose authority-held sync receipt is read. */
+    stationId: string;
+    /** The host this command runs on. Never conflated with `stationId`. */
+    localStationId: string;
+    sessionId?: string;
+    /** Read the reference from the locally synced snapshot; never ask the authority. */
+    cached?: boolean;
+}
+/** A station receipt reduced to what this receipt compares. */
+export interface ProvenanceStationObservation {
+    profileId: string;
+    profileRevision: string;
+    appliedAt: string;
+    workspaceId?: string;
+    selections: readonly {
+        slug: string;
+        version: string;
+    }[];
+}
+export interface SelectionProvenanceOptions extends SelectionCacheOptions {
+    /** Injected by the SDK and tests; defaults to the authenticated reads. */
+    readSelected?: (profileId: string) => Promise<{
+        profileId: string;
+        profileRevision: string;
+        authority?: string;
+        workspaceId?: string;
+        selections: readonly {
+            slug: string;
+            version: string;
+        }[];
+    }>;
+    readStation?: (stationId: string) => Promise<ProvenanceStationObservation>;
+}
+export declare function readSelectionProvenance(input: SelectionProvenanceInput, options?: SelectionProvenanceOptions): Promise<SelectionProvenanceReceipt>;