@acidicsoil/portable-capabilities 0.1.8 → 0.1.10

package/dist-release/index.js

@@ -3541,9 +3541,9 @@ function normalizeDigestValue(value) {
 function stableManifestDigest(value) {
   return digestBytes(new TextEncoder().encode(JSON.stringify(normalizeDigestValue(value))));
 }
-function packageEntriesDigest(entries2, packageIdentities = []) {
+function packageEntriesDigest(entries, packageIdentities = []) {
   return stableManifestDigest({
-    entries: [...entries2].sort((left, right) => left.path.localeCompare(right.path)).map((entry) => ({ path: entry.path, digest: entry.digest, mode: entry.mode })),
+    entries: [...entries].sort((left, right) => left.path.localeCompare(right.path)).map((entry) => ({ path: entry.path, digest: entry.digest, mode: entry.mode })),
     packageIdentities: [...packageIdentities].sort(
       (left, right) => left.lockPath.localeCompare(right.lockPath)
     )
@@ -3792,9 +3792,9 @@ async function copyAtomically(source3, target, mode) {
   await rename2(temporary, target);
 }
 async function desiredEntries(sourceRoot, files) {
-  const entries2 = [];
-  for (const file of files) entries2.push(await entryFor(join3(sourceRoot, file), file));
-  return entries2;
+  const entries = [];
+  for (const file of files) entries.push(await entryFor(join3(sourceRoot, file), file));
+  return entries;
 }
 async function selectedPackageFiles(options) {
   const files = await listPackageFiles(options.sourceRoot);
@@ -3860,9 +3860,9 @@ async function unselectedPackageRoots(options) {
   }
   return Object.freeze(roots);
 }
-async function installedPackageIdentities(sourceRoot, entries2) {
+async function installedPackageIdentities(sourceRoot, entries) {
   const identities = [];
-  for (const entry of entries2.filter((item) => item.path.endsWith("/capability.lock.json"))) {
+  for (const entry of entries.filter((item) => item.path.endsWith("/capability.lock.json"))) {
     const lock = JSON.parse(await readFile2(join3(sourceRoot, entry.path), "utf8"));
     if (lock.schemaVersion !== "2.0.0" || !lock.integrity?.package?.digest || lock.generatedDigest !== lock.integrity.package.digest) {
       throw new Error(`Invalid capability package identity: ${entry.path}`);
@@ -4155,6 +4155,19 @@ async function assertPlanPathsSafe(targetRoot, plan) {
 }
 async function executePreparedInstallation(options) {
   const manifest = await readInstallationManifest(options.targetRoot);
+  const operation = options.preparedOperation ?? "install";
+  if (options.preparedDiagnostics?.length) {
+    return result(operation, "degraded", {
+      ok: false,
+      diagnostics: options.preparedDiagnostics
+    });
+  }
+  if (options.preparedMutations.length === 0) {
+    return result(operation, "degraded", {
+      ok: false,
+      diagnostics: ["No prepared mutations can be installed"]
+    });
+  }
   const duplicatePaths = /* @__PURE__ */ new Set();
   for (const mutation of options.preparedMutations) {
     if (duplicatePaths.has(mutation.path)) {
@@ -4229,7 +4242,6 @@ async function executePreparedInstallation(options) {
     packageIdentities,
     entries: nextEntries
   };
-  const operation = options.preparedOperation ?? "install";
   if (options.dryRun)
     return result(operation, manifest ? "healthy" : "missing", {
       dryRun: true,
@@ -4338,12 +4350,12 @@ async function removeInstallation(targetRoot, faultInjector, capabilityIds) {
   const removes = manifest.entries.filter((entry) => unchanged.has(entry.path)).map((entry) => entry.path);
   const preserved = manifest.entries.filter((entry) => !unchanged.has(entry.path));
   const nextManifest = preserved.length ? (() => {
-    const entries2 = Object.freeze(preserved);
-    const preservedPaths = new Set(entries2.map((entry) => entry.path));
+    const entries = Object.freeze(preserved);
+    const preservedPaths = new Set(entries.map((entry) => entry.path));
     const packageIdentities = Object.freeze(
       manifest.packageIdentities.filter((identity3) => preservedPaths.has(identity3.lockPath))
     );
-    const packageDigest = packageEntriesDigest(entries2, packageIdentities);
+    const packageDigest = packageEntriesDigest(entries, packageIdentities);
     const base = {
       runtimeId: manifest.runtimeId,
       packageVersion: manifest.packageVersion,
@@ -4351,7 +4363,7 @@ async function removeInstallation(targetRoot, faultInjector, capabilityIds) {
       journalVersion: manifest.journalVersion,
       lifecycleState: "modified",
       packageIdentities,
-      entries: entries2
+      entries
     };
     return {
       ...manifest,
@@ -11762,8 +11774,8 @@ async function assertNoSymlinks(current) {
 async function treeDigest(root) {
   const hash = createHash3("sha256");
   async function visit(current, relative5 = "") {
-    const entries2 = await readdir2(current, { withFileTypes: true });
-    for (const entry of entries2.sort((left, right) => left.name.localeCompare(right.name))) {
+    const entries = await readdir2(current, { withFileTypes: true });
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
       if ([".git", "node_modules", ".turbo"].includes(entry.name)) continue;
       const path9 = join4(current, entry.name);
       const child = relative5 ? `${relative5}/${entry.name}` : entry.name;
@@ -12051,10 +12063,81 @@ import { parse } from "yaml";
 import { parseDocument } from "yaml";
 
 // packages/compiler/src/evidence/runtime-claims.ts
+function parseVersion(value) {
+  const match = value.match(/(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/u);
+  if (!match) return void 0;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split(".").map((part) => /^\d+$/u.test(part) ? Number(part) : part) : []
+  };
+}
+function compareVersions(left, right) {
+  for (const key of ["major", "minor", "patch"]) {
+    if (left[key] !== right[key]) return left[key] > right[key] ? 1 : -1;
+  }
+  if (left.prerelease.length === 0 && right.prerelease.length === 0) return 0;
+  if (left.prerelease.length === 0) return 1;
+  if (right.prerelease.length === 0) return -1;
+  for (let index = 0; index < Math.max(left.prerelease.length, right.prerelease.length); index += 1) {
+    const leftPart = left.prerelease[index];
+    const rightPart = right.prerelease[index];
+    if (leftPart === void 0) return -1;
+    if (rightPart === void 0) return 1;
+    if (leftPart === rightPart) continue;
+    if (typeof leftPart === "number" && typeof rightPart === "string") return -1;
+    if (typeof leftPart === "string" && typeof rightPart === "number") return 1;
+    return leftPart > rightPart ? 1 : -1;
+  }
+  return 0;
+}
+function caretUpperBound(version) {
+  if (version.major > 0) return { major: version.major + 1, minor: 0, patch: 0, prerelease: [] };
+  if (version.minor > 0) return { major: 0, minor: version.minor + 1, patch: 0, prerelease: [] };
+  return { major: 0, minor: 0, patch: version.patch + 1, prerelease: [] };
+}
+function tildeUpperBound(version) {
+  return { major: version.major, minor: version.minor + 1, patch: 0, prerelease: [] };
+}
+function matchesConstraint(actual, operator, expected) {
+  if (actual.prerelease.length > 0 && expected.prerelease.length === 0) return false;
+  const comparison = compareVersions(actual, expected);
+  switch (operator ?? "=") {
+    case ">=":
+      return comparison >= 0;
+    case "<=":
+      return comparison <= 0;
+    case ">":
+      return comparison > 0;
+    case "<":
+      return comparison < 0;
+    case "^":
+      return comparison >= 0 && compareVersions(actual, caretUpperBound(expected)) < 0;
+    case "~":
+      return comparison >= 0 && compareVersions(actual, tildeUpperBound(expected)) < 0;
+    default:
+      return comparison === 0;
+  }
+}
+function isRuntimeVersionInRange(range, runtimeVersion) {
+  const normalizedRange = range.trim();
+  if (normalizedRange === "*") return true;
+  const actual = parseVersion(runtimeVersion);
+  if (!actual) return false;
+  const expression = normalizedRange.includes(";") ? normalizedRange.slice(normalizedRange.lastIndexOf(";") + 1).trim() : normalizedRange;
+  const constraints = expression.split(/\s+/u).map((token) => {
+    const match = token.match(/^(>=|<=|>|<|=|\^|~)?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/u);
+    if (!match || !match[2]) return void 0;
+    const version = parseVersion(match[2]);
+    return version ? { operator: match[1], version } : void 0;
+  });
+  return constraints.length > 0 && constraints.every(
+    (constraint) => constraint?.version && matchesConstraint(actual, constraint.operator, constraint.version)
+  );
+}
 function resolveRuntimeEvidence(claim4, runtimeVersion) {
-  const rangeMajor = claim4.versionRange.match(/\d+/)?.[0];
-  const runtimeMajor = runtimeVersion.match(/^\d+/)?.[0];
-  const applicable = claim4.versionRange === "*" || rangeMajor !== void 0 && rangeMajor === runtimeMajor;
+  const applicable = isRuntimeVersionInRange(claim4.versionRange, runtimeVersion);
   const sufficientState = ["documented", "source-observed", "runtime-observed"].includes(
     claim4.state
   );
@@ -12072,85 +12155,26 @@ function resolveRuntimeEvidence(claim4, runtimeVersion) {
 }
 
 // packages/compiler/src/negotiation/adapter-registry.ts
-var entries = [
-  {
-    id: "materialize-markdown",
-    operationKinds: ["MaterializeArtifact"],
-    purityClass: "pure",
-    effectClass: "filesystem",
-    requiredEvidenceCategories: ["location", "discovery"]
-  },
-  {
-    id: "patch-structured-config",
-    operationKinds: ["PatchStructuredConfig"],
-    purityClass: "planned-effect",
-    effectClass: "configuration",
-    requiredEvidenceCategories: ["configuration"]
-  },
-  {
-    id: "pi-extension-registration",
-    operationKinds: ["InstallExtension"],
-    purityClass: "planned-effect",
-    effectClass: "registration",
-    requiredEvidenceCategories: ["configuration"]
-  },
-  {
-    id: "oh-my-pi-code-as-hooks",
-    operationKinds: ["InstallExtension"],
-    purityClass: "planned-effect",
-    effectClass: "registration",
-    requiredEvidenceCategories: ["hooks", "configuration"]
-  },
-  {
-    id: "antigravity-plugin-registration",
-    operationKinds: ["RegisterPlugin"],
-    purityClass: "planned-effect",
-    effectClass: "registration",
-    requiredEvidenceCategories: ["plugin", "location"]
-  },
-  {
-    id: "antigravity-hook-registration",
-    operationKinds: ["RegisterHook"],
-    purityClass: "planned-effect",
-    effectClass: "registration",
-    requiredEvidenceCategories: ["hooks", "location"]
-  },
-  {
-    id: "antigravity-mcp-registration",
-    operationKinds: ["RegisterMcpServer"],
-    purityClass: "planned-effect",
-    effectClass: "registration",
-    requiredEvidenceCategories: ["mcp", "location"]
-  },
-  {
-    id: "opencode-custom-tool",
-    operationKinds: ["InstallExtension"],
-    purityClass: "planned-effect",
-    effectClass: "registration",
-    requiredEvidenceCategories: ["location", "discovery"]
-  },
-  {
-    id: "opencode-plugin",
-    operationKinds: ["RegisterPlugin"],
-    purityClass: "planned-effect",
-    effectClass: "registration",
-    requiredEvidenceCategories: ["plugin", "discovery"]
-  }
-];
-var adapterRegistry = new Map(
-  entries.map((x) => [x.id, x])
-);
+var adapterIds = Object.freeze([
+  "materialize-markdown",
+  "patch-structured-config",
+  "pi-extension-registration",
+  "oh-my-pi-code-as-hooks",
+  "antigravity-plugin-registration",
+  "antigravity-hook-registration",
+  "antigravity-mcp-registration",
+  "opencode-custom-tool",
+  "opencode-plugin"
+]);
 function requireAdapter(id) {
-  const item = adapterRegistry.get(id);
-  if (!item) throw new Error(`Unknown adapter ID: ${id}`);
-  return item;
+  if (!adapterIds.includes(id)) throw new Error(`Unknown adapter ID: ${id}`);
 }
 
 // packages/compiler/src/negotiation/negotiate-capability.ts
 function negotiateCapability(artifact, descriptor, claims, version) {
   return artifact.invocationIntents.map((intent) => {
     const surface = descriptor.surfaces.find(
-      (x) => x.semanticKind === intent && x.evidenceClaimIds.some((claimId) => {
+      (x) => x.semanticKind === intent && (x.versionRange === void 0 || isRuntimeVersionInRange(x.versionRange, version)) && x.evidenceClaimIds.some((claimId) => {
         const claim4 = claims.find((candidate) => candidate.id === claimId);
         return claim4 !== void 0 && resolveRuntimeEvidence(claim4, version).reason !== "version-inapplicable";
       })
@@ -12206,8 +12230,8 @@ var operationalSectionNames = Object.freeze([
 ]);
 function validateOperationalSkillContract(contract) {
   for (const section of operationalSectionNames) {
-    const entries2 = contract[section];
-    if (!Array.isArray(entries2) || entries2.length === 0 || entries2.some((entry) => !entry.trim())) {
+    const entries = contract[section];
+    if (!Array.isArray(entries) || entries.length === 0 || entries.some((entry) => !entry.trim())) {
       throw new Error(`Missing operational section: ${section}`);
     }
   }
@@ -12227,13 +12251,26 @@ var headings = {
 function renderOperationalSkillContract(contract) {
   validateOperationalSkillContract(contract);
   return operationalSectionNames.map((section) => {
-    const entries2 = contract[section].map((entry, index) => `${index + 1}. ${entry}`).join("\n");
+    const entries = contract[section].map((entry, index) => `${index + 1}. ${entry}`).join("\n");
     return `## ${headings[section]}
 
-${entries2}`;
+${entries}`;
   }).join("\n\n");
 }
 
+// packages/contracts/src/skill-document.ts
+function renderSkillDocument(input) {
+  const description = input.description.replace(/[\r\n\t]+/gu, " ").replace(/\s{2,}/gu, " ").trim();
+  if (!description) throw new Error(`Skill ${input.name} requires a non-empty description`);
+  return `---
+name: ${JSON.stringify(input.name)}
+description: ${JSON.stringify(description)}
+---
+${input.marker}
+${input.content}
+`;
+}
+
 // packages/contracts/src/structured-config.ts
 import { existsSync, readFileSync as readFileSync4 } from "node:fs";
 import { parse as parse2, stringify } from "yaml";
@@ -12266,6 +12303,7 @@ function planProjection(artifact, runtimeId, scope, negotiations) {
         id: `materialize:${n4.intent}`,
         artifactId: artifact.id,
         logicalDestination: `${n4.intent}/${artifact.id}`,
+        description: artifact.title,
         content: artifact.operationalContract ? renderOperationalSkillContract(artifact.operationalContract) : artifact.title
       });
       for (const resource2 of artifact.resourceFiles ?? [])
@@ -12301,14 +12339,14 @@ function planProjection(artifact, runtimeId, scope, negotiations) {
 
 // packages/compiler/src/planning/plan-installation.ts
 import { createHash as createHash6 } from "node:crypto";
-function planInstallation(plan, descriptor) {
+function planInstallation(plan, descriptor, runtimeVersion) {
   const operations = [];
   for (const op of plan.operations) {
     if (op.kind === "MaterializeArtifact") {
       const location = descriptor.locations.find(
-        (x) => x.scope === plan.scope && (x.artifactKind === "skill" || x.artifactKind === op.logicalDestination.split("/")[0])
+        (x) => x.scope === plan.scope && (x.artifactKind === "skill" || x.artifactKind === op.logicalDestination.split("/")[0]) && (!x.versionRange || isRuntimeVersionInRange(x.versionRange, runtimeVersion))
       );
-      if (!location || !location.pathTemplate || location.installation === "manual") {
+      if (!location?.pathTemplate || location.installation === "manual") {
         operations.push({
           kind: "EmitManualStep",
           id: `manual:${op.id}`,
@@ -12336,14 +12374,15 @@ function planInstallation(plan, descriptor) {
         uninstall: "remove-owned-only",
         ownershipIntent: "own",
         destination: `${location.pathTemplate}/${op.logicalDestination}`,
+        description: op.description,
         content: op.content
       });
     }
     if (op.kind === "IncludeResource") {
       const location = descriptor.locations.find(
-        (candidate) => candidate.scope === plan.scope && candidate.artifactKind === "skill"
+        (candidate) => candidate.scope === plan.scope && candidate.artifactKind === "skill" && (!candidate.versionRange || isRuntimeVersionInRange(candidate.versionRange, runtimeVersion))
       );
-      if (!location || !location.pathTemplate || location.installation === "manual") {
+      if (!location?.pathTemplate || location.installation === "manual") {
         operations.push({
           kind: "EmitManualStep",
           id: `manual:${op.id}`,
@@ -12415,7 +12454,7 @@ function planSetup(request, artifact, descriptor, claims, ownershipManifest) {
     request.runtimeVersion
   );
   const projectionPlan = planProjection(artifact, descriptor.id, request.scope, negotiations);
-  const baseInstallationPlan = planInstallation(projectionPlan, descriptor);
+  const baseInstallationPlan = planInstallation(projectionPlan, descriptor, request.runtimeVersion);
   const mutatingIntent = request.intent === "setup" || request.intent === "update";
   let installationPlan = mutatingIntent ? baseInstallationPlan : { ...baseInstallationPlan, operations: [] };
   if (request.intent === "remove") {
@@ -12486,7 +12525,7 @@ function planSetup(request, artifact, descriptor, claims, ownershipManifest) {
     approvals: request.approvalPolicy === "preapproved" ? [] : approvals,
     manualSteps: installationPlan.operations.filter((operation) => operation.kind === "EmitManualStep").map((operation) => operation.id),
     verificationExpectations: projectionPlan.operations.filter((operation) => operation.kind === "ExpectVerification").map((operation) => operation.expectation),
-    nativeUsageInputs: negotiations.filter((outcome) => outcome.surfaceId).map((outcome) => outcome.surfaceId)
+    nativeUsageInputs: negotiations.flatMap(({ surfaceId }) => surfaceId ? [surfaceId] : [])
   };
 }
 
@@ -12601,9 +12640,9 @@ async function resolveVerifiedCapabilityEntrypoint(options) {
 }
 
 // packages/cli/src/release.ts
-var cliVersion = true ? "0.1.8" : createRequire(import.meta.url)("../../../package.json").version;
+var cliVersion = true ? "0.1.10" : createRequire(import.meta.url)("../../../package.json").version;
 
-// packages/adapters/antigravity/src/materialize.ts
+// packages/adapters/src/antigravity/materialize.ts
 import { resolve as resolve4 } from "node:path";
 var marker = "<!-- portable-capabilities:owned antigravity -->";
 function destination(value) {
@@ -12634,15 +12673,15 @@ function diagnostic(operation, kind, message) {
 }
 function render(operation) {
   const skill = operation.destination.match(/skills\/skill\/([^/]+)$/);
-  if (!skill) return `${marker}
+  const name = skill?.[1];
+  if (!name) return `${marker}
 ${operation.content}`;
-  return `---
-name: ${skill[1]}
-description: ${operation.content.replace(/[\r\n]+/g, " ").trim()}
----
-${marker}
-${operation.content}
-`;
+  return renderSkillDocument({
+    name,
+    description: operation.description,
+    marker,
+    content: operation.content
+  });
 }
 function registration(operation) {
   return `${JSON.stringify({ adapterId: operation.adapterId, kind: operation.kind, target: operation.target }, null, 2)}
@@ -12751,7 +12790,7 @@ function prepareAntigravityMaterialization(plan, root) {
   });
 }
 
-// packages/adapters/antigravity/src/runtime-descriptor.ts
+// packages/adapters/src/antigravity/runtime-descriptor.ts
 var markdown = "materialize-markdown";
 var plugin = "antigravity-plugin-registration";
 var hook = "antigravity-hook-registration";
@@ -12944,7 +12983,7 @@ var antigravityRuntimeDescriptor = {
   ]
 };
 
-// packages/adapters/antigravity/src/runtime-evidence.ts
+// packages/adapters/src/antigravity/runtime-evidence.ts
 import { createHash as createHash9 } from "node:crypto";
 var digest2 = (value) => createHash9("sha256").update(value).digest("hex");
 var retrievedAt = "2026-08-10T00:00:00.000Z";
@@ -13092,7 +13131,7 @@ var antigravityRuntimeEvidence = [
   )
 ];
 
-// packages/adapters/claude-code/src/materialize.ts
+// packages/adapters/src/claude-code/materialize.ts
 import { resolve as resolve5 } from "node:path";
 var marker2 = "<!-- portable-capabilities:owned claude-code -->";
 function destination2(value) {
@@ -13127,15 +13166,15 @@ function diagnostic2(operation, kind, message) {
 }
 function render2(operation) {
   const skill = operation.destination.match(/skills\/skill\/([^/]+)$/);
-  if (!skill) return `${marker2}
+  const name = skill?.[1];
+  if (!name) return `${marker2}
 ${operation.content}`;
-  return `---
-name: ${skill[1]}
-description: ${operation.content.replace(/[\r\n]+/g, " ").trim()}
----
-${marker2}
-${operation.content}
-`;
+  return renderSkillDocument({
+    name,
+    description: operation.description,
+    marker: marker2,
+    content: operation.content
+  });
 }
 function config(operation, root, path9) {
   if (operation.format !== "json")
@@ -13249,7 +13288,7 @@ function prepareClaudeCodeMaterialization(plan, root) {
   });
 }
 
-// packages/adapters/claude-code/src/runtime-descriptor.ts
+// packages/adapters/src/claude-code/runtime-descriptor.ts
 var markdown2 = "materialize-markdown";
 var claudeCodeRuntimeDescriptor = {
   schemaVersion: "1.0",
@@ -13451,7 +13490,7 @@ var claudeCodeRuntimeDescriptor = {
   ]
 };
 
-// packages/adapters/claude-code/src/runtime-evidence.ts
+// packages/adapters/src/claude-code/runtime-evidence.ts
 import { createHash as createHash10 } from "node:crypto";
 var digest3 = (value) => createHash10("sha256").update(value).digest("hex");
 var retrievedAt2 = "2026-08-10T00:00:00.000Z";
@@ -13622,18 +13661,20 @@ var claudeCodeRuntimeEvidence = Object.freeze([
   }))
 ]);
 
-// packages/adapters/codex/src/materialize.ts
+// packages/adapters/src/codex/materialize.ts
 import { resolve as resolve6 } from "node:path";
 var marker3 = "<!-- portable-capabilities:owned codex -->";
 function destination3(value) {
   const project = value.match(/^\.codex\/skills\/skill\/(.+)$/);
   if (project) return `.codex/skills/${project[1]}/SKILL.md`;
+  const currentProject = value.match(/^\.agents\/skills\/skill\/(.+)$/);
+  if (currentProject) return `.agents/skills/${currentProject[1]}/SKILL.md`;
   const user = value.match(/^\$CODEX_HOME\/skills\/skill\/(.+)$/);
   if (user) return `.codex-user/skills/${user[1]}/SKILL.md`;
   return value.replace(/^\$CODEX_HOME\//, ".codex-user/");
 }
 function resourceDestination3(value) {
-  return value.replace(/^\.codex\/skills\/skill\//u, ".codex/skills/").replace(/^\$CODEX_HOME\/skills\/skill\//u, ".codex-user/skills/");
+  return value.replace(/^\.codex\/skills\/skill\//u, ".codex/skills/").replace(/^\.agents\/skills\/skill\//u, ".agents/skills/").replace(/^\$CODEX_HOME\/skills\/skill\//u, ".codex-user/skills/");
 }
 function confined3(root, path9) {
   const target = resolve6(root, path9);
@@ -13643,15 +13684,15 @@ function confined3(root, path9) {
 }
 function render3(operation) {
   const skill = operation.destination.match(/skills\/skill\/([^/]+)$/);
-  if (!skill) return `${marker3}
+  const name = skill?.[1];
+  if (!name) return `${marker3}
 ${operation.content}`;
-  return `---
-name: ${skill[1]}
-description: ${operation.content.replace(/[\r\n]+/g, " ").trim()}
----
-${marker3}
-${operation.content}
-`;
+  return renderSkillDocument({
+    name,
+    description: operation.description,
+    marker: marker3,
+    content: operation.content
+  });
 }
 function transform(operation) {
   if (operation.format !== "json")
@@ -13715,25 +13756,48 @@ function prepareCodexMaterialization(plan, root, ..._options) {
   });
 }
 
-// packages/adapters/codex/src/runtime-descriptor.ts
+// packages/adapters/src/codex/runtime-descriptor.ts
 var codexRuntimeDescriptor = {
   schemaVersion: "1.0",
   id: "codex",
   aliases: ["codex-cli"],
-  supportedVersions: [">=0.146.0"],
+  supportedVersions: ["=0.146.0", ">=0.147.0 <0.148.0"],
   locations: [
     {
-      id: "codex-project-skills",
+      id: "codex-project-skills-0146",
       artifactKind: "skill",
       scope: "project",
       pathTemplate: ".codex/skills",
       evidenceClaimIds: ["codex.location.project-skills"],
+      versionRange: "=0.146.0",
+      installation: "automatic",
+      registration: "discovery",
+      uninstall: "automatic"
+    },
+    {
+      id: "codex-project-skills-0147",
+      artifactKind: "skill",
+      scope: "project",
+      pathTemplate: ".agents/skills",
+      evidenceClaimIds: ["codex.location.project-skills-agents"],
+      versionRange: ">=0.147.0 <0.148.0",
       installation: "automatic",
       registration: "discovery",
       uninstall: "automatic"
     },
     {
-      id: "codex-user-skills",
+      id: "codex-user-skills-0147",
+      artifactKind: "skill",
+      scope: "user",
+      pathTemplate: ".agents/skills",
+      evidenceClaimIds: ["codex.location.user-skills-agents"],
+      versionRange: ">=0.147.0 <0.148.0",
+      installation: "automatic",
+      registration: "discovery",
+      uninstall: "automatic"
+    },
+    {
+      id: "codex-user-skills-0146",
       artifactKind: "skill",
       scope: "user",
       pathTemplate: "$CODEX_HOME/skills",
@@ -13746,16 +13810,30 @@ var codexRuntimeDescriptor = {
   ],
   surfaces: [
     {
-      id: "codex-direct-skill",
+      id: "codex-direct-skill-0146",
       semanticKind: "skill",
       integrationMode: "declarative",
       adapterId: "materialize-markdown",
-      discovery: "Codex discovers project and user skills from its native skills roots.",
-      invocation: "Invoke the installed skill through Codex's native skill mechanism.",
+      discovery: "Codex 0.146.x discovers project skills from .codex/skills.",
+      invocation: "Invoke the installed skill through Codex 0.146.x native skill selection.",
       precedence: ["project", "user"],
       evidenceClaimIds: ["codex.discovery.skills", "codex.invocation.skills"],
-      stability: "stable",
+      versionRange: "=0.146.0",
+      stability: "version-gated",
       evidenceState: "runtime-observed"
+    },
+    {
+      id: "codex-direct-skill-0147",
+      semanticKind: "skill",
+      integrationMode: "declarative",
+      adapterId: "materialize-markdown",
+      discovery: "Codex 0.147.x discovers project skills from .agents/skills.",
+      invocation: "Invoke the installed skill through Codex 0.147.x native skill selection.",
+      precedence: ["project", "user"],
+      evidenceClaimIds: ["codex.discovery.skills-0147", "codex.invocation.skills-0147"],
+      versionRange: ">=0.147.0 <0.148.0",
+      stability: "version-gated",
+      evidenceState: "source-observed"
     }
   ],
   configuration: [],
@@ -13765,10 +13843,37 @@ var codexRuntimeDescriptor = {
   degradation: []
 };
 
-// packages/adapters/codex/src/runtime-evidence.ts
+// packages/adapters/src/codex/runtime-evidence.ts
 import { createHash as createHash11 } from "node:crypto";
 var digest4 = (value) => createHash11("sha256").update(value).digest("hex");
 var observedAt = "2026-08-08T00:00:00.000Z";
+var sourceObservedAt = "2026-08-15T00:00:00.000Z";
+var codexSource = "https://github.com/openai/codex";
+var codexSkillRootsSource = "https://github.com/openai/codex/blob/53f3fa749659498fa24c81da8fde5440fa7bba7f/codex-rs/ext/skills/src/host_roots.rs";
+var codexCurrentRange = ">=0.147.0 <0.148.0";
+var projectSkillRootExcerpt = 'const AGENTS_DIR_NAME: &str = ".agents";\nconst SKILLS_DIR_NAME: &str = "skills";';
+var userSkillRootExcerpt = "home_dir.join(AGENTS_DIR_NAME).join(SKILLS_DIR_NAME), SkillScope::User";
+var discoveryExcerpt = "let agents_skills = directory.join(AGENTS_DIR_NAME).join(SKILLS_DIR_NAME);";
+var invocationExcerpt = 'UserInput::Skill {\n                name: "demo".to_string(),';
+var sourceClaim2 = (id, subject, assertion, sourceLocator, sourceExcerpt) => ({
+  schemaVersion: "1.0",
+  id,
+  runtimeId: "codex",
+  category: id.includes("location") ? "location" : id.includes("discovery") ? "discovery" : "invocation",
+  subject,
+  assertion,
+  versionRange: codexCurrentRange,
+  sourceType: "official-source",
+  source: codexSource,
+  sourceLocator,
+  sourceExcerpt,
+  sourceDigest: digest4(sourceExcerpt),
+  state: "source-observed",
+  confidence: "high",
+  verificationStatus: "verified",
+  stability: "version-gated",
+  verifiedAt: sourceObservedAt
+});
 var codexRuntimeEvidence = Object.freeze([
   {
     schemaVersion: "1.0",
@@ -13776,54 +13881,82 @@ var codexRuntimeEvidence = Object.freeze([
     runtimeId: "codex",
     category: "location",
     subject: "project skill root",
-    assertion: "Codex project skills are materialized beneath .codex/skills.",
-    versionRange: ">=0.146.0",
+    assertion: "Codex 0.146.x project skills are materialized beneath .codex/skills.",
+    versionRange: "=0.146.0",
     sourceType: "runtime-probe",
     source: "codex-cli",
-    sourceLocator: "native vertical tracer",
+    sourceLocator: "packages/conformance/src/tracer/codex-native-evidence.json",
     sourceExcerpt: ".codex/skills",
-    sourceDigest: digest4("codex project skills .codex/skills"),
+    sourceDigest: digest4("codex 0.146 project skills .codex/skills"),
     state: "runtime-observed",
     confidence: "high",
     verificationStatus: "verified",
-    stability: "stable",
+    stability: "version-gated",
     verifiedAt: observedAt
   },
+  sourceClaim2(
+    "codex.location.project-skills-agents",
+    "project skill root",
+    "Codex 0.147.x project skills are discovered beneath .agents/skills.",
+    `${codexSkillRootsSource}#L92-L101`,
+    projectSkillRootExcerpt
+  ),
+  sourceClaim2(
+    "codex.location.user-skills-agents",
+    "user skill root",
+    "Codex 0.147.x user skills are discovered beneath ~/.agents/skills.",
+    `${codexSkillRootsSource}#L107-L119`,
+    userSkillRootExcerpt
+  ),
   {
     schemaVersion: "1.0",
     id: "codex.location.user-skills",
     runtimeId: "codex",
     category: "location",
     subject: "user skill root",
-    assertion: "Codex user skills are materialized beneath CODEX_HOME/skills.",
-    versionRange: ">=0.146.0",
+    assertion: "Codex 0.146.x user skills are materialized beneath CODEX_HOME/skills.",
+    versionRange: "=0.146.0",
     sourceType: "runtime-probe",
     source: "codex-cli",
     sourceLocator: "native vertical tracer",
     sourceExcerpt: "CODEX_HOME/skills",
-    sourceDigest: digest4("codex user skills CODEX_HOME/skills"),
+    sourceDigest: digest4("codex 0.146 user skills CODEX_HOME/skills"),
     state: "runtime-observed",
     confidence: "high",
     verificationStatus: "verified",
-    stability: "stable",
+    stability: "version-gated",
     verifiedAt: observedAt
   },
+  sourceClaim2(
+    "codex.discovery.skills-0147",
+    "native skill discovery",
+    "Codex 0.147.x discovers Agent Skills from .agents/skills.",
+    `${codexSkillRootsSource}#L139-L161`,
+    discoveryExcerpt
+  ),
+  sourceClaim2(
+    "codex.invocation.skills-0147",
+    "native skill invocation",
+    "Codex 0.147.x invokes a discovered Agent Skill through its native skill selection.",
+    "https://github.com/openai/codex/blob/53f3fa749659498fa24c81da8fde5440fa7bba7f/codex-rs/core/tests/suite/skills.rs",
+    invocationExcerpt
+  ),
   {
     schemaVersion: "1.0",
     id: "codex.discovery.skills",
     runtimeId: "codex",
     category: "discovery",
     subject: "native skill discovery",
-    assertion: "Codex natively discovers a skill installed in its project skill root.",
-    versionRange: ">=0.146.0",
+    assertion: "Codex 0.146.x natively discovers a skill installed in its project skill root.",
+    versionRange: "=0.146.0",
     sourceType: "runtime-probe",
     source: "codex-cli",
     sourceLocator: "packages/conformance/src/tracer/codex-native-evidence.json",
-    sourceDigest: digest4("codex native discovery"),
+    sourceDigest: digest4("codex 0.146 native discovery"),
     state: "runtime-observed",
     confidence: "high",
     verificationStatus: "verified",
-    stability: "stable",
+    stability: "version-gated",
     verifiedAt: observedAt
   },
   {
@@ -13832,21 +13965,22 @@ var codexRuntimeEvidence = Object.freeze([
     runtimeId: "codex",
     category: "invocation",
     subject: "native skill invocation",
-    assertion: "Codex can invoke an installed skill through the native client.",
-    versionRange: ">=0.146.0",
+    assertion: "Codex 0.146.x can invoke an installed skill through the native client.",
+    versionRange: "=0.146.0",
     sourceType: "runtime-probe",
     source: "codex-cli",
     sourceLocator: "packages/conformance/src/tracer/codex-native-evidence.json",
-    sourceDigest: digest4("codex native invocation"),
+    sourceDigest: digest4("codex 0.146 native invocation"),
     state: "runtime-observed",
     confidence: "high",
     verificationStatus: "verified",
-    stability: "stable",
+    stability: "version-gated",
     verifiedAt: observedAt
   }
 ]);
 
-// packages/adapters/dcode/src/materialize.ts
+// packages/adapters/src/dcode/materialize.ts
+import { readFile as readFile5 } from "node:fs/promises";
 import { resolve as resolve7 } from "node:path";
 var marker4 = "<!-- portable-capabilities:owned dcode -->";
 function destination4(value) {
@@ -13878,21 +14012,46 @@ function diagnostic3(operation, kind, message) {
 }
 function render4(operation) {
   const skill = operation.destination.match(/skills\/skill\/([^/]+)$/);
-  if (!skill) return `${marker4}
+  const name = skill?.[1];
+  if (!name) return `${marker4}
 ${operation.content}`;
-  return `---
-name: ${skill[1]}
-description: ${operation.content.replace(/[\r\n]+/g, " ").trim()}
----
-${marker4}
-${operation.content}
-`;
+  return renderSkillDocument({
+    name,
+    description: operation.description,
+    marker: marker4,
+    content: operation.content
+  });
 }
 function registration3(operation) {
   return `${JSON.stringify({ adapterId: operation.adapterId, kind: operation.kind, target: operation.target }, null, 2)}
 `;
 }
-function prepareDCodeMaterialization(plan, root) {
+async function mergedInstructions(root, path9, operations, removedIds) {
+  let existing;
+  try {
+    existing = await readFile5(resolve7(root, path9), "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  if (!existing && operations.length === 0) return void 0;
+  const selectedIds = new Set(operations.map((operation) => operation.id));
+  const existingText = existing ?? "";
+  const firstHeading = existingText.search(/^## .+$/mu);
+  const preamble = firstHeading >= 0 ? existingText.slice(0, firstHeading).trim() : existingText.trim();
+  const sections = firstHeading >= 0 ? existingText.slice(firstHeading).split(/(?=^## .+$)/mu) : [];
+  const retained = sections.filter((section) => {
+    const id = section.match(/^## ([^\n]+)/u)?.[1] ?? "";
+    return !selectedIds.has(id) && !removedIds.some((removedId) => id.startsWith(`${removedId}:`));
+  }).map((section) => section.trim());
+  const generated = operations.slice().sort((left, right) => left.id.localeCompare(right.id)).map((operation) => `## ${operation.id}
+
+${operation.content.trim()}`);
+  const sectionsToWrite = [...retained, ...generated];
+  return sectionsToWrite.length > 0 ? `${preamble || marker4}
+${sectionsToWrite.join("\n\n")}
+` : void 0;
+}
+async function prepareDCodeMaterialization(plan, root) {
   if (plan.runtimeId !== "dcode") throw new Error(`DCode adapter cannot prepare ${plan.runtimeId}`);
   const mutations = [];
   const diagnostics = [];
@@ -13994,28 +14153,39 @@ function prepareDCodeMaterialization(plan, root) {
         );
     }
   }
-  if (instructionOperations.length > 0) {
+  const instructionRemovals = plan.operations.filter(
+    (operation) => operation.kind === "RemoveOwnedArtifact" && /^\.deepagents\/skills\/[^/]+\/SKILL\.md$/u.test(destination4(operation.detail))
+  );
+  if (instructionOperations.length > 0 || instructionRemovals.length > 0) {
     const instructionPath = ".deepagents/AGENTS.md";
     confined4(root, instructionPath);
-    const content = instructionOperations.sort((left, right) => left.id.localeCompare(right.id)).map((operation) => `## ${operation.id}
-
-${operation.content.trim()}`).join("\n\n");
-    const first = instructionOperations[0];
-    mutations.push({
-      path: instructionPath,
-      kind: "write",
-      content: `<!-- portable-capabilities:owned dcode -->
-${content}
-`,
-      mode: 420,
-      operationId: "dcode:shared-instructions",
-      sourceProjectionOperationId: first.sourceProjectionOperationId,
-      ownershipIntent: first.ownershipIntent,
-      approval: first.approval,
-      rollback: first.rollback,
-      upgrade: first.upgrade,
-      uninstall: first.uninstall
+    const first = instructionOperations[0] ?? instructionRemovals[0];
+    if (!first) throw new Error("DCode shared instruction operation is missing");
+    const removedIds = instructionRemovals.flatMap((operation) => {
+      const match = operation.detail.match(/^\.deepagents\/skills\/([^/]+)\/SKILL\.md$/u);
+      return match?.[1] ? [match[1]] : [];
     });
+    const content = await mergedInstructions(
+      root,
+      instructionPath,
+      instructionOperations,
+      removedIds
+    );
+    mutations.push(
+      content ? {
+        path: instructionPath,
+        kind: "write",
+        content,
+        mode: 420,
+        operationId: "dcode:shared-instructions",
+        sourceProjectionOperationId: first.sourceProjectionOperationId,
+        ownershipIntent: first.ownershipIntent,
+        approval: first.approval,
+        rollback: first.rollback,
+        upgrade: first.upgrade,
+        uninstall: first.uninstall
+      } : { path: instructionPath, kind: "remove", ...metadata3(first) }
+    );
   }
   return Object.freeze({
     runtimeId: plan.runtimeId,
@@ -14025,7 +14195,7 @@ ${content}
   });
 }
 
-// packages/adapters/dcode/src/runtime-descriptor.ts
+// packages/adapters/src/dcode/runtime-descriptor.ts
 var markdown3 = "materialize-markdown";
 var source2 = "source-observed";
 var dcodeRuntimeDescriptor = {
@@ -14230,7 +14400,7 @@ var dcodeRuntimeDescriptor = {
   ]
 };
 
-// packages/adapters/dcode/src/runtime-evidence.ts
+// packages/adapters/src/dcode/runtime-evidence.ts
 import { createHash as createHash12 } from "node:crypto";
 var digest5 = (value) => createHash12("sha256").update(value).digest("hex");
 var verifiedAt = "2026-08-10T00:00:00.000Z";
@@ -14413,7 +14583,7 @@ var dcodeRuntimeEvidence = Object.freeze([
   })
 ]);
 
-// packages/adapters/oh-my-pi/src/materialize.ts
+// packages/adapters/src/oh-my-pi/materialize.ts
 import { resolve as resolve8 } from "node:path";
 var marker5 = "<!-- portable-capabilities:owned oh-my-pi -->";
 function resolveOhMyPiProfile(input) {
@@ -14471,13 +14641,13 @@ function diagnostic4(operation, kind, message) {
 }
 function render5(operation) {
   const skill = operation.destination.match(/skills\/skill\/([^/]+)$/);
-  return skill ? `---
-name: ${skill[1]}
-description: ${operation.content.replace(/[\r\n]+/g, " ").trim()}
----
-${marker5}
-${operation.content}
-` : `${marker5}
+  const name = skill?.[1];
+  return name ? renderSkillDocument({
+    name,
+    description: operation.description,
+    marker: marker5,
+    content: operation.content
+  }) : `${marker5}
 ${operation.content}`;
 }
 function registration4(operation) {
@@ -14586,7 +14756,7 @@ async function prepareOhMyPiMaterialization(plan, root, profile = { home: root }
   });
 }
 
-// packages/adapters/oh-my-pi/src/runtime-descriptor.ts
+// packages/adapters/src/oh-my-pi/runtime-descriptor.ts
 var markdown4 = "materialize-markdown";
 var hooks = "oh-my-pi-code-as-hooks";
 var config2 = "patch-structured-config";
@@ -14834,7 +15004,7 @@ var ohMyPiRuntimeDescriptor = {
   ]
 };
 
-// packages/adapters/oh-my-pi/src/runtime-evidence.ts
+// packages/adapters/src/oh-my-pi/runtime-evidence.ts
 import { createHash as createHash13 } from "node:crypto";
 var digest6 = (value) => createHash13("sha256").update(value).digest("hex");
 var verifiedAt2 = "2026-08-10T00:00:00.000Z";
@@ -14984,7 +15154,7 @@ var ohMyPiRuntimeEvidence = [
   }
 ];
 
-// packages/adapters/opencode/src/materialize.ts
+// packages/adapters/src/opencode/materialize.ts
 import { resolve as resolve9 } from "node:path";
 var marker6 = "<!-- portable-capabilities:owned opencode -->";
 function destination5(value) {
@@ -15021,15 +15191,15 @@ function diagnostic5(operation, kind, message) {
 }
 function render6(operation) {
   const skill = operation.destination.match(/skills\/skill\/([^/]+)$/);
-  if (!skill) return `${marker6}
+  const name = skill?.[1];
+  if (!name) return `${marker6}
 ${operation.content}`;
-  return `---
-name: ${skill[1]}
-description: ${operation.content.replace(/[\r\n]+/g, " ").trim()}
----
-${marker6}
-${operation.content}
-`;
+  return renderSkillDocument({
+    name,
+    description: operation.description,
+    marker: marker6,
+    content: operation.content
+  });
 }
 function config3(operation, root, path9) {
   if (operation.format !== "json")
@@ -15137,7 +15307,7 @@ async function prepareOpencodeMaterialization(plan, root) {
   });
 }
 
-// packages/adapters/opencode/src/runtime-descriptor.ts
+// packages/adapters/src/opencode/runtime-descriptor.ts
 var native = "opencode.stable";
 var beta = "opencode.v2-beta";
 var opencodeRuntimeDescriptor = {
@@ -15419,7 +15589,7 @@ var opencodeRuntimeDescriptor = {
   ]
 };
 
-// packages/adapters/opencode/src/runtime-evidence.ts
+// packages/adapters/src/opencode/runtime-evidence.ts
 import { createHash as createHash14 } from "node:crypto";
 var retrievedAt3 = "2026-08-10T00:00:00.000Z";
 var docs2 = "docs/RFC/runtime-capability-profiles-revised.md";
@@ -15503,14 +15673,14 @@ var sourceClaims = [
     "discovery",
     "stable skill discovery",
     "OpenCode discovers native project and user skills.",
-    "runtime-observed"
+    "source-observed"
   ],
   [
     "invocation.skills",
     "invocation",
     "stable skill invocation",
     "OpenCode invokes a discovered skill through its native skill tool.",
-    "runtime-observed"
+    "source-observed"
   ],
   [
     "discovery.agents",
@@ -15648,7 +15818,7 @@ var opencodeRuntimeEvidence = Object.freeze([
   ...betaClaims
 ]);
 
-// packages/adapters/pi/src/materialize.ts
+// packages/adapters/src/pi/materialize.ts
 import { resolve as resolve10 } from "node:path";
 var marker7 = "<!-- portable-capabilities:owned pi -->";
 function destination6(value) {
@@ -15669,15 +15839,15 @@ function confined7(root, path9) {
 }
 function render7(operation) {
   const skill = operation.destination.match(/skills\/skill\/([^/]+)$/);
-  if (!skill) return `${marker7}
+  const name = skill?.[1];
+  if (!name) return `${marker7}
 ${operation.content}`;
-  return `---
-name: ${skill[1]}
-description: ${operation.content.replace(/[\r\n]+/g, " ").trim()}
----
-${marker7}
-${operation.content}
-`;
+  return renderSkillDocument({
+    name,
+    description: operation.description,
+    marker: marker7,
+    content: operation.content
+  });
 }
 function transform2(operation) {
   if (operation.format !== "json")
@@ -15741,7 +15911,7 @@ function preparePiMaterialization(plan, root, ..._options) {
   });
 }
 
-// packages/adapters/pi/src/runtime-descriptor.ts
+// packages/adapters/src/pi/runtime-descriptor.ts
 var piRuntimeDescriptor = {
   schemaVersion: "1.0",
   id: "pi",
@@ -15819,7 +15989,7 @@ var piRuntimeDescriptor = {
   ]
 };
 
-// packages/adapters/pi/src/runtime-evidence.ts
+// packages/adapters/src/pi/runtime-evidence.ts
 import { createHash as createHash15 } from "node:crypto";
 var digest8 = (value) => createHash15("sha256").update(value).digest("hex");
 var observedAt2 = "2026-08-08T04:24:00-05:00";
@@ -15885,7 +16055,7 @@ var piRuntimeEvidence = [
     category: "discovery",
     subject: "native skill discovery",
     assertion: "Pi natively discovers a project skill with extensions disabled.",
-    versionRange: ">=0.64.0",
+    versionRange: "=0.64.0",
     sourceType: "runtime-probe",
     source: "pi",
     sourceLocator: "packages/conformance/src/tracer/pi-native-evidence.json",
@@ -15903,7 +16073,7 @@ var piRuntimeEvidence = [
     category: "invocation",
     subject: "native skill invocation",
     assertion: "Pi invokes a discovered project skill with extensions disabled.",
-    versionRange: ">=0.64.0",
+    versionRange: "=0.64.0",
     sourceType: "runtime-probe",
     source: "pi",
     sourceLocator: "packages/conformance/src/tracer/pi-native-evidence.json",
@@ -16027,7 +16197,7 @@ function normalizeSetupRequest(input) {
 // packages/cli/src/setup/service.ts
 import { createHash as createHash16 } from "node:crypto";
 import { existsSync as existsSync2 } from "node:fs";
-import { readdir as readdir4, readFile as readFile5 } from "node:fs/promises";
+import { readdir as readdir4, readFile as readFile6 } from "node:fs/promises";
 import { dirname as dirname5, isAbsolute as isAbsolute3, relative as relative4, resolve as resolve12 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 import { parse as parse3 } from "yaml";
@@ -16089,7 +16259,7 @@ async function loadCanonicalArtifact(catalogRoot, capabilityId) {
   if (!capabilityId || /[\\/]/u.test(capabilityId))
     throw new Error("capability IDs must be single path segments");
   const file = resolve12(catalogRoot, "roles", `${capabilityId}.yaml`);
-  const role = parse3(await readFile5(file, "utf8"));
+  const role = parse3(await readFile6(file, "utf8"));
   if (role.schemaVersion !== "1.0" || role.id !== capabilityId || !role.purpose || !Array.isArray(role.inputs) || !role.output || !role.family || !role.taxonomy || !Array.isArray(role.precedence) || !Array.isArray(role.requiredBehavior) || !Array.isArray(role.forbiddenBehavior) || !Array.isArray(role.evaluation?.criteria)) {
     throw new Error(`Invalid canonical capability: ${file}`);
   }
@@ -16098,7 +16268,7 @@ async function loadCanonicalArtifact(catalogRoot, capabilityId) {
   const schemaRelativePath = relative4(resolve12(catalogRoot), schemaFile);
   if (isAbsolute3(schemaRelativePath) || schemaRelativePath.startsWith(".."))
     throw new Error(`Canonical output schema escapes catalog: ${role.output.schema}`);
-  const schemaContent = await readFile5(schemaFile, "utf8");
+  const schemaContent = await readFile6(schemaFile, "utf8");
   const contract = operationalContract(role);
   const contractContent = `${JSON.stringify(
     { ...role, output: { ...role.output, schema: "resources/output.schema.json" } },
@@ -16182,6 +16352,27 @@ function renderVerifiedUsage(preview, descriptor, claims, runtimeVersion) {
     return verified ? `${descriptor.id}: ${surface.invocation}` : `${descriptor.id}: native usage unavailable; use manual guidance`;
   });
 }
+function composeInstallationPlan(previews, artifacts, runtimeId) {
+  const first = previews[0]?.installationPlan;
+  if (!first) throw new Error("at least one installation plan is required");
+  const operations = previews.flatMap((preview, index) => {
+    const capabilityId = artifacts[index]?.id;
+    if (!capabilityId) throw new Error("installation plan is missing its capability");
+    return preview.installationPlan.operations.map((operation) => ({
+      ...operation,
+      id: `${capabilityId}:${operation.id}`,
+      sourceProjectionOperationId: `${capabilityId}:${operation.sourceProjectionOperationId}`
+    }));
+  });
+  const base = {
+    schemaVersion: first.schemaVersion,
+    id: `installation:${runtimeId}:${artifacts.map((artifact) => artifact.id).join(",")}`,
+    runtimeId,
+    scope: first.scope,
+    operations
+  };
+  return { ...base, digest: stableDigest(base) };
+}
 function defaultCatalogRoot() {
   const moduleDir = dirname5(fileURLToPath4(import.meta.url));
   const packagedCatalog = [resolve12(moduleDir, "catalog"), resolve12(moduleDir, "../catalog")].find(
@@ -16240,30 +16431,41 @@ async function executeSetupSelection(request, artifacts, descriptor, claims, con
     ...context.faultInjector ? { faultInjector: context.faultInjector } : {}
   };
   const runtime = resolveProductionRuntime(executionRequest.runtimeId);
-  const lifecycle = executionRequest.intent === "setup" || executionRequest.intent === "update" ? await executePreparedInstallation({
-    ...lifecycleOptions,
-    preparedOperation: executionRequest.intent === "update" ? "upgrade" : "install",
-    preparedMutations: (await Promise.all(
-      previews.map((preview) => runtime.prepare(preview.installationPlan, targetRoot))
-    )).flatMap((prepared) => prepared.mutations)
-  }) : executionRequest.intent === "remove" ? await removeInstallation(
-    targetRoot,
-    context.faultInjector,
-    executionRequest.capabilityIds
-  ) : await statusInstallation(targetRoot);
+  const lifecycle = executionRequest.intent === "setup" || executionRequest.intent === "update" || executionRequest.intent === "remove" ? await (async () => {
+    const installationPlan = composeInstallationPlan(
+      previews,
+      planningArtifacts,
+      executionRequest.runtimeId
+    );
+    const prepared = await runtime.prepare(installationPlan, targetRoot);
+    if (prepared.runtimeId !== installationPlan.runtimeId || prepared.planId !== installationPlan.id) {
+      throw new Error(`Materializer returned an invalid ${executionRequest.runtimeId} plan`);
+    }
+    const duplicatePath = prepared.mutations.map((mutation) => mutation.path).find((path9, index, paths) => paths.indexOf(path9) !== index);
+    if (duplicatePath)
+      throw new Error(`Selection produced duplicate prepared path: ${duplicatePath}`);
+    return executePreparedInstallation({
+      ...lifecycleOptions,
+      preparedOperation: executionRequest.intent === "update" ? "upgrade" : executionRequest.intent === "remove" ? "remove" : "install",
+      preparedMutations: prepared.mutations,
+      ...prepared.diagnostics ? {
+        preparedDiagnostics: prepared.diagnostics.map(
+          (diagnostic6) => `${diagnostic6.kind}: ${diagnostic6.message}`
+        )
+      } : {}
+    });
+  })() : await statusInstallation(targetRoot);
   return { request, previews, lifecycle };
 }
 async function executeSetupLifecycle(request, artifact, descriptor, claims, context) {
   const result2 = await executeSetupSelection(request, [artifact], descriptor, claims, context);
   const preview = result2.previews[0];
+  if (!preview) throw new Error("at least one capability is required");
   if (!result2.lifecycle)
     throw new Error("approval required; rerun with approvalPolicy=preapproved");
   return { request, preview, lifecycle: result2.lifecycle };
 }
 
-// packages/cli/src/wizard.ts
-import { execFileSync } from "node:child_process";
-
 // node_modules/.pnpm/@clack+core@1.4.3/node_modules/@clack/core/dist/index.mjs
 import { styleText } from "node:util";
 import { stdout, stdin } from "node:process";
@@ -17471,6 +17673,73 @@ ${r2}
   }
 }).prompt();
 
+// packages/cli/src/setup/probe.ts
+import { execFileSync } from "node:child_process";
+var executables = Object.freeze({
+  antigravity: "agy",
+  "claude-code": "claude",
+  codex: "codex",
+  dcode: "dcode",
+  "oh-my-pi": "omp",
+  opencode: "opencode",
+  pi: "pi"
+});
+function resolveRuntimeProbe(runtimeId) {
+  const runtime = resolveProductionRuntime(runtimeId);
+  const canonicalId = runtime.descriptor.id;
+  const executable = executables[canonicalId];
+  if (!executable) throw new Error(`No runtime probe configured for ${canonicalId}`);
+  return {
+    runtimeId: canonicalId,
+    executable,
+    args: ["--version"],
+    supportedVersions: runtime.descriptor.supportedVersions
+  };
+}
+function parseVersion2(output) {
+  return output.match(/\bv?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\b/u)?.[1];
+}
+function defaultRun(probe) {
+  return execFileSync(probe.executable, probe.args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 5e3
+  });
+}
+function probeRuntimeVersion(runtimeId, options = {}) {
+  const probe = resolveRuntimeProbe(runtimeId);
+  let output;
+  try {
+    output = (options.run ?? defaultRun)(probe);
+  } catch (error) {
+    const code = error.code;
+    const unavailable = code === "ENOENT" || code === "EACCES";
+    return {
+      status: unavailable ? "unavailable" : "failed",
+      runtimeId: probe.runtimeId,
+      executable: probe.executable,
+      reason: unavailable ? `${probe.executable} is not installed or is not executable` : error instanceof Error ? error.message : String(error)
+    };
+  }
+  const version = parseVersion2(output);
+  if (!version)
+    return {
+      status: "unknown-version",
+      runtimeId: probe.runtimeId,
+      executable: probe.executable,
+      reason: "version probe returned no parseable semantic version"
+    };
+  if (!probe.supportedVersions.some((range) => isRuntimeVersionInRange(range, version)))
+    return {
+      status: "unsupported-version",
+      runtimeId: probe.runtimeId,
+      executable: probe.executable,
+      version,
+      reason: `version ${version} is outside the supported runtime ranges`
+    };
+  return { status: "detected", runtimeId: probe.runtimeId, executable: probe.executable, version };
+}
+
 // packages/cli/src/wizard.ts
 var supportedRuntimes = [...productionRuntimeRegistry.keys()];
 function unwrap(value) {
@@ -17481,17 +17750,6 @@ function unwrap(value) {
   }
   return value;
 }
-function detectRuntimeVersion(runtime) {
-  try {
-    const output = execFileSync(runtime, ["--version"], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-    return output.match(/\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?/)?.[0] ?? "unknown";
-  } catch {
-    return "unknown";
-  }
-}
 async function runInstallWizard() {
   intro("Portable Capabilities setup");
   try {
@@ -17511,6 +17769,12 @@ async function runInstallWizard() {
         options: supportedRuntimes.map((value) => ({ value, label: value }))
       })
     );
+    const probe = probeRuntimeVersion(runtime);
+    if (probe.status !== "detected" || !probe.version) {
+      log.error(`${runtime}: ${probe.reason ?? probe.status}`);
+      process.exitCode = 4;
+      return;
+    }
     const target = String(
       unwrap(
         await text({
@@ -17528,7 +17792,7 @@ async function runInstallWizard() {
     );
     const request = normalizeSetupRequest({
       runtimeId: runtime,
-      runtimeVersion: detectRuntimeVersion(runtime),
+      runtimeVersion: probe.version,
       scope: "project",
       projectDirectory: target,
       capabilityIds,
@@ -17550,7 +17814,7 @@ async function runInstallWizard() {
       runtimeEntry.claims,
       { sourceRoot: process.cwd(), packageVersion: cliVersion }
     );
-    if (!result2.lifecycle || !result2.lifecycle.ok) {
+    if (!result2.lifecycle?.ok) {
       for (const diagnostic6 of result2.lifecycle?.diagnostics ?? ["Approval required."])
         log.error(diagnostic6);
       process.exitCode = 4;
@@ -17755,11 +18019,13 @@ export {
   normalizeSetupRequest,
   persistInvocation,
   previewSetup,
+  probeRuntimeVersion,
   productionRuntimeRegistry,
   recoverInstallation,
   removeInstallation,
   renderVerifiedUsage,
   resolveProductionRuntime,
+  resolveRuntimeProbe,
   statusInstallation,
   structuredLog,
   upgradePackage,