agentwheel 0.14.3 → 0.14.4

package/dist/index.js

@@ -9,9 +9,9 @@ import {
 } from "./chunk-B3FMBTWC.js";
 
 // src/cli/index.ts
-import { mkdir as mkdir16, rm as rm9, writeFile as writeFile14 } from "fs/promises";
+import { mkdir as mkdir17, rm as rm10, writeFile as writeFile16 } from "fs/promises";
 import { homedir as homedir9 } from "os";
-import { dirname as dirname23, join as join31, resolve as resolve18 } from "path";
+import { dirname as dirname25, join as join38, resolve as resolve18 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { Command } from "commander";
 
@@ -91,8 +91,19 @@ var targetMappingSchema = z2.object({
   enabled: z2.boolean().default(true),
   root: z2.enum(["target", "home"]).optional(),
   formats: z2.array(z2.string().min(1)).optional(),
-  semantic: z2.enum(["openclaw-plugin", "codex-subagent", "copilot-instruction", "copilot-prompt", "copilot-agent"]).optional(),
-  merge: z2.enum(["json-deep", "codex-toml-mcp"]).optional()
+  semantic: z2.enum([
+    "openclaw-plugin",
+    "claude-plugin",
+    "codex-plugin",
+    "hermes-plugin",
+    "copilot-plugin",
+    "codex-subagent",
+    "copilot-instruction",
+    "copilot-prompt",
+    "copilot-agent"
+  ]).optional(),
+  merge: z2.enum(["json-deep", "yaml-deep", "codex-toml-mcp"]).optional(),
+  mode: z2.enum(["managed-block"]).optional()
 });
 var targetRegistrySchema = z2.record(installationTypeSchema, targetMappingSchema);
 var targetRegistryInputSchema = z2.union([
@@ -203,8 +214,8 @@ var claudeAdapter = {
   displayName: "Claude Code",
   targets: {
     instructions: {
-      local: { enabled: true, dest: "CLAUDE.md" },
-      user: { enabled: true, root: "home", dest: ".claude/CLAUDE.md" }
+      local: { enabled: true, dest: "CLAUDE.md", mode: "managed-block" },
+      user: { enabled: true, root: "home", dest: ".claude/CLAUDE.md", mode: "managed-block" }
     },
     rules: {
       local: { enabled: true, dest: ".claude/rules", formats: ["markdown-rule", "claude-markdown-rule"] },
@@ -222,6 +233,10 @@ var claudeAdapter = {
       local: { enabled: true, dest: ".claude/agents" },
       user: { enabled: true, root: "home", dest: ".claude/agents" }
     },
+    plugins: {
+      local: { enabled: true, dest: ".agentwheel/plugins/claude", semantic: "claude-plugin" },
+      user: { enabled: true, root: "home", dest: ".agentwheel/plugins/claude", semantic: "claude-plugin" }
+    },
     mcp: {
       local: { enabled: true, dest: ".mcp.json", merge: "json-deep" }
     },
@@ -242,8 +257,8 @@ var copilotAdapter = {
   displayName: "GitHub Copilot CLI",
   targets: {
     instructions: {
-      local: { enabled: true, dest: ".github/copilot-instructions.md" },
-      user: { enabled: true, root: "home", dest: ".copilot/copilot-instructions.md" }
+      local: { enabled: true, dest: ".github/copilot-instructions.md", mode: "managed-block" },
+      user: { enabled: true, root: "home", dest: ".copilot/copilot-instructions.md", mode: "managed-block" }
     },
     rules: {
       local: { enabled: true, dest: ".github/instructions", formats: ["markdown-rule", "copilot-instruction-rule"], semantic: "copilot-instruction" },
@@ -256,6 +271,9 @@ var copilotAdapter = {
       local: { enabled: true, dest: ".github/skills" },
       user: { enabled: true, root: "home", dest: ".copilot/skills" }
     },
+    plugins: {
+      user: { enabled: true, root: "home", dest: ".agentwheel/plugins/copilot", semantic: "copilot-plugin" }
+    },
     subagents: {
       local: { enabled: true, dest: ".github/agents", semantic: "copilot-agent" },
       user: { enabled: true, root: "home", dest: ".copilot/agents", semantic: "copilot-agent" }
@@ -267,6 +285,10 @@ var copilotAdapter = {
     hooks: {
       local: { enabled: true, dest: ".github/hooks" },
       user: { enabled: true, root: "home", dest: ".copilot/hooks" }
+    },
+    settings: {
+      local: { enabled: true, dest: ".github/settings.json", merge: "json-deep" },
+      user: { enabled: true, root: "home", dest: ".copilot/settings.json", merge: "json-deep" }
     }
   }
 };
@@ -277,17 +299,17 @@ var codexAdapter = {
   displayName: "Codex CLI",
   targets: {
     instructions: {
-      local: { enabled: true, dest: "AGENTS.md" },
-      user: { enabled: true, root: "home", dest: ".codex/AGENTS.md" }
-    },
-    rules: {
-      local: { enabled: true, dest: ".codex/rules", formats: ["codex-command-policy"] },
-      user: { enabled: true, root: "home", dest: ".codex/rules", formats: ["codex-command-policy"] }
+      local: { enabled: true, dest: "AGENTS.md", mode: "managed-block" },
+      user: { enabled: true, root: "home", dest: ".codex/AGENTS.md", mode: "managed-block" }
     },
     skills: {
       local: { enabled: true, dest: ".agents/skills" },
       user: { enabled: true, root: "home", dest: ".agents/skills" }
     },
+    plugins: {
+      local: { enabled: true, dest: ".agentwheel/plugins/codex", semantic: "codex-plugin" },
+      user: { enabled: true, root: "home", dest: ".agentwheel/plugins/codex", semantic: "codex-plugin" }
+    },
     subagents: {
       local: { enabled: true, dest: ".codex/agents", semantic: "codex-subagent" },
       user: { enabled: true, root: "home", dest: ".codex/agents", semantic: "codex-subagent" }
@@ -309,10 +331,21 @@ var hermesAdapter = {
   displayName: "Hermes",
   targets: {
     instructions: {
-      local: { enabled: true, dest: "AGENTS.md" }
+      local: { enabled: true, dest: "AGENTS.md", mode: "managed-block" },
+      // Hermes documents SOUL.md as the user-level instruction surface.
+      user: { enabled: true, root: "home", dest: ".hermes/SOUL.md", mode: "managed-block" }
     },
     skills: {
       user: { enabled: true, root: "home", dest: ".hermes/skills" }
+    },
+    mcp: {
+      user: { enabled: true, root: "home", dest: ".hermes/config.yaml", merge: "yaml-deep" }
+    },
+    settings: {
+      user: { enabled: true, root: "home", dest: ".hermes/config.yaml", merge: "yaml-deep" }
+    },
+    plugins: {
+      user: { enabled: true, root: "home", dest: ".agentwheel/plugins/hermes", semantic: "hermes-plugin" }
     }
   }
 };
@@ -322,10 +355,19 @@ var openClawAdapter = {
   name: "openclaw",
   displayName: "OpenClaw",
   targets: {
+    instructions: {
+      user: { enabled: true, root: "home", dest: ".openclaw/workspace/AGENTS.md", mode: "managed-block" }
+    },
     skills: {
       local: { enabled: true, dest: "skills" },
       user: { enabled: true, root: "home", dest: ".openclaw/skills" }
     },
+    mcp: {
+      user: { enabled: true, root: "home", dest: ".openclaw/openclaw.json", merge: "json-deep" }
+    },
+    settings: {
+      user: { enabled: true, root: "home", dest: ".openclaw/openclaw.json", merge: "json-deep" }
+    },
     plugins: {
       local: { enabled: true, dest: ".openclaw/plugins", formats: ["openclaw-plugin"], semantic: "openclaw-plugin" }
     }
@@ -411,9 +453,9 @@ async function resolveAdapter(options) {
 
 // src/install/apply.ts
 import { execFile as execFile3 } from "child_process";
-import { mkdtemp, rm as rm3, writeFile as writeFile6 } from "fs/promises";
-import { tmpdir as tmpdir2 } from "os";
-import { basename as basename2, join as join4 } from "path";
+import { mkdtemp as mkdtemp2, rm as rm4, writeFile as writeFile8 } from "fs/promises";
+import { tmpdir as tmpdir3 } from "os";
+import { basename as basename3, join as join5 } from "path";
 import { promisify as promisify3 } from "util";
 
 // src/model/graph-lock.ts
@@ -835,6 +877,16 @@ import { resolve as resolve3 } from "path";
 import { z as z4 } from "zod";
 var dependencyRoleSchema = z4.enum(["root", "direct", "transitive", "fragment"]);
 var legacyUnownedWorkspaceOwner = "legacy:unowned";
+var semanticPluginSpecSchema = z4.object({
+  runtime: z4.enum(["openclaw", "claude", "codex", "copilot", "hermes"]),
+  pluginName: z4.string().min(1),
+  marketplaceName: z4.string().min(1).optional(),
+  stateRoot: z4.string().min(1).optional(),
+  installCommands: z4.array(z4.array(z4.string()).min(1)).min(1),
+  uninstallCommands: z4.array(z4.array(z4.string()).min(1)).min(1),
+  enableCommands: z4.array(z4.array(z4.string()).min(1)).optional(),
+  disableCommands: z4.array(z4.array(z4.string()).min(1)).optional()
+});
 var manifestEntryV1Schema = z4.object({
   path: z4.string().min(1),
   artifactType: artifactTypeSchema,
@@ -846,8 +898,10 @@ var manifestEntryV1Schema = z4.object({
   channel: z4.enum(["managed", "overlay", "addition", "override", "ejected"]).default("managed"),
   packageName: z4.string().min(1).optional(),
   semanticCommand: z4.array(z4.string()).optional(),
+  semanticPlugin: semanticPluginSpecSchema.optional(),
   executed: z4.boolean().optional(),
-  mergeStrategy: z4.enum(["json-deep", "codex-toml-mcp"]).optional(),
+  mergeStrategy: z4.enum(["json-deep", "yaml-deep", "codex-toml-mcp"]).optional(),
+  mode: z4.enum(["managed-block"]).optional(),
   composedFrom: z4.array(composedFromEntrySchema).optional()
 });
 var manifestEntrySchema = manifestEntryV1Schema.extend({
@@ -1245,6 +1299,65 @@ function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+// src/install/yaml-merge.ts
+import { mkdir as mkdir6, readFile as readFile7, writeFile as writeFile6 } from "fs/promises";
+import { dirname as dirname7 } from "path";
+import { parse as parse2, stringify } from "yaml";
+async function mergeYamlFile(sourcePath, destPath) {
+  const source = parseYamlValue(await readFile7(sourcePath, "utf8"));
+  const current = await pathExists(destPath) ? parseYamlValue(await readFile7(destPath, "utf8")) : {};
+  const merged = deepMerge2(current, source);
+  await mkdir6(dirname7(destPath), { recursive: true });
+  await writeFile6(destPath, stringify(merged), "utf8");
+}
+function parseYamlValue(content) {
+  return normalizeYamlValue(parse2(content));
+}
+function normalizeYamlValue(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(normalizeYamlValue);
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      out[key] = normalizeYamlValue(child);
+    }
+    return out;
+  }
+  return value === void 0 ? null : String(value);
+}
+function deepMerge2(base, incoming) {
+  if (Array.isArray(base) && Array.isArray(incoming)) {
+    return dedupeArray2([...base, ...incoming]);
+  }
+  if (isRecord3(base) && isRecord3(incoming)) {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(incoming)) {
+      out[key] = key in out ? deepMerge2(out[key], value) : value;
+    }
+    return out;
+  }
+  return incoming;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function dedupeArray2(values) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const value of values) {
+    const key = JSON.stringify(value);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(value);
+  }
+  return out;
+}
+
 // src/install/desired.ts
 function normalizeOwners(owners) {
   const normalized = [...new Set(owners.map((owner) => owner.trim()).filter(Boolean))].sort();
@@ -1254,6 +1367,189 @@ function normalizeOwners(owners) {
   return normalized;
 }
 
+// src/install/instructions-block.ts
+import { createHash as createHash3 } from "crypto";
+import { mkdtemp, readFile as readFile8, realpath, rm as rm3, writeFile as writeFile7 } from "fs/promises";
+import { tmpdir as tmpdir2 } from "os";
+import { basename as basename2, dirname as dirname8, join as join4, relative as relative2 } from "path";
+var managedInstructionBlockMode = "managed-block";
+var managedInstructionBanner = "<!-- agentwheel-managed: edit fragments, not this block -->";
+async function desiredManagedInstructionBlockHash(sourcePath) {
+  const source = await readFile8(sourcePath, "utf8");
+  return hashText(managedBlockBody(source));
+}
+async function readManagedInstructionBlockState(destPath, selector, transport) {
+  if (!await transport.pathExists(destPath)) {
+    return { exists: false, hasBlock: false, drifted: false };
+  }
+  const content = await transport.readFile(destPath);
+  const block = findManagedInstructionBlock(content, selector);
+  if (!block) return { exists: true, hasBlock: false, drifted: false };
+  const hash = hashText(block.body);
+  return {
+    exists: true,
+    hasBlock: true,
+    hash,
+    markerHash: block.markerHash,
+    drifted: hash !== block.markerHash
+  };
+}
+async function writeManagedInstructionBlock(sourcePath, destPath, selector, transport, expectedHash) {
+  const source = await readFile8(sourcePath, "utf8");
+  const desired = renderManagedInstructionBlock(selector, source);
+  const existing = await readOptionalText(destPath, transport);
+  const merged = upsertManagedInstructionBlock(existing ?? "", selector, desired.block, expectedHash);
+  await writeTextWithTransport(destPath, merged, transport);
+  return desired.hash;
+}
+async function removeManagedInstructionBlock(destPath, selector, transport, expectedHash) {
+  if (!await transport.pathExists(destPath)) return;
+  const existing = await transport.readFile(destPath);
+  const updated = removeManagedBlockFromContent(existing, selector, expectedHash);
+  await writeTextWithTransport(destPath, updated, transport);
+}
+async function managedInstructionBlockLanded(destPath, selector, expectedHash, transport) {
+  if (!expectedHash) return false;
+  const state = await readManagedInstructionBlockState(destPath, selector, transport);
+  return state.exists && state.hasBlock && !state.drifted && state.hash === expectedHash;
+}
+async function managedInstructionPhysicalKey(destPath, transport) {
+  if (transport.kind !== "local" || !await transport.pathExists(destPath)) return destPath;
+  return realpath(destPath);
+}
+async function claudeInstructionBridgesAgents(claudePath, agentsPath, transport) {
+  if (!await transport.pathExists(claudePath)) return false;
+  if (await samePhysicalPath(claudePath, agentsPath, transport)) return true;
+  const claudeContent = await transport.readFile(claudePath);
+  return referencesAgentsMd(claudeContent, claudePath, agentsPath);
+}
+function managedInstructionSelector(selector, artifactType, artifactName) {
+  if (!selector) return `${artifactType}/${artifactName}`;
+  const unscoped = selector.split(":").at(-1);
+  return unscoped?.includes("/") ? unscoped : selector;
+}
+function renderManagedInstructionBlock(selector, source) {
+  const body = managedBlockBody(source);
+  const hash = hashText(body);
+  return {
+    block: `<!-- BEGIN openpack:include ${selector} sha256:${hash} -->
+${body}<!-- END openpack:include ${selector} -->
+`,
+    hash
+  };
+}
+function upsertManagedInstructionBlock(content, selector, block, expectedHash) {
+  const existing = findManagedInstructionBlock(content, selector);
+  if (!existing) {
+    if (expectedHash) throw new Error(`Managed instruction block missing for ${selector}`);
+    return appendManagedInstructionBlock(content, block);
+  }
+  assertCleanBlock(existing, selector);
+  if (expectedHash && hashText(existing.body) !== expectedHash) {
+    throw new Error(`Managed instruction block drift detected for ${selector}`);
+  }
+  return `${content.slice(0, existing.start)}${block}${content.slice(existing.end)}`;
+}
+function removeManagedBlockFromContent(content, selector, expectedHash) {
+  const existing = findManagedInstructionBlock(content, selector);
+  if (!existing) return content;
+  assertCleanBlock(existing, selector);
+  if (expectedHash && hashText(existing.body) !== expectedHash) {
+    throw new Error(`Managed instruction block drift detected for ${selector}`);
+  }
+  return `${content.slice(0, existing.start)}${content.slice(existing.end)}`;
+}
+function findManagedInstructionBlock(content, selector) {
+  const beginPattern = new RegExp(`<!-- BEGIN openpack:include ${escapeRegex(selector)} sha256:([a-f0-9]+) -->\\r?\\n?`);
+  const begin = beginPattern.exec(content);
+  if (!begin || begin.index === void 0) return void 0;
+  const markerHash = begin[1];
+  const bodyStart = begin.index + begin[0].length;
+  const endMarker = `<!-- END openpack:include ${selector} -->`;
+  const endIndex = content.indexOf(endMarker, bodyStart);
+  if (endIndex < 0) {
+    return {
+      start: begin.index,
+      end: content.length,
+      body: content.slice(bodyStart),
+      markerHash
+    };
+  }
+  let blockEnd = endIndex + endMarker.length;
+  if (content[blockEnd] === "\r" && content[blockEnd + 1] === "\n") blockEnd += 2;
+  else if (content[blockEnd] === "\n") blockEnd += 1;
+  return {
+    start: begin.index,
+    end: blockEnd,
+    body: content.slice(bodyStart, endIndex),
+    markerHash
+  };
+}
+function managedBlockBody(source) {
+  return `${managedInstructionBanner}
+${ensureTrailingNewline(source)}`;
+}
+function appendManagedInstructionBlock(content, block) {
+  if (content.length === 0) return block;
+  const separator = content.endsWith("\n\n") ? "" : content.endsWith("\n") ? "\n" : "\n\n";
+  return `${content}${separator}${block}`;
+}
+function assertCleanBlock(block, selector) {
+  const actual = hashText(block.body);
+  if (actual !== block.markerHash) {
+    throw new Error(`Managed instruction block drift detected for ${selector}`);
+  }
+}
+function referencesAgentsMd(content, claudePath, agentsPath) {
+  const claudeDir = dirname8(claudePath);
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    const atImport = /^@import\s+(.+)$/i.exec(line);
+    const atPath = /^@(.+AGENTS\.md)$/i.exec(line);
+    const referenced = atImport?.[1] ?? atPath?.[1];
+    if (!referenced) continue;
+    const cleaned = referenced.trim().replace(/^["']|["']$/g, "");
+    if (!/AGENTS\.md$/i.test(cleaned)) continue;
+    const candidate = cleaned.startsWith("/") ? cleaned : join4(claudeDir, cleaned);
+    if (relative2(dirname8(agentsPath), candidate).replaceAll("\\", "/") === "AGENTS.md") return true;
+    if (candidate === agentsPath) return true;
+  }
+  return false;
+}
+async function samePhysicalPath(left, right, transport) {
+  if (transport.kind !== "local") return false;
+  if (!await transport.pathExists(left) || !await transport.pathExists(right)) return false;
+  return await realpath(left) === await realpath(right);
+}
+async function readOptionalText(path, transport) {
+  if (!await transport.pathExists(path)) return void 0;
+  return transport.readFile(path);
+}
+async function writeTextWithTransport(path, content, transport) {
+  if (transport.kind === "local") {
+    await transport.writeFileAtomic(path, content);
+    return;
+  }
+  const tempRoot = await mkdtemp(join4(tmpdir2(), "agentwheel-instructions-"));
+  const localPath = join4(tempRoot, basename2(path) || "instructions.md");
+  try {
+    await writeFile7(localPath, content, "utf8");
+    await transport.atomicCopy(localPath, path, "file");
+  } finally {
+    await rm3(tempRoot, { recursive: true, force: true });
+  }
+}
+function ensureTrailingNewline(content) {
+  return content.endsWith("\n") ? content : `${content}
+`;
+}
+function hashText(content) {
+  return createHash3("sha256").update(content).digest("hex");
+}
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 // src/install/apply.ts
 var execFileAsync3 = promisify3(execFile3);
 async function applyCombinedInstallPlan(plan, options = {}) {
@@ -1264,7 +1560,7 @@ async function recoverPendingApply(targetRoot, adapter, transport = localTranspo
   try {
     const journal = await readApplyJournal(targetRoot, adapter, transport, scope);
     if (!journal) return void 0;
-    if (journal.operations.some((operation) => operation.action === "plugin" || operation.action === "program")) {
+    if (journal.operations.some((operation) => operation.action === "plugin" || operation.action === "program" || operation.semanticPlugin)) {
       throw new Error("Cannot automatically recover a journal containing semantic plugin or programmatic operations");
     }
     const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -1475,7 +1771,7 @@ async function commitJournalState(journal, transport, entries, now) {
     await writeInstallManifest(manifest, transport);
   }
   if (journal.graphLockPath && journal.graphLock) await writeGraphLock(journal.graphLockPath, journal.graphLock);
-  if (journal.graphLockRemovePath) await rm3(journal.graphLockRemovePath, { force: true });
+  if (journal.graphLockRemovePath) await rm4(journal.graphLockRemovePath, { force: true });
   if (journal.workspaceConfigPath && journal.workspaceConfig) await writeJsonAtomic(journal.workspaceConfigPath, journal.workspaceConfig);
   await removeApplyJournal(journal.targetRoot, journal.adapter, transport, {
     installationType: journal.installationType,
@@ -1490,9 +1786,6 @@ async function applyOperation(operation, context) {
       throw new Error(`Invalid plugin operation missing hash: ${operation.relativeDestPath}`);
     }
     if (context.executePlugins) {
-      if (!operation.semanticCommand || operation.semanticCommand.length === 0) {
-        throw new Error(`Invalid plugin operation missing command: ${operation.relativeDestPath}`);
-      }
       await executePluginInstall(operation, transport);
     }
     return manifestEntryForOperation(operation, {
@@ -1527,10 +1820,27 @@ async function applyOperation(operation, context) {
     if (!operation.sourcePath || !operation.desiredHash) {
       throw new Error(`Invalid operation missing source/hash: ${operation.relativeDestPath}`);
     }
+    if (operation.mode === managedInstructionBlockMode) {
+      const selector = managedInstructionSelector(operation.logicalSelector, operation.artifactType, operation.artifactName);
+      const hash2 = await writeManagedInstructionBlock(operation.sourcePath, operation.destPath, selector, transport, operation.manifestHash);
+      if (hash2 !== operation.desiredHash) {
+        throw new Error(`Managed block hash verification failed for ${operation.relativeDestPath}: expected ${operation.desiredHash}, got ${hash2}`);
+      }
+      return manifestEntryForOperation(operation, {
+        now,
+        hash: hash2,
+        sourceHash: operation.desiredHash,
+        graphLockDigest: context.graphLockDigest
+      });
+    }
     if (operation.mergeStrategy === "json-deep") {
       await mergeWithTransport(operation.sourcePath, operation.destPath, transport, mergeJsonFile);
+    } else if (operation.mergeStrategy === "yaml-deep") {
+      await mergeWithTransport(operation.sourcePath, operation.destPath, transport, mergeYamlFile);
     } else if (operation.mergeStrategy === "codex-toml-mcp") {
       await mergeWithTransport(operation.sourcePath, operation.destPath, transport, mergeCodexTomlMcp);
+    } else if (operation.mergeStrategy) {
+      throw new Error(`Merge strategy '${operation.mergeStrategy}' is not implemented by apply.`);
     } else {
       await transport.atomicCopy(operation.sourcePath, operation.destPath, operation.kind);
     }
@@ -1551,7 +1861,7 @@ async function applyOperation(operation, context) {
     }
     return manifestEntryForOperation(operation, {
       now,
-      hash: operation.mergeStrategy && operation.currentHash ? operation.currentHash : operation.desiredHash,
+      hash: (operation.mergeStrategy || operation.mode === managedInstructionBlockMode) && operation.currentHash ? operation.currentHash : operation.desiredHash,
       sourceHash: operation.desiredHash,
       graphLockDigest: context.graphLockDigest
     });
@@ -1568,40 +1878,198 @@ async function applyOperation(operation, context) {
     });
   }
   if (operation.action === "remove") {
-    await transport.rm(operation.destPath);
+    if (operation.semanticPlugin) {
+      if (operation.execute !== false) await executePluginUninstall(operation, transport);
+      return void 0;
+    }
+    if (operation.mode === managedInstructionBlockMode) {
+      const selector = managedInstructionSelector(operation.logicalSelector, operation.artifactType, operation.artifactName);
+      await removeManagedInstructionBlock(operation.destPath, selector, transport, operation.manifestHash);
+    } else {
+      await transport.rm(operation.destPath);
+    }
     return void 0;
   }
   return void 0;
 }
 async function executePluginInstall(operation, transport) {
-  const command = operation.semanticCommand?.[0];
-  const args = operation.semanticCommand?.slice(1) ?? [];
-  if (!command) {
-    throw new Error(`Invalid plugin operation missing command: ${operation.relativeDestPath}`);
-  }
+  const commands = semanticInstallCommands(operation);
+  if (commands.length === 0) throw new Error(`Invalid plugin operation missing command: ${operation.relativeDestPath}`);
   if (!operation.sourcePath) {
     throw new Error(`Invalid plugin operation missing source path: ${operation.relativeDestPath}`);
   }
+  if (operation.semanticPlugin?.stateRoot) {
+    await prepareSemanticPluginState(operation, transport);
+  }
+  await executeSemanticCommands(operation, commands, transport, { stageSource: operation.semanticPlugin?.stateRoot ? false : true });
+}
+async function executePluginUninstall(operation, transport) {
+  const commands = operation.semanticPlugin?.uninstallCommands ?? [];
+  if (commands.length === 0) throw new Error(`Invalid semantic plugin operation missing uninstall command: ${operation.relativeDestPath}`);
+  await executeSemanticCommands(operation, commands, transport);
+  if (operation.semanticPlugin?.stateRoot) {
+    await transport.rm(operation.semanticPlugin.stateRoot);
+  }
+}
+async function prepareSemanticPluginState(operation, transport) {
+  const spec = operation.semanticPlugin;
+  if (!spec?.stateRoot) return;
+  if (!operation.sourcePath) {
+    throw new Error(`Invalid semantic plugin operation missing source path: ${operation.relativeDestPath}`);
+  }
+  if (spec.runtime === "claude") {
+    await prepareClaudeMarketplace(operation, transport);
+    return;
+  }
+  if (spec.runtime === "codex") {
+    await prepareCodexMarketplace(operation, transport);
+    return;
+  }
+  if (spec.runtime === "copilot") {
+    await prepareCopilotPlugin(operation, transport);
+    return;
+  }
+  if (spec.runtime === "hermes") {
+    await prepareHermesGitShim(operation, transport);
+  }
+}
+async function prepareClaudeMarketplace(operation, transport) {
+  const spec = requireSemanticPluginState(operation);
+  const marketplaceName = requireMarketplaceName(operation);
+  const marketplaceRoot = join5(spec.stateRoot, "marketplace");
+  await transport.rm(spec.stateRoot);
+  await transport.atomicCopy(requireSourcePath(operation), join5(marketplaceRoot, "plugins", spec.pluginName), operation.kind);
+  await transport.writeJsonAtomic(join5(marketplaceRoot, ".claude-plugin", "marketplace.json"), {
+    name: marketplaceName,
+    owner: { name: "Agentwheel" },
+    plugins: [
+      {
+        name: spec.pluginName,
+        source: `./plugins/${spec.pluginName}`,
+        description: `Installed by Agentwheel${operation.packageName ? ` from ${operation.packageName}` : ""}`
+      }
+    ]
+  });
+}
+async function prepareCodexMarketplace(operation, transport) {
+  const spec = requireSemanticPluginState(operation);
+  const marketplaceName = requireMarketplaceName(operation);
+  const marketplaceRoot = join5(spec.stateRoot, "marketplace");
+  await transport.rm(spec.stateRoot);
+  await transport.atomicCopy(requireSourcePath(operation), join5(marketplaceRoot, "plugins", spec.pluginName), operation.kind);
+  await transport.writeJsonAtomic(join5(marketplaceRoot, ".agents", "plugins", "marketplace.json"), {
+    name: marketplaceName,
+    interface: {
+      displayName: "Agentwheel"
+    },
+    plugins: [
+      {
+        name: spec.pluginName,
+        source: {
+          source: "local",
+          path: `./plugins/${spec.pluginName}`
+        },
+        policy: {
+          installation: "AVAILABLE",
+          authentication: "ON_INSTALL"
+        },
+        category: "Agentwheel"
+      }
+    ]
+  });
+}
+async function prepareCopilotPlugin(operation, transport) {
+  const spec = requireSemanticPluginState(operation);
+  await transport.rm(spec.stateRoot);
+  await transport.atomicCopy(requireSourcePath(operation), join5(spec.stateRoot, "plugin"), operation.kind);
+}
+async function prepareHermesGitShim(operation, transport) {
+  const spec = requireSemanticPluginState(operation);
+  const repoRoot = join5(spec.stateRoot, "repo");
+  await transport.rm(spec.stateRoot);
+  await transport.atomicCopy(requireSourcePath(operation), repoRoot, operation.kind);
+  if (!transport.execFile) {
+    throw new Error(`Cannot prepare Hermes plugin git shim over ${transport.description}: transport does not support remote commands.`);
+  }
+  await transport.execFile("git", ["init", repoRoot], { cwd: operation.destPath });
+  await transport.execFile("git", ["-C", repoRoot, "add", "-A"], { cwd: operation.destPath });
+  await transport.execFile("git", [
+    "-C",
+    repoRoot,
+    "-c",
+    "user.name=agentwheel",
+    "-c",
+    "user.email=agentwheel@example.invalid",
+    "commit",
+    "-m",
+    `agentwheel plugin ${operation.desiredHash ?? "unknown"}`
+  ], { cwd: operation.destPath });
+}
+function requireSemanticPluginState(operation) {
+  const spec = operation.semanticPlugin;
+  if (!spec?.stateRoot) throw new Error(`Invalid semantic plugin operation missing state root: ${operation.relativeDestPath}`);
+  return spec;
+}
+function requireSourcePath(operation) {
+  if (!operation.sourcePath) throw new Error(`Invalid semantic plugin operation missing source path: ${operation.relativeDestPath}`);
+  return operation.sourcePath;
+}
+function requireMarketplaceName(operation) {
+  const marketplaceName = operation.semanticPlugin?.marketplaceName;
+  if (!marketplaceName) throw new Error(`Invalid semantic plugin operation missing marketplace name: ${operation.relativeDestPath}`);
+  return marketplaceName;
+}
+async function executeSemanticCommands(operation, commands, transport, options = {}) {
   if (transport.kind === "local") {
-    await execFileAsync3(command, args);
+    for (const [command, ...args] of commands) {
+      if (!command) throw new Error(`Invalid semantic plugin command for ${operation.relativeDestPath}`);
+      await execFileAsync3(command, args);
+    }
     return;
   }
   if (!transport.execFile) {
-    throw new Error(`Cannot execute semantic plugin install over ${transport.description}: transport does not support remote commands.`);
+    throw new Error(`Cannot execute semantic plugin command over ${transport.description}: transport does not support remote commands.`);
+  }
+  if (!options.stageSource) {
+    for (const [command, ...args] of commands) {
+      if (!command) throw new Error(`Invalid semantic plugin command for ${operation.relativeDestPath}`);
+      await transport.execFile(command, args, { cwd: operation.destPath });
+    }
+    return;
+  }
+  if (!operation.sourcePath) {
+    throw new Error(`Invalid semantic plugin operation missing source path: ${operation.relativeDestPath}`);
   }
-  const stagingRoot = join4(operation.destPath, ".agentwheel", "plugin-staging", `${process.pid}-${Date.now()}`);
-  const remoteSourcePath = join4(stagingRoot, basename2(operation.sourcePath));
+  const stagingRoot = join5(operation.destPath, ".agentwheel", "plugin-staging", `${process.pid}-${Date.now()}`);
+  const remoteSourcePath = join5(stagingRoot, basename3(operation.sourcePath));
   try {
     await transport.atomicCopy(operation.sourcePath, remoteSourcePath, operation.kind);
-    const remoteArgs = args.map((arg) => arg === operation.sourcePath ? remoteSourcePath : arg);
-    await transport.execFile(command, remoteArgs, { cwd: operation.destPath });
+    for (const [command, ...args] of commands) {
+      if (!command) throw new Error(`Invalid semantic plugin command for ${operation.relativeDestPath}`);
+      const remoteArgs = args.map((arg) => arg === operation.sourcePath ? remoteSourcePath : arg);
+      await transport.execFile(command, remoteArgs, { cwd: operation.destPath });
+    }
   } finally {
     await transport.rm(stagingRoot);
   }
 }
+function semanticInstallCommands(operation) {
+  if (operation.semanticPlugin) return operation.semanticPlugin.installCommands;
+  return operation.semanticCommand ? [operation.semanticCommand] : [];
+}
 async function entryForCompletedOperation(operation, transport, now, graphLockDigest) {
   if (operation.action === "remove") return void 0;
   if (operation.action === "create" || operation.action === "update") {
+    if (operation.mode === managedInstructionBlockMode) {
+      const selector = managedInstructionSelector(operation.logicalSelector, operation.artifactType, operation.artifactName);
+      const state = await readManagedInstructionBlockState(operation.destPath, selector, transport);
+      return manifestEntryForOperation(operation, {
+        now,
+        hash: state.hash ?? requireDesiredHash(operation),
+        sourceHash: requireDesiredHash(operation),
+        graphLockDigest
+      });
+    }
     return manifestEntryForOperation(operation, {
       now,
       hash: await transport.hashPath(operation.destPath),
@@ -1612,7 +2080,7 @@ async function entryForCompletedOperation(operation, transport, now, graphLockDi
   if (operation.action === "skip") {
     return manifestEntryForOperation(operation, {
       now,
-      hash: operation.mergeStrategy && operation.currentHash ? operation.currentHash : requireDesiredHash(operation),
+      hash: (operation.mergeStrategy || operation.mode === managedInstructionBlockMode) && operation.currentHash ? operation.currentHash : requireDesiredHash(operation),
       sourceHash: requireDesiredHash(operation),
       graphLockDigest
     });
@@ -1639,8 +2107,10 @@ function manifestEntryForOperation(operation, values) {
     channel: operation.channel,
     packageName: operation.packageName,
     semanticCommand: operation.semanticCommand,
+    semanticPlugin: operation.semanticPlugin,
     executed: values.executed ?? operation.execute,
     mergeStrategy: operation.mergeStrategy,
+    mode: operation.mode,
     composedFrom: operation.composedFrom,
     graphLockDigest: operation.graphLockDigest ?? values.graphLockDigest
   };
@@ -1656,15 +2126,27 @@ async function assertBaseRevision(plan, transport) {
   }
 }
 function isJournaledMutation(operation) {
+  if (operation.semanticPlugin && (operation.action === "plugin" || operation.action === "remove")) return false;
   return operation.action === "create" || operation.action === "update" || operation.action === "remove";
 }
 function operationNeedsSource(operation) {
   return operation.action === "create" || operation.action === "update";
 }
 async function operationLanded(operation, transport) {
-  if (operation.action === "remove") return !await transport.pathExists(operation.destPath);
+  if (operation.action === "remove") {
+    if (operation.mode === managedInstructionBlockMode) {
+      const selector = managedInstructionSelector(operation.logicalSelector, operation.artifactType, operation.artifactName);
+      const state = await readManagedInstructionBlockState(operation.destPath, selector, transport);
+      return !state.exists || !state.hasBlock;
+    }
+    return !await transport.pathExists(operation.destPath);
+  }
   if (operation.action !== "create" && operation.action !== "update") return false;
   if (!await transport.pathExists(operation.destPath)) return false;
+  if (operation.mode === managedInstructionBlockMode) {
+    const selector = managedInstructionSelector(operation.logicalSelector, operation.artifactType, operation.artifactName);
+    return managedInstructionBlockLanded(operation.destPath, selector, operation.desiredHash, transport);
+  }
   if (operation.mergeStrategy) return true;
   if (!operation.desiredHash) return false;
   return await transport.hashPath(operation.destPath) === operation.desiredHash;
@@ -1684,25 +2166,25 @@ async function mergeWithTransport(sourcePath, destPath, transport, merge) {
     await merge(sourcePath, destPath);
     return;
   }
-  const tempRoot = await mkdtemp(join4(tmpdir2(), "agentwheel-merge-"));
-  const localDest = join4(tempRoot, basename2(destPath) || "merged");
+  const tempRoot = await mkdtemp2(join5(tmpdir3(), "agentwheel-merge-"));
+  const localDest = join5(tempRoot, basename3(destPath) || "merged");
   try {
     if (await transport.pathExists(destPath)) {
-      await writeFile6(localDest, await transport.readFile(destPath), "utf8");
+      await writeFile8(localDest, await transport.readFile(destPath), "utf8");
     }
     await merge(sourcePath, localDest);
     await transport.atomicCopy(localDest, destPath, "file");
   } finally {
-    await rm3(tempRoot, { recursive: true, force: true });
+    await rm4(tempRoot, { recursive: true, force: true });
   }
 }
 
 // src/install/plan.ts
-import { join as join8, relative as relative2 } from "path";
+import { basename as basename7, join as join15, relative as relative3 } from "path";
 
 // src/staging/codex-subagents.ts
-import { mkdir as mkdir6, readFile as readFile7, writeFile as writeFile7 } from "fs/promises";
-import { basename as basename3, dirname as dirname7, join as join5 } from "path";
+import { mkdir as mkdir7, readFile as readFile9, writeFile as writeFile9 } from "fs/promises";
+import { basename as basename4, dirname as dirname9, join as join6 } from "path";
 var requiredCodexAgentFields = ["name", "description", "developer_instructions"];
 async function renderCodexSubagents(artifacts, stageRoot, adapter) {
   if (adapter?.name !== "codex") return artifacts;
@@ -1725,42 +2207,42 @@ async function renderCodexSubagents(artifacts, stageRoot, adapter) {
 async function renderCodexSubagent(artifact, stageRoot) {
   const sourcePath = artifact.stagedPath ?? artifact.sourcePath;
   const agentName = codexAgentName(artifact);
-  const renderedPath = join5(stageRoot, ".agentwheel-rendered", "codex-subagents", `${agentName}.toml`);
+  const renderedPath = join6(stageRoot, ".agentwheel-rendered", "codex-subagents", `${agentName}.toml`);
   const lowerSourcePath = sourcePath.toLowerCase();
   if (artifact.kind === "file" && (artifact.name.toLowerCase().endsWith(".toml") || lowerSourcePath.endsWith(".toml"))) {
-    const content = await readFile7(sourcePath, "utf8");
+    const content = await readFile9(sourcePath, "utf8");
     validateCodexAgentToml(content, sourcePath);
     return {
       ...artifact,
       name: agentName,
-      relativePath: join5("subagents", `${agentName}.toml`),
+      relativePath: join6("subagents", `${agentName}.toml`),
       kind: "file",
       hash: await hashPath(sourcePath)
     };
   }
-  const markdownPath = artifact.kind === "dir" ? join5(sourcePath, "AGENTS.md") : sourcePath;
+  const markdownPath = artifact.kind === "dir" ? join6(sourcePath, "AGENTS.md") : sourcePath;
   if (artifact.kind === "dir" && !await pathExists(markdownPath)) {
     throw new Error(`Codex subagent directory ${artifact.relativePath} must contain AGENTS.md.`);
   }
   if (artifact.kind === "file" && !artifact.name.toLowerCase().endsWith(".md") && !lowerSourcePath.endsWith(".md")) {
     throw new Error(`Codex subagent ${artifact.relativePath} must be a .toml file, .md file, or directory containing AGENTS.md.`);
   }
-  const markdown = await readFile7(markdownPath, "utf8");
+  const markdown = await readFile9(markdownPath, "utf8");
   const toml = markdownToCodexAgentToml(agentName, markdown);
-  await mkdir6(dirname7(renderedPath), { recursive: true });
-  await writeFile7(renderedPath, toml, "utf8");
+  await mkdir7(dirname9(renderedPath), { recursive: true });
+  await writeFile9(renderedPath, toml, "utf8");
   return {
     ...artifact,
     name: agentName,
     sourcePath: renderedPath,
     stagedPath: renderedPath,
-    relativePath: join5("subagents", `${agentName}.toml`),
+    relativePath: join6("subagents", `${agentName}.toml`),
     kind: "file",
     hash: await hashPath(renderedPath)
   };
 }
 function codexAgentName(artifact) {
-  const raw = artifact.kind === "dir" ? artifact.name : basename3(artifact.name);
+  const raw = artifact.kind === "dir" ? artifact.name : basename4(artifact.name);
   return raw.replace(/\.toml$/i, "").replace(/\.md$/i, "");
 }
 function validateCodexAgentToml(content, path) {
@@ -1816,8 +2298,8 @@ function escapeRegExp(value) {
 }
 
 // src/staging/copilot-artifacts.ts
-import { mkdir as mkdir7, readFile as readFile8, writeFile as writeFile8 } from "fs/promises";
-import { basename as basename4, dirname as dirname8, join as join6 } from "path";
+import { mkdir as mkdir8, readFile as readFile10, writeFile as writeFile10 } from "fs/promises";
+import { basename as basename5, dirname as dirname10, join as join7 } from "path";
 async function renderCopilotArtifacts(artifacts, stageRoot, adapter) {
   if (adapter?.name !== "copilot") return artifacts;
   const names = /* @__PURE__ */ new Set();
@@ -1839,29 +2321,29 @@ async function renderCopilotArtifacts(artifacts, stageRoot, adapter) {
 async function renderCopilotSubagent(artifact, stageRoot) {
   const sourcePath = artifact.stagedPath ?? artifact.sourcePath;
   const agentName = copilotAgentName(artifact);
-  const renderedPath = join6(stageRoot, ".agentwheel-rendered", "copilot-subagents", `${agentName}.agent.md`);
-  const markdownPath = artifact.kind === "dir" ? join6(sourcePath, "AGENTS.md") : sourcePath;
+  const renderedPath = join7(stageRoot, ".agentwheel-rendered", "copilot-subagents", `${agentName}.agent.md`);
+  const markdownPath = artifact.kind === "dir" ? join7(sourcePath, "AGENTS.md") : sourcePath;
   if (artifact.kind === "dir" && !await pathExists(markdownPath)) {
     throw new Error(`Copilot subagent directory ${artifact.relativePath} must contain AGENTS.md.`);
   }
   if (artifact.kind === "file" && !artifact.name.toLowerCase().endsWith(".md")) {
     throw new Error(`Copilot subagent ${artifact.relativePath} must be a .md file or directory containing AGENTS.md.`);
   }
-  const markdown = await readFile8(markdownPath, "utf8");
-  await mkdir7(dirname8(renderedPath), { recursive: true });
-  await writeFile8(renderedPath, ensureCopilotAgentDescription(agentName, markdown), "utf8");
+  const markdown = await readFile10(markdownPath, "utf8");
+  await mkdir8(dirname10(renderedPath), { recursive: true });
+  await writeFile10(renderedPath, ensureCopilotAgentDescription(agentName, markdown), "utf8");
   return {
     ...artifact,
     name: `${agentName}.agent.md`,
     sourcePath: renderedPath,
     stagedPath: renderedPath,
-    relativePath: join6("subagents", `${agentName}.agent.md`),
+    relativePath: join7("subagents", `${agentName}.agent.md`),
     kind: "file",
     hash: await hashPath(renderedPath)
   };
 }
 function copilotAgentName(artifact) {
-  const raw = artifact.kind === "dir" ? artifact.name : basename4(artifact.name);
+  const raw = artifact.kind === "dir" ? artifact.name : basename5(artifact.name);
   return raw.replace(/\.agent\.md$/i, "").replace(/\.md$/i, "");
 }
 function ensureCopilotAgentDescription(agentName, markdown) {
@@ -1901,14 +2383,322 @@ function yamlString(value) {
   return JSON.stringify(value);
 }
 
+// src/targets/plugins/claude.ts
+import { join as join9 } from "path";
+
+// src/targets/plugins/common.ts
+import { readFile as readFile11 } from "fs/promises";
+import { join as join8 } from "path";
+import { parseDocument } from "yaml";
+function pluginStateRoot(request) {
+  return join8(
+    request.targetRoot,
+    ".agentwheel",
+    "plugins",
+    request.runtime,
+    request.installationType,
+    safeNameSegment(request.packageName ?? "package"),
+    safeNameSegment(request.installName)
+  );
+}
+function agentwheelMarketplaceName(packageName, pluginName) {
+  return `agentwheel-${safeNameSegment(packageName ?? "package")}-${safeNameSegment(pluginName)}`;
+}
+function safeNameSegment(value) {
+  const normalized = value.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return normalized.length > 0 ? normalized : "unnamed";
+}
+async function jsonPluginName(root, relativeManifestPath, fallback) {
+  const manifestPath = join8(root, relativeManifestPath);
+  if (!await pathExists(manifestPath)) return fallback;
+  const parsed = JSON.parse(await readFile11(manifestPath, "utf8"));
+  return typeof parsed.name === "string" && parsed.name.trim().length > 0 ? parsed.name.trim() : fallback;
+}
+async function yamlPluginName(root, relativeManifestPaths, fallback) {
+  for (const relativeManifestPath of relativeManifestPaths) {
+    const manifestPath = join8(root, relativeManifestPath);
+    if (!await pathExists(manifestPath)) continue;
+    const document = parseDocument(await readFile11(manifestPath, "utf8"));
+    const parsed = document.toJSON();
+    if (!isRecord4(parsed)) continue;
+    for (const key of ["name", "module", "package"]) {
+      const value = parsed[key];
+      if (typeof value === "string" && value.trim().length > 0) return value.trim();
+    }
+    const packageValue = parsed.package;
+    if (isRecord4(packageValue) && typeof packageValue.name === "string" && packageValue.name.trim().length > 0) {
+      return packageValue.name.trim();
+    }
+  }
+  return fallback;
+}
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/targets/plugins/claude.ts
+async function claudePluginSpec(request) {
+  const pluginName = await jsonPluginName(request.sourcePath, ".claude-plugin/plugin.json", request.installName);
+  const marketplaceName = agentwheelMarketplaceName(request.artifact.packageName, pluginName);
+  const stateRoot = pluginStateRoot({
+    targetRoot: request.targetRoot,
+    runtime: "claude",
+    installationType: request.installationType,
+    packageName: request.artifact.packageName,
+    installName: request.installName
+  });
+  const marketplaceRoot = join9(stateRoot, "marketplace");
+  const scope = claudeScope(request.installationType);
+  const selector = `${pluginName}@${marketplaceName}`;
+  return {
+    runtime: "claude",
+    pluginName,
+    marketplaceName,
+    stateRoot,
+    installCommands: [
+      ["claude", "plugin", "marketplace", "add", marketplaceRoot, "--scope", scope],
+      ["claude", "plugin", "install", selector, "--scope", scope]
+    ],
+    uninstallCommands: [
+      ["claude", "plugin", "uninstall", selector, "--scope", scope],
+      ["claude", "plugin", "marketplace", "remove", marketplaceName, "--scope", scope]
+    ]
+  };
+}
+function claudeScope(installationType) {
+  if (installationType === "user" || installationType === "local") return installationType;
+  if (installationType === "project") return "project";
+  throw new Error(`Claude plugins support installation types user, local, or project; got '${installationType}'.`);
+}
+
+// src/targets/plugins/codex.ts
+import { join as join10 } from "path";
+async function codexPluginSpec(request) {
+  const pluginName = await jsonPluginName(request.sourcePath, ".codex-plugin/plugin.json", request.installName);
+  const marketplaceName = agentwheelMarketplaceName(request.artifact.packageName, pluginName);
+  const stateRoot = pluginStateRoot({
+    targetRoot: request.targetRoot,
+    runtime: "codex",
+    installationType: request.installationType,
+    packageName: request.artifact.packageName,
+    installName: request.installName
+  });
+  const marketplaceRoot = join10(stateRoot, "marketplace");
+  const selector = `${pluginName}@${marketplaceName}`;
+  return {
+    runtime: "codex",
+    pluginName,
+    marketplaceName,
+    stateRoot,
+    installCommands: [
+      ["codex", "plugin", "marketplace", "add", marketplaceRoot, "--json"],
+      ["codex", "plugin", "add", selector, "--json"]
+    ],
+    uninstallCommands: [
+      ["codex", "plugin", "remove", selector, "--json"],
+      ["codex", "plugin", "marketplace", "remove", marketplaceName, "--json"]
+    ]
+  };
+}
+
+// src/targets/plugins/copilot.ts
+import { join as join11 } from "path";
+async function copilotPluginSpec(request) {
+  if (request.installationType !== "user") {
+    throw new Error("Copilot plugins are persistent user-level installs only; pass --installation-type user.");
+  }
+  const pluginName = await jsonPluginName(request.sourcePath, "plugin.json", request.installName);
+  const stateRoot = pluginStateRoot({
+    targetRoot: request.targetRoot,
+    runtime: "copilot",
+    installationType: request.installationType,
+    packageName: request.artifact.packageName,
+    installName: request.installName
+  });
+  const pluginRoot = join11(stateRoot, "plugin");
+  return {
+    runtime: "copilot",
+    pluginName,
+    stateRoot,
+    installCommands: [["copilot", "plugin", "install", pluginRoot]],
+    uninstallCommands: [["copilot", "plugin", "uninstall", pluginName]]
+  };
+}
+
+// src/targets/plugins/hermes.ts
+import { join as join12 } from "path";
+async function hermesPluginSpec(request) {
+  if (request.installationType !== "user") {
+    throw new Error("Hermes plugins are user-level installs only; pass --installation-type user.");
+  }
+  const pluginName = await yamlPluginName(request.sourcePath, ["plugin.yaml", "plugin.yml"], request.installName);
+  const stateRoot = pluginStateRoot({
+    targetRoot: request.targetRoot,
+    runtime: "hermes",
+    installationType: request.installationType,
+    packageName: request.artifact.packageName,
+    installName: request.installName
+  });
+  const repoRoot = join12(stateRoot, "repo");
+  return {
+    runtime: "hermes",
+    pluginName,
+    stateRoot,
+    installCommands: [["hermes", "plugins", "install", "--force", "--enable", `file://${repoRoot}`]],
+    uninstallCommands: [["hermes", "plugins", "remove", pluginName]]
+  };
+}
+
 // src/targets/plugins/openclaw.ts
+import { readFile as readFile12 } from "fs/promises";
+import { join as join13 } from "path";
 function openClawPluginInstallCommand(request) {
   return ["openclaw", "plugins", "install", "--force", request.path];
 }
+function openClawPluginUninstallCommand(pluginName) {
+  return ["openclaw", "plugins", "uninstall", pluginName, "--force"];
+}
+async function openClawPluginSpec(request) {
+  const pluginName = await openClawPluginName(request.path, request.fallbackPluginName);
+  return {
+    runtime: "openclaw",
+    pluginName,
+    installCommands: [openClawPluginInstallCommand({ path: request.path, dryRun: true })],
+    uninstallCommands: [openClawPluginUninstallCommand(pluginName)]
+  };
+}
+async function openClawPluginName(root, fallback) {
+  for (const manifestName of ["plugin.json", "openclaw.plugin.json"]) {
+    const manifestPath = join13(root, manifestName);
+    if (!await pathExists(manifestPath)) continue;
+    const parsed = JSON.parse(await readFile12(manifestPath, "utf8"));
+    if (typeof parsed.name === "string" && parsed.name.trim().length > 0) return parsed.name.trim();
+  }
+  return fallback;
+}
+
+// src/targets/plugins/index.ts
+async function semanticPluginSpecForArtifact(request) {
+  if (request.semantic === "openclaw-plugin") {
+    return openClawPluginSpec({
+      path: request.sourcePath,
+      fallbackPluginName: request.installName
+    });
+  }
+  if (request.semantic === "claude-plugin") {
+    return claudePluginSpec(request);
+  }
+  if (request.semantic === "codex-plugin") {
+    return codexPluginSpec(request);
+  }
+  if (request.semantic === "copilot-plugin") {
+    return copilotPluginSpec(request);
+  }
+  if (request.semantic === "hermes-plugin") {
+    return hermesPluginSpec(request);
+  }
+  return void 0;
+}
+
+// src/validation/artifacts.ts
+import { readFile as readFile13 } from "fs/promises";
+import { basename as basename6, join as join14 } from "path";
+import { parseDocument as parseDocument2 } from "yaml";
+
+// src/model/selection.ts
+function artifactSelectorKey(artifact) {
+  return `${artifact.type}/${artifact.name}`;
+}
+function artifactSelectorAliases(artifact) {
+  const primary = artifactSelectorKey(artifact);
+  if (artifact.type !== "subagents") return [primary];
+  const baseName = subagentBaseName(artifact.name);
+  if (baseName === artifact.name) return [primary];
+  return [primary, `subagents/${baseName}`];
+}
+function normalizeArtifactSelectors(select, legacySkills) {
+  const selected = [
+    ...select ?? [],
+    ...(legacySkills ?? []).map((name) => `skills/${name}`)
+  ].flatMap(splitSelectorList);
+  if (selected.length === 0) return void 0;
+  return [...new Set(selected.map(parseArtifactSelector))];
+}
+function filterArtifactsBySelection(artifacts, selectors, legacySkills) {
+  const selected = normalizeArtifactSelectors(selectors, legacySkills);
+  if (!selected?.length) return artifacts;
+  const selectedSet = new Set(selected);
+  const available = new Set(artifacts.flatMap(artifactSelectorAliases));
+  const missing = selected.filter((selector) => !available.has(selector));
+  if (missing.length > 0) {
+    throw new Error(`Selected artifact not found in package: ${missing.join(", ")}`);
+  }
+  return artifacts.filter((artifact) => artifact.required || artifactSelectorAliases(artifact).some((selector) => selectedSet.has(selector)));
+}
+function splitSelectorList(value) {
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function parseArtifactSelector(value) {
+  const slash = value.indexOf("/");
+  if (slash <= 0 || slash === value.length - 1) {
+    throw new Error(`Invalid artifact selector: ${value}. Expected <type>/<name>.`);
+  }
+  const type = value.slice(0, slash);
+  const name = value.slice(slash + 1);
+  const parsedType = artifactTypeSchema.safeParse(type);
+  if (!parsedType.success) {
+    throw new Error(`Invalid artifact selector type: ${type}`);
+  }
+  return `${parsedType.data}/${name}`;
+}
+function subagentBaseName(name) {
+  return name.replace(/\.agent\.md$/i, "").replace(/\.toml$/i, "").replace(/\.md$/i, "");
+}
 
 // src/validation/artifacts.ts
-import { readFile as readFile9 } from "fs/promises";
-import { basename as basename5, join as join7 } from "path";
+var behavioralRuleFormats = ["markdown-rule", "claude-markdown-rule", "copilot-instruction-rule"];
+var pluginFormats = ["claude-plugin", "codex-plugin", "hermes-plugin", "copilot-plugin", "openclaw-plugin"];
+async function filterArtifactsByInstallFormat(artifacts, adapter, installationType, options = {}) {
+  const selectedSet = new Set(normalizeArtifactSelectors(options.selected ?? []) ?? []);
+  const kept = [];
+  const skipped = [];
+  let installableCount = 0;
+  for (const artifact of artifacts) {
+    if (artifact.type === "fragments") {
+      kept.push(artifact);
+      continue;
+    }
+    const target = targetMappingForArtifact(adapter, artifact.type, installationType);
+    if (!target?.enabled) {
+      if (artifact.type === "rules") {
+        skipped.push({
+          artifact,
+          compatibility: {
+            compatible: false,
+            knownIncompatible: true,
+            expected: behavioralRuleFormats,
+            message: "target does not support behavioral Markdown rules"
+          }
+        });
+        continue;
+      }
+      kept.push(artifact);
+      continue;
+    }
+    const compatibility = await artifactFormatCompatibility(artifact, target);
+    if (compatibility.knownIncompatible) {
+      skipped.push({ artifact, compatibility });
+      continue;
+    }
+    kept.push(artifact);
+    installableCount += 1;
+  }
+  if (installableCount === 0 && skipped.length > 0) return artifacts;
+  for (const item of skipped) {
+    options.warn?.(formatSkipWarning(item.artifact, item.compatibility, adapter, installationType, selectedSet));
+  }
+  return kept;
+}
 async function validateArtifactsForInstall(artifacts, adapter, installationType) {
   const issues = [];
   for (const artifact of artifacts) {
@@ -1928,17 +2718,18 @@ async function validateArtifactsForInstall(artifacts, adapter, installationType)
 }
 async function validateArtifact(artifact, target) {
   const issues = [];
-  const format = artifact.format ?? await inferArtifactFormat(artifact, target) ?? semanticDefaultFormat(target);
-  if (target.formats?.length) {
+  const compatibility = await artifactFormatCompatibility(artifact, target);
+  const format = compatibility.format;
+  if (compatibility.expected?.length) {
     if (!format) {
       issues.push({
         artifact,
-        message: `format is unknown; expected one of: ${target.formats.join(", ")}`
+        message: `format is unknown; expected one of: ${compatibility.expected.join(", ")}`
       });
-    } else if (!target.formats.includes(format)) {
+    } else if (!compatibility.compatible) {
       issues.push({
         artifact,
-        message: `format '${format}' is not compatible; expected one of: ${target.formats.join(", ")}`
+        message: compatibility.message ?? `format '${format}' is not compatible; expected one of: ${compatibility.expected.join(", ")}`
       });
     }
   }
@@ -1946,9 +2737,31 @@ async function validateArtifact(artifact, target) {
   issues.push(...await validateGenericStructure(artifact, target));
   return issues;
 }
+async function artifactFormatCompatibility(artifact, target) {
+  const format = artifact.format ?? await inferArtifactFormat(artifact, target) ?? semanticDefaultFormat(artifact, target);
+  const expected = expectedFormats(artifact, target);
+  if (!expected?.length) return { compatible: true, knownIncompatible: false, format };
+  if (!format) return { compatible: false, knownIncompatible: false, expected };
+  if (artifact.type === "rules" && target.formats?.length && target.formats.every((item) => !behavioralRuleFormats.includes(item))) {
+    return {
+      compatible: false,
+      knownIncompatible: true,
+      format,
+      expected,
+      message: `target does not support behavioral Markdown rules; expected one of: ${expected.join(", ")}`
+    };
+  }
+  const compatible = expected.includes(format);
+  return {
+    compatible,
+    knownIncompatible: !compatible,
+    format,
+    expected
+  };
+}
 async function inferArtifactFormat(artifact, target) {
   if (artifact.type === "rules") {
-    if (hasExtension(artifact, ".rules")) return "codex-command-policy";
+    if (artifact.format === "codex-command-policy" || hasExtension(artifact, ".rules")) return "codex-command-policy";
     if (hasExtension(artifact, ".md") || hasExtension(artifact, ".markdown")) return "markdown-rule";
     return void 0;
   }
@@ -1957,26 +2770,51 @@ async function inferArtifactFormat(artifact, target) {
   }
   return void 0;
 }
-function semanticDefaultFormat(target) {
-  if (target.semantic === "openclaw-plugin") return "openclaw-plugin";
+function semanticDefaultFormat(artifact, target) {
+  if (artifact.type === "plugins" && isPluginFormat(target.semantic)) return target.semantic;
   return void 0;
 }
+function expectedFormats(artifact, target) {
+  if (artifact.type === "rules") {
+    const declared = target.formats?.filter((format) => behavioralRuleFormats.includes(format));
+    if (target.formats?.length) return declared?.length ? declared : behavioralRuleFormats;
+    return behavioralRuleFormats;
+  }
+  if (artifact.type === "plugins") {
+    if (isPluginFormat(target.semantic)) return [target.semantic];
+    const declared = target.formats?.filter((format) => pluginFormats.includes(format));
+    if (target.formats?.length) return declared?.length ? declared : pluginFormats;
+  }
+  return target.formats;
+}
 async function validateKnownFormat(artifact, format, target) {
   if (!format) return [];
-  if (format === "codex-command-policy") return validateCodexCommandPolicyRule(artifact);
   if (format === "markdown-rule" || format === "claude-markdown-rule" || format === "copilot-instruction-rule") {
     return validateMarkdownRule(artifact, format);
   }
   if (format === "openclaw-plugin" || target.semantic === "openclaw-plugin") {
     return validateOpenClawPlugin(artifact);
   }
+  if (format === "claude-plugin" || target.semantic === "claude-plugin") {
+    return validateJsonPluginDescriptor(artifact, ".claude-plugin/plugin.json", "Claude");
+  }
+  if (format === "codex-plugin" || target.semantic === "codex-plugin") {
+    return validateJsonPluginDescriptor(artifact, ".codex-plugin/plugin.json", "Codex");
+  }
+  if (format === "copilot-plugin" || target.semantic === "copilot-plugin") {
+    return validateJsonPluginDescriptor(artifact, "plugin.json", "Copilot");
+  }
+  if (format === "hermes-plugin" || target.semantic === "hermes-plugin") {
+    return validateHermesPlugin(artifact);
+  }
+  if (pluginFormats.includes(format)) return validatePluginArtifact(artifact, format);
   return [];
 }
 async function validateGenericStructure(artifact, target) {
   const issues = [];
   if (artifact.type === "skills") {
     if (artifact.kind === "dir") {
-      const skillMd = join7(artifactPath(artifact), "SKILL.md");
+      const skillMd = join14(artifactPath(artifact), "SKILL.md");
       if (!await pathExists(skillMd)) {
         issues.push({ artifact, message: "skill directory must contain SKILL.md" });
       } else {
@@ -1992,6 +2830,10 @@ async function validateGenericStructure(artifact, target) {
     const parsed = await parseJsonObjectArtifact(artifact);
     if (!parsed.ok) issues.push({ artifact, message: parsed.message });
   }
+  if (target.merge === "yaml-deep") {
+    const parsed = await parseYamlObjectArtifact(artifact);
+    if (!parsed.ok) issues.push({ artifact, message: parsed.message });
+  }
   if (target.merge === "codex-toml-mcp") {
     const parsed = await parseJsonObjectArtifact(artifact);
     if (!parsed.ok) {
@@ -2005,7 +2847,7 @@ async function validateGenericStructure(artifact, target) {
 async function validateSkillFrontmatter(artifact, skillMdPath) {
   let content;
   try {
-    content = await readFile9(skillMdPath, "utf8");
+    content = await readFile13(skillMdPath, "utf8");
   } catch (error) {
     return [{ artifact, message: `could not read SKILL.md: ${errorMessage(error)}` }];
   }
@@ -2031,33 +2873,6 @@ async function validateSkillFrontmatter(artifact, skillMdPath) {
   }
   return issues;
 }
-async function validateCodexCommandPolicyRule(artifact) {
-  const issues = [];
-  if (artifact.type !== "rules") {
-    return [{ artifact, message: "codex-command-policy format is only valid for rules artifacts" }];
-  }
-  if (artifact.kind !== "file") {
-    issues.push({ artifact, message: "Codex command-policy rules must be files" });
-  }
-  if (!hasExtension(artifact, ".rules")) {
-    issues.push({ artifact, message: "Codex command-policy rules must use the .rules extension" });
-  }
-  const content = await readUtf8Artifact(artifact, issues);
-  if (content === void 0) return issues;
-  if (!/\bprefix_rule\s*\(/.test(content)) {
-    issues.push({ artifact, message: "Codex command-policy rules must contain at least one prefix_rule(...)" });
-  }
-  if (/\bprefix_rule\s*\(/.test(content) && !/\bpattern\s*=/.test(content)) {
-    issues.push({ artifact, message: "Codex command-policy rules must define a pattern field" });
-  }
-  for (const match of content.matchAll(/\bdecision\s*=\s*["']([^"']+)["']/g)) {
-    const decision = match[1];
-    if (decision !== "allow" && decision !== "prompt" && decision !== "forbidden") {
-      issues.push({ artifact, message: `Codex command-policy decision '${decision}' must be allow, prompt, or forbidden` });
-    }
-  }
-  return issues;
-}
 function validateMarkdownRule(artifact, format) {
   const label = format === "copilot-instruction-rule" ? "Copilot instruction rules" : format === "claude-markdown-rule" ? "Claude markdown rules" : "Markdown rules";
   const issues = [];
@@ -2072,6 +2887,72 @@ function validateMarkdownRule(artifact, format) {
   }
   return issues;
 }
+function validatePluginArtifact(artifact, format) {
+  const issues = [];
+  if (artifact.type !== "plugins") {
+    issues.push({ artifact, message: `${format} format is only valid for plugins artifacts` });
+  }
+  if (artifact.kind !== "dir") {
+    issues.push({ artifact, message: `${format} plugins must be directory artifacts` });
+  }
+  return issues;
+}
+async function validateJsonPluginDescriptor(artifact, relativeManifestPath, label) {
+  const generic = validatePluginArtifact(artifact, `${label.toLowerCase()}-plugin`);
+  if (generic.length > 0) return generic;
+  const manifestPath = join14(artifactPath(artifact), relativeManifestPath);
+  if (!await pathExists(manifestPath)) {
+    return [{ artifact, message: `${label} plugins must contain ${relativeManifestPath}` }];
+  }
+  const parsed = await parseJsonPluginManifest(manifestPath, label);
+  return parsed.ok ? [] : [{ artifact, message: parsed.message }];
+}
+async function validateHermesPlugin(artifact) {
+  const generic = validatePluginArtifact(artifact, "hermes-plugin");
+  if (generic.length > 0) return generic;
+  const root = artifactPath(artifact);
+  const manifestPaths = [join14(root, "plugin.yaml"), join14(root, "plugin.yml")];
+  const manifestPath = await firstExistingPath(manifestPaths);
+  if (!manifestPath) {
+    return [{ artifact, message: "Hermes plugins must contain plugin.yaml or plugin.yml" }];
+  }
+  try {
+    const document = parseDocument2(await readFile13(manifestPath, "utf8"));
+    if (document.errors.length > 0) {
+      return [{ artifact, message: `Hermes ${basename6(manifestPath)} must be valid YAML: ${document.errors[0]?.message ?? "parse error"}` }];
+    }
+    const parsed = document.toJSON();
+    if (!isUnknownRecord(parsed)) {
+      return [{ artifact, message: `Hermes ${basename6(manifestPath)} must contain a YAML object` }];
+    }
+    if (!hasStringField(parsed, "name") && !hasStringField(parsed, "module") && !hasStringField(parsed, "package") && !hasNestedPackageName(parsed)) {
+      return [{ artifact, message: `Hermes ${basename6(manifestPath)} must declare a non-empty name, module, or package name` }];
+    }
+    return [];
+  } catch (error) {
+    return [{ artifact, message: `Hermes ${basename6(manifestPath)} must be valid YAML: ${errorMessage(error)}` }];
+  }
+}
+async function firstExistingPath(paths) {
+  for (const path of paths) {
+    if (await pathExists(path)) return path;
+  }
+  return void 0;
+}
+async function parseJsonPluginManifest(manifestPath, label) {
+  try {
+    const parsed = JSON.parse(await readFile13(manifestPath, "utf8"));
+    if (!isRecord5(parsed)) {
+      return { ok: false, message: `${label} ${basename6(manifestPath)} must be a JSON object` };
+    }
+    if (typeof parsed.name !== "string" || parsed.name.trim().length === 0) {
+      return { ok: false, message: `${label} ${basename6(manifestPath)} must declare a non-empty name` };
+    }
+    return { ok: true, name: parsed.name.trim() };
+  } catch (error) {
+    return { ok: false, message: `${label} ${basename6(manifestPath)} must be valid JSON: ${errorMessage(error)}` };
+  }
+}
 async function validateOpenClawPlugin(artifact) {
   const issues = [];
   if (artifact.type !== "plugins") {
@@ -2097,15 +2978,15 @@ async function validateOpenClawPlugin(artifact) {
 }
 async function openClawPluginManifestPaths(artifact) {
   const root = artifactPath(artifact);
-  const candidates = [join7(root, "plugin.json"), join7(root, "openclaw.plugin.json")];
+  const candidates = [join14(root, "plugin.json"), join14(root, "openclaw.plugin.json")];
   const existing = await Promise.all(candidates.map(async (candidate) => await pathExists(candidate) ? candidate : void 0));
   return existing.filter((candidate) => candidate !== void 0);
 }
 async function parseOpenClawPluginManifest(manifestPath) {
-  const manifestName = basename5(manifestPath);
+  const manifestName = basename6(manifestPath);
   try {
-    const parsed = JSON.parse(await readFile9(manifestPath, "utf8"));
-    if (!isRecord3(parsed)) {
+    const parsed = JSON.parse(await readFile13(manifestPath, "utf8"));
+    if (!isRecord5(parsed)) {
       return { ok: false, path: manifestPath, message: `OpenClaw ${manifestName} must be a JSON object` };
     }
     if (typeof parsed.name !== "string" || parsed.name.trim().length === 0) {
@@ -2116,32 +2997,39 @@ async function parseOpenClawPluginManifest(manifestPath) {
     return { ok: false, path: manifestPath, message: `OpenClaw ${manifestName} must be valid JSON: ${errorMessage(error)}` };
   }
 }
-async function readUtf8Artifact(artifact, issues) {
-  if (artifact.kind !== "file") return void 0;
+async function parseJsonObjectArtifact(artifact) {
+  if (artifact.kind !== "file") {
+    return { ok: false, message: "merge artifacts must be JSON files" };
+  }
   try {
-    return await readFile9(artifactPath(artifact), "utf8");
+    const parsed = JSON.parse(await readFile13(artifactPath(artifact), "utf8"));
+    if (!isRecord5(parsed)) return { ok: false, message: "merge artifacts must contain a JSON object" };
+    return { ok: true, value: parsed };
   } catch (error) {
-    issues.push({ artifact, message: `could not read artifact: ${errorMessage(error)}` });
-    return void 0;
+    return { ok: false, message: `merge artifact must be valid JSON: ${errorMessage(error)}` };
   }
 }
-async function parseJsonObjectArtifact(artifact) {
+async function parseYamlObjectArtifact(artifact) {
   if (artifact.kind !== "file") {
-    return { ok: false, message: "merge artifacts must be JSON files" };
+    return { ok: false, message: "merge artifacts must be YAML files" };
   }
   try {
-    const parsed = JSON.parse(await readFile9(artifactPath(artifact), "utf8"));
-    if (!isRecord3(parsed)) return { ok: false, message: "merge artifacts must contain a JSON object" };
+    const document = parseDocument2(await readFile13(artifactPath(artifact), "utf8"));
+    if (document.errors.length > 0) {
+      return { ok: false, message: `merge artifact must be valid YAML: ${document.errors[0]?.message ?? "parse error"}` };
+    }
+    const parsed = document.toJSON();
+    if (!isUnknownRecord(parsed)) return { ok: false, message: "merge artifacts must contain a YAML object" };
     return { ok: true, value: parsed };
   } catch (error) {
-    return { ok: false, message: `merge artifact must be valid JSON: ${errorMessage(error)}` };
+    return { ok: false, message: `merge artifact must be valid YAML: ${errorMessage(error)}` };
   }
 }
 function extractMcpServers2(source) {
-  const raw = isRecord3(source.mcpServers) ? source.mcpServers : source;
+  const raw = isRecord5(source.mcpServers) ? source.mcpServers : source;
   const servers = {};
   for (const [name, value] of Object.entries(raw)) {
-    if (isRecord3(value)) servers[name] = value;
+    if (isRecord5(value)) servers[name] = value;
   }
   return servers;
 }
@@ -2153,11 +3041,33 @@ function artifactLabel(artifact) {
   return `${owner}${artifact.type}/${artifact.name}`;
 }
 function hasExtension(artifact, extension) {
-  return basename5(artifact.name).toLowerCase().endsWith(extension) || basename5(artifactPath(artifact)).toLowerCase().endsWith(extension);
+  return basename6(artifact.name).toLowerCase().endsWith(extension) || basename6(artifactPath(artifact)).toLowerCase().endsWith(extension);
 }
-function isRecord3(value) {
+function isPluginFormat(value) {
+  return value !== void 0 && pluginFormats.includes(value);
+}
+function isRecord5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isUnknownRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function hasStringField(value, field) {
+  const raw = value[field];
+  return typeof raw === "string" && raw.trim().length > 0;
+}
+function hasNestedPackageName(value) {
+  const raw = value.package;
+  return isUnknownRecord(raw) && hasStringField(raw, "name");
+}
+function formatSkipWarning(artifact, compatibility, adapter, installationType, selectedSet) {
+  const selector = artifactSelectorKey(artifact);
+  const reason = selectedSet.has(selector) ? "selected but format-incompatible" : "format-incompatible";
+  const expected = compatibility.expected?.join(", ") ?? "supported format";
+  const format = compatibility.format ?? "unknown";
+  const details = compatibility.message ?? `${adapter.name}/${installationType} expects ${expected}, got ${format}`;
+  return `skip ${selector} (${reason}: ${details})`;
+}
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -2165,17 +3075,18 @@ function errorMessage(error) {
 // src/install/plan.ts
 async function createCombinedInstallPlan(desiredArtifacts, adapter, targetRoot, manifest, transport = localTransport, options = {}) {
   const requestedInstallationType = options.installationType ?? defaultInstallationType;
-  const installationType = resolveInstallationTypeForArtifacts(adapter, desiredArtifacts.map((artifact) => artifact.type), requestedInstallationType);
-  const installRoot = installRootForArtifacts(adapter, targetRoot, installationType, desiredArtifacts.map((artifact) => artifact.type), transport.kind === "ssh");
-  await validateArtifactsForInstall(desiredArtifacts, adapter, installationType);
-  for (const artifact of desiredArtifacts) {
+  const installableArtifacts = await filterArtifactsByInstallFormat(desiredArtifacts, adapter, requestedInstallationType, { warn: options.warn });
+  const installationType = resolveInstallationTypeForArtifacts(adapter, installableArtifacts.map((artifact) => artifact.type), requestedInstallationType);
+  const installRoot = installRootForArtifacts(adapter, targetRoot, installationType, installableArtifacts.map((artifact) => artifact.type), transport.kind === "ssh");
+  await validateArtifactsForInstall(installableArtifacts, adapter, installationType);
+  for (const artifact of installableArtifacts) {
     if (artifact.meta.dependencyRole !== "root" && isGuardedMergeTarget(artifact.type)) {
       throw new Error(`Dependency-provided ${artifact.type} artifacts cannot be installed until per-subentry ownership exists: ${artifact.type}/${artifact.name}`);
     }
   }
   const desired = [];
-  for (const artifact of desiredArtifacts) {
-    const op = operationForArtifact(artifact, adapter, installRoot, installationType, artifact.meta);
+  for (const artifact of installableArtifacts) {
+    const op = await operationForArtifact(artifact, adapter, installRoot, installationType, artifact.meta);
     if (op) {
       desired.push(op);
     }
@@ -2188,20 +3099,21 @@ async function createPlanFromOperations(desiredOps, adapter, targetRoot, manifes
   if (workspaceOwner) {
     for (const op of desiredOps) op.workspaceOwner = workspaceOwner;
   }
-  for (const op of desiredOps) assertOperationContained(op, targetRoot);
-  const migration = await migrateManifestForPlan(manifest, desiredOps, targetRoot, transport);
+  const preparedOps = await prepareManagedBlockOperations(desiredOps, adapter, targetRoot, transport, options);
+  for (const op of preparedOps) assertOperationContained(op, targetRoot);
+  const migration = await migrateManifestForPlan(manifest, preparedOps, targetRoot, transport);
   const effectiveEntries = migration.entries;
   const manifestByPath = new Map(effectiveEntries.map((entry) => [entry.path, entry]));
-  const { desired, collisions } = await splitCollisionOperations(desiredOps, manifestByPath, transport);
+  const { desired, collisions } = await splitCollisionOperations(preparedOps, manifestByPath, transport);
   const operations = [];
   operations.push(...collisions);
   for (const op of desired.values()) {
     if (op.action === "plugin") {
       const existing2 = manifestByPath.get(op.relativeDestPath);
-      if (existing2 && existing2.hash === op.desiredHash) {
-        operations.push({ ...op, action: "skip", manifestHash: existing2.hash, reason: "plugin already planned" });
+      if (existing2 && existing2.sourceHash === op.desiredHash && existing2.executed === true) {
+        operations.push({ ...op, action: "skip", manifestHash: existing2.hash, reason: "semantic plugin already executed" });
       } else {
-        operations.push(op);
+        operations.push(existing2 && existing2.sourceHash === op.desiredHash ? { ...op, manifestHash: existing2.hash, reason: "semantic plugin pending execution" } : op);
       }
       continue;
     }
@@ -2214,6 +3126,10 @@ async function createPlanFromOperations(desiredOps, adapter, targetRoot, manifes
       }
       continue;
     }
+    if (op.mode === managedInstructionBlockMode) {
+      operations.push(...await planManagedBlockOperation(op, manifestByPath, transport, options, workspaceOwner, targetRoot));
+      continue;
+    }
     if (op.mergeStrategy) {
       const existing2 = manifestByPath.get(op.relativeDestPath);
       const exists2 = await transport.pathExists(op.destPath);
@@ -2225,7 +3141,7 @@ async function createPlanFromOperations(desiredOps, adapter, targetRoot, manifes
       if (existing2 && existing2.sourceHash === op.desiredHash) {
         operations.push({ ...op, action: "skip", currentHash: currentHash2, manifestHash: existing2.hash, reason: "merged source already up to date" });
       } else {
-        operations.push({ ...op, action: "update", currentHash: currentHash2, manifestHash: existing2?.hash, reason: existing2 ? "merge source changed" : "merge into existing JSON" });
+        operations.push({ ...op, action: "update", currentHash: currentHash2, manifestHash: existing2?.hash, reason: existing2 ? "merge source changed" : "merge into existing destination" });
       }
       continue;
     }
@@ -2301,9 +3217,10 @@ async function createPlanFromOperations(desiredOps, adapter, targetRoot, manifes
   }
   for (const entry of effectiveEntries) {
     if (desired.has(entry.path)) continue;
-    const destPath = join8(targetRoot, entry.path);
-    if (!await transport.pathExists(destPath)) continue;
-    const currentHash = await transport.hashPath(destPath);
+    const semanticPlugin = entry.semanticPlugin;
+    const destPath = semanticPlugin ? targetRoot : join15(targetRoot, entry.path);
+    if (!semanticPlugin && !await transport.pathExists(destPath)) continue;
+    const currentHash = semanticPlugin ? entry.hash : await currentEntryHash(entry, destPath, transport);
     if (workspaceOwner && !entryOwnedByWorkspace(entry, workspaceOwner)) {
       operations.push(keepForeignManifestEntryOperation(entry, targetRoot, workspaceOwner, void 0, currentHash));
       continue;
@@ -2321,6 +3238,11 @@ async function createPlanFromOperations(desiredOps, adapter, targetRoot, manifes
         reason: "managed stale destination changed outside agentwheel",
         channel: entry.channel,
         packageName: entry.packageName,
+        semanticCommand: entry.semanticCommand,
+        semanticPlugin,
+        execute: entry.executed,
+        mergeStrategy: entry.mergeStrategy,
+        mode: entry.mode,
         composedFrom: entry.composedFrom,
         ...operationMetadataFromEntry(entry),
         ...options.forceDrift ? { action: "remove", reason: "force removing drifted stale managed destination" } : {}
@@ -2338,6 +3260,11 @@ async function createPlanFromOperations(desiredOps, adapter, targetRoot, manifes
         reason: "artifact removed from source",
         channel: entry.channel,
         packageName: entry.packageName,
+        semanticCommand: semanticPlugin?.uninstallCommands[0] ?? entry.semanticCommand,
+        semanticPlugin,
+        execute: entry.executed,
+        mergeStrategy: entry.mergeStrategy,
+        mode: entry.mode,
         composedFrom: entry.composedFrom,
         ...operationMetadataFromEntry(entry)
       });
@@ -2407,11 +3334,131 @@ async function migrateManifestForPlan(manifest, desired, targetRoot, transport)
     }
   };
 }
+async function prepareManagedBlockOperations(desiredOps, adapter, targetRoot, transport, options) {
+  const prepared = [];
+  const physicalInstructionPaths = /* @__PURE__ */ new Map();
+  for (const op of desiredOps) {
+    if (op.mode !== managedInstructionBlockMode) {
+      prepared.push(op);
+      continue;
+    }
+    if (!op.sourcePath) {
+      throw new Error(`Managed block instruction operation missing source: ${op.relativeDestPath}`);
+    }
+    const managedOp = {
+      ...op,
+      desiredHash: await desiredManagedInstructionBlockHash(op.sourcePath)
+    };
+    if (await shouldSkipClaudeBridge(adapter, managedOp, targetRoot, transport)) {
+      continue;
+    }
+    await warnOnCopilotDoubleRead(adapter, managedOp, targetRoot, transport, options);
+    const physicalKey = await managedInstructionPhysicalKey(managedOp.destPath, transport);
+    const incumbent = physicalInstructionPaths.get(physicalKey);
+    if (incumbent) {
+      if (incumbent.desiredHash !== managedOp.desiredHash) {
+        options.warn?.(`Multiple instruction targets resolve to ${managedOp.relativeDestPath}; using ${incumbent.relativeDestPath} and skipping duplicate with different content.`);
+      }
+      continue;
+    }
+    physicalInstructionPaths.set(physicalKey, managedOp);
+    prepared.push(managedOp);
+  }
+  return prepared;
+}
+async function shouldSkipClaudeBridge(adapter, op, targetRoot, transport) {
+  if (adapter.name !== "claude" || op.artifactType !== "instructions" || basename7(op.destPath).toLowerCase() !== "claude.md") {
+    return false;
+  }
+  const agentsPath = join15(targetRoot, "AGENTS.md");
+  return claudeInstructionBridgesAgents(op.destPath, agentsPath, transport);
+}
+async function warnOnCopilotDoubleRead(adapter, op, targetRoot, transport, options) {
+  if (adapter.name !== "claude" || op.artifactType !== "instructions" || basename7(op.destPath).toLowerCase() !== "claude.md") return;
+  const agentsPath = join15(targetRoot, "AGENTS.md");
+  if (!await transport.pathExists(agentsPath)) return;
+  if (await claudeInstructionBridgesAgents(op.destPath, agentsPath, transport)) return;
+  options.warn?.("CLAUDE.md and AGENTS.md are separate instruction files; if Copilot is active it may read the managed instructions twice.");
+}
+async function planManagedBlockOperation(op, manifestByPath, transport, options, workspaceOwner, targetRoot) {
+  const existing = manifestByPath.get(op.relativeDestPath);
+  if (existing && workspaceOwner && !entryOwnedByWorkspace(existing, workspaceOwner)) {
+    return [keepForeignManifestEntryOperation(existing, targetRoot, workspaceOwner, op)];
+  }
+  const selector = managedInstructionSelector(op.logicalSelector, op.artifactType, op.artifactName);
+  const state = await readManagedInstructionBlockState(op.destPath, selector, transport);
+  if (!state.exists) {
+    return [{ ...op, action: "create", reason: "managed instruction destination missing" }];
+  }
+  if (!existing) {
+    if (state.hasBlock && !state.drifted && state.hash === op.desiredHash && options.forceConflict) {
+      return [{
+        ...op,
+        action: "skip",
+        currentHash: state.hash,
+        reason: "force adopting unmanaged managed-block destination with matching hash"
+      }];
+    }
+    if (options.replaceConflict) {
+      return [{
+        ...op,
+        action: "update",
+        currentHash: state.hash,
+        reason: "force adopting managed-block destination"
+      }];
+    }
+    return [{
+      ...op,
+      action: "conflict",
+      currentHash: state.hash,
+      reason: "destination exists but is not managed"
+    }];
+  }
+  if (!state.hasBlock || state.drifted || state.hash !== existing.hash) {
+    const composedFromDiff = changedComposedSelectors(op.composedFrom, existing.composedFrom);
+    if (options.forceDrift) {
+      return [{
+        ...op,
+        action: "update",
+        currentHash: state.hash,
+        manifestHash: existing.hash,
+        reason: reasonWithComposedDiff("force replacing drifted managed instruction block", op.composedFrom, existing.composedFrom),
+        composedFromDiff
+      }];
+    }
+    return [{
+      ...op,
+      action: "drift",
+      currentHash: state.hash,
+      manifestHash: existing.hash,
+      reason: state.hasBlock ? "managed instruction block changed outside agentwheel" : "managed instruction block missing from destination",
+      blockedDesiredHash: op.desiredHash,
+      blockedReason: blockedDriftReason(op.composedFrom, existing.composedFrom),
+      composedFromDiff
+    }];
+  }
+  if (existing.sourceHash === op.desiredHash) {
+    return [{ ...op, action: "skip", currentHash: state.hash, manifestHash: existing.hash, reason: "managed instruction block already up to date" }];
+  }
+  return [{
+    ...op,
+    action: "update",
+    currentHash: state.hash,
+    manifestHash: existing.hash,
+    reason: reasonWithComposedDiff("managed instruction source changed", op.composedFrom, existing.composedFrom)
+  }];
+}
+async function currentEntryHash(entry, destPath, transport) {
+  if (entry.mode !== managedInstructionBlockMode) return transport.hashPath(destPath);
+  const selector = managedInstructionSelector("logicalSelector" in entry ? entry.logicalSelector : void 0, entry.artifactType, entry.artifactName);
+  const state = await readManagedInstructionBlockState(destPath, selector, transport);
+  return state.drifted ? state.markerHash : state.hash;
+}
 async function canStrictlyAdoptLegacyEntry(entry, op, targetRoot, transport) {
   if (entry.artifactType !== op.artifactType || entry.artifactName !== op.artifactName) return false;
   if (!op.desiredHash || entry.sourceHash !== op.desiredHash) return false;
   if (!packageIdentityMatches(entry, op)) return false;
-  const destPath = join8(targetRoot, entry.path);
+  const destPath = join15(targetRoot, entry.path);
   if (!await transport.pathExists(destPath)) return false;
   return await transport.hashPath(destPath) === entry.hash;
 }
@@ -2501,7 +3548,8 @@ function adoptLegacyEntry(entry, op) {
     refCount: owners.length,
     workspaceOwner: op.workspaceOwner ?? legacyUnownedWorkspaceOwner,
     graphLockDigest: op.graphLockDigest,
-    composedFrom: op.composedFrom ?? entry.composedFrom
+    composedFrom: op.composedFrom ?? entry.composedFrom,
+    mode: op.mode
   };
 }
 function operationMetadataFromDesired(artifact, meta) {
@@ -2541,7 +3589,7 @@ function keepForeignManifestEntryOperation(entry, targetRoot, workspaceOwner, op
     artifactType: entry.artifactType,
     artifactName: entry.artifactName,
     kind: entry.kind,
-    destPath: operation?.destPath ?? join8(targetRoot, entry.path),
+    destPath: operation?.destPath ?? join15(targetRoot, entry.path),
     relativeDestPath: entry.path,
     desiredHash: entry.sourceHash,
     currentHash: currentHash ?? operation?.currentHash ?? entry.hash,
@@ -2550,8 +3598,10 @@ function keepForeignManifestEntryOperation(entry, targetRoot, workspaceOwner, op
     channel: entry.channel,
     packageName: entry.packageName,
     semanticCommand: entry.semanticCommand,
+    semanticPlugin: entry.semanticPlugin,
     execute: entry.executed,
     mergeStrategy: entry.mergeStrategy,
+    mode: entry.mode,
     composedFrom: entry.composedFrom,
     preserveInManifest: true,
     ...operationMetadataFromEntry(entry)
@@ -2563,7 +3613,7 @@ function normalizeOperationOwners(op) {
 function isGuardedMergeTarget(type) {
   return type === "mcp" || type === "hooks" || type === "settings" || type === "plugins";
 }
-function operationForArtifact(artifact, adapter, targetRoot, installationType, meta) {
+async function operationForArtifact(artifact, adapter, targetRoot, installationType, meta) {
   if (artifact.type === "fragments") return void 0;
   const target = targetMappingForArtifact(adapter, artifact.type, installationType);
   if (!target?.enabled) {
@@ -2576,27 +3626,38 @@ function operationForArtifact(artifact, adapter, targetRoot, installationType, m
   assertSafeInstallName(rawInstallName, `${artifact.type}/${artifact.name}`);
   const installName = semanticInstallName(artifact, target.semantic, rawInstallName);
   assertSafeInstallName(installName, `${artifact.type}/${artifact.name}`);
-  if (artifact.type === "plugins" && target.semantic === "openclaw-plugin") {
+  if (artifact.type === "plugins") {
     const sourcePath = artifact.stagedPath ?? artifact.sourcePath;
-    return {
-      action: "plugin",
-      artifactType: artifact.type,
-      artifactName: artifact.name,
-      kind: artifact.kind,
+    const semanticPlugin = await semanticPluginSpecForArtifact({
+      semantic: target.semantic,
+      artifact,
+      installName,
       sourcePath,
-      destPath: targetRoot,
-      relativeDestPath: `plugins/${installName}`,
-      desiredHash: artifact.hash,
-      reason: "semantic plugin install planned",
-      channel: artifact.channel ?? "managed",
-      packageName: artifact.packageName,
-      semanticCommand: openClawPluginInstallCommand({ path: sourcePath, dryRun: true }),
-      composedFrom: metadata.composedFrom,
-      ...metadata
-    };
+      targetRoot,
+      installationType
+    });
+    if (semanticPlugin) {
+      return {
+        action: "plugin",
+        artifactType: artifact.type,
+        artifactName: artifact.name,
+        kind: artifact.kind,
+        sourcePath,
+        destPath: targetRoot,
+        relativeDestPath: `plugins/${installName}`,
+        desiredHash: artifact.hash,
+        reason: "semantic plugin install planned",
+        channel: artifact.channel ?? "managed",
+        packageName: artifact.packageName,
+        semanticCommand: semanticPlugin.installCommands[0],
+        semanticPlugin,
+        composedFrom: metadata.composedFrom,
+        ...metadata
+      };
+    }
   }
   if (artifact.type === "subagents" && target.semantic === "codex-subagent") {
-    const destPath2 = join8(targetRoot, target.dest, `${installName.replace(/\.toml$/i, "")}.toml`);
+    const destPath2 = join15(targetRoot, target.dest, `${installName.replace(/\.toml$/i, "")}.toml`);
     return {
       action: "create",
       artifactType: artifact.type,
@@ -2604,7 +3665,7 @@ function operationForArtifact(artifact, adapter, targetRoot, installationType, m
       kind: "file",
       sourcePath: artifact.stagedPath ?? artifact.sourcePath,
       destPath: destPath2,
-      relativeDestPath: relative2(targetRoot, destPath2).replaceAll("\\", "/"),
+      relativeDestPath: relative3(targetRoot, destPath2).replaceAll("\\", "/"),
       desiredHash: artifact.hash,
       reason: "destination missing",
       channel: artifact.channel ?? "managed",
@@ -2614,7 +3675,7 @@ function operationForArtifact(artifact, adapter, targetRoot, installationType, m
       installName: installName.replace(/\.toml$/i, "")
     };
   }
-  const destPath = artifact.type === "instructions" || artifact.type === "settings" || isFileTarget(target.dest) ? join8(targetRoot, target.dest) : join8(targetRoot, target.dest, installName);
+  const destPath = artifact.type === "instructions" || artifact.type === "settings" || isFileTarget(target.dest) ? join15(targetRoot, target.dest) : join15(targetRoot, target.dest, installName);
   return {
     action: "create",
     artifactType: artifact.type,
@@ -2622,12 +3683,13 @@ function operationForArtifact(artifact, adapter, targetRoot, installationType, m
     kind: artifact.kind,
     sourcePath: artifact.stagedPath ?? artifact.sourcePath,
     destPath,
-    relativeDestPath: relative2(targetRoot, destPath).replaceAll("\\", "/"),
+    relativeDestPath: relative3(targetRoot, destPath).replaceAll("\\", "/"),
     desiredHash: artifact.hash,
     reason: "destination missing",
     channel: artifact.channel ?? "managed",
     packageName: artifact.packageName,
     mergeStrategy: target.merge,
+    mode: target.mode,
     composedFrom: metadata.composedFrom,
     ...metadata,
     installName
@@ -2651,7 +3713,7 @@ function withExtension(name, targetExtension, knownExtensions) {
   return `${base}${targetExtension}`;
 }
 function isFileTarget(dest) {
-  return /\.(json|jsonc|toml|md)$/i.test(dest);
+  return /\.(json|jsonc|ya?ml|toml|md)$/i.test(dest);
 }
 function reasonWithComposedDiff(reason, desired, current) {
   const changed = changedComposedSelectors(desired, current);
@@ -2692,13 +3754,14 @@ function isPendingInstallOperation(operation) {
 }
 
 // src/install/uninstall.ts
-import { join as join9 } from "path";
+import { join as join16 } from "path";
 async function createUninstallPlan(manifest, transport = localTransport) {
   const operations = [];
   for (const entry of manifest.entries) {
-    const destPath = join9(manifest.targetRoot, entry.path);
-    if (!await transport.pathExists(destPath)) continue;
-    const currentHash = await transport.hashPath(destPath);
+    const semanticPlugin = "semanticPlugin" in entry ? entry.semanticPlugin : void 0;
+    const destPath = semanticPlugin ? manifest.targetRoot : join16(manifest.targetRoot, entry.path);
+    if (!semanticPlugin && !await transport.pathExists(destPath)) continue;
+    const currentHash = semanticPlugin ? entry.hash : await currentEntryHash2(entry, destPath, transport);
     if (currentHash !== entry.hash) {
       operations.push({
         action: "keep",
@@ -2714,7 +3777,10 @@ async function createUninstallPlan(manifest, transport = localTransport) {
         channel: entry.channel,
         packageName: entry.packageName,
         semanticCommand: entry.semanticCommand,
+        semanticPlugin,
+        execute: entry.executed,
         mergeStrategy: entry.mergeStrategy,
+        mode: entry.mode,
         composedFrom: entry.composedFrom,
         ...operationMetadataFromEntry2(entry)
       });
@@ -2732,8 +3798,11 @@ async function createUninstallPlan(manifest, transport = localTransport) {
         reason: "uninstall managed artifact",
         channel: entry.channel,
         packageName: entry.packageName,
-        semanticCommand: entry.semanticCommand,
+        semanticCommand: semanticPlugin?.uninstallCommands[0] ?? entry.semanticCommand,
+        semanticPlugin,
+        execute: entry.executed,
         mergeStrategy: entry.mergeStrategy,
+        mode: entry.mode,
         composedFrom: entry.composedFrom,
         ...operationMetadataFromEntry2(entry)
       });
@@ -2760,9 +3829,10 @@ async function createOwnershipUninstallPlan(manifest, remainingDesired, adapter,
   );
   const operations = [];
   for (const entry of manifest.entries) {
-    const destPath = join9(manifest.targetRoot, entry.path);
-    if (!await transport.pathExists(destPath)) continue;
-    const currentHash = await transport.hashPath(destPath);
+    const semanticPlugin = "semanticPlugin" in entry ? entry.semanticPlugin : void 0;
+    const destPath = semanticPlugin ? manifest.targetRoot : join16(manifest.targetRoot, entry.path);
+    if (!semanticPlugin && !await transport.pathExists(destPath)) continue;
+    const currentHash = semanticPlugin ? entry.hash : await currentEntryHash2(entry, destPath, transport);
     const remainingOwners = ownersByPath.get(entry.path) ?? [];
     if (remainingOwners.length > 0) {
       operations.push({
@@ -2779,7 +3849,10 @@ async function createOwnershipUninstallPlan(manifest, remainingDesired, adapter,
         channel: entry.channel,
         packageName: entry.packageName,
         semanticCommand: entry.semanticCommand,
+        semanticPlugin,
+        execute: entry.executed,
         mergeStrategy: entry.mergeStrategy,
+        mode: entry.mode,
         composedFrom: entry.composedFrom,
         ...operationMetadataFromEntry2(entry, remainingOwners),
         graphLockDigest: options.graphLockDigest,
@@ -2802,7 +3875,10 @@ async function createOwnershipUninstallPlan(manifest, remainingDesired, adapter,
         channel: entry.channel,
         packageName: entry.packageName,
         semanticCommand: entry.semanticCommand,
+        semanticPlugin,
+        execute: entry.executed,
         mergeStrategy: entry.mergeStrategy,
+        mode: entry.mode,
         composedFrom: entry.composedFrom,
         ...operationMetadataFromEntry2(entry),
         graphLockDigest: options.graphLockDigest
@@ -2821,8 +3897,11 @@ async function createOwnershipUninstallPlan(manifest, remainingDesired, adapter,
         reason: "owner set became empty",
         channel: entry.channel,
         packageName: entry.packageName,
-        semanticCommand: entry.semanticCommand,
+        semanticCommand: semanticPlugin?.uninstallCommands[0] ?? entry.semanticCommand,
+        semanticPlugin,
+        execute: entry.executed,
         mergeStrategy: entry.mergeStrategy,
+        mode: entry.mode,
         composedFrom: entry.composedFrom,
         ...operationMetadataFromEntry2(entry, [])
       });
@@ -2841,6 +3920,12 @@ async function createOwnershipUninstallPlan(manifest, remainingDesired, adapter,
     graphLockDigest: options.graphLockDigest
   };
 }
+async function currentEntryHash2(entry, destPath, transport) {
+  if (entry.mode !== managedInstructionBlockMode) return transport.hashPath(destPath);
+  const selector = managedInstructionSelector("logicalSelector" in entry ? entry.logicalSelector : void 0, entry.artifactType, entry.artifactName);
+  const state = await readManagedInstructionBlockState(destPath, selector, transport);
+  return state.drifted ? state.markerHash : state.hash;
+}
 function operationMetadataFromEntry2(entry, ownersOverride) {
   if ("owners" in entry) {
     return {
@@ -2887,7 +3972,7 @@ function formatPlan(plan) {
   }
   for (const operation of sortedPlanOperations(plan.operations)) {
     const source = operation.sourcePath ? `${operation.sourcePath} -> ` : "";
-    const command = operation.semanticCommand ? ` :: ${operation.semanticCommand.join(" ")}` : "";
+    const command = formatSemanticCommandSuffix(operation);
     const blocked = operation.blockedReason ? `; ${operation.blockedReason}` : "";
     lines.push(`${labels[operation.action].padEnd(8)} ${channelLabels[operation.channel].padEnd(8)} ${operation.artifactType}/${operation.artifactName} ${source}${operation.relativeDestPath} (${operation.reason}${blocked})${command}`);
   }
@@ -2897,6 +3982,18 @@ function formatPlan(plan) {
   );
   return lines.join("\n");
 }
+function formatSemanticCommandSuffix(operation) {
+  const commands = semanticCommandsForOperation(operation);
+  return commands.length > 0 ? ` :: ${commands.map((command) => command.join(" ")).join(" && ")}` : "";
+}
+function semanticCommandsForOperation(operation) {
+  if (operation.semanticPlugin) {
+    if (operation.action === "remove" && operation.execute === false) return [];
+    if (operation.action === "remove") return operation.semanticPlugin.uninstallCommands;
+    if (operation.action === "plugin") return operation.semanticPlugin.installCommands;
+  }
+  return operation.semanticCommand ? [operation.semanticCommand] : [];
+}
 function sortedPlanOperations(operations) {
   return [...operations].sort((a, b) => {
     const destructiveA = a.action === "remove" || a.action === "drift" || a.action === "conflict";
@@ -3053,15 +4150,15 @@ function ownerChains(lock, nodeId) {
 
 // src/source/git.ts
 import { execFile as execFile4 } from "child_process";
-import { cp as cp2, mkdir as mkdir8, rename as rename3, rm as rm4, writeFile as writeFile9 } from "fs/promises";
+import { cp as cp2, mkdir as mkdir9, rename as rename3, rm as rm5, writeFile as writeFile11 } from "fs/promises";
 import { homedir as homedir2 } from "os";
-import { basename as basename7, dirname as dirname9, join as join12, resolve as resolve6 } from "path";
+import { basename as basename9, dirname as dirname11, join as join19, resolve as resolve6 } from "path";
 import { promisify as promisify4 } from "util";
 
 // src/model/package.ts
-import { readFile as readFile10 } from "fs/promises";
-import { join as join10 } from "path";
-import { parse as parse2, printParseErrorCode as printParseErrorCode2 } from "jsonc-parser";
+import { readFile as readFile14 } from "fs/promises";
+import { join as join17 } from "path";
+import { parse as parse3, printParseErrorCode as printParseErrorCode2 } from "jsonc-parser";
 import { z as z5 } from "zod";
 var legacyArtifactTypeSchema = z5.enum([
   "instructions",
@@ -3137,7 +4234,7 @@ var packageManifestNames = [...openPackManifestNames, ...legacyPackageManifestNa
 var warnedLegacyManifestPaths = /* @__PURE__ */ new Set();
 async function findPackageManifestPath(root, options = {}) {
   for (const name of packageManifestNames) {
-    const candidate = join10(root, name);
+    const candidate = join17(root, name);
     if (!await pathExists(candidate)) continue;
     if (isLegacyPackageManifestName(name) && options.warnLegacy !== false && !warnedLegacyManifestPaths.has(candidate)) {
       warnedLegacyManifestPaths.add(candidate);
@@ -3150,9 +4247,9 @@ async function findPackageManifestPath(root, options = {}) {
 async function readPackageManifest(root) {
   const path = await findPackageManifestPath(root);
   if (!path) return void 0;
-  const content = await readFile10(path, "utf8");
+  const content = await readFile14(path, "utf8");
   const errors = [];
-  const parsed = parse2(content, errors, { allowTrailingComma: true, disallowComments: false });
+  const parsed = parse3(content, errors, { allowTrailingComma: true, disallowComments: false });
   if (errors.length > 0) {
     const details = errors.map((error) => `${printParseErrorCode2(error.error)} at offset ${error.offset}`).join(", ");
     throw new Error(`Invalid package manifest ${path}: ${details}`);
@@ -3160,7 +4257,7 @@ async function readPackageManifest(root) {
   return parsePackageManifest(parsed, path);
 }
 function parsePackageManifest(parsed, path = "package manifest") {
-  if (!isRecord4(parsed)) {
+  if (!isRecord6(parsed)) {
     throw new Error(`Invalid package manifest ${path}: expected an object`);
   }
   if (parsed.schemaVersion === 1) {
@@ -3188,7 +4285,7 @@ function v1OpenPackViolations(manifest) {
   }
   const provides = Array.isArray(manifest.provides) ? manifest.provides : [];
   for (const [index, provide] of provides.entries()) {
-    if (!isRecord4(provide)) continue;
+    if (!isRecord6(provide)) continue;
     if (provide.type === "fragments") violations.push(`provides[${index}].type=fragments`);
     for (const key of ["format", "items", "compose", "runtimes"]) {
       if (Object.prototype.hasOwnProperty.call(provide, key)) violations.push(`provides[${index}].${key}`);
@@ -3199,14 +4296,14 @@ function v1OpenPackViolations(manifest) {
 function isLegacyPackageManifestName(name) {
   return legacyPackageManifestNames.includes(name);
 }
-function isRecord4(value) {
+function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 // src/source/local.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import { readdir, stat as stat3 } from "fs/promises";
-import { basename as basename6, join as join11, relative as relative3, resolve as resolve5 } from "path";
+import { basename as basename8, join as join18, relative as relative4, resolve as resolve5 } from "path";
 var LocalSourceDriver = class {
   name = "local";
   async resolve(source) {
@@ -3236,29 +4333,29 @@ var LocalSourceDriver = class {
     }
     const artifacts = [];
     const root = resolved.resolvedPath;
-    const instructions = await firstExisting([join11(root, "instructions.md"), join11(root, "AGENTS.md")]);
+    const instructions = await firstExisting([join18(root, "instructions.md"), join18(root, "AGENTS.md")]);
     if (instructions) {
       artifacts.push({
         type: "instructions",
-        name: basename6(instructions),
+        name: basename8(instructions),
         sourcePath: instructions,
-        relativePath: basename6(instructions),
+        relativePath: basename8(instructions),
         kind: "file",
         hash: await hashPath(instructions),
         packageName: resolved.packageName,
         channel: "managed"
       });
     }
-    const rulesDir = join11(root, "rules");
+    const rulesDir = join18(root, "rules");
     if (await pathExists(rulesDir)) {
       for (const entry of await sortedDirEntries(rulesDir)) {
-        const full = join11(rulesDir, entry.name);
+        const full = join18(rulesDir, entry.name);
         if (entry.isFile()) {
           artifacts.push({
             type: "rules",
             name: entry.name,
             sourcePath: full,
-            relativePath: join11("rules", entry.name),
+            relativePath: join18("rules", entry.name),
             kind: "file",
             hash: await hashPath(full),
             packageName: resolved.packageName,
@@ -3267,16 +4364,16 @@ var LocalSourceDriver = class {
         }
       }
     }
-    const fragmentsDir = join11(root, "fragments");
+    const fragmentsDir = join18(root, "fragments");
     if (await pathExists(fragmentsDir)) {
       for (const entry of await sortedDirEntries(fragmentsDir)) {
-        const full = join11(fragmentsDir, entry.name);
+        const full = join18(fragmentsDir, entry.name);
         if (entry.isFile()) {
           artifacts.push({
             type: "fragments",
             name: entry.name,
             sourcePath: full,
-            relativePath: join11("fragments", entry.name),
+            relativePath: join18("fragments", entry.name),
             kind: "file",
             hash: await hashPath(full),
             packageName: resolved.packageName,
@@ -3285,16 +4382,16 @@ var LocalSourceDriver = class {
         }
       }
     }
-    const skillsDir = join11(root, "skills");
+    const skillsDir = join18(root, "skills");
     if (await pathExists(skillsDir)) {
       for (const entry of await sortedDirEntries(skillsDir)) {
-        const full = join11(skillsDir, entry.name);
+        const full = join18(skillsDir, entry.name);
         if (entry.isDirectory()) {
           artifacts.push({
             type: "skills",
             name: entry.name,
             sourcePath: full,
-            relativePath: join11("skills", entry.name),
+            relativePath: join18("skills", entry.name),
             kind: "dir",
             hash: await hashPath(full),
             packageName: resolved.packageName,
@@ -3305,7 +4402,7 @@ var LocalSourceDriver = class {
             type: "skills",
             name: entry.name.replace(/\.md$/, ""),
             sourcePath: full,
-            relativePath: join11("skills", entry.name),
+            relativePath: join18("skills", entry.name),
             kind: "file",
             hash: await hashPath(full),
             packageName: resolved.packageName,
@@ -3315,7 +4412,7 @@ var LocalSourceDriver = class {
       }
     }
     for (const type of ["commands", "subagents", "mcp", "hooks", "settings", "plugins"]) {
-      const dir = join11(root, type);
+      const dir = join18(root, type);
       if (!await pathExists(dir)) continue;
       artifacts.push(...await listGenericArtifacts(type, dir, type, resolved.packageName));
     }
@@ -3331,7 +4428,7 @@ var LocalSourceDriver = class {
       findings.push({ level: "warning", message: "No instructions.md or AGENTS.md found", path: resolved.resolvedPath });
     }
     for (const artifact of artifacts.filter((item) => item.type === "skills" && item.kind === "dir")) {
-      if (!await pathExists(join11(artifact.sourcePath, "SKILL.md"))) {
+      if (!await pathExists(join18(artifact.sourcePath, "SKILL.md"))) {
         findings.push({ level: "warning", message: `Skill directory has no SKILL.md: ${artifact.name}`, path: artifact.sourcePath });
       }
     }
@@ -3346,16 +4443,16 @@ var LocalSourceDriver = class {
 };
 async function hashLocalSource(root, manifest) {
   if (!manifest) return hashPath(root);
-  const hash = createHash3("sha256").update("local-openpack\0");
+  const hash = createHash4("sha256").update("local-openpack\0");
   const manifestPath = await findPackageManifestPath(root, { warnLegacy: false });
   if (manifestPath) {
     hash.update("manifest\0");
-    hash.update(relative3(root, manifestPath).replaceAll("\\", "/")).update("\0");
+    hash.update(relative4(root, manifestPath).replaceAll("\\", "/")).update("\0");
     hash.update(await hashPath(manifestPath)).update("\0");
   }
   const provides = [...manifest.provides].sort((a, b) => `${a.type}\0${a.path}`.localeCompare(`${b.type}\0${b.path}`));
   for (const provide of provides) {
-    const full = join11(root, provide.path);
+    const full = join18(root, provide.path);
     if (!await pathExists(full)) continue;
     hash.update("provide\0");
     hash.update(provide.type).update("\0");
@@ -3378,27 +4475,27 @@ async function listFromManifest(root, packageName) {
   if (!manifest) return [];
   const artifacts = [];
   for (const provide of manifest.provides) {
-    const full = join11(root, provide.path);
+    const full = join18(root, provide.path);
     if (!await pathExists(full)) continue;
     const stats = await stat3(full);
     if (provide.type === "instructions") {
       if (stats.isFile()) {
-        artifacts.push(await artifactForFile(provide.type, basename6(full), full, provide.path, packageName, provide, manifest, basename6(full)));
+        artifacts.push(await artifactForFile(provide.type, basename8(full), full, provide.path, packageName, provide, manifest, basename8(full)));
       }
       continue;
     }
     if (stats.isDirectory()) {
       for (const entry of await sortedDirEntries(full)) {
-        const child = join11(full, entry.name);
+        const child = join18(full, entry.name);
         if ((provide.type === "skills" || provide.type === "plugins" || provide.type === "subagents") && entry.isDirectory()) {
-          artifacts.push(await artifactForDir(provide.type, entry.name, child, join11(provide.path, entry.name), packageName, provide, manifest, entry.name));
+          artifacts.push(await artifactForDir(provide.type, entry.name, child, join18(provide.path, entry.name), packageName, provide, manifest, entry.name));
         } else if (entry.isFile()) {
           const name = provide.type === "rules" && entry.name.endsWith(".md") ? entry.name : entry.name;
-          artifacts.push(await artifactForFile(provide.type, name, child, join11(provide.path, entry.name), packageName, provide, manifest, name));
+          artifacts.push(await artifactForFile(provide.type, name, child, join18(provide.path, entry.name), packageName, provide, manifest, name));
         }
       }
     } else if (stats.isFile()) {
-      artifacts.push(await artifactForFile(provide.type, basename6(full), full, provide.path, packageName, provide, manifest, basename6(full)));
+      artifacts.push(await artifactForFile(provide.type, basename8(full), full, provide.path, packageName, provide, manifest, basename8(full)));
     }
   }
   return artifacts;
@@ -3406,11 +4503,11 @@ async function listFromManifest(root, packageName) {
 async function listGenericArtifacts(type, dir, relativeRoot, packageName) {
   const artifacts = [];
   for (const entry of await sortedDirEntries(dir)) {
-    const full = join11(dir, entry.name);
+    const full = join18(dir, entry.name);
     if (entry.isDirectory()) {
-      artifacts.push(await artifactForDir(type, entry.name, full, join11(relativeRoot, entry.name), packageName));
+      artifacts.push(await artifactForDir(type, entry.name, full, join18(relativeRoot, entry.name), packageName));
     } else if (entry.isFile()) {
-      artifacts.push(await artifactForFile(type, entry.name, full, join11(relativeRoot, entry.name), packageName));
+      artifacts.push(await artifactForFile(type, entry.name, full, join18(relativeRoot, entry.name), packageName));
     }
   }
   return artifacts;
@@ -3488,12 +4585,12 @@ var GitSourceDriver = class {
   async fetch(resolved) {
     return withFilesystemLock(`${resolved.resolvedPath}.lock`, resolved.cacheLockTimeoutMs ?? 3e4, async () => {
       const parsed = parseGitSource(resolved.source);
-      await mkdir8(resolve6(resolved.resolvedPath, ".."), { recursive: true });
-      if (!await pathExists(join12(resolved.resolvedPath, ".git"))) {
+      await mkdir9(resolve6(resolved.resolvedPath, ".."), { recursive: true });
+      if (!await pathExists(join19(resolved.resolvedPath, ".git"))) {
         if (resolved.frozenLock) {
           throw new Error(`Frozen lock requires cached git checkout at ${resolved.resolvedPath}`);
         }
-        await rm4(resolved.resolvedPath, { recursive: true, force: true });
+        await rm5(resolved.resolvedPath, { recursive: true, force: true });
         await git(["clone", "--no-tags", parsed.url, resolved.resolvedPath]);
       } else if (!resolved.frozenLock) {
         await git(["-C", resolved.resolvedPath, "fetch", "--prune", "origin"]);
@@ -3556,36 +4653,36 @@ function parseGitSource(source) {
   throw new Error(`Invalid git source: ${source}`);
 }
 function cachePathFor(url, cacheRoot) {
-  const root = cacheRoot ? resolve6(cacheRoot) : join12(homedir2(), ".agentwheel", "cache");
+  const root = cacheRoot ? resolve6(cacheRoot) : join19(homedir2(), ".agentwheel", "cache");
   const slug2 = url.replace(/^[a-z]+:\/\//i, "").replace(/\.git$/i, "").replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "");
-  return join12(root, slug2 || basename7(url));
+  return join19(root, slug2 || basename9(url));
 }
 async function git(args) {
   return execFileAsync4("git", args, { maxBuffer: 1024 * 1024 * 10 });
 }
 async function snapshotCheckout(checkoutPath, commit) {
-  const snapshotPath = join12(dirname9(checkoutPath), `${basename7(checkoutPath)}-${commit.slice(0, 12)}`);
+  const snapshotPath = join19(dirname11(checkoutPath), `${basename9(checkoutPath)}-${commit.slice(0, 12)}`);
   if (await pathExists(snapshotPath)) return snapshotPath;
-  const tempPath = join12(dirname9(checkoutPath), `${basename7(snapshotPath)}.tmp-${process.pid}-${Date.now()}`);
-  await rm4(tempPath, { recursive: true, force: true });
+  const tempPath = join19(dirname11(checkoutPath), `${basename9(snapshotPath)}.tmp-${process.pid}-${Date.now()}`);
+  await rm5(tempPath, { recursive: true, force: true });
   await cp2(checkoutPath, tempPath, { recursive: true, dereference: true });
-  await rm4(join12(tempPath, ".git"), { recursive: true, force: true });
+  await rm5(join19(tempPath, ".git"), { recursive: true, force: true });
   try {
     await rename3(tempPath, snapshotPath);
   } catch (error) {
     if (!isAlreadyExists2(error)) throw error;
-    await rm4(tempPath, { recursive: true, force: true });
+    await rm5(tempPath, { recursive: true, force: true });
     return snapshotPath;
   }
   return snapshotPath;
 }
 async function withFilesystemLock(lockPath, timeoutMs, fn) {
-  await mkdir8(dirname9(lockPath), { recursive: true });
+  await mkdir9(dirname11(lockPath), { recursive: true });
   const started = Date.now();
   while (true) {
     try {
-      await mkdir8(lockPath);
-      await writeFile9(join12(lockPath, "owner.json"), JSON.stringify({ pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() }), "utf8");
+      await mkdir9(lockPath);
+      await writeFile11(join19(lockPath, "owner.json"), JSON.stringify({ pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() }), "utf8");
       break;
     } catch (error) {
       if (!isAlreadyExists2(error)) throw error;
@@ -3598,7 +4695,7 @@ async function withFilesystemLock(lockPath, timeoutMs, fn) {
   try {
     return await fn();
   } finally {
-    await rm4(lockPath, { recursive: true, force: true });
+    await rm5(lockPath, { recursive: true, force: true });
   }
 }
 function isAlreadyExists2(error) {
@@ -3606,14 +4703,14 @@ function isAlreadyExists2(error) {
 }
 
 // src/source/skillkit.ts
-import { cp as cp3, mkdir as mkdir9, readFile as readFile11, rm as rm5 } from "fs/promises";
+import { cp as cp3, mkdir as mkdir10, readFile as readFile15, rm as rm6 } from "fs/promises";
 import { homedir as homedir3 } from "os";
-import { basename as basename9, dirname as dirname11, join as join14, resolve as resolve7 } from "path";
+import { basename as basename11, dirname as dirname13, join as join21, resolve as resolve7 } from "path";
 import * as defaultSkillKit from "@skillkit/core";
 
 // src/source/skill-artifacts.ts
 import { readdir as readdir2, stat as stat4 } from "fs/promises";
-import { basename as basename8, dirname as dirname10, extname as extname2, join as join13 } from "path";
+import { basename as basename10, dirname as dirname12, extname as extname2, join as join20 } from "path";
 async function artifactsFromSkillPaths(paths, packageName) {
   const artifacts = [];
   const seen = /* @__PURE__ */ new Set();
@@ -3635,28 +4732,28 @@ async function discoverSkillPaths(root) {
 async function artifactFromSkillPath(item, packageName) {
   const stats = await stat4(item.path);
   if (stats.isDirectory()) {
-    const skillMd = join13(item.path, "SKILL.md");
+    const skillMd = join20(item.path, "SKILL.md");
     if (!await pathExists(skillMd)) return void 0;
-    const name = sanitizeSkillName(item.name ?? basename8(item.path));
+    const name = sanitizeSkillName(item.name ?? basename10(item.path));
     return {
       type: "skills",
       name,
       sourcePath: item.path,
-      relativePath: join13("skills", name),
+      relativePath: join20("skills", name),
       kind: "dir",
       hash: await hashPath(item.path),
       packageName,
       channel: "managed"
     };
   }
-  if (stats.isFile() && basename8(item.path).toLowerCase() === "skill.md") {
-    const dir = dirname10(item.path);
-    const name = sanitizeSkillName(item.name ?? basename8(dir));
+  if (stats.isFile() && basename10(item.path).toLowerCase() === "skill.md") {
+    const dir = dirname12(item.path);
+    const name = sanitizeSkillName(item.name ?? basename10(dir));
     return {
       type: "skills",
       name,
       sourcePath: dir,
-      relativePath: join13("skills", name),
+      relativePath: join20("skills", name),
       kind: "dir",
       hash: await hashPath(dir),
       packageName,
@@ -3664,12 +4761,12 @@ async function artifactFromSkillPath(item, packageName) {
     };
   }
   if (stats.isFile() && extname2(item.path).toLowerCase() === ".md") {
-    const name = sanitizeSkillName(item.name ?? basename8(item.path, ".md"));
+    const name = sanitizeSkillName(item.name ?? basename10(item.path, ".md"));
     return {
       type: "skills",
       name,
       sourcePath: item.path,
-      relativePath: join13("skills", `${name}.md`),
+      relativePath: join20("skills", `${name}.md`),
       kind: "file",
       hash: await hashPath(item.path),
       packageName,
@@ -3687,7 +4784,7 @@ async function walk(dir, paths) {
   }
   for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
     if (!entry.isDirectory() || entry.name === ".git" || entry.name === "node_modules") continue;
-    await walk(join13(dir, entry.name), paths);
+    await walk(join20(dir, entry.name), paths);
   }
 }
 function sanitizeSkillName(name) {
@@ -3709,7 +4806,7 @@ var SkillKitSourceDriver = class {
         driver: this.name,
         source,
         resolvedPath,
-        packageName: `skillkit/${basename9(resolvedPath)}`,
+        packageName: `skillkit/${basename11(resolvedPath)}`,
         mode: options.mode ?? "pinned",
         sourceHash: await hashPath(resolvedPath)
       };
@@ -3743,17 +4840,17 @@ var SkillKitSourceDriver = class {
     if (!provider?.clone) {
       throw new Error("SkillKit provider API unavailable or cannot resolve source. Expected @skillkit/core detectProvider().clone().");
     }
-    await mkdir9(dirname11(resolved.resolvedPath), { recursive: true });
+    await mkdir10(dirname13(resolved.resolvedPath), { recursive: true });
     const result = await provider.clone(providerSpec, resolved.resolvedPath, {});
     if (!result.success || !result.path) {
       throw new Error(`SkillKit provider failed to fetch ${spec}: ${result.error ?? "unknown error"}`);
     }
     if (resolve7(result.path) !== resolve7(resolved.resolvedPath)) {
-      await rm5(resolved.resolvedPath, { recursive: true, force: true });
+      await rm6(resolved.resolvedPath, { recursive: true, force: true });
       await cp3(result.path, resolved.resolvedPath, { recursive: true, dereference: true });
     }
     if (result.tempRoot) {
-      await rm5(result.tempRoot, { recursive: true, force: true });
+      await rm6(result.tempRoot, { recursive: true, force: true });
     }
     return {
       ...resolved,
@@ -3787,9 +4884,9 @@ var SkillKitSourceDriver = class {
       throw new Error("SkillKit translateSkill API unavailable");
     }
     for (const skill of this.discover(resolved.resolvedPath)) {
-      const skillMd = join14(skill.path, "SKILL.md");
+      const skillMd = join21(skill.path, "SKILL.md");
       if (await pathExists(skillMd)) {
-        this.core.translateSkill(await readFile11(skillMd, "utf8"), "openclaw", { sourceFilename: "SKILL.md" });
+        this.core.translateSkill(await readFile15(skillMd, "utf8"), "openclaw", { sourceFilename: "SKILL.md" });
       }
     }
     return resolved;
@@ -3818,8 +4915,8 @@ function normalizeProviderSource(spec) {
   return spec;
 }
 function cachePathFor2(spec, cacheRoot) {
-  const root = cacheRoot ? resolve7(cacheRoot) : join14(homedir3(), ".agentwheel", "cache");
-  return join14(root, "skillkit", packageSlug(spec));
+  const root = cacheRoot ? resolve7(cacheRoot) : join21(homedir3(), ".agentwheel", "cache");
+  return join21(root, "skillkit", packageSlug(spec));
 }
 function packageSlug(spec) {
   return spec.replace(/^[a-z]+:\/\//i, "").replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "") || "source";
@@ -3832,7 +4929,7 @@ function mapSeverity(severity) {
 
 // src/source/vercel-skills.ts
 import { stat as stat5 } from "fs/promises";
-import { basename as basename10, join as join15, resolve as resolve8 } from "path";
+import { basename as basename12, join as join22, resolve as resolve8 } from "path";
 var VercelSkillsSourceDriver = class {
   name = "vercel-skills";
   git = new GitSourceDriver();
@@ -3847,7 +4944,7 @@ var VercelSkillsSourceDriver = class {
         driver: this.name,
         source,
         resolvedPath,
-        packageName: `vercel/${basename10(resolvedPath)}`,
+        packageName: `vercel/${basename12(resolvedPath)}`,
         mode: options.mode ?? "pinned",
         sourceHash: await hashPath(resolvedPath)
       };
@@ -3868,7 +4965,7 @@ var VercelSkillsSourceDriver = class {
       driver: "git",
       source: parsed.gitSource
     });
-    const resolvedPath = parsed.subpath ? join15(fetched.resolvedPath, parsed.subpath) : fetched.resolvedPath;
+    const resolvedPath = parsed.subpath ? join22(fetched.resolvedPath, parsed.subpath) : fetched.resolvedPath;
     if (!await pathExists(resolvedPath)) {
       throw new Error(`Vercel skills subpath not found: ${parsed.subpath}`);
     }
@@ -3957,14 +5054,14 @@ function getSourceDriver(name = "local") {
 }
 
 // src/staging/staging.ts
-import { chmod, cp as cp5, mkdir as mkdir11, mkdtemp as mkdtemp2, readdir as readdir5, stat as stat8 } from "fs/promises";
-import { basename as basename13, dirname as dirname14, join as join18, relative as relative5, resolve as resolve10, sep as sep2 } from "path";
-import { tmpdir as tmpdir3 } from "os";
+import { chmod, cp as cp5, mkdir as mkdir12, mkdtemp as mkdtemp3, readdir as readdir5, stat as stat8 } from "fs/promises";
+import { basename as basename15, dirname as dirname16, join as join25, relative as relative6, resolve as resolve10, sep as sep2 } from "path";
+import { tmpdir as tmpdir4 } from "os";
 
 // src/compose/markdown.ts
-import { createHash as createHash4 } from "crypto";
-import { readdir as readdir3, readFile as readFile12, stat as stat6, writeFile as writeFile10 } from "fs/promises";
-import { basename as basename11, dirname as dirname12, extname as extname3, join as join16, relative as relative4, resolve as resolve9, sep } from "path";
+import { createHash as createHash5 } from "crypto";
+import { readdir as readdir3, readFile as readFile16, stat as stat6, writeFile as writeFile12 } from "fs/promises";
+import { basename as basename13, dirname as dirname14, extname as extname3, join as join23, relative as relative5, resolve as resolve9, sep } from "path";
 var includePattern = /<!--\s*openpack:include(\?)?\s+([^>]+?)\s*-->/g;
 var escapedIncludePattern = /<!--\s*openpack\\:include(\?)?\s+([^>]+?)\s*-->/g;
 var generatedPattern = /<!--\s*(?:BEGIN|END)\s+openpack:include\b/;
@@ -3979,7 +5076,7 @@ async function expandMarkdownIncludes(artifacts, packageRoot, options = {}) {
     const composedFrom = [];
     for (const file of files) {
       const result = await expandFile(file, packageRoot, composeEntriesForFile(artifact, file), artifactPaths, options);
-      if (result.changed) await writeFile10(file, result.content, "utf8");
+      if (result.changed) await writeFile12(file, result.content, "utf8");
       composedFrom.push(...result.composedFrom);
     }
     const stagedPath = artifact.stagedPath ?? artifact.sourcePath;
@@ -4001,7 +5098,7 @@ async function validateMarkdownIncludes(artifacts, packageRoot, options = {}) {
   }
 }
 async function expandFile(file, packageRoot, appendEntries, artifactPaths, options) {
-  const raw = await readFile12(file, "utf8");
+  const raw = await readFile16(file, "utf8");
   const owner = ownerSelector(packageRoot, file, options.nodeId);
   const expanded = await expandContent(raw, packageRoot, [owner], artifactPaths, options);
   let content = expanded.content;
@@ -4094,7 +5191,7 @@ async function expandInclude(selector, packageRoot, artifactPaths, options) {
   if (!stats.isFile()) {
     throw new Error(`OpenPack include is not a file: ${displaySelector}`);
   }
-  const raw = sourceContent ?? await readFile12(sourcePath, "utf8");
+  const raw = sourceContent ?? await readFile16(sourcePath, "utf8");
   const { optional: _optional, markers: _markers, chain: _chain, ...childOptions } = options;
   const expanded = await expandContent(raw, includePackageRoot, [...options.chain, displaySelector], includeArtifactPaths, {
     ...childOptions,
@@ -4170,7 +5267,7 @@ async function listMarkdownFiles(root) {
   const out = [];
   async function walk2(dir) {
     for (const entry of (await readdir3(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
-      const full = join16(dir, entry.name);
+      const full = join23(dir, entry.name);
       if (entry.isDirectory()) {
         await walk2(full);
       } else if (entry.isFile() && extname3(entry.name).toLowerCase() === ".md") {
@@ -4184,7 +5281,7 @@ async function listMarkdownFiles(root) {
 function composeEntriesForFile(artifact, file) {
   if (!artifact.compose?.length) return [];
   if (artifact.kind === "file") return [resolve9(artifact.stagedPath ?? artifact.sourcePath), resolve9(file)].every(Boolean) && resolve9(artifact.stagedPath ?? artifact.sourcePath) === resolve9(file) ? artifact.compose : [];
-  return basename11(file) === "SKILL.md" && dirname12(file) === resolve9(artifact.stagedPath ?? artifact.sourcePath) ? artifact.compose : [];
+  return basename13(file) === "SKILL.md" && dirname14(file) === resolve9(artifact.stagedPath ?? artifact.sourcePath) ? artifact.compose : [];
 }
 function orderedForExpansion(artifacts) {
   return [...artifacts].sort((a, b) => Number(a.type === "fragments") - Number(b.type === "fragments"));
@@ -4201,7 +5298,7 @@ function applyReplacements(content, replacements) {
   return out + content.slice(cursor);
 }
 function relativeSelector(root, file) {
-  return relative4(root, file).replaceAll("\\", "/");
+  return relative5(root, file).replaceAll("\\", "/");
 }
 function ownerSelector(root, file, nodeId) {
   const selector = relativeSelector(root, file);
@@ -4215,7 +5312,7 @@ function cleanSelector(value) {
   return value.trim().replace(/\s+/g, " ");
 }
 function sha256(content) {
-  return createHash4("sha256").update(content).digest("hex");
+  return createHash5("sha256").update(content).digest("hex");
 }
 function uniqueComposedFrom(entries) {
   if (entries.length === 0) return [];
@@ -4230,8 +5327,8 @@ function artifactPathMap(artifacts) {
 }
 
 // src/staging/customize.ts
-import { cp as cp4, mkdir as mkdir10, readdir as readdir4, readFile as readFile13, writeFile as writeFile11 } from "fs/promises";
-import { dirname as dirname13, join as join17 } from "path";
+import { cp as cp4, mkdir as mkdir11, readdir as readdir4, readFile as readFile17, writeFile as writeFile13 } from "fs/promises";
+import { dirname as dirname15, join as join24 } from "path";
 async function applyCustomizations(artifacts, options) {
   let next = [...artifacts];
   next = await applyReplacements2(next, options, "override", installableArtifactTypes());
@@ -4247,16 +5344,16 @@ async function applyFragmentCustomizations(artifacts, options) {
   return next.sort((a, b) => `${a.type}:${a.name}:${a.channel}`.localeCompare(`${b.type}:${b.name}:${b.channel}`));
 }
 async function applyInstructionOverlay(artifacts, options) {
-  const overlayPath = join17(options.workspaceRoot, ".agentwheel", "overlays", options.adapter.name, "instructions.local.md");
+  const overlayPath = join24(options.workspaceRoot, ".agentwheel", "overlays", options.adapter.name, "instructions.local.md");
   if (!await pathExists(overlayPath)) return artifacts;
   const index = artifacts.findIndex((artifact2) => artifact2.type === "instructions");
   if (index < 0) return artifacts;
   const artifact = artifacts[index];
-  const managed = await readFile13(artifact.stagedPath ?? artifact.sourcePath, "utf8");
-  const local = await readFile13(overlayPath, "utf8");
-  const composedPath = join17(options.stageRoot, ".agentwheel-composed", "instructions", "AGENTS.md");
-  await mkdir10(dirname13(composedPath), { recursive: true });
-  await writeFile11(
+  const managed = await readFile17(artifact.stagedPath ?? artifact.sourcePath, "utf8");
+  const local = await readFile17(overlayPath, "utf8");
+  const composedPath = join24(options.stageRoot, ".agentwheel-composed", "instructions", "AGENTS.md");
+  await mkdir11(dirname15(composedPath), { recursive: true });
+  await writeFile13(
     composedPath,
     [
       "<!-- BEGIN agentwheel managed: upstream -->",
@@ -4282,19 +5379,19 @@ async function applyInstructionOverlay(artifacts, options) {
   return [...artifacts.slice(0, index), updated, ...artifacts.slice(index + 1)];
 }
 async function applyAdditions(artifacts, options) {
-  const additionsRoot = join17(options.workspaceRoot, ".agentwheel", "additions");
-  const rulesRoot = join17(additionsRoot, "rules");
+  const additionsRoot = join24(options.workspaceRoot, ".agentwheel", "additions");
+  const rulesRoot = join24(additionsRoot, "rules");
   if (!await pathExists(rulesRoot)) return artifacts;
   const additions = [];
   for (const entry of await sortedDirEntries2(rulesRoot)) {
-    const full = join17(rulesRoot, entry.name);
+    const full = join24(rulesRoot, entry.name);
     if (!entry.isFile()) continue;
     additions.push({
       type: "rules",
       name: entry.name,
       sourcePath: full,
       stagedPath: full,
-      relativePath: join17("additions", "rules", entry.name),
+      relativePath: join24("additions", "rules", entry.name),
       kind: "file",
       hash: await hashPath(full),
       packageName: options.packageName,
@@ -4318,17 +5415,17 @@ async function applyReplacements2(artifacts, options, channel, artifactTypes) {
       );
     }
     for (const type of artifactTypes) {
-      const typeRoot = join17(root, type);
+      const typeRoot = join24(root, type);
       if (!await pathExists(typeRoot)) continue;
       for (const entry of await sortedDirEntries2(typeRoot)) {
         const artifactMapKey = `${type}:${entry.name}`;
         if (seen.has(artifactMapKey)) continue;
         seen.add(artifactMapKey);
-        const full = join17(typeRoot, entry.name);
+        const full = join24(typeRoot, entry.name);
         const artifactKind = entry.isDirectory() ? "dir" : "file";
         const existing = byKey.get(artifactMapKey);
-        const stagedPath = join17(options.stageRoot, ".agentwheel-composed", channel, type, entry.name);
-        await mkdir10(dirname13(stagedPath), { recursive: true });
+        const stagedPath = join24(options.stageRoot, ".agentwheel-composed", channel, type, entry.name);
+        await mkdir11(dirname15(stagedPath), { recursive: true });
         await cp4(full, stagedPath, { recursive: artifactKind === "dir", dereference: true });
         byKey.set(artifactMapKey, {
           ...existing,
@@ -4336,7 +5433,7 @@ async function applyReplacements2(artifacts, options, channel, artifactTypes) {
           name: entry.name,
           sourcePath: full,
           stagedPath,
-          relativePath: existing?.relativePath ?? join17(type, entry.name),
+          relativePath: existing?.relativePath ?? join24(type, entry.name),
           kind: artifactKind,
           hash: await hashPath(stagedPath),
           packageName,
@@ -4351,13 +5448,13 @@ function replacementRoots(options, channel) {
   const stateDir = channel === "override" ? "overrides" : "ejected";
   const roots = [];
   if (options.graphNodeId) {
-    roots.push({ root: join17(options.workspaceRoot, ".agentwheel", stateDir, ...options.graphNodeId.split("/")), kind: "node" });
+    roots.push({ root: join24(options.workspaceRoot, ".agentwheel", stateDir, ...options.graphNodeId.split("/")), kind: "node" });
   }
   if (options.packageName && options.packageVersion) {
-    roots.push({ root: join17(options.workspaceRoot, ".agentwheel", stateDir, ...`${options.packageName}@${options.packageVersion}`.split("/")), kind: "version" });
+    roots.push({ root: join24(options.workspaceRoot, ".agentwheel", stateDir, ...`${options.packageName}@${options.packageVersion}`.split("/")), kind: "version" });
   }
   if (options.packageName) {
-    roots.push({ root: join17(options.workspaceRoot, ".agentwheel", stateDir, ...options.packageName.split("/")), kind: "package" });
+    roots.push({ root: join24(options.workspaceRoot, ".agentwheel", stateDir, ...options.packageName.split("/")), kind: "package" });
   }
   return roots;
 }
@@ -4371,56 +5468,6 @@ async function sortedDirEntries2(path) {
   return (await readdir4(path, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
 }
 
-// src/model/selection.ts
-function artifactSelectorKey(artifact) {
-  return `${artifact.type}/${artifact.name}`;
-}
-function artifactSelectorAliases(artifact) {
-  const primary = artifactSelectorKey(artifact);
-  if (artifact.type !== "subagents") return [primary];
-  const baseName = subagentBaseName(artifact.name);
-  if (baseName === artifact.name) return [primary];
-  return [primary, `subagents/${baseName}`];
-}
-function normalizeArtifactSelectors(select, legacySkills) {
-  const selected = [
-    ...select ?? [],
-    ...(legacySkills ?? []).map((name) => `skills/${name}`)
-  ].flatMap(splitSelectorList);
-  if (selected.length === 0) return void 0;
-  return [...new Set(selected.map(parseArtifactSelector))];
-}
-function filterArtifactsBySelection(artifacts, selectors, legacySkills) {
-  const selected = normalizeArtifactSelectors(selectors, legacySkills);
-  if (!selected?.length) return artifacts;
-  const selectedSet = new Set(selected);
-  const available = new Set(artifacts.flatMap(artifactSelectorAliases));
-  const missing = selected.filter((selector) => !available.has(selector));
-  if (missing.length > 0) {
-    throw new Error(`Selected artifact not found in package: ${missing.join(", ")}`);
-  }
-  return artifacts.filter((artifact) => artifact.required || artifactSelectorAliases(artifact).some((selector) => selectedSet.has(selector)));
-}
-function splitSelectorList(value) {
-  return value.split(",").map((item) => item.trim()).filter(Boolean);
-}
-function parseArtifactSelector(value) {
-  const slash = value.indexOf("/");
-  if (slash <= 0 || slash === value.length - 1) {
-    throw new Error(`Invalid artifact selector: ${value}. Expected <type>/<name>.`);
-  }
-  const type = value.slice(0, slash);
-  const name = value.slice(slash + 1);
-  const parsedType = artifactTypeSchema.safeParse(type);
-  if (!parsedType.success) {
-    throw new Error(`Invalid artifact selector type: ${type}`);
-  }
-  return `${parsedType.data}/${name}`;
-}
-function subagentBaseName(name) {
-  return name.replace(/\.agent\.md$/i, "").replace(/\.toml$/i, "").replace(/\.md$/i, "");
-}
-
 // src/staging/staging.ts
 async function stageSource(driver, source, options = {}) {
   return renderStagedBundle(await stageSourceRaw(driver, source, options), options);
@@ -4434,15 +5481,15 @@ async function stageResolvedSourceRaw(driver, resolved) {
   return stageResolvedArtifactsRaw(resolved, artifacts);
 }
 async function stageResolvedArtifactsRaw(resolved, artifacts) {
-  const root = await mkdtemp2(join18(tmpdir3(), "agentwheel-stage-"));
+  const root = await mkdtemp3(join25(tmpdir4(), "agentwheel-stage-"));
   const stagedArtifacts = [];
   for (const artifact of artifacts) {
-    const stagedPath = join18(root, artifact.relativePath);
-    await mkdir11(dirname14(stagedPath), { recursive: true });
+    const stagedPath = join25(root, artifact.relativePath);
+    await mkdir12(dirname16(stagedPath), { recursive: true });
     await cp5(artifact.sourcePath, stagedPath, {
       recursive: artifact.kind === "dir",
       dereference: true,
-      filter: (path) => !isIgnoredGeneratedEntry(basename13(path))
+      filter: (path) => !isIgnoredGeneratedEntry(basename15(path))
     });
     await composeAssets(artifact, resolved.resolvedPath, stagedPath);
     stagedArtifacts.push({
@@ -4523,16 +5570,16 @@ async function composeAssets(artifact, packageRoot, stagedPath) {
   }
   for (const asset of artifact.assets) {
     const source = resolvePackagePath(packageRoot, asset.from);
-    const dest = join18(stagedPath, asset.into);
+    const dest = join25(stagedPath, asset.into);
     await copyAsset(asset, source, dest);
   }
 }
 async function copyAsset(asset, source, dest) {
   const sourceStats = await stat8(source);
   if (sourceStats.isFile()) {
-    if (matchesAny(basename13(source), asset.include)) {
-      await mkdir11(dest, { recursive: true });
-      await copyAssetFile(source, join18(dest, basename13(source)), asset);
+    if (matchesAny(basename15(source), asset.include)) {
+      await mkdir12(dest, { recursive: true });
+      await copyAssetFile(source, join25(dest, basename15(source)), asset);
     }
     return;
   }
@@ -4540,19 +5587,19 @@ async function copyAsset(asset, source, dest) {
     throw new Error(`Asset include source is not a file or directory: ${source}`);
   }
   if (!asset.include?.length) {
-    await mkdir11(dirname14(dest), { recursive: true });
+    await mkdir12(dirname16(dest), { recursive: true });
     await cp5(source, dest, { recursive: true, dereference: true });
     if (asset.mode === "copy") await normalizeCopiedModes(dest);
     return;
   }
   for (const file of await listFiles(source)) {
-    const rel = relative5(source, file).replaceAll("\\", "/");
-    if (!matchesAny(rel, asset.include) && !matchesAny(basename13(file), asset.include)) continue;
-    await copyAssetFile(file, join18(dest, rel), asset);
+    const rel = relative6(source, file).replaceAll("\\", "/");
+    if (!matchesAny(rel, asset.include) && !matchesAny(basename15(file), asset.include)) continue;
+    await copyAssetFile(file, join25(dest, rel), asset);
   }
 }
 async function copyAssetFile(source, dest, asset) {
-  await mkdir11(dirname14(dest), { recursive: true });
+  await mkdir12(dirname16(dest), { recursive: true });
   await cp5(source, dest, { dereference: true });
   if (asset.mode === "copy") await chmod(dest, 420);
 }
@@ -4568,7 +5615,7 @@ async function listFiles(root) {
   const out = [];
   async function walk2(dir) {
     for (const entry of (await readdir5(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
-      const full = join18(dir, entry.name);
+      const full = join25(dir, entry.name);
       if (entry.isDirectory()) {
         await walk2(full);
       } else if (entry.isFile()) {
@@ -4587,7 +5634,7 @@ async function normalizeCopiedModes(path) {
   }
   if (!stats.isDirectory()) return;
   for (const entry of await readdir5(path, { withFileTypes: true })) {
-    await normalizeCopiedModes(join18(path, entry.name));
+    await normalizeCopiedModes(join25(path, entry.name));
   }
 }
 function matchesAny(path, patterns) {
@@ -4600,9 +5647,9 @@ function matchesGlob(path, pattern) {
 }
 
 // src/model/workspace.ts
-import { readFile as readFile14 } from "fs/promises";
+import { readFile as readFile18 } from "fs/promises";
 import { homedir as homedir4 } from "os";
-import { dirname as dirname15, join as join19, resolve as resolve11 } from "path";
+import { dirname as dirname17, join as join26, resolve as resolve11 } from "path";
 import { z as z6 } from "zod";
 var workspacePackageSchema = z6.object({
   name: z6.string().min(1),
@@ -4671,12 +5718,12 @@ var workspaceConfigSchema = z6.object({
   agents: z6.record(z6.string(), workspaceAgentSchema).default({})
 });
 function workspaceConfigPath(workspaceRoot) {
-  return join19(workspaceRoot, ".agentwheel", "config.json");
+  return join26(workspaceRoot, ".agentwheel", "config.json");
 }
 async function readWorkspaceConfig(workspaceRoot) {
   const path = workspaceConfigPath(workspaceRoot);
   if (!await pathExists(path)) return emptyWorkspaceConfig();
-  return workspaceConfigSchema.parse(JSON.parse(await readFile14(path, "utf8")));
+  return workspaceConfigSchema.parse(JSON.parse(await readFile18(path, "utf8")));
 }
 async function writeWorkspaceConfig(workspaceRoot, config) {
   await writeJsonAtomic(workspaceConfigPath(workspaceRoot), workspaceConfigSchema.parse(config));
@@ -4689,13 +5736,13 @@ function upsertPackage(config, entry) {
   return { schemaVersion: 1, packages, bootstrapSkills: parsed.bootstrapSkills, registry: parsed.registry ?? {}, trust: parsed.trust ?? {}, profiles: parsed.profiles ?? {}, agents: parsed.agents ?? {} };
 }
 function globalWorkspaceConfigPath(globalRoot = homedir4()) {
-  return join19(globalRoot, ".agentwheel", "config.json");
+  return join26(globalRoot, ".agentwheel", "config.json");
 }
 async function findWorkspaceRoot(start = process.cwd()) {
   let current = resolve11(start);
   while (true) {
     if (await pathExists(workspaceConfigPath(current))) return current;
-    const parent = dirname15(current);
+    const parent = dirname17(current);
     if (parent === current) return resolve11(start);
     current = parent;
   }
@@ -4731,7 +5778,7 @@ function emptyWorkspaceConfig() {
 }
 async function readConfigPath(path) {
   if (!await pathExists(path)) return emptyWorkspaceConfig();
-  return workspaceConfigSchema.parse(JSON.parse(await readFile14(path, "utf8")));
+  return workspaceConfigSchema.parse(JSON.parse(await readFile18(path, "utf8")));
 }
 function mergeWorkspaceTrust(global, project) {
   return {
@@ -4746,23 +5793,23 @@ function sortedUnique2(values) {
 }
 
 // src/lifecycle/customization.ts
-import { appendFile, cp as cp6, mkdir as mkdir12, rm as rm7 } from "fs/promises";
-import { dirname as dirname17, join as join22 } from "path";
+import { appendFile, cp as cp6, mkdir as mkdir13, rm as rm8 } from "fs/promises";
+import { dirname as dirname19, join as join29 } from "path";
 
 // src/resolve/graph.ts
-import { createHash as createHash5 } from "crypto";
-import { mkdtemp as mkdtemp3, readdir as readdir6, readFile as readFile16, stat as stat10 } from "fs/promises";
-import { tmpdir as tmpdir4 } from "os";
-import { basename as basename14, extname as extname4, join as join21 } from "path";
+import { createHash as createHash6 } from "crypto";
+import { mkdtemp as mkdtemp4, readdir as readdir6, readFile as readFile20, stat as stat10 } from "fs/promises";
+import { tmpdir as tmpdir5 } from "os";
+import { basename as basename16, extname as extname4, join as join28 } from "path";
 
 // src/resolve/identity.ts
 import { homedir as homedir6 } from "os";
 import { resolve as resolve13 } from "path";
 
 // src/registry/client.ts
-import { readFile as readFile15, rm as rm6, stat as stat9 } from "fs/promises";
+import { readFile as readFile19, rm as rm7, stat as stat9 } from "fs/promises";
 import { homedir as homedir5 } from "os";
-import { dirname as dirname16, join as join20, resolve as resolve12 } from "path";
+import { dirname as dirname18, join as join27, resolve as resolve12 } from "path";
 import { fileURLToPath } from "url";
 
 // src/model/registry.ts
@@ -4837,7 +5884,7 @@ var RegistryClient = class {
     );
   }
   async clearCache() {
-    await rm6(this.cachePath, { force: true });
+    await rm7(this.cachePath, { force: true });
   }
   async getSources() {
     if (this.options.sources?.length) return this.options.sources;
@@ -4860,7 +5907,7 @@ var RegistryClient = class {
   }
   async readCache() {
     if (!await pathExists(this.cachePath)) return void 0;
-    return registryCacheSchema.parse(JSON.parse(await readFile15(this.cachePath, "utf8")));
+    return registryCacheSchema.parse(JSON.parse(await readFile19(this.cachePath, "utf8")));
   }
   isExpired(cache, ttlMs) {
     return this.now().getTime() - new Date(cache.fetchedAt).getTime() > ttlMs;
@@ -4879,10 +5926,10 @@ var RegistryClient = class {
     if (await pathExists(filePath)) {
       const fullPath = resolve12(filePath);
       const stats = await stat9(fullPath);
-      return readFile15(stats.isDirectory() ? join20(fullPath, "index.json") : fullPath, "utf8");
+      return readFile19(stats.isDirectory() ? join27(fullPath, "index.json") : fullPath, "utf8");
     }
-    const resolved = await this.git.fetch(await this.git.resolve(source, { cacheRoot: join20(dirname16(this.cachePath), "registry-repos") }));
-    return readFile15(join20(resolved.resolvedPath, "index.json"), "utf8");
+    const resolved = await this.git.fetch(await this.git.resolve(source, { cacheRoot: join27(dirname18(this.cachePath), "registry-repos") }));
+    return readFile19(join27(resolved.resolvedPath, "index.json"), "utf8");
   }
   warnCompatibility(entries) {
     for (const entry of entries) {
@@ -4917,7 +5964,7 @@ function mergeIndexes(indexes) {
   return [...merged.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 function defaultRegistryCachePath() {
-  return join20(homedir5(), ".agentwheel", "registry-cache.json");
+  return join27(homedir5(), ".agentwheel", "registry-cache.json");
 }
 function sameSources(a, b) {
   return a.length === b.length && a.every((source, index) => source === b[index]);
@@ -5146,7 +6193,7 @@ function compareSemver(a, b) {
 var cacheLocks = /* @__PURE__ */ new Map();
 async function resolveDependencyGraph(roots, options) {
   if (roots.length === 0) throw new Error("At least one graph root is required.");
-  const graphRoot = await mkdtemp3(join21(tmpdir4(), "agentwheel-graph-"));
+  const graphRoot = await mkdtemp4(join28(tmpdir5(), "agentwheel-graph-"));
   const fetchCache = /* @__PURE__ */ new Map();
   const nodesByKey = /* @__PURE__ */ new Map();
   const rootResults = [];
@@ -5508,7 +6555,7 @@ async function collectIncludeNeeds(artifact, artifactsByRelativePath) {
     const file = stack.shift();
     if (scanned.has(file)) continue;
     scanned.add(file);
-    const content = await readFile16(file, "utf8");
+    const content = await readFile20(file, "utf8");
     for (const include of extractOpenPackIncludeSelectors(content)) {
       await collectIncludeSelector(include.raw, include.optional, artifactsByRelativePath, scanned, stack, needs);
     }
@@ -5551,7 +6598,7 @@ async function listMarkdownFiles2(root) {
   const out = [];
   async function walk2(dir) {
     for (const entry of (await readdir6(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
-      const full = join21(dir, entry.name);
+      const full = join28(dir, entry.name);
       if (entry.isDirectory()) {
         await walk2(full);
       } else if (entry.isFile() && extname4(entry.name).toLowerCase() === ".md") {
@@ -5586,7 +6633,7 @@ async function fetchPackage(normalized, mode, options, fetchCache, refOverride)
   const promise = (async () => {
     const driver = getSourceDriver(normalized.driver);
     const resolved = await driver.resolve(normalized.source, {
-      cacheRoot: options.cacheRoot ?? join21(options.workspaceRoot, ".agentwheel", "cache"),
+      cacheRoot: options.cacheRoot ?? join28(options.workspaceRoot, ".agentwheel", "cache"),
       mode,
       ref: refOverride ?? normalized.requestedRef,
       frozenLock: hardLockedCheckout
@@ -5596,7 +6643,7 @@ async function fetchPackage(normalized, mode, options, fetchCache, refOverride)
     const exported = await driver.export(translated);
     const manifest = await readPackageManifest(exported.resolvedPath);
     const artifacts = await driver.list(exported);
-    const name = manifest?.name ?? exported.packageName ?? basename14(exported.resolvedPath);
+    const name = manifest?.name ?? exported.packageName ?? basename16(exported.resolvedPath);
     const version = manifest?.version ?? exported.packageVersion ?? "0.0.0";
     const sourceHash = exported.sourceHash ?? await hashPath(exported.resolvedPath);
     return {
@@ -5772,7 +6819,7 @@ function detectDirectCollisions(nodes) {
   }
 }
 function graphNodeId(name, version, normalizedSource, resolvedCommit, sourceHash) {
-  const digest = createHash5("sha256").update(normalizedSource).update("\0").update(resolvedCommit ?? sourceHash).digest("hex").slice(0, 12);
+  const digest = createHash6("sha256").update(normalizedSource).update("\0").update(resolvedCommit ?? sourceHash).digest("hex").slice(0, 12);
   return `${name}@${version}+${digest}`;
 }
 function sortedUnique3(values) {
@@ -5793,8 +6840,8 @@ async function mapLimit(items, limit, fn) {
 
 // src/lifecycle/customization.ts
 async function remember(workspaceRoot, runtime, text) {
-  const overlayPath = join22(workspaceRoot, ".agentwheel", "overlays", runtime, "instructions.local.md");
-  await mkdir12(dirname17(overlayPath), { recursive: true });
+  const overlayPath = join29(workspaceRoot, ".agentwheel", "overlays", runtime, "instructions.local.md");
+  await mkdir13(dirname19(overlayPath), { recursive: true });
   await appendFile(overlayPath, `${text.trim()}
 `, "utf8");
   return { overlayPath };
@@ -5817,9 +6864,9 @@ async function ejectArtifact(workspaceRoot, item) {
       throw new Error(`Artifact not found: ${item}`);
     }
     const ejectedIdentity = parsed.packageIdentity === parsed.packageName ? parsed.packageIdentity : candidate.nodeId === parsed.packageIdentity ? candidate.nodeId : `${candidate.packageName}@${candidate.packageVersion}`;
-    const ejectedPath = join22(workspaceRoot, ".agentwheel", "ejected", ...ejectedIdentity.split("/"), parsed.type, parsed.name);
-    await mkdir12(dirname17(ejectedPath), { recursive: true });
-    await rm7(ejectedPath, { recursive: true, force: true });
+    const ejectedPath = join29(workspaceRoot, ".agentwheel", "ejected", ...ejectedIdentity.split("/"), parsed.type, parsed.name);
+    await mkdir13(dirname19(ejectedPath), { recursive: true });
+    await rm8(ejectedPath, { recursive: true, force: true });
     await cp6(artifact.stagedPath ?? artifact.sourcePath, ejectedPath, { recursive: artifact.kind === "dir", dereference: true });
     return {
       ...parsed,
@@ -5830,7 +6877,7 @@ async function ejectArtifact(workspaceRoot, item) {
       ejectedPath
     };
   } finally {
-    await Promise.all(candidates.map((candidate) => rm7(candidate.bundle.root, { recursive: true, force: true })));
+    await Promise.all(candidates.map((candidate) => rm8(candidate.bundle.root, { recursive: true, force: true })));
   }
 }
 function parseEjectItem(item) {
@@ -5860,7 +6907,7 @@ async function stageEjectCandidate(workspaceRoot, pkg) {
   const adapter = pkg.adapterConfig ? await loadAdapterConfig(pkg.adapterConfig) : getAdapter(pkg.adapter);
   const bundle = await stageSource(driver, normalized.source, {
     adapter,
-    cacheRoot: join22(workspaceRoot, ".agentwheel", "cache"),
+    cacheRoot: join29(workspaceRoot, ".agentwheel", "cache"),
     mode: pkg.mode,
     ref: normalized.requestedRef ?? pkg.requestedRef
   });
@@ -5907,12 +6954,12 @@ function ejectCommands(candidates, parsed) {
 }
 
 // src/lifecycle/profile.ts
-import { rm as rm8 } from "fs/promises";
+import { rm as rm9 } from "fs/promises";
 
 // src/lifecycle/source-plan.ts
-import { createHash as createHash7 } from "crypto";
-import { mkdir as mkdir14 } from "fs/promises";
-import { dirname as dirname19, join as join25, resolve as resolve14 } from "path";
+import { createHash as createHash8 } from "crypto";
+import { mkdir as mkdir15 } from "fs/promises";
+import { dirname as dirname21, join as join32, resolve as resolve14 } from "path";
 
 // src/resolve/graph-diff.ts
 function diffGraphLocks(previous, next) {
@@ -6033,12 +7080,12 @@ function short(hash) {
 }
 
 // src/resolve/render.ts
-import { createHash as createHash6 } from "crypto";
-import { readFile as readFile17, mkdtemp as mkdtemp4 } from "fs/promises";
-import { tmpdir as tmpdir5 } from "os";
-import { join as join23 } from "path";
+import { createHash as createHash7 } from "crypto";
+import { readFile as readFile21, mkdtemp as mkdtemp5 } from "fs/promises";
+import { tmpdir as tmpdir6 } from "os";
+import { join as join30 } from "path";
 async function renderGraphForTarget(graph, targetContext = {}) {
-  const root = await mkdtemp4(join23(tmpdir5(), "agentwheel-render-"));
+  const root = await mkdtemp5(join30(tmpdir6(), "agentwheel-render-"));
   const artifacts = [];
   const stagedNodes = /* @__PURE__ */ new Map();
   const includeEdges = /* @__PURE__ */ new Map();
@@ -6121,7 +7168,11 @@ async function renderGraphForTarget(graph, targetContext = {}) {
       graphNodeId: rawNode.node.id,
       packageNameAmbiguous: ambiguousPackageNames.has(rawNode.node.name)
     }) : runtimeRenderedArtifacts;
-    const installableArtifacts = renderedArtifacts.filter((artifact) => rawNode.depth === 0 || artifact.type !== "fragments");
+    const compatibleArtifacts = targetContext.adapter && targetContext.installationType ? await filterArtifactsByInstallFormat(renderedArtifacts, targetContext.adapter, targetContext.installationType, {
+      selected: rawNode.node.selected,
+      warn: targetContext.warn
+    }) : renderedArtifacts;
+    const installableArtifacts = compatibleArtifacts.filter((artifact) => rawNode.depth === 0 || artifact.type !== "fragments");
     artifacts.push(...installableArtifacts.map((artifact) => ({
       ...artifact,
       graphNodeId: rawNode.node.id,
@@ -6154,7 +7205,7 @@ async function artifactContentMap(artifacts) {
   const out = /* @__PURE__ */ new Map();
   for (const artifact of artifacts) {
     if (artifact.kind !== "file") continue;
-    out.set(artifact.relativePath.replaceAll("\\", "/"), await readFile17(artifact.stagedPath ?? artifact.sourcePath, "utf8"));
+    out.set(artifact.relativePath.replaceAll("\\", "/"), await readFile21(artifact.stagedPath ?? artifact.sourcePath, "utf8"));
   }
   return out;
 }
@@ -6168,7 +7219,7 @@ function filterArtifactsByRuntime2(artifacts, adapterName, selectedSet) {
   });
 }
 function sha2562(content) {
-  return createHash6("sha256").update(content).digest("hex");
+  return createHash7("sha256").update(content).digest("hex");
 }
 function assignInstallNames(graph, artifacts) {
   const aliases = workspaceAliases(graph);
@@ -6417,9 +7468,9 @@ function lockArtifactFor(artifact) {
 }
 
 // src/lifecycle/trust.ts
-import { mkdir as mkdir13, readFile as readFile18 } from "fs/promises";
+import { mkdir as mkdir14, readFile as readFile22 } from "fs/promises";
 import { homedir as homedir7 } from "os";
-import { dirname as dirname18, join as join24 } from "path";
+import { dirname as dirname20, join as join31 } from "path";
 import { z as z8 } from "zod";
 var trustStoreSchema = z8.object({
   version: z8.literal(1),
@@ -6493,14 +7544,14 @@ function sortedUnique4(values) {
 }
 async function readTrustStore(path) {
   if (!await pathExists(path)) return { version: 1, acceptedSources: [] };
-  return trustStoreSchema.parse(JSON.parse(await readFile18(path, "utf8")));
+  return trustStoreSchema.parse(JSON.parse(await readFile22(path, "utf8")));
 }
 async function writeTrustStore(path, store) {
-  await mkdir13(dirname18(path), { recursive: true });
+  await mkdir14(dirname20(path), { recursive: true });
   await writeJsonAtomic(path, trustStoreSchema.parse(store));
 }
 function defaultTrustStorePath() {
-  return process.env.AGENTWHEEL_TRUST_STORE ?? join24(homedir7(), ".agentwheel", "trust.json");
+  return process.env.AGENTWHEEL_TRUST_STORE ?? join31(homedir7(), ".agentwheel", "trust.json");
 }
 
 // src/lifecycle/source-plan.ts
@@ -6538,7 +7589,7 @@ async function createGraphSourcePlan(options) {
   const registryClient = new RegistryClient({ workspaceRoot, offline: lockMode, offlineLabel: lockLabel, warn });
   const graph = await resolveDependencyGraph(options.roots, {
     workspaceRoot,
-    cacheRoot: join25(workspaceRoot, ".agentwheel", "cache"),
+    cacheRoot: join32(workspaceRoot, ".agentwheel", "cache"),
     registryClient,
     noDeps: options.noDeps,
     lockedResolution: options.lockedResolution,
@@ -6557,7 +7608,9 @@ async function createGraphSourcePlan(options) {
   const bundle = await renderGraphForTarget(graph, {
     workspaceRoot,
     adapter: options.adapter,
-    targetFingerprint
+    installationType,
+    targetFingerprint,
+    warn
   });
   const desiredArtifacts = desiredArtifactsFromGraphBundle(bundle);
   const resolvedInstallationType = resolveInstallationTypeForArtifacts(options.adapter, desiredArtifacts.map((artifact) => artifact.type), installationType);
@@ -6573,7 +7626,8 @@ async function createGraphSourcePlan(options) {
     stateKey,
     forceDrift: options.forceDrift,
     forceConflict: options.forceConflict,
-    replaceConflict: options.replaceConflict
+    replaceConflict: options.replaceConflict,
+    warn
   });
   return {
     plan,
@@ -6633,13 +7687,13 @@ async function readExistingGraphLock(path) {
   return readGraphLock(path);
 }
 function pathForGraphLock(workspaceRoot, targetKey, adapter, targetFingerprint) {
-  return join25(workspaceRoot, ".agentwheel", "locks", sanitizePathSegment(targetKey), sanitizePathSegment(adapter), `${targetFingerprint}.graph-lock.json`);
+  return join32(workspaceRoot, ".agentwheel", "locks", sanitizePathSegment(targetKey), sanitizePathSegment(adapter), `${targetFingerprint}.graph-lock.json`);
 }
 function sanitizePathSegment(value) {
   return value.replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "") || "default";
 }
 function digestGraphLock(lock) {
-  return createHash7("sha256").update(canonicalGraphLockJson(lock)).digest("hex");
+  return createHash8("sha256").update(canonicalGraphLockJson(lock)).digest("hex");
 }
 function workspaceOwnerId(workspaceRoot) {
   return `workspace-root:${resolve14(workspaceRoot)}`;
@@ -6697,7 +7751,7 @@ ${sources.map((source) => `- ${source}`).join("\n")}`);
 }
 
 // src/runtime/target.ts
-import { basename as basename15, dirname as dirname20, join as join26, resolve as resolve15 } from "path";
+import { basename as basename17, dirname as dirname22, join as join33, resolve as resolve15 } from "path";
 var runtimeMarkers = [
   { adapter: "openclaw", dirs: [".openclaw", ".clawdbot", ".moltbot"] },
   { adapter: "claude", dirs: [".claude"] },
@@ -6808,9 +7862,9 @@ async function detectRuntimeTargets(cwd = process.cwd(), adapterFilter) {
   for (const marker of runtimeMarkers) {
     if (adapterFilter && marker.adapter !== adapterFilter) continue;
     for (const dir of marker.dirs) {
-      if (basename15(root) === dir) {
-        matches.push({ adapter: marker.adapter, targetRoot: dirname20(root) });
-      } else if (await pathExists(join26(root, dir))) {
+      if (basename17(root) === dir) {
+        matches.push({ adapter: marker.adapter, targetRoot: dirname22(root) });
+      } else if (await pathExists(join33(root, dir))) {
         matches.push({ adapter: marker.adapter, targetRoot: root });
       }
     }
@@ -6849,7 +7903,7 @@ function dedupeTargets(matches) {
 function runtimeScanRoot(request) {
   const root = resolve15(request.targetRoot ?? request.cwd ?? process.cwd());
   if (request.targetRoot) return root;
-  return runtimeMarkers.some((marker) => marker.dirs.includes(basename15(root))) ? dirname20(root) : root;
+  return runtimeMarkers.some((marker) => marker.dirs.includes(basename17(root))) ? dirname22(root) : root;
 }
 
 // src/lifecycle/profile.ts
@@ -6935,7 +7989,7 @@ async function syncProfile(options) {
         });
       }
     } finally {
-      await rm8(graphPlan.bundle.root, { recursive: true, force: true });
+      await rm9(graphPlan.bundle.root, { recursive: true, force: true });
     }
   }
   return results;
@@ -6959,9 +8013,9 @@ async function packageFromSource(source, options) {
 }
 
 // src/cli/update-check.ts
-import { mkdir as mkdir15, readFile as readFile19, writeFile as writeFile12 } from "fs/promises";
+import { mkdir as mkdir16, readFile as readFile23, writeFile as writeFile14 } from "fs/promises";
 import { homedir as homedir8 } from "os";
-import { dirname as dirname21, join as join27 } from "path";
+import { dirname as dirname23, join as join34 } from "path";
 var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
 var DEFAULT_TIMEOUT_MS = 300;
 var REGISTRY_URL = "https://registry.npmjs.org/agentwheel";
@@ -6969,7 +8023,7 @@ async function maybeCheckForUpdate(options) {
   if (isDisabled(options)) return;
   const now = options.now?.() ?? /* @__PURE__ */ new Date();
   const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
-  const cachePath = options.cachePath ?? join27(homedir8(), ".agentwheel", "update-check.json");
+  const cachePath = options.cachePath ?? join34(homedir8(), ".agentwheel", "update-check.json");
   try {
     const cached = await readCache(cachePath);
     if (cached && now.getTime() - Date.parse(cached.checkedAt) < ttlMs) {
@@ -7006,7 +8060,7 @@ async function fetchLatestVersion(fetchImpl, timeoutMs) {
 }
 async function readCache(path) {
   try {
-    const parsed = JSON.parse(await readFile19(path, "utf8"));
+    const parsed = JSON.parse(await readFile23(path, "utf8"));
     if (typeof parsed.checkedAt !== "string" || typeof parsed.latest !== "string") return void 0;
     return { checkedAt: parsed.checkedAt, latest: parsed.latest };
   } catch {
@@ -7014,8 +8068,8 @@ async function readCache(path) {
   }
 }
 async function writeCache(path, cache) {
-  await mkdir15(dirname21(path), { recursive: true });
-  await writeFile12(path, `${JSON.stringify(cache, null, 2)}
+  await mkdir16(dirname23(path), { recursive: true });
+  await writeFile14(path, `${JSON.stringify(cache, null, 2)}
 `, "utf8");
 }
 function warnIfNewer(latest, current, stderr = process.stderr) {
@@ -7161,13 +8215,13 @@ function isCrossPackageSelector(value) {
 }
 
 // src/model/package-migrate.ts
-import { readFile as readFile20, rename as rename4, writeFile as writeFile13 } from "fs/promises";
-import { join as join29, resolve as resolve17 } from "path";
-import { applyEdits, modify, parse as parse3 } from "jsonc-parser";
+import { readFile as readFile24, rename as rename4, writeFile as writeFile15 } from "fs/promises";
+import { join as join36, resolve as resolve17 } from "path";
+import { applyEdits, modify, parse as parse4 } from "jsonc-parser";
 async function migratePackageManifest(root) {
   const packageRoot = resolve17(root);
   for (const name of openPackManifestNames) {
-    const path = join29(packageRoot, name);
+    const path = join36(packageRoot, name);
     if (await pathExists(path)) {
       return { changed: false, to: path, message: `Package already uses ${name}.` };
     }
@@ -7176,24 +8230,24 @@ async function migratePackageManifest(root) {
   if (!legacyName) {
     throw new Error(`No legacy package manifest found at ${packageRoot}`);
   }
-  const from = join29(packageRoot, legacyName);
+  const from = join36(packageRoot, legacyName);
   const toName = legacyName.endsWith(".jsonc") ? "openpack.jsonc" : "openpack.json";
-  const to = join29(packageRoot, toName);
-  const content = await readFile20(from, "utf8");
+  const to = join36(packageRoot, toName);
+  const content = await readFile24(from, "utf8");
   const updated = updateSchemaVersion(content);
   await rename4(from, to);
-  await writeFile13(to, updated, "utf8");
+  await writeFile15(to, updated, "utf8");
   return { changed: true, from, to, message: `Migrated ${legacyName} to ${toName}.` };
 }
 async function firstExistingLegacyManifest(root) {
   for (const name of legacyPackageManifestNames) {
-    if (await pathExists(join29(root, name))) return name;
+    if (await pathExists(join36(root, name))) return name;
   }
   return void 0;
 }
 function updateSchemaVersion(content) {
   const errors = [];
-  parse3(content, errors, { allowTrailingComma: true, disallowComments: false });
+  parse4(content, errors, { allowTrailingComma: true, disallowComments: false });
   if (errors.length > 0) {
     throw new Error("Cannot migrate invalid JSON/JSONC package manifest.");
   }
@@ -7205,20 +8259,20 @@ function updateSchemaVersion(content) {
 
 // src/cli/version.ts
 import { readFileSync } from "fs";
-import { dirname as dirname22, join as join30 } from "path";
+import { dirname as dirname24, join as join37 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var FALLBACK_VERSION = "0.0.0";
 function resolveCliVersion() {
-  let dir = dirname22(fileURLToPath2(import.meta.url));
+  let dir = dirname24(fileURLToPath2(import.meta.url));
   while (true) {
     try {
-      const pkg = JSON.parse(readFileSync(join30(dir, "package.json"), "utf8"));
+      const pkg = JSON.parse(readFileSync(join37(dir, "package.json"), "utf8"));
       if (pkg.name === "agentwheel" && typeof pkg.version === "string") {
         return pkg.version;
       }
     } catch {
     }
-    const parent = dirname22(dir);
+    const parent = dirname24(dir);
     if (parent === dir) return FALLBACK_VERSION;
     dir = parent;
   }
@@ -7226,6 +8280,8 @@ function resolveCliVersion() {
 
 // src/cli/index.ts
 var CLI_VERSION = resolveCliVersion();
+var COMPANION_SKILL_SOURCE = "github:NestDevLab/agentwheel";
+var COMPANION_SKILL_NAME = "agentwheel";
 var program = new Command();
 program.name("agentwheel").description("Multi-runtime agent artifact orchestrator").version(CLI_VERSION).showSuggestionAfterError(false).option("--no-update-check", "disable npm version update check", false).addHelpText("after", `
 
@@ -7264,7 +8320,7 @@ program.command("list").description("list artifacts exposed by a package source"
   const selectedArtifacts = selectedArtifactsFromOptions(options);
   const resolvedInput = await resolvePackageSource(source, targetRoot);
   const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
-  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join31(targetRoot, ".agentwheel", "cache") }))));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join38(targetRoot, ".agentwheel", "cache") }))));
   const artifacts = filterArtifactsBySelection(await driver.list(resolved), selectedArtifacts);
   for (const artifact of artifacts) {
     console.log(`${artifact.type}	${artifact.name}	${artifact.relativePath}`);
@@ -7274,7 +8330,7 @@ program.command("scan").description("scan a package source for validation findin
   const targetRoot = normalizeTargetRoot(options.targetRoot);
   const resolvedInput = await resolvePackageSource(source, targetRoot);
   const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
-  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join31(targetRoot, ".agentwheel", "cache") }))));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join38(targetRoot, ".agentwheel", "cache") }))));
   const result = await driver.scan(resolved);
   if (result.findings.length === 0) {
     console.log("Scan ok: no findings");
@@ -7316,7 +8372,7 @@ program.command("deps").description("inspect the OpenPack dependency graph").add
           for (const decision of result.bundle.graphLock.canonical.overrides) {
             console.log(`OVERRIDE ${decision.graphNodeId}:${decision.type}/${decision.name} replaces ${decision.overriddenGraphNodeId}:${decision.type}/${decision.name} via ${decision.rootId} (${decision.selector})`);
           }
-          await rm9(result.bundle.root, { recursive: true, force: true });
+          await rm10(result.bundle.root, { recursive: true, force: true });
         }
         continue;
       }
@@ -7437,6 +8493,16 @@ program.command("status").description("show configured packages and runtime inst
     await printStatus(target, normalizedOptions);
   }
 });
+program.command("doctor").description("check agentwheel runtime setup and companion skill guidance").option("--adapter <adapter>", "built-in adapter").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "shortcut for --installation-type user and home-scoped state", false).option("--local", "shortcut for --installation-type local", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).action(async (options) => {
+  const normalizedOptions = normalizeRuntimeScopeOptions(options);
+  const target = await resolveRuntimeTarget({
+    targetRoot: normalizedOptions.targetRoot,
+    adapter: normalizedOptions.adapter,
+    installationType: normalizedOptions.installationType,
+    agent: normalizedOptions.agent
+  });
+  await printDoctor(target, normalizedOptions);
+});
 async function runInstallCommand(nameOrSource, options, behavior) {
   const normalizedOptions = normalizeRuntimeScopeOptions(options, { defaultUser: shouldDefaultUserInstall(nameOrSource, options) });
   if (options.profile) {
@@ -7510,7 +8576,7 @@ async function runInstallCommand(nameOrSource, options, behavior) {
         });
         console.log(`Applied ${result.plan.adapter} at ${result.plan.targetRoot}.`);
       }
-      await rm9(result.bundle.root, { recursive: true, force: true });
+      await rm10(result.bundle.root, { recursive: true, force: true });
       if (result.plan.hasBlockingChanges) process.exitCode = 1;
     }
     if (behavior.apply && extraPackage && !targetOptions.onlySource) {
@@ -7536,7 +8602,7 @@ async function packageEntryFromSource(source, targetRoot, options) {
   const bundle = await stageSource(driver, resolvedSource, {
     workspaceRoot: targetRoot,
     adapter,
-    cacheRoot: join31(targetRoot, ".agentwheel", "cache"),
+    cacheRoot: join38(targetRoot, ".agentwheel", "cache"),
     mode: options.mode,
     frozenLock: lockMode,
     select: selectedArtifacts
@@ -7558,7 +8624,7 @@ async function packageEntryFromSource(source, targetRoot, options) {
       overrides: overrideArtifactsFromOptions(options)
     };
   } finally {
-    await rm9(bundle.root, { recursive: true, force: true });
+    await rm10(bundle.root, { recursive: true, force: true });
   }
 }
 function findConfiguredPackage(packages, value) {
@@ -7699,7 +8765,7 @@ async function runConfiguredGraphPackages(target, options, behavior) {
       });
       console.log(`Applied ${result.plan.adapter} at ${result.plan.targetRoot}.`);
     }
-    await rm9(result.bundle.root, { recursive: true, force: true });
+    await rm10(result.bundle.root, { recursive: true, force: true });
     if (result.plan.hasBlockingChanges) process.exitCode = 1;
   }
 }
@@ -7888,7 +8954,7 @@ function keepManifestEntryOperation(entry, targetRoot, rootId, operation, option
     artifactType: entry.artifactType,
     artifactName: entry.artifactName,
     kind: entry.kind,
-    destPath: operation?.destPath ?? join31(targetRoot, entry.path),
+    destPath: operation?.destPath ?? join38(targetRoot, entry.path),
     relativeDestPath: entry.path,
     desiredHash: entry.sourceHash,
     currentHash: operation?.currentHash ?? entry.hash,
@@ -7897,6 +8963,7 @@ function keepManifestEntryOperation(entry, targetRoot, rootId, operation, option
     channel: entry.channel,
     packageName: entry.packageName,
     semanticCommand: entry.semanticCommand,
+    semanticPlugin: entry.semanticPlugin,
     execute: entry.executed,
     mergeStrategy: entry.mergeStrategy,
     composedFrom: entry.composedFrom,
@@ -7998,7 +9065,7 @@ async function uninstallConfiguredPackage(target, packageName, options) {
     if (!options.dryRun) {
       console.log(formatUninstallResult(result));
     }
-    if (renderedRoot) await rm9(renderedRoot, { recursive: true, force: true });
+    if (renderedRoot) await rm10(renderedRoot, { recursive: true, force: true });
     if (plan.hasBlockingChanges) process.exitCode = 1;
   }
 }
@@ -8126,9 +9193,57 @@ async function printPendingInstallWork(target, options) {
     const message = error instanceof Error ? error.message : String(error);
     console.log(`Pending install work: unavailable (${message})`);
   } finally {
-    await Promise.all(results.map((result) => rm9(result.bundle.root, { recursive: true, force: true })));
+    await Promise.all(results.map((result) => rm10(result.bundle.root, { recursive: true, force: true })));
   }
 }
+async function printDoctor(target, options) {
+  const adapterOptions = adapterOptionsForTarget(target, options);
+  const adapter = await resolveAdapterForTarget(target, adapterOptions);
+  const installationType = options.installationType ?? target.installationType ?? resolveInstallationTypeForArtifacts(adapter, ["skills"]);
+  const targetMapping = targetMappingForArtifact(adapter, "skills", installationType);
+  if (!targetMapping?.enabled) {
+    throw new Error(`Adapter ${adapter.name} does not support skills for installation type '${installationType}'.`);
+  }
+  const installRoot = installRootForAdapterInstallationType(adapter, target.targetRoot, installationType, target.transport === "ssh");
+  const companionSkillPath = join38(installRoot, targetMapping.dest, COMPANION_SKILL_NAME);
+  const installed = await pathExists(companionSkillPath);
+  console.log(`Doctor for ${adapter.name}/${installationType} at ${installRoot}`);
+  if (installed) {
+    console.log(`Agentwheel companion skill: installed at ${companionSkillPath}`);
+    return;
+  }
+  console.log(`Agentwheel companion skill: missing at ${companionSkillPath}`);
+  console.log("Suggested commands:");
+  console.log(`  ${companionSkillInstallCommand(adapter.name, installationType, options, { dryRun: true })}`);
+  console.log(`  ${companionSkillInstallCommand(adapter.name, installationType, options)}`);
+}
+function companionSkillInstallCommand(adapter, installationType, options, behavior = {}) {
+  const args = [
+    "agentwheel",
+    "install",
+    COMPANION_SKILL_SOURCE,
+    "--adapter",
+    adapter,
+    ...installationTypeCommandArgs(installationType),
+    ...targetRootCommandArgs(options),
+    "--skill",
+    COMPANION_SKILL_NAME
+  ];
+  if (behavior.dryRun) args.push("--dry-run");
+  return args.map(shellQuoteArg).join(" ");
+}
+function installationTypeCommandArgs(installationType) {
+  if (installationType === "user") return ["--user"];
+  if (installationType === "local") return ["--local"];
+  return ["--installation-type", installationType];
+}
+function targetRootCommandArgs(options) {
+  return options.targetRoot && options.installationType !== "user" ? ["--target-root", options.targetRoot] : [];
+}
+function shellQuoteArg(value) {
+  if (/^[A-Za-z0-9_./:@=-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
 function collectSelectOption(value, previous) {
   return [...previous, ...splitSelectorList(value)];
 }
@@ -8224,10 +9339,10 @@ function filterUninstallPlanBySelection(plan, selected) {
   };
 }
 async function initPackage(root) {
-  await mkdir16(join31(root, "instructions"), { recursive: true });
-  await mkdir16(join31(root, "rules"), { recursive: true });
-  await mkdir16(join31(root, "skills"), { recursive: true });
-  const manifestPath = join31(root, "openpack.json");
+  await mkdir17(join38(root, "instructions"), { recursive: true });
+  await mkdir17(join38(root, "rules"), { recursive: true });
+  await mkdir17(join38(root, "skills"), { recursive: true });
+  const manifestPath = join38(root, "openpack.json");
   const manifest = {
     schemaVersion: 2,
     name: "example/agentwheel-package",
@@ -8238,12 +9353,12 @@ async function initPackage(root) {
       { type: "skills", path: "skills" }
     ]
   };
-  await writeFile14(manifestPath, `${JSON.stringify(manifest, null, 2)}
+  await writeFile16(manifestPath, `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
-  await writeFile14(join31(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
+  await writeFile16(join38(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
 }
 async function defaultBootstrapPackage(_root) {
-  const packageRoot = await findAgentwheelPackageRoot(dirname23(fileURLToPath3(import.meta.url)));
+  const packageRoot = await findAgentwheelPackageRoot(dirname25(fileURLToPath3(import.meta.url)));
   if (!packageRoot) return void 0;
   return {
     name: "agentwheel",
@@ -8290,7 +9405,7 @@ async function findAgentwheelPackageRoot(start) {
   let current = resolve18(start);
   while (true) {
     if (await findPackageManifestPath(current, { warnLegacy: false })) return current;
-    const parent = dirname23(current);
+    const parent = dirname25(current);
     if (parent === current) return void 0;
     current = parent;
   }