agentwheel 0.14.4 → 0.14.6

package/dist/index.js

@@ -6,12 +6,13 @@ import {
   isIgnoredGeneratedEntry,
   pathExists,
   writeJsonAtomic
-} from "./chunk-B3FMBTWC.js";
+} from "./chunk-QJTTISLY.js";
 
 // src/cli/index.ts
-import { mkdir as mkdir17, rm as rm10, writeFile as writeFile16 } from "fs/promises";
+import { existsSync } from "fs";
+import { mkdir as mkdir20, rm as rm11, writeFile as writeFile19 } from "fs/promises";
 import { homedir as homedir9 } from "os";
-import { dirname as dirname25, join as join38, resolve as resolve18 } from "path";
+import { dirname as dirname28, join as join40, resolve as resolve20 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { Command } from "commander";
 
@@ -60,6 +61,18 @@ var packageItemRequireSchema = z.union([
   z.string().min(1),
   packageItemRequireObjectSchema
 ]);
+var packageItemSuggestObjectSchema = z.object({
+  alias: z.string().min(1),
+  select: z.array(z.string().min(1)).optional(),
+  optional: z.boolean().optional(),
+  runtimes: z.array(z.string().min(1)).optional(),
+  reason: z.string().min(1).optional(),
+  when: z.string().min(1).optional()
+}).passthrough();
+var packageItemSuggestSchema = z.union([
+  z.string().min(1),
+  packageItemSuggestObjectSchema
+]);
 var composedFromEntrySchema = z.object({
   selector: z.string().min(1),
   hash: z.string().min(16)
@@ -78,6 +91,7 @@ var artifactSchema = z.object({
   assets: z.array(packageAssetSchema).optional(),
   required: z.boolean().optional(),
   requires: z.array(packageItemRequireSchema).optional(),
+  suggests: z.array(packageItemSuggestSchema).optional(),
   compose: z.array(packageComposeEntrySchema).optional(),
   runtimes: z.array(z.string().min(1)).optional(),
   composedFrom: z.array(composedFromEntrySchema).optional()
@@ -102,7 +116,7 @@ var targetMappingSchema = z2.object({
     "copilot-prompt",
     "copilot-agent"
   ]).optional(),
-  merge: z2.enum(["json-deep", "yaml-deep", "codex-toml-mcp"]).optional(),
+  merge: z2.enum(["json-deep", "openclaw-json-deep", "yaml-deep", "codex-toml-mcp"]).optional(),
   mode: z2.enum(["managed-block"]).optional()
 });
 var targetRegistrySchema = z2.record(installationTypeSchema, targetMappingSchema);
@@ -363,13 +377,13 @@ var openClawAdapter = {
       user: { enabled: true, root: "home", dest: ".openclaw/skills" }
     },
     mcp: {
-      user: { enabled: true, root: "home", dest: ".openclaw/openclaw.json", merge: "json-deep" }
+      user: { enabled: true, root: "home", dest: ".openclaw/openclaw.json", merge: "openclaw-json-deep" }
     },
     settings: {
-      user: { enabled: true, root: "home", dest: ".openclaw/openclaw.json", merge: "json-deep" }
+      user: { enabled: true, root: "home", dest: ".openclaw/openclaw.json", merge: "openclaw-json-deep" }
     },
     plugins: {
-      local: { enabled: true, dest: ".openclaw/plugins", formats: ["openclaw-plugin"], semantic: "openclaw-plugin" }
+      local: { enabled: true, dest: ".openclaw/plugins", formats: ["openclaw-plugin", "openclaw-clawhub-plugin"], semantic: "openclaw-plugin" }
     }
   }
 };
@@ -453,7 +467,7 @@ async function resolveAdapter(options) {
 
 // src/install/apply.ts
 import { execFile as execFile3 } from "child_process";
-import { mkdtemp as mkdtemp2, rm as rm4, writeFile as writeFile8 } from "fs/promises";
+import { mkdtemp as mkdtemp2, rm as rm4, writeFile as writeFile9 } from "fs/promises";
 import { tmpdir as tmpdir3 } from "os";
 import { basename as basename3, join as join5 } from "path";
 import { promisify as promisify3 } from "util";
@@ -759,13 +773,13 @@ async function spawnWithInput(command, args, input) {
   if (result.stderr) throw new Error(result.stderr);
 }
 function waitForProcess(child, label) {
-  return new Promise((resolve19, reject) => {
+  return new Promise((resolve21, reject) => {
     const stderr = [];
     child.stderr?.on("data", (chunk) => stderr.push(chunk));
     child.on("error", reject);
     child.on("close", (code) => {
       const message = Buffer.concat(stderr).toString("utf8");
-      if (code === 0) resolve19({ stderr: "" });
+      if (code === 0) resolve21({ stderr: "" });
       else reject(new Error(`${label} exited ${code}${message ? `: ${message}` : ""}`));
     });
   });
@@ -869,6 +883,58 @@ function dedupeArray(values) {
   return out;
 }
 
+// src/install/openclaw-json-merge.ts
+import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname5 } from "path";
+async function mergeOpenClawJsonFile(sourcePath, destPath) {
+  const source = expandEnvPlaceholders(
+    normalizeOpenClawConfig(JSON.parse(await readFile6(sourcePath, "utf8"))),
+    sourcePath
+  );
+  const current = await pathExists(destPath) ? JSON.parse(await readFile6(destPath, "utf8")) : {};
+  const merged = deepMerge(current, source);
+  await mkdir4(dirname5(destPath), { recursive: true });
+  await writeFile5(destPath, `${JSON.stringify(merged, null, 2)}
+`, "utf8");
+}
+function expandEnvPlaceholders(value, sourcePath) {
+  if (typeof value === "string") {
+    return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => {
+      const replacement = process.env[name];
+      if (replacement === void 0) {
+        throw new Error(`Missing environment variable ${name} while rendering OpenClaw JSON merge artifact ${sourcePath}`);
+      }
+      return replacement;
+    });
+  }
+  if (Array.isArray(value)) return value.map((item) => expandEnvPlaceholders(item, sourcePath));
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [key, expandEnvPlaceholders(child, sourcePath)])
+  );
+}
+function normalizeOpenClawConfig(value) {
+  if (!isRecord(value)) return value;
+  const rootMcpServers = isRecord(value.mcpServers) ? value.mcpServers : void 0;
+  if (!rootMcpServers) return value;
+  const out = { ...value };
+  const normalizedServers = {};
+  for (const [name, server] of Object.entries(rootMcpServers)) {
+    if (isRecord(server)) normalizedServers[name] = normalizeOpenClawMcpServer(server);
+  }
+  const mcp = isRecord(out.mcp) ? out.mcp : {};
+  out.mcp = deepMerge(mcp, { servers: normalizedServers });
+  delete out.mcpServers;
+  return out;
+}
+function normalizeOpenClawMcpServer(server) {
+  const out = { ...server };
+  const type = typeof out.type === "string" ? out.type : void 0;
+  if (type && typeof out.transport !== "string") out.transport = type;
+  delete out.type;
+  return out;
+}
+
 // src/install/manifest.ts
 import { createHash as createHash2 } from "crypto";
 import { resolve as resolve3 } from "path";
@@ -900,7 +966,7 @@ var manifestEntryV1Schema = z4.object({
   semanticCommand: z4.array(z4.string()).optional(),
   semanticPlugin: semanticPluginSpecSchema.optional(),
   executed: z4.boolean().optional(),
-  mergeStrategy: z4.enum(["json-deep", "yaml-deep", "codex-toml-mcp"]).optional(),
+  mergeStrategy: z4.enum(["json-deep", "openclaw-json-deep", "yaml-deep", "codex-toml-mcp"]).optional(),
   mode: z4.enum(["managed-block"]).optional(),
   composedFrom: z4.array(composedFromEntrySchema).optional()
 });
@@ -1092,8 +1158,8 @@ function assertOperationContained(operation, targetRoot) {
 }
 
 // src/install/transaction.ts
-import { cp, mkdir as mkdir4, rm as rm2, stat as stat2 } from "fs/promises";
-import { dirname as dirname5, join as join3 } from "path";
+import { cp, mkdir as mkdir5, rm as rm2, stat as stat2 } from "fs/promises";
+import { dirname as dirname6, join as join3 } from "path";
 function applyLockPath(targetRoot, adapter, scope = {}) {
   return join3(metadataDir(targetRoot), `${stateKeyFor(adapter, scope)}.apply-lock`);
 }
@@ -1158,7 +1224,7 @@ async function recordBackup(operation, index, targetRoot, adapter, transport = l
   }
   const backupPath = join3(applyBackupDir(targetRoot, adapter, scope), String(index));
   await rm2(backupPath, { recursive: true, force: true });
-  await mkdir4(dirname5(backupPath), { recursive: true });
+  await mkdir5(dirname6(backupPath), { recursive: true });
   await cp(operation.destPath, backupPath, { recursive: operation.kind === "dir", dereference: true });
   return {
     index,
@@ -1212,16 +1278,16 @@ async function localPathExists(path) {
 }
 
 // src/install/toml-merge.ts
-import { mkdir as mkdir5, readFile as readFile6, writeFile as writeFile5 } from "fs/promises";
-import { dirname as dirname6 } from "path";
+import { mkdir as mkdir6, readFile as readFile7, writeFile as writeFile6 } from "fs/promises";
+import { dirname as dirname7 } from "path";
 async function mergeCodexTomlMcp(sourcePath, destPath) {
-  const source = JSON.parse(await readFile6(sourcePath, "utf8"));
+  const source = JSON.parse(await readFile7(sourcePath, "utf8"));
   const servers = extractMcpServers(source);
-  const current = await pathExists(destPath) ? await readFile6(destPath, "utf8") : "";
+  const current = await pathExists(destPath) ? await readFile7(destPath, "utf8") : "";
   const withoutManaged = removeManagedMcpSections(current, Object.keys(servers));
   const merged = appendMcpServers(withoutManaged, servers);
-  await mkdir5(dirname6(destPath), { recursive: true });
-  await writeFile5(destPath, merged, "utf8");
+  await mkdir6(dirname7(destPath), { recursive: true });
+  await writeFile6(destPath, merged, "utf8");
 }
 function extractMcpServers(source) {
   const raw = isRecord2(source.mcpServers) ? source.mcpServers : source;
@@ -1300,15 +1366,15 @@ function isRecord2(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 { mkdir as mkdir7, readFile as readFile8, writeFile as writeFile7 } from "fs/promises";
+import { dirname as dirname8 } 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 source = parseYamlValue(await readFile8(sourcePath, "utf8"));
+  const current = await pathExists(destPath) ? parseYamlValue(await readFile8(destPath, "utf8")) : {};
   const merged = deepMerge2(current, source);
-  await mkdir6(dirname7(destPath), { recursive: true });
-  await writeFile6(destPath, stringify(merged), "utf8");
+  await mkdir7(dirname8(destPath), { recursive: true });
+  await writeFile7(destPath, stringify(merged), "utf8");
 }
 function parseYamlValue(content) {
   return normalizeYamlValue(parse2(content));
@@ -1369,13 +1435,13 @@ function normalizeOwners(owners) {
 
 // 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 { mkdtemp, readFile as readFile9, realpath, rm as rm3, writeFile as writeFile8 } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
-import { basename as basename2, dirname as dirname8, join as join4, relative as relative2 } from "path";
+import { basename as basename2, dirname as dirname9, 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");
+  const source = await readFile9(sourcePath, "utf8");
   return hashText(managedBlockBody(source));
 }
 async function readManagedInstructionBlockState(destPath, selector, transport) {
@@ -1394,18 +1460,18 @@ async function readManagedInstructionBlockState(destPath, selector, transport) {
     drifted: hash !== block.markerHash
   };
 }
-async function writeManagedInstructionBlock(sourcePath, destPath, selector, transport, expectedHash) {
-  const source = await readFile8(sourcePath, "utf8");
+async function writeManagedInstructionBlock(sourcePath, destPath, selector, transport, options = {}) {
+  const source = await readFile9(sourcePath, "utf8");
   const desired = renderManagedInstructionBlock(selector, source);
   const existing = await readOptionalText(destPath, transport);
-  const merged = upsertManagedInstructionBlock(existing ?? "", selector, desired.block, expectedHash);
+  const merged = upsertManagedInstructionBlock(existing ?? "", selector, desired.block, options);
   await writeTextWithTransport(destPath, merged, transport);
   return desired.hash;
 }
-async function removeManagedInstructionBlock(destPath, selector, transport, expectedHash) {
+async function removeManagedInstructionBlock(destPath, selector, transport, options = {}) {
   if (!await transport.pathExists(destPath)) return;
   const existing = await transport.readFile(destPath);
-  const updated = removeManagedBlockFromContent(existing, selector, expectedHash);
+  const updated = removeManagedBlockFromContent(existing, selector, options);
   await writeTextWithTransport(destPath, updated, transport);
 }
 async function managedInstructionBlockLanded(destPath, selector, expectedHash, transport) {
@@ -1438,24 +1504,30 @@ ${body}<!-- END openpack:include ${selector} -->
     hash
   };
 }
-function upsertManagedInstructionBlock(content, selector, block, expectedHash) {
+function upsertManagedInstructionBlock(content, selector, block, options) {
+  const { expectedHash, allowDrift = false } = options;
   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}`);
+  if (!allowDrift) {
+    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) {
+function removeManagedBlockFromContent(content, selector, options) {
+  const { expectedHash, allowDrift = false } = options;
   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}`);
+  if (!allowDrift) {
+    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)}`;
 }
@@ -1501,7 +1573,7 @@ function assertCleanBlock(block, selector) {
   }
 }
 function referencesAgentsMd(content, claudePath, agentsPath) {
-  const claudeDir = dirname8(claudePath);
+  const claudeDir = dirname9(claudePath);
   for (const rawLine of content.split(/\r?\n/)) {
     const line = rawLine.trim();
     const atImport = /^@import\s+(.+)$/i.exec(line);
@@ -1511,7 +1583,7 @@ function referencesAgentsMd(content, claudePath, agentsPath) {
     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 (relative2(dirname9(agentsPath), candidate).replaceAll("\\", "/") === "AGENTS.md") return true;
     if (candidate === agentsPath) return true;
   }
   return false;
@@ -1533,7 +1605,7 @@ async function writeTextWithTransport(path, content, transport) {
   const tempRoot = await mkdtemp(join4(tmpdir2(), "agentwheel-instructions-"));
   const localPath = join4(tempRoot, basename2(path) || "instructions.md");
   try {
-    await writeFile7(localPath, content, "utf8");
+    await writeFile8(localPath, content, "utf8");
     await transport.atomicCopy(localPath, path, "file");
   } finally {
     await rm3(tempRoot, { recursive: true, force: true });
@@ -1677,7 +1749,7 @@ async function uninstall(plan, options = {}) {
     const blockers = plan.operations.filter((operation) => operation.action === "conflict");
     throw new Error(`Refusing to uninstall with blocking changes: ${blockers.map((item) => item.relativeDestPath).join(", ")}`);
   }
-  const removable = plan.operations.filter((operation) => operation.action === "remove" || resolvedOptions.force && isForceRemovableKeep(operation)).map((operation) => operation.action === "keep" ? { ...operation, action: "remove", reason: `${operation.reason}; force removing drifted managed file` } : operation);
+  const removable = plan.operations.filter((operation) => operation.action === "remove" || resolvedOptions.force && isForceRemovableKeep(operation)).map((operation) => operation.action === "keep" ? { ...operation, action: "remove", overrideDrift: true, reason: `${operation.reason}; force removing drifted managed file` } : operation);
   const kept = plan.operations.filter((operation) => operation.action === "keep" && (!resolvedOptions.force || !isForceRemovableKeep(operation)));
   const skipped = plan.operations.filter((operation) => operation.action === "skip");
   const removedDrifted = resolvedOptions.force ? plan.operations.filter((operation) => operation.action === "keep" && isForceRemovableKeep(operation)).length : 0;
@@ -1822,7 +1894,7 @@ async function applyOperation(operation, context) {
     }
     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);
+      const hash2 = await writeManagedInstructionBlock(operation.sourcePath, operation.destPath, selector, transport, managedBlockMutationOptions(operation));
       if (hash2 !== operation.desiredHash) {
         throw new Error(`Managed block hash verification failed for ${operation.relativeDestPath}: expected ${operation.desiredHash}, got ${hash2}`);
       }
@@ -1835,6 +1907,8 @@ async function applyOperation(operation, context) {
     }
     if (operation.mergeStrategy === "json-deep") {
       await mergeWithTransport(operation.sourcePath, operation.destPath, transport, mergeJsonFile);
+    } else if (operation.mergeStrategy === "openclaw-json-deep") {
+      await mergeWithTransport(operation.sourcePath, operation.destPath, transport, mergeOpenClawJsonFile);
     } else if (operation.mergeStrategy === "yaml-deep") {
       await mergeWithTransport(operation.sourcePath, operation.destPath, transport, mergeYamlFile);
     } else if (operation.mergeStrategy === "codex-toml-mcp") {
@@ -1884,7 +1958,7 @@ async function applyOperation(operation, context) {
     }
     if (operation.mode === managedInstructionBlockMode) {
       const selector = managedInstructionSelector(operation.logicalSelector, operation.artifactType, operation.artifactName);
-      await removeManagedInstructionBlock(operation.destPath, selector, transport, operation.manifestHash);
+      await removeManagedInstructionBlock(operation.destPath, selector, transport, managedBlockMutationOptions(operation));
     } else {
       await transport.rm(operation.destPath);
     }
@@ -2057,6 +2131,12 @@ function semanticInstallCommands(operation) {
   if (operation.semanticPlugin) return operation.semanticPlugin.installCommands;
   return operation.semanticCommand ? [operation.semanticCommand] : [];
 }
+function managedBlockMutationOptions(operation) {
+  return {
+    expectedHash: operation.overrideDrift ? void 0 : operation.manifestHash,
+    allowDrift: operation.overrideDrift === true
+  };
+}
 async function entryForCompletedOperation(operation, transport, now, graphLockDigest) {
   if (operation.action === "remove") return void 0;
   if (operation.action === "create" || operation.action === "update") {
@@ -2170,7 +2250,7 @@ async function mergeWithTransport(sourcePath, destPath, transport, merge) {
   const localDest = join5(tempRoot, basename3(destPath) || "merged");
   try {
     if (await transport.pathExists(destPath)) {
-      await writeFile8(localDest, await transport.readFile(destPath), "utf8");
+      await writeFile9(localDest, await transport.readFile(destPath), "utf8");
     }
     await merge(sourcePath, localDest);
     await transport.atomicCopy(localDest, destPath, "file");
@@ -2183,8 +2263,8 @@ async function mergeWithTransport(sourcePath, destPath, transport, merge) {
 import { basename as basename7, join as join15, relative as relative3 } from "path";
 
 // src/staging/codex-subagents.ts
-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";
+import { mkdir as mkdir8, readFile as readFile10, writeFile as writeFile10 } from "fs/promises";
+import { basename as basename4, dirname as dirname10, join as join6 } from "path";
 var requiredCodexAgentFields = ["name", "description", "developer_instructions"];
 async function renderCodexSubagents(artifacts, stageRoot, adapter) {
   if (adapter?.name !== "codex") return artifacts;
@@ -2210,7 +2290,7 @@ async function renderCodexSubagent(artifact, stageRoot) {
   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 readFile9(sourcePath, "utf8");
+    const content = await readFile10(sourcePath, "utf8");
     validateCodexAgentToml(content, sourcePath);
     return {
       ...artifact,
@@ -2227,10 +2307,10 @@ async function renderCodexSubagent(artifact, stageRoot) {
   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 readFile9(markdownPath, "utf8");
+  const markdown = await readFile10(markdownPath, "utf8");
   const toml = markdownToCodexAgentToml(agentName, markdown);
-  await mkdir7(dirname9(renderedPath), { recursive: true });
-  await writeFile9(renderedPath, toml, "utf8");
+  await mkdir8(dirname10(renderedPath), { recursive: true });
+  await writeFile10(renderedPath, toml, "utf8");
   return {
     ...artifact,
     name: agentName,
@@ -2298,8 +2378,8 @@ function escapeRegExp(value) {
 }
 
 // src/staging/copilot-artifacts.ts
-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";
+import { mkdir as mkdir9, readFile as readFile11, writeFile as writeFile11 } from "fs/promises";
+import { basename as basename5, dirname as dirname11, join as join7 } from "path";
 async function renderCopilotArtifacts(artifacts, stageRoot, adapter) {
   if (adapter?.name !== "copilot") return artifacts;
   const names = /* @__PURE__ */ new Set();
@@ -2329,9 +2409,9 @@ async function renderCopilotSubagent(artifact, stageRoot) {
   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 readFile10(markdownPath, "utf8");
-  await mkdir8(dirname10(renderedPath), { recursive: true });
-  await writeFile10(renderedPath, ensureCopilotAgentDescription(agentName, markdown), "utf8");
+  const markdown = await readFile11(markdownPath, "utf8");
+  await mkdir9(dirname11(renderedPath), { recursive: true });
+  await writeFile11(renderedPath, ensureCopilotAgentDescription(agentName, markdown), "utf8");
   return {
     ...artifact,
     name: `${agentName}.agent.md`,
@@ -2387,7 +2467,7 @@ function yamlString(value) {
 import { join as join9 } from "path";
 
 // src/targets/plugins/common.ts
-import { readFile as readFile11 } from "fs/promises";
+import { readFile as readFile12 } from "fs/promises";
 import { join as join8 } from "path";
 import { parseDocument } from "yaml";
 function pluginStateRoot(request) {
@@ -2411,14 +2491,14 @@ function safeNameSegment(value) {
 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"));
+  const parsed = JSON.parse(await readFile12(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 document = parseDocument(await readFile12(manifestPath, "utf8"));
     const parsed = document.toJSON();
     if (!isRecord4(parsed)) continue;
     for (const key of ["name", "module", "package"]) {
@@ -2550,7 +2630,7 @@ async function hermesPluginSpec(request) {
 }
 
 // src/targets/plugins/openclaw.ts
-import { readFile as readFile12 } from "fs/promises";
+import { readFile as readFile13 } from "fs/promises";
 import { join as join13 } from "path";
 function openClawPluginInstallCommand(request) {
   return ["openclaw", "plugins", "install", "--force", request.path];
@@ -2559,6 +2639,15 @@ function openClawPluginUninstallCommand(pluginName) {
   return ["openclaw", "plugins", "uninstall", pluginName, "--force"];
 }
 async function openClawPluginSpec(request) {
+  if (request.format === "openclaw-clawhub-plugin") {
+    const metadata = await openClawClawHubPluginMetadata(request.path, request.fallbackPluginName);
+    return {
+      runtime: "openclaw",
+      pluginName: metadata.pluginName,
+      installCommands: [openClawPluginInstallCommand({ path: metadata.installSpec, dryRun: true })],
+      uninstallCommands: [openClawPluginUninstallCommand(metadata.pluginName)]
+    };
+  }
   const pluginName = await openClawPluginName(request.path, request.fallbackPluginName);
   return {
     runtime: "openclaw",
@@ -2571,17 +2660,37 @@ 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"));
+    const parsed = JSON.parse(await readFile13(manifestPath, "utf8"));
     if (typeof parsed.name === "string" && parsed.name.trim().length > 0) return parsed.name.trim();
   }
   return fallback;
 }
+async function openClawClawHubPluginMetadata(root, fallback) {
+  const metadataPath = join13(root, "clawhub.json");
+  if (!await pathExists(metadataPath)) {
+    throw new Error("OpenClaw ClawHub plugins must contain clawhub.json");
+  }
+  const parsed = JSON.parse(await readFile13(metadataPath, "utf8"));
+  const installSpec = stringField(parsed.installSpec);
+  if (!installSpec?.startsWith("clawhub:")) {
+    throw new Error("OpenClaw ClawHub plugin metadata must declare installSpec starting with clawhub:");
+  }
+  const pluginName = stringField(parsed.runtimeId) ?? installNameFor(stringField(parsed.name) ?? fallback);
+  return { installSpec, pluginName };
+}
+function stringField(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function installNameFor(value) {
+  return value.split("/").at(-1).replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "") || "clawhub-plugin";
+}
 
 // src/targets/plugins/index.ts
 async function semanticPluginSpecForArtifact(request) {
   if (request.semantic === "openclaw-plugin") {
     return openClawPluginSpec({
       path: request.sourcePath,
+      format: request.artifact.format,
       fallbackPluginName: request.installName
     });
   }
@@ -2601,7 +2710,7 @@ async function semanticPluginSpecForArtifact(request) {
 }
 
 // src/validation/artifacts.ts
-import { readFile as readFile13 } from "fs/promises";
+import { readFile as readFile14 } from "fs/promises";
 import { basename as basename6, join as join14 } from "path";
 import { parseDocument as parseDocument2 } from "yaml";
 
@@ -2657,7 +2766,7 @@ function subagentBaseName(name) {
 
 // src/validation/artifacts.ts
 var behavioralRuleFormats = ["markdown-rule", "claude-markdown-rule", "copilot-instruction-rule"];
-var pluginFormats = ["claude-plugin", "codex-plugin", "hermes-plugin", "copilot-plugin", "openclaw-plugin"];
+var pluginFormats = ["claude-plugin", "codex-plugin", "hermes-plugin", "copilot-plugin", "openclaw-plugin", "openclaw-clawhub-plugin"];
 async function filterArtifactsByInstallFormat(artifacts, adapter, installationType, options = {}) {
   const selectedSet = new Set(normalizeArtifactSelectors(options.selected ?? []) ?? []);
   const kept = [];
@@ -2766,6 +2875,7 @@ async function inferArtifactFormat(artifact, target) {
     return void 0;
   }
   if (artifact.type === "plugins" && target.semantic === "openclaw-plugin") {
+    if (artifact.kind === "dir" && await pathExists(join14(artifactPath(artifact), "clawhub.json"))) return "openclaw-clawhub-plugin";
     if (artifact.kind === "dir" && (await openClawPluginManifestPaths(artifact)).length > 0) return "openclaw-plugin";
   }
   return void 0;
@@ -2781,9 +2891,9 @@ function expectedFormats(artifact, target) {
     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;
+    if (isPluginFormat(target.semantic)) return [target.semantic];
   }
   return target.formats;
 }
@@ -2792,7 +2902,10 @@ async function validateKnownFormat(artifact, format, target) {
   if (format === "markdown-rule" || format === "claude-markdown-rule" || format === "copilot-instruction-rule") {
     return validateMarkdownRule(artifact, format);
   }
-  if (format === "openclaw-plugin" || target.semantic === "openclaw-plugin") {
+  if (format === "openclaw-clawhub-plugin") {
+    return validateOpenClawClawHubPlugin(artifact);
+  }
+  if (format === "openclaw-plugin") {
     return validateOpenClawPlugin(artifact);
   }
   if (format === "claude-plugin" || target.semantic === "claude-plugin") {
@@ -2847,7 +2960,7 @@ async function validateGenericStructure(artifact, target) {
 async function validateSkillFrontmatter(artifact, skillMdPath) {
   let content;
   try {
-    content = await readFile13(skillMdPath, "utf8");
+    content = await readFile14(skillMdPath, "utf8");
   } catch (error) {
     return [{ artifact, message: `could not read SKILL.md: ${errorMessage(error)}` }];
   }
@@ -2917,7 +3030,7 @@ async function validateHermesPlugin(artifact) {
     return [{ artifact, message: "Hermes plugins must contain plugin.yaml or plugin.yml" }];
   }
   try {
-    const document = parseDocument2(await readFile13(manifestPath, "utf8"));
+    const document = parseDocument2(await readFile14(manifestPath, "utf8"));
     if (document.errors.length > 0) {
       return [{ artifact, message: `Hermes ${basename6(manifestPath)} must be valid YAML: ${document.errors[0]?.message ?? "parse error"}` }];
     }
@@ -2941,7 +3054,7 @@ async function firstExistingPath(paths) {
 }
 async function parseJsonPluginManifest(manifestPath, label) {
   try {
-    const parsed = JSON.parse(await readFile13(manifestPath, "utf8"));
+    const parsed = JSON.parse(await readFile14(manifestPath, "utf8"));
     if (!isRecord5(parsed)) {
       return { ok: false, message: `${label} ${basename6(manifestPath)} must be a JSON object` };
     }
@@ -2976,6 +3089,33 @@ async function validateOpenClawPlugin(artifact) {
   }
   return issues;
 }
+async function validateOpenClawClawHubPlugin(artifact) {
+  if (artifact.type !== "plugins") {
+    return [{ artifact, message: "openclaw-clawhub-plugin format is only valid for plugins artifacts" }];
+  }
+  if (artifact.kind !== "dir") {
+    return [{ artifact, message: "OpenClaw ClawHub plugins must be directory artifacts" }];
+  }
+  const metadataPath = join14(artifactPath(artifact), "clawhub.json");
+  if (!await pathExists(metadataPath)) {
+    return [{ artifact, message: "OpenClaw ClawHub plugins must contain clawhub.json" }];
+  }
+  try {
+    const parsed = JSON.parse(await readFile14(metadataPath, "utf8"));
+    if (!isRecord5(parsed)) {
+      return [{ artifact, message: "OpenClaw ClawHub clawhub.json must be a JSON object" }];
+    }
+    if (typeof parsed.installSpec !== "string" || !parsed.installSpec.trim().startsWith("clawhub:")) {
+      return [{ artifact, message: "OpenClaw ClawHub clawhub.json must declare installSpec starting with clawhub:" }];
+    }
+    if (typeof parsed.name !== "string" || parsed.name.trim().length === 0) {
+      return [{ artifact, message: "OpenClaw ClawHub clawhub.json must declare a non-empty name" }];
+    }
+    return [];
+  } catch (error) {
+    return [{ artifact, message: `OpenClaw ClawHub clawhub.json must be valid JSON: ${errorMessage(error)}` }];
+  }
+}
 async function openClawPluginManifestPaths(artifact) {
   const root = artifactPath(artifact);
   const candidates = [join14(root, "plugin.json"), join14(root, "openclaw.plugin.json")];
@@ -2985,7 +3125,7 @@ async function openClawPluginManifestPaths(artifact) {
 async function parseOpenClawPluginManifest(manifestPath) {
   const manifestName = basename6(manifestPath);
   try {
-    const parsed = JSON.parse(await readFile13(manifestPath, "utf8"));
+    const parsed = JSON.parse(await readFile14(manifestPath, "utf8"));
     if (!isRecord5(parsed)) {
       return { ok: false, path: manifestPath, message: `OpenClaw ${manifestName} must be a JSON object` };
     }
@@ -3002,7 +3142,7 @@ async function parseJsonObjectArtifact(artifact) {
     return { ok: false, message: "merge artifacts must be JSON files" };
   }
   try {
-    const parsed = JSON.parse(await readFile13(artifactPath(artifact), "utf8"));
+    const parsed = JSON.parse(await readFile14(artifactPath(artifact), "utf8"));
     if (!isRecord5(parsed)) return { ok: false, message: "merge artifacts must contain a JSON object" };
     return { ok: true, value: parsed };
   } catch (error) {
@@ -3014,7 +3154,7 @@ async function parseYamlObjectArtifact(artifact) {
     return { ok: false, message: "merge artifacts must be YAML files" };
   }
   try {
-    const document = parseDocument2(await readFile13(artifactPath(artifact), "utf8"));
+    const document = parseDocument2(await readFile14(artifactPath(artifact), "utf8"));
     if (document.errors.length > 0) {
       return { ok: false, message: `merge artifact must be valid YAML: ${document.errors[0]?.message ?? "parse error"}` };
     }
@@ -3139,7 +3279,7 @@ async function createPlanFromOperations(desiredOps, adapter, targetRoot, manifes
       }
       const currentHash2 = await transport.hashPath(op.destPath);
       if (existing2 && existing2.sourceHash === op.desiredHash) {
-        operations.push({ ...op, action: "skip", currentHash: currentHash2, manifestHash: existing2.hash, reason: "merged source already up to date" });
+        operations.push(options.forceDrift ? { ...op, action: "update", currentHash: currentHash2, manifestHash: existing2.hash, reason: "force refreshing managed merge destination" } : { ...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 destination" });
       }
@@ -3186,6 +3326,7 @@ async function createPlanFromOperations(desiredOps, adapter, targetRoot, manifes
           action: "update",
           currentHash,
           manifestHash: existing.hash,
+          overrideDrift: true,
           reason: reasonWithComposedDiff("force replacing drifted managed destination", op.composedFrom, existing.composedFrom),
           composedFromDiff
         });
@@ -3245,7 +3386,7 @@ async function createPlanFromOperations(desiredOps, adapter, targetRoot, manifes
         mode: entry.mode,
         composedFrom: entry.composedFrom,
         ...operationMetadataFromEntry(entry),
-        ...options.forceDrift ? { action: "remove", reason: "force removing drifted stale managed destination" } : {}
+        ...options.forceDrift ? { action: "remove", reason: "force removing drifted stale managed destination", overrideDrift: true } : {}
       });
     } else {
       operations.push({
@@ -3422,6 +3563,7 @@ async function planManagedBlockOperation(op, manifestByPath, transport, options,
         action: "update",
         currentHash: state.hash,
         manifestHash: existing.hash,
+        overrideDrift: true,
         reason: reasonWithComposedDiff("force replacing drifted managed instruction block", op.composedFrom, existing.composedFrom),
         composedFromDiff
       }];
@@ -3452,7 +3594,7 @@ 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;
+  return state.hash;
 }
 async function canStrictlyAdoptLegacyEntry(entry, op, targetRoot, transport) {
   if (entry.artifactType !== op.artifactType || entry.artifactName !== op.artifactName) return false;
@@ -3924,7 +4066,7 @@ 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;
+  return state.hash;
 }
 function operationMetadataFromEntry2(entry, ownersOverride) {
   if ("owners" in entry) {
@@ -4148,15 +4290,17 @@ function ownerChains(lock, nodeId) {
   return incoming.flatMap((edge) => ownerChains(lock, edge.from).map((chain) => [...chain, `${edge.alias}:${nodeId}`]));
 }
 
-// src/source/git.ts
-import { execFile as execFile4 } from "child_process";
-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 basename9, dirname as dirname11, join as join19, resolve as resolve6 } from "path";
-import { promisify as promisify4 } from "util";
+// src/source/clawhub.ts
+import { mkdir as mkdir10, rm as rm5, writeFile as writeFile12 } from "fs/promises";
+import { basename as basename9, dirname as dirname12, join as join19, resolve as resolve6 } from "path";
+
+// src/source/local.ts
+import { createHash as createHash4 } from "crypto";
+import { readdir, stat as stat3 } from "fs/promises";
+import { basename as basename8, join as join18, relative as relative4, resolve as resolve5 } from "path";
 
 // src/model/package.ts
-import { readFile as readFile14 } from "fs/promises";
+import { readFile as readFile15 } 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";
@@ -4181,6 +4325,7 @@ var packageProvideBaseSchema = z5.object({
 var packageItemSchema = z5.object({
   format: artifactFormatSchema.optional(),
   requires: z5.array(packageItemRequireSchema).optional(),
+  suggests: z5.array(packageItemSuggestSchema).optional(),
   compose: z5.array(packageComposeEntrySchema).optional(),
   runtimes: runtimeListSchema.optional()
 });
@@ -4194,6 +4339,10 @@ var packageDependencySchema = z5.object({
   integrity: z5.string().min(1).optional(),
   runtimes: runtimeListSchema.optional()
 });
+var packageSuggestionSchema = packageDependencySchema.extend({
+  reason: z5.string().min(1).optional(),
+  when: z5.string().min(1).optional()
+});
 var packageProvideV1Schema = packageProvideBaseSchema.extend({
   type: legacyArtifactTypeSchema
 });
@@ -4214,6 +4363,7 @@ var packageManifestV2Schema = z5.object({
   version: z5.string().min(1),
   runtimes: runtimeListSchema.optional(),
   requires: z5.record(z5.string().min(1), packageDependencySchema).optional(),
+  suggests: z5.record(z5.string().min(1), packageSuggestionSchema).optional(),
   compose: z5.array(packageComposeEntrySchema).optional(),
   provides: z5.array(packageProvideSchema).default([])
 }).superRefine((manifest, ctx) => {
@@ -4247,7 +4397,7 @@ async function findPackageManifestPath(root, options = {}) {
 async function readPackageManifest(root) {
   const path = await findPackageManifestPath(root);
   if (!path) return void 0;
-  const content = await readFile14(path, "utf8");
+  const content = await readFile15(path, "utf8");
   const errors = [];
   const parsed = parse3(content, errors, { allowTrailingComma: true, disallowComments: false });
   if (errors.length > 0) {
@@ -4301,9 +4451,6 @@ function isRecord6(value) {
 }
 
 // src/source/local.ts
-import { createHash as createHash4 } from "crypto";
-import { readdir, stat as stat3 } from "fs/promises";
-import { basename as basename8, join as join18, relative as relative4, resolve as resolve5 } from "path";
 var LocalSourceDriver = class {
   name = "local";
   async resolve(source) {
@@ -4527,6 +4674,7 @@ async function artifactForFile(type, name, sourcePath, relativePath, packageName
     assets: provide?.assets,
     required: provide?.required,
     requires: item.requires,
+    suggests: item.suggests,
     compose: item.compose,
     runtimes: item.runtimes ?? provideRuntimes(provide) ?? manifestRuntimes(manifest)
   };
@@ -4546,6 +4694,7 @@ async function artifactForDir(type, name, sourcePath, relativePath, packageName,
     assets: provide?.assets,
     required: provide?.required,
     requires: item.requires,
+    suggests: item.suggests,
     compose: item.compose,
     runtimes: item.runtimes ?? provideRuntimes(provide) ?? manifestRuntimes(manifest)
   };
@@ -4554,7 +4703,7 @@ function itemMetadata(provide, itemName) {
   if (!provide || !("items" in provide) || !provide.items || !itemName) return {};
   const item = provide.items[itemName];
   if (!item) return {};
-  return { format: item.format, requires: item.requires, compose: item.compose, runtimes: item.runtimes };
+  return { format: item.format, requires: item.requires, suggests: item.suggests, compose: item.compose, runtimes: item.runtimes };
 }
 function provideRuntimes(provide) {
   return provide && "runtimes" in provide ? provide.runtimes : void 0;
@@ -4563,7 +4712,154 @@ function manifestRuntimes(manifest) {
   return manifest && manifest.schemaVersion === 2 ? manifest.runtimes : void 0;
 }
 
+// src/source/clawhub.ts
+var clawHubBaseUrl = "https://clawhub.ai/api/v1";
+var sourcePrefix = "clawhub:";
+var transientStatuses = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var ClawHubSourceDriver = class {
+  constructor(fetchImpl = fetch) {
+    this.fetchImpl = fetchImpl;
+  }
+  fetchImpl;
+  name = "clawhub";
+  local = new LocalSourceDriver();
+  async resolve(source, options = {}) {
+    const packageName = parseClawHubSource(source);
+    return {
+      driver: this.name,
+      source,
+      resolvedPath: cachePathFor(packageName, options.cacheRoot),
+      packageName: `clawhub/${packageName}`,
+      mode: options.mode ?? "tracking",
+      requestedRef: options.ref ?? "latest",
+      frozenLock: options.frozenLock,
+      cacheLockTimeoutMs: options.cacheLockTimeoutMs
+    };
+  }
+  async fetch(resolved) {
+    if (resolved.frozenLock) {
+      if (!await pathExists(resolved.resolvedPath)) {
+        throw new Error(`Frozen lock requires cached ClawHub source at ${resolved.resolvedPath}`);
+      }
+      return {
+        ...resolved,
+        sourceHash: await hashPath(resolved.resolvedPath)
+      };
+    }
+    const requestedName = parseClawHubSource(resolved.source);
+    const response = await fetchClawHubPackage(this.fetchImpl, requestedName);
+    if (!response.ok) {
+      throw new Error(`ClawHub lookup failed for ${requestedName}: HTTP ${response.status}`);
+    }
+    const payload = await response.json();
+    const packageInfo = payload.package;
+    if (!packageInfo?.name) {
+      throw new Error(`ClawHub response missing package metadata for ${requestedName}`);
+    }
+    if (!isInstallableOpenClawPackage(packageInfo.family)) {
+      throw new Error(`ClawHub package is not an OpenClaw plugin or hook package: ${packageInfo.name}`);
+    }
+    await writeGeneratedPackage(resolved.resolvedPath, packageInfo);
+    return {
+      ...resolved,
+      packageName: `clawhub/${packageInfo.name}`,
+      packageVersion: packageInfo.latestVersion ?? "latest",
+      sourceHash: await hashPath(resolved.resolvedPath)
+    };
+  }
+  async list(resolved) {
+    return this.local.list({ ...resolved, driver: "local" });
+  }
+  async scan(resolved) {
+    if (!await pathExists(join19(resolved.resolvedPath, "plugins"))) {
+      return { ok: false, findings: [{ level: "error", message: "ClawHub source has no generated plugin artifact" }] };
+    }
+    return { ok: true, findings: [] };
+  }
+  async translate(resolved) {
+    return resolved;
+  }
+  async export(resolved) {
+    return resolved;
+  }
+};
+async function fetchClawHubPackage(fetchImpl, packageName) {
+  const url = `${clawHubBaseUrl}/packages/${encodeURIComponent(packageName)}`;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const response = await fetchImpl(url, { headers: { Accept: "application/json" } });
+    if (!transientStatuses.has(response.status) || attempt === 2) return response;
+    await delay((attempt + 1) * 250);
+  }
+  throw new Error(`ClawHub lookup failed for ${packageName}`);
+}
+async function delay(ms) {
+  await new Promise((resolve21) => setTimeout(resolve21, ms));
+}
+function parseClawHubSource(source) {
+  if (!source.startsWith(sourcePrefix)) {
+    throw new Error(`Invalid ClawHub source: ${source}`);
+  }
+  const packageName = source.slice(sourcePrefix.length).trim();
+  if (!packageName) throw new Error(`Invalid ClawHub source: ${source}`);
+  return packageName;
+}
+function isInstallableOpenClawPackage(family) {
+  if (!family) return true;
+  return family.endsWith("-plugin") || family === "hook-pack";
+}
+async function writeGeneratedPackage(root, packageInfo) {
+  const name = packageInfo.name?.trim();
+  if (!name) throw new Error("ClawHub package metadata must include a name");
+  const pluginId = installNameFor2(packageInfo.runtimeId ?? name);
+  const plugin = {
+    name,
+    installSpec: `${sourcePrefix}${name}`,
+    pluginId,
+    displayName: packageInfo.displayName,
+    runtimeId: packageInfo.runtimeId,
+    latestVersion: packageInfo.latestVersion,
+    family: packageInfo.family,
+    summary: packageInfo.summary ?? packageInfo.description,
+    artifact: packageInfo.artifact,
+    verification: packageInfo.verification
+  };
+  const pluginPath = join19(root, "plugins", pluginId, "clawhub.json");
+  await rm5(root, { recursive: true, force: true });
+  await mkdir10(dirname12(pluginPath), { recursive: true });
+  await writeFile12(join19(root, "openpack.json"), `${JSON.stringify({
+    schemaVersion: 2,
+    name: `clawhub/${name}`,
+    version: packageInfo.latestVersion ?? "latest",
+    runtimes: ["openclaw"],
+    provides: [
+      {
+        type: "plugins",
+        path: "plugins",
+        format: "openclaw-clawhub-plugin",
+        runtimes: ["openclaw"],
+        required: true
+      }
+    ]
+  }, null, 2)}
+`, "utf8");
+  await writeFile12(pluginPath, `${JSON.stringify(plugin, null, 2)}
+`, "utf8");
+}
+function installNameFor2(value) {
+  return basename9(value).replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "") || "clawhub-plugin";
+}
+function cachePathFor(packageName, cacheRoot) {
+  const root = cacheRoot ? resolve6(cacheRoot) : join19(process.env.HOME ?? ".", ".agentwheel", "cache");
+  const slug2 = `clawhub-${packageName}`.replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "");
+  return join19(root, slug2 || "clawhub-package");
+}
+
 // src/source/git.ts
+import { execFile as execFile4 } from "child_process";
+import { cp as cp2, mkdir as mkdir11, rename as rename3, rm as rm6, writeFile as writeFile13 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { basename as basename10, dirname as dirname13, join as join20, resolve as resolve7 } from "path";
+import { promisify as promisify4 } from "util";
 var execFileAsync4 = promisify4(execFile4);
 var GitSourceDriver = class {
   name = "git";
@@ -4575,7 +4871,7 @@ var GitSourceDriver = class {
     return {
       driver: this.name,
       source,
-      resolvedPath: cachePathFor(parsed.url, options.cacheRoot),
+      resolvedPath: cachePathFor2(parsed.url, options.cacheRoot),
       mode,
       requestedRef,
       frozenLock: options.frozenLock,
@@ -4585,12 +4881,12 @@ var GitSourceDriver = class {
   async fetch(resolved) {
     return withFilesystemLock(`${resolved.resolvedPath}.lock`, resolved.cacheLockTimeoutMs ?? 3e4, async () => {
       const parsed = parseGitSource(resolved.source);
-      await mkdir9(resolve6(resolved.resolvedPath, ".."), { recursive: true });
-      if (!await pathExists(join19(resolved.resolvedPath, ".git"))) {
+      await mkdir11(resolve7(resolved.resolvedPath, ".."), { recursive: true });
+      if (!await pathExists(join20(resolved.resolvedPath, ".git"))) {
         if (resolved.frozenLock) {
           throw new Error(`Frozen lock requires cached git checkout at ${resolved.resolvedPath}`);
         }
-        await rm5(resolved.resolvedPath, { recursive: true, force: true });
+        await rm6(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"]);
@@ -4652,65 +4948,201 @@ function parseGitSource(source) {
   }
   throw new Error(`Invalid git source: ${source}`);
 }
-function cachePathFor(url, cacheRoot) {
-  const root = cacheRoot ? resolve6(cacheRoot) : join19(homedir2(), ".agentwheel", "cache");
+function cachePathFor2(url, cacheRoot) {
+  const root = cacheRoot ? resolve7(cacheRoot) : join20(homedir2(), ".agentwheel", "cache");
   const slug2 = url.replace(/^[a-z]+:\/\//i, "").replace(/\.git$/i, "").replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "");
-  return join19(root, slug2 || basename9(url));
+  return join20(root, slug2 || basename10(url));
 }
 async function git(args) {
   return execFileAsync4("git", args, { maxBuffer: 1024 * 1024 * 10 });
 }
 async function snapshotCheckout(checkoutPath, commit) {
-  const snapshotPath = join19(dirname11(checkoutPath), `${basename9(checkoutPath)}-${commit.slice(0, 12)}`);
+  const snapshotPath = join20(dirname13(checkoutPath), `${basename10(checkoutPath)}-${commit.slice(0, 12)}`);
   if (await pathExists(snapshotPath)) return snapshotPath;
-  const tempPath = join19(dirname11(checkoutPath), `${basename9(snapshotPath)}.tmp-${process.pid}-${Date.now()}`);
-  await rm5(tempPath, { recursive: true, force: true });
+  const tempPath = join20(dirname13(checkoutPath), `${basename10(snapshotPath)}.tmp-${process.pid}-${Date.now()}`);
+  await rm6(tempPath, { recursive: true, force: true });
   await cp2(checkoutPath, tempPath, { recursive: true, dereference: true });
-  await rm5(join19(tempPath, ".git"), { recursive: true, force: true });
+  await rm6(join20(tempPath, ".git"), { recursive: true, force: true });
   try {
     await rename3(tempPath, snapshotPath);
   } catch (error) {
     if (!isAlreadyExists2(error)) throw error;
-    await rm5(tempPath, { recursive: true, force: true });
+    await rm6(tempPath, { recursive: true, force: true });
     return snapshotPath;
   }
   return snapshotPath;
 }
 async function withFilesystemLock(lockPath, timeoutMs, fn) {
-  await mkdir9(dirname11(lockPath), { recursive: true });
+  await mkdir11(dirname13(lockPath), { recursive: true });
   const started = Date.now();
   while (true) {
     try {
-      await mkdir9(lockPath);
-      await writeFile11(join19(lockPath, "owner.json"), JSON.stringify({ pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() }), "utf8");
+      await mkdir11(lockPath);
+      await writeFile13(join20(lockPath, "owner.json"), JSON.stringify({ pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() }), "utf8");
       break;
     } catch (error) {
       if (!isAlreadyExists2(error)) throw error;
       if (Date.now() - started > timeoutMs) {
         throw new Error(`Timed out waiting for git cache lock at ${lockPath}`);
       }
-      await new Promise((resolve19) => setTimeout(resolve19, 50));
+      await new Promise((resolve21) => setTimeout(resolve21, 50));
     }
   }
   try {
     return await fn();
   } finally {
-    await rm5(lockPath, { recursive: true, force: true });
+    await rm6(lockPath, { recursive: true, force: true });
   }
 }
 function isAlreadyExists2(error) {
   return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
 }
 
+// src/source/mcp-registry.ts
+import { mkdir as mkdir12, writeFile as writeFile14 } from "fs/promises";
+import { basename as basename11, dirname as dirname14, join as join21, resolve as resolve8 } from "path";
+var registryBaseUrl = "https://registry.modelcontextprotocol.io/v0.1";
+var sourcePrefix2 = "mcp-registry:";
+var McpRegistrySourceDriver = class {
+  constructor(fetchImpl = fetch) {
+    this.fetchImpl = fetchImpl;
+  }
+  fetchImpl;
+  name = "mcp-registry";
+  local = new LocalSourceDriver();
+  async resolve(source, options = {}) {
+    const serverName = parseMcpRegistrySource(source);
+    return {
+      driver: this.name,
+      source,
+      resolvedPath: cachePathFor3(serverName, options.cacheRoot),
+      packageName: `mcp-registry/${serverName}`,
+      mode: options.mode ?? "tracking",
+      requestedRef: options.ref ?? "latest",
+      frozenLock: options.frozenLock
+    };
+  }
+  async fetch(resolved) {
+    if (resolved.frozenLock) {
+      if (!await pathExists(resolved.resolvedPath)) {
+        throw new Error(`Frozen lock requires cached MCP registry source at ${resolved.resolvedPath}`);
+      }
+      return {
+        ...resolved,
+        sourceHash: await hashPath(resolved.resolvedPath)
+      };
+    }
+    const serverName = parseMcpRegistrySource(resolved.source);
+    const response = await this.fetchImpl(`${registryBaseUrl}/servers/${encodeURIComponent(serverName)}/versions/latest`, {
+      headers: { Accept: "application/json" }
+    });
+    if (!response.ok) {
+      throw new Error(`MCP registry lookup failed for ${serverName}: HTTP ${response.status}`);
+    }
+    const payload = await response.json();
+    const server = payload.server;
+    if (!server?.name) {
+      throw new Error(`MCP registry response missing server metadata for ${serverName}`);
+    }
+    const remote = supportedRemote(server.remotes ?? []);
+    if (!remote) {
+      throw new Error(`MCP registry server is discovery-only for Agentwheel: ${serverName}`);
+    }
+    await writeGeneratedPackage2(resolved.resolvedPath, {
+      serverName: server.name,
+      title: server.title,
+      description: server.description,
+      version: server.version,
+      url: remote.url
+    });
+    return {
+      ...resolved,
+      packageName: `mcp-registry/${server.name}`,
+      packageVersion: server.version,
+      sourceHash: await hashPath(resolved.resolvedPath)
+    };
+  }
+  async list(resolved) {
+    return this.local.list({ ...resolved, driver: "local" });
+  }
+  async scan(resolved) {
+    if (!await pathExists(join21(resolved.resolvedPath, "mcp"))) {
+      return { ok: false, findings: [{ level: "error", message: "MCP registry source has no generated mcp artifact" }] };
+    }
+    return { ok: true, findings: [] };
+  }
+  async translate(resolved) {
+    return resolved;
+  }
+  async export(resolved) {
+    return resolved;
+  }
+};
+function parseMcpRegistrySource(source) {
+  if (!source.startsWith(sourcePrefix2)) {
+    throw new Error(`Invalid MCP registry source: ${source}`);
+  }
+  const serverName = source.slice(sourcePrefix2.length).trim();
+  if (!serverName) throw new Error(`Invalid MCP registry source: ${source}`);
+  return serverName;
+}
+function supportedRemote(remotes) {
+  for (const remote of remotes ?? []) {
+    if (remote?.type !== "streamable-http") continue;
+    if (!isSafeHttpUrl(remote.url)) continue;
+    if ((remote.headers ?? []).some((header) => header.isRequired && header.isSecret)) continue;
+    return { url: remote.url };
+  }
+  return void 0;
+}
+function isSafeHttpUrl(value) {
+  if (typeof value !== "string") return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+async function writeGeneratedPackage2(root, server) {
+  const serverId = installNameFor3(server.serverName);
+  const mcpPath = join21(root, "mcp", `${serverId}.json`);
+  await mkdir12(dirname14(mcpPath), { recursive: true });
+  await writeFile14(join21(root, "openpack.json"), `${JSON.stringify({
+    schemaVersion: 2,
+    name: `mcp-registry/${server.serverName}`,
+    version: server.version ?? "latest",
+    provides: [{ type: "mcp", path: "mcp" }]
+  }, null, 2)}
+`, "utf8");
+  await writeFile14(mcpPath, `${JSON.stringify({
+    mcpServers: {
+      [serverId]: {
+        type: "streamable-http",
+        url: server.url
+      }
+    }
+  }, null, 2)}
+`, "utf8");
+}
+function installNameFor3(serverName) {
+  return basename11(serverName).replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "") || "mcp-server";
+}
+function cachePathFor3(serverName, cacheRoot) {
+  const root = cacheRoot ? resolve8(cacheRoot) : join21(process.env.HOME ?? ".", ".agentwheel", "cache");
+  const slug2 = `mcp-registry-${serverName}`.replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "");
+  return join21(root, slug2 || "mcp-registry-server");
+}
+
 // src/source/skillkit.ts
-import { cp as cp3, mkdir as mkdir10, readFile as readFile15, rm as rm6 } from "fs/promises";
+import { cp as cp3, mkdir as mkdir13, readFile as readFile16, rm as rm7 } from "fs/promises";
 import { homedir as homedir3 } from "os";
-import { basename as basename11, dirname as dirname13, join as join21, resolve as resolve7 } from "path";
+import { basename as basename13, dirname as dirname16, join as join23, resolve as resolve9 } 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 basename10, dirname as dirname12, extname as extname2, join as join20 } from "path";
+import { basename as basename12, dirname as dirname15, extname as extname2, join as join22 } from "path";
 async function artifactsFromSkillPaths(paths, packageName) {
   const artifacts = [];
   const seen = /* @__PURE__ */ new Set();
@@ -4732,28 +5164,28 @@ async function discoverSkillPaths(root) {
 async function artifactFromSkillPath(item, packageName) {
   const stats = await stat4(item.path);
   if (stats.isDirectory()) {
-    const skillMd = join20(item.path, "SKILL.md");
+    const skillMd = join22(item.path, "SKILL.md");
     if (!await pathExists(skillMd)) return void 0;
-    const name = sanitizeSkillName(item.name ?? basename10(item.path));
+    const name = sanitizeSkillName(item.name ?? basename12(item.path));
     return {
       type: "skills",
       name,
       sourcePath: item.path,
-      relativePath: join20("skills", name),
+      relativePath: join22("skills", name),
       kind: "dir",
       hash: await hashPath(item.path),
       packageName,
       channel: "managed"
     };
   }
-  if (stats.isFile() && basename10(item.path).toLowerCase() === "skill.md") {
-    const dir = dirname12(item.path);
-    const name = sanitizeSkillName(item.name ?? basename10(dir));
+  if (stats.isFile() && basename12(item.path).toLowerCase() === "skill.md") {
+    const dir = dirname15(item.path);
+    const name = sanitizeSkillName(item.name ?? basename12(dir));
     return {
       type: "skills",
       name,
       sourcePath: dir,
-      relativePath: join20("skills", name),
+      relativePath: join22("skills", name),
       kind: "dir",
       hash: await hashPath(dir),
       packageName,
@@ -4761,12 +5193,12 @@ async function artifactFromSkillPath(item, packageName) {
     };
   }
   if (stats.isFile() && extname2(item.path).toLowerCase() === ".md") {
-    const name = sanitizeSkillName(item.name ?? basename10(item.path, ".md"));
+    const name = sanitizeSkillName(item.name ?? basename12(item.path, ".md"));
     return {
       type: "skills",
       name,
       sourcePath: item.path,
-      relativePath: join20("skills", `${name}.md`),
+      relativePath: join22("skills", `${name}.md`),
       kind: "file",
       hash: await hashPath(item.path),
       packageName,
@@ -4784,7 +5216,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(join20(dir, entry.name), paths);
+    await walk(join22(dir, entry.name), paths);
   }
 }
 function sanitizeSkillName(name) {
@@ -4801,12 +5233,12 @@ var SkillKitSourceDriver = class {
   async resolve(source, options = {}) {
     const spec = parseSkillKitSource(source);
     if (await pathExists(spec)) {
-      const resolvedPath = resolve7(spec);
+      const resolvedPath = resolve9(spec);
       return {
         driver: this.name,
         source,
         resolvedPath,
-        packageName: `skillkit/${basename11(resolvedPath)}`,
+        packageName: `skillkit/${basename13(resolvedPath)}`,
         mode: options.mode ?? "pinned",
         sourceHash: await hashPath(resolvedPath)
       };
@@ -4814,7 +5246,7 @@ var SkillKitSourceDriver = class {
     return {
       driver: this.name,
       source,
-      resolvedPath: cachePathFor2(spec, options.cacheRoot),
+      resolvedPath: cachePathFor4(spec, options.cacheRoot),
       packageName: `skillkit/${packageSlug(spec)}`,
       mode: options.mode ?? "tracking",
       requestedRef: options.ref,
@@ -4840,17 +5272,17 @@ var SkillKitSourceDriver = class {
     if (!provider?.clone) {
       throw new Error("SkillKit provider API unavailable or cannot resolve source. Expected @skillkit/core detectProvider().clone().");
     }
-    await mkdir10(dirname13(resolved.resolvedPath), { recursive: true });
+    await mkdir13(dirname16(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 rm6(resolved.resolvedPath, { recursive: true, force: true });
+    if (resolve9(result.path) !== resolve9(resolved.resolvedPath)) {
+      await rm7(resolved.resolvedPath, { recursive: true, force: true });
       await cp3(result.path, resolved.resolvedPath, { recursive: true, dereference: true });
     }
     if (result.tempRoot) {
-      await rm6(result.tempRoot, { recursive: true, force: true });
+      await rm7(result.tempRoot, { recursive: true, force: true });
     }
     return {
       ...resolved,
@@ -4884,9 +5316,9 @@ var SkillKitSourceDriver = class {
       throw new Error("SkillKit translateSkill API unavailable");
     }
     for (const skill of this.discover(resolved.resolvedPath)) {
-      const skillMd = join21(skill.path, "SKILL.md");
+      const skillMd = join23(skill.path, "SKILL.md");
       if (await pathExists(skillMd)) {
-        this.core.translateSkill(await readFile15(skillMd, "utf8"), "openclaw", { sourceFilename: "SKILL.md" });
+        this.core.translateSkill(await readFile16(skillMd, "utf8"), "openclaw", { sourceFilename: "SKILL.md" });
       }
     }
     return resolved;
@@ -4914,9 +5346,9 @@ function normalizeProviderSource(spec) {
   if (spec.startsWith("git:https://github.com/")) return spec.slice("git:".length);
   return spec;
 }
-function cachePathFor2(spec, cacheRoot) {
-  const root = cacheRoot ? resolve7(cacheRoot) : join21(homedir3(), ".agentwheel", "cache");
-  return join21(root, "skillkit", packageSlug(spec));
+function cachePathFor4(spec, cacheRoot) {
+  const root = cacheRoot ? resolve9(cacheRoot) : join23(homedir3(), ".agentwheel", "cache");
+  return join23(root, "skillkit", packageSlug(spec));
 }
 function packageSlug(spec) {
   return spec.replace(/^[a-z]+:\/\//i, "").replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "") || "source";
@@ -4929,14 +5361,14 @@ function mapSeverity(severity) {
 
 // src/source/vercel-skills.ts
 import { stat as stat5 } from "fs/promises";
-import { basename as basename12, join as join22, resolve as resolve8 } from "path";
+import { basename as basename14, join as join24, relative as relative5, resolve as resolve10 } from "path";
 var VercelSkillsSourceDriver = class {
   name = "vercel-skills";
   git = new GitSourceDriver();
   async resolve(source, options = {}) {
     const parsed = parseVercelSource(source);
     if (parsed.kind === "local") {
-      const resolvedPath = resolve8(parsed.path);
+      const resolvedPath = resolve10(parsed.path);
       if (!await pathExists(resolvedPath) || !(await stat5(resolvedPath)).isDirectory()) {
         throw new Error(`Vercel skills local source not found: ${resolvedPath}`);
       }
@@ -4944,7 +5376,7 @@ var VercelSkillsSourceDriver = class {
         driver: this.name,
         source,
         resolvedPath,
-        packageName: `vercel/${basename12(resolvedPath)}`,
+        packageName: `vercel/${basename14(resolvedPath)}`,
         mode: options.mode ?? "pinned",
         sourceHash: await hashPath(resolvedPath)
       };
@@ -4965,10 +5397,7 @@ var VercelSkillsSourceDriver = class {
       driver: "git",
       source: parsed.gitSource
     });
-    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}`);
-    }
+    const resolvedPath = await resolveVercelSkillSubpath(fetched.resolvedPath, parsed.subpath);
     return {
       ...resolved,
       resolvedPath,
@@ -4993,6 +5422,15 @@ var VercelSkillsSourceDriver = class {
     return resolved;
   }
 };
+async function resolveVercelSkillSubpath(root, subpath) {
+  if (!subpath) return root;
+  const candidates = [join24(root, subpath), join24(root, "skills", subpath)];
+  for (const candidate of candidates) {
+    if (await pathExists(candidate)) return candidate;
+  }
+  const tried = candidates.map((candidate) => relative5(root, candidate)).join(", ");
+  throw new Error(`Vercel skills subpath not found: ${subpath} (tried ${tried})`);
+}
 function parseVercelSource(source) {
   if (!source.startsWith("vercel:")) {
     throw new Error(`Invalid Vercel skills source: ${source}`);
@@ -5043,7 +5481,9 @@ var drivers = [
   new LocalSourceDriver(),
   new GitSourceDriver(),
   new SkillKitSourceDriver(),
-  new VercelSkillsSourceDriver()
+  new VercelSkillsSourceDriver(),
+  new McpRegistrySourceDriver(),
+  new ClawHubSourceDriver()
 ];
 function getSourceDriver(name = "local") {
   const driver = drivers.find((candidate) => candidate.name === name);
@@ -5054,14 +5494,14 @@ function getSourceDriver(name = "local") {
 }
 
 // src/staging/staging.ts
-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 { chmod, cp as cp5, mkdir as mkdir15, mkdtemp as mkdtemp3, readdir as readdir5, stat as stat8 } from "fs/promises";
+import { basename as basename17, dirname as dirname19, join as join27, relative as relative7, resolve as resolve12, sep as sep2 } from "path";
 import { tmpdir as tmpdir4 } from "os";
 
 // src/compose/markdown.ts
 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";
+import { readdir as readdir3, readFile as readFile17, stat as stat6, writeFile as writeFile15 } from "fs/promises";
+import { basename as basename15, dirname as dirname17, extname as extname3, join as join25, relative as relative6, resolve as resolve11, 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/;
@@ -5076,7 +5516,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 writeFile12(file, result.content, "utf8");
+      if (result.changed) await writeFile15(file, result.content, "utf8");
       composedFrom.push(...result.composedFrom);
     }
     const stagedPath = artifact.stagedPath ?? artifact.sourcePath;
@@ -5098,7 +5538,7 @@ async function validateMarkdownIncludes(artifacts, packageRoot, options = {}) {
   }
 }
 async function expandFile(file, packageRoot, appendEntries, artifactPaths, options) {
-  const raw = await readFile16(file, "utf8");
+  const raw = await readFile17(file, "utf8");
   const owner = ownerSelector(packageRoot, file, options.nodeId);
   const expanded = await expandContent(raw, packageRoot, [owner], artifactPaths, options);
   let content = expanded.content;
@@ -5191,7 +5631,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 readFile16(sourcePath, "utf8");
+  const raw = sourceContent ?? await readFile17(sourcePath, "utf8");
   const { optional: _optional, markers: _markers, chain: _chain, ...childOptions } = options;
   const expanded = await expandContent(raw, includePackageRoot, [...options.chain, displaySelector], includeArtifactPaths, {
     ...childOptions,
@@ -5249,8 +5689,8 @@ function extractOpenPackIncludeSelectors(content) {
   return selectors;
 }
 function resolvePackageSelector(packageRoot, selector) {
-  const root = resolve9(packageRoot);
-  const resolved = resolve9(root, selector);
+  const root = resolve11(packageRoot);
+  const resolved = resolve11(root, selector);
   if (resolved !== root && !resolved.startsWith(`${root}${sep}`)) {
     throw new Error(`OpenPack include escapes package root: ${selector}`);
   }
@@ -5267,7 +5707,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 = join23(dir, entry.name);
+      const full = join25(dir, entry.name);
       if (entry.isDirectory()) {
         await walk2(full);
       } else if (entry.isFile() && extname3(entry.name).toLowerCase() === ".md") {
@@ -5280,8 +5720,8 @@ 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 basename13(file) === "SKILL.md" && dirname14(file) === resolve9(artifact.stagedPath ?? artifact.sourcePath) ? artifact.compose : [];
+  if (artifact.kind === "file") return [resolve11(artifact.stagedPath ?? artifact.sourcePath), resolve11(file)].every(Boolean) && resolve11(artifact.stagedPath ?? artifact.sourcePath) === resolve11(file) ? artifact.compose : [];
+  return basename15(file) === "SKILL.md" && dirname17(file) === resolve11(artifact.stagedPath ?? artifact.sourcePath) ? artifact.compose : [];
 }
 function orderedForExpansion(artifacts) {
   return [...artifacts].sort((a, b) => Number(a.type === "fragments") - Number(b.type === "fragments"));
@@ -5298,7 +5738,7 @@ function applyReplacements(content, replacements) {
   return out + content.slice(cursor);
 }
 function relativeSelector(root, file) {
-  return relative5(root, file).replaceAll("\\", "/");
+  return relative6(root, file).replaceAll("\\", "/");
 }
 function ownerSelector(root, file, nodeId) {
   const selector = relativeSelector(root, file);
@@ -5327,8 +5767,8 @@ function artifactPathMap(artifacts) {
 }
 
 // src/staging/customize.ts
-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";
+import { cp as cp4, mkdir as mkdir14, readdir as readdir4, readFile as readFile18, writeFile as writeFile16 } from "fs/promises";
+import { dirname as dirname18, join as join26 } from "path";
 async function applyCustomizations(artifacts, options) {
   let next = [...artifacts];
   next = await applyReplacements2(next, options, "override", installableArtifactTypes());
@@ -5344,16 +5784,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 = join24(options.workspaceRoot, ".agentwheel", "overlays", options.adapter.name, "instructions.local.md");
+  const overlayPath = join26(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 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(
+  const managed = await readFile18(artifact.stagedPath ?? artifact.sourcePath, "utf8");
+  const local = await readFile18(overlayPath, "utf8");
+  const composedPath = join26(options.stageRoot, ".agentwheel-composed", "instructions", "AGENTS.md");
+  await mkdir14(dirname18(composedPath), { recursive: true });
+  await writeFile16(
     composedPath,
     [
       "<!-- BEGIN agentwheel managed: upstream -->",
@@ -5379,19 +5819,19 @@ async function applyInstructionOverlay(artifacts, options) {
   return [...artifacts.slice(0, index), updated, ...artifacts.slice(index + 1)];
 }
 async function applyAdditions(artifacts, options) {
-  const additionsRoot = join24(options.workspaceRoot, ".agentwheel", "additions");
-  const rulesRoot = join24(additionsRoot, "rules");
+  const additionsRoot = join26(options.workspaceRoot, ".agentwheel", "additions");
+  const rulesRoot = join26(additionsRoot, "rules");
   if (!await pathExists(rulesRoot)) return artifacts;
   const additions = [];
   for (const entry of await sortedDirEntries2(rulesRoot)) {
-    const full = join24(rulesRoot, entry.name);
+    const full = join26(rulesRoot, entry.name);
     if (!entry.isFile()) continue;
     additions.push({
       type: "rules",
       name: entry.name,
       sourcePath: full,
       stagedPath: full,
-      relativePath: join24("additions", "rules", entry.name),
+      relativePath: join26("additions", "rules", entry.name),
       kind: "file",
       hash: await hashPath(full),
       packageName: options.packageName,
@@ -5415,17 +5855,17 @@ async function applyReplacements2(artifacts, options, channel, artifactTypes) {
       );
     }
     for (const type of artifactTypes) {
-      const typeRoot = join24(root, type);
+      const typeRoot = join26(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 = join24(typeRoot, entry.name);
+        const full = join26(typeRoot, entry.name);
         const artifactKind = entry.isDirectory() ? "dir" : "file";
         const existing = byKey.get(artifactMapKey);
-        const stagedPath = join24(options.stageRoot, ".agentwheel-composed", channel, type, entry.name);
-        await mkdir11(dirname15(stagedPath), { recursive: true });
+        const stagedPath = join26(options.stageRoot, ".agentwheel-composed", channel, type, entry.name);
+        await mkdir14(dirname18(stagedPath), { recursive: true });
         await cp4(full, stagedPath, { recursive: artifactKind === "dir", dereference: true });
         byKey.set(artifactMapKey, {
           ...existing,
@@ -5433,7 +5873,7 @@ async function applyReplacements2(artifacts, options, channel, artifactTypes) {
           name: entry.name,
           sourcePath: full,
           stagedPath,
-          relativePath: existing?.relativePath ?? join24(type, entry.name),
+          relativePath: existing?.relativePath ?? join26(type, entry.name),
           kind: artifactKind,
           hash: await hashPath(stagedPath),
           packageName,
@@ -5448,13 +5888,13 @@ function replacementRoots(options, channel) {
   const stateDir = channel === "override" ? "overrides" : "ejected";
   const roots = [];
   if (options.graphNodeId) {
-    roots.push({ root: join24(options.workspaceRoot, ".agentwheel", stateDir, ...options.graphNodeId.split("/")), kind: "node" });
+    roots.push({ root: join26(options.workspaceRoot, ".agentwheel", stateDir, ...options.graphNodeId.split("/")), kind: "node" });
   }
   if (options.packageName && options.packageVersion) {
-    roots.push({ root: join24(options.workspaceRoot, ".agentwheel", stateDir, ...`${options.packageName}@${options.packageVersion}`.split("/")), kind: "version" });
+    roots.push({ root: join26(options.workspaceRoot, ".agentwheel", stateDir, ...`${options.packageName}@${options.packageVersion}`.split("/")), kind: "version" });
   }
   if (options.packageName) {
-    roots.push({ root: join24(options.workspaceRoot, ".agentwheel", stateDir, ...options.packageName.split("/")), kind: "package" });
+    roots.push({ root: join26(options.workspaceRoot, ".agentwheel", stateDir, ...options.packageName.split("/")), kind: "package" });
   }
   return roots;
 }
@@ -5481,15 +5921,15 @@ async function stageResolvedSourceRaw(driver, resolved) {
   return stageResolvedArtifactsRaw(resolved, artifacts);
 }
 async function stageResolvedArtifactsRaw(resolved, artifacts) {
-  const root = await mkdtemp3(join25(tmpdir4(), "agentwheel-stage-"));
+  const root = await mkdtemp3(join27(tmpdir4(), "agentwheel-stage-"));
   const stagedArtifacts = [];
   for (const artifact of artifacts) {
-    const stagedPath = join25(root, artifact.relativePath);
-    await mkdir12(dirname16(stagedPath), { recursive: true });
+    const stagedPath = join27(root, artifact.relativePath);
+    await mkdir15(dirname19(stagedPath), { recursive: true });
     await cp5(artifact.sourcePath, stagedPath, {
       recursive: artifact.kind === "dir",
       dereference: true,
-      filter: (path) => !isIgnoredGeneratedEntry(basename15(path))
+      filter: (path) => !isIgnoredGeneratedEntry(basename17(path))
     });
     await composeAssets(artifact, resolved.resolvedPath, stagedPath);
     stagedArtifacts.push({
@@ -5570,16 +6010,16 @@ async function composeAssets(artifact, packageRoot, stagedPath) {
   }
   for (const asset of artifact.assets) {
     const source = resolvePackagePath(packageRoot, asset.from);
-    const dest = join25(stagedPath, asset.into);
+    const dest = join27(stagedPath, asset.into);
     await copyAsset(asset, source, dest);
   }
 }
 async function copyAsset(asset, source, dest) {
   const sourceStats = await stat8(source);
   if (sourceStats.isFile()) {
-    if (matchesAny(basename15(source), asset.include)) {
-      await mkdir12(dest, { recursive: true });
-      await copyAssetFile(source, join25(dest, basename15(source)), asset);
+    if (matchesAny(basename17(source), asset.include)) {
+      await mkdir15(dest, { recursive: true });
+      await copyAssetFile(source, join27(dest, basename17(source)), asset);
     }
     return;
   }
@@ -5587,25 +6027,25 @@ async function copyAsset(asset, source, dest) {
     throw new Error(`Asset include source is not a file or directory: ${source}`);
   }
   if (!asset.include?.length) {
-    await mkdir12(dirname16(dest), { recursive: true });
+    await mkdir15(dirname19(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 = relative6(source, file).replaceAll("\\", "/");
-    if (!matchesAny(rel, asset.include) && !matchesAny(basename15(file), asset.include)) continue;
-    await copyAssetFile(file, join25(dest, rel), asset);
+    const rel = relative7(source, file).replaceAll("\\", "/");
+    if (!matchesAny(rel, asset.include) && !matchesAny(basename17(file), asset.include)) continue;
+    await copyAssetFile(file, join27(dest, rel), asset);
   }
 }
 async function copyAssetFile(source, dest, asset) {
-  await mkdir12(dirname16(dest), { recursive: true });
+  await mkdir15(dirname19(dest), { recursive: true });
   await cp5(source, dest, { dereference: true });
   if (asset.mode === "copy") await chmod(dest, 420);
 }
 function resolvePackagePath(packageRoot, path) {
-  const resolved = resolve10(packageRoot, path);
-  const root = resolve10(packageRoot);
+  const resolved = resolve12(packageRoot, path);
+  const root = resolve12(packageRoot);
   if (resolved !== root && !resolved.startsWith(`${root}${sep2}`)) {
     throw new Error(`Asset include escapes package root: ${path}`);
   }
@@ -5615,7 +6055,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 = join25(dir, entry.name);
+      const full = join27(dir, entry.name);
       if (entry.isDirectory()) {
         await walk2(full);
       } else if (entry.isFile()) {
@@ -5634,7 +6074,7 @@ async function normalizeCopiedModes(path) {
   }
   if (!stats.isDirectory()) return;
   for (const entry of await readdir5(path, { withFileTypes: true })) {
-    await normalizeCopiedModes(join25(path, entry.name));
+    await normalizeCopiedModes(join27(path, entry.name));
   }
 }
 function matchesAny(path, patterns) {
@@ -5647,14 +6087,14 @@ function matchesGlob(path, pattern) {
 }
 
 // src/model/workspace.ts
-import { readFile as readFile18 } from "fs/promises";
+import { readFile as readFile19 } from "fs/promises";
 import { homedir as homedir4 } from "os";
-import { dirname as dirname17, join as join26, resolve as resolve11 } from "path";
+import { dirname as dirname20, join as join28, resolve as resolve13 } from "path";
 import { z as z6 } from "zod";
 var workspacePackageSchema = z6.object({
   name: z6.string().min(1),
   source: z6.string().min(1),
-  driver: z6.enum(["local", "git", "skillkit", "vercel-skills"]).default("local"),
+  driver: z6.enum(["local", "git", "skillkit", "vercel-skills", "mcp-registry", "clawhub"]).default("local"),
   adapter: z6.string().min(1).default("openclaw"),
   adapterConfig: z6.string().min(1).optional(),
   adapterModule: z6.string().min(1).optional(),
@@ -5664,6 +6104,8 @@ var workspacePackageSchema = z6.object({
   requestedRef: z6.string().min(1).optional(),
   select: z6.array(z6.string().min(1)).optional(),
   skills: z6.array(z6.string().min(1)).optional(),
+  withSuggestions: z6.boolean().optional(),
+  suggestions: z6.array(z6.string().min(1)).optional(),
   aliases: z6.record(z6.string(), z6.string().min(1)).optional(),
   overrides: z6.array(z6.string().min(1)).optional()
 });
@@ -5718,12 +6160,12 @@ var workspaceConfigSchema = z6.object({
   agents: z6.record(z6.string(), workspaceAgentSchema).default({})
 });
 function workspaceConfigPath(workspaceRoot) {
-  return join26(workspaceRoot, ".agentwheel", "config.json");
+  return join28(workspaceRoot, ".agentwheel", "config.json");
 }
 async function readWorkspaceConfig(workspaceRoot) {
   const path = workspaceConfigPath(workspaceRoot);
   if (!await pathExists(path)) return emptyWorkspaceConfig();
-  return workspaceConfigSchema.parse(JSON.parse(await readFile18(path, "utf8")));
+  return workspaceConfigSchema.parse(JSON.parse(await readFile19(path, "utf8")));
 }
 async function writeWorkspaceConfig(workspaceRoot, config) {
   await writeJsonAtomic(workspaceConfigPath(workspaceRoot), workspaceConfigSchema.parse(config));
@@ -5736,14 +6178,14 @@ 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 join26(globalRoot, ".agentwheel", "config.json");
+  return join28(globalRoot, ".agentwheel", "config.json");
 }
 async function findWorkspaceRoot(start = process.cwd()) {
-  let current = resolve11(start);
+  let current = resolve13(start);
   while (true) {
     if (await pathExists(workspaceConfigPath(current))) return current;
-    const parent = dirname17(current);
-    if (parent === current) return resolve11(start);
+    const parent = dirname20(current);
+    if (parent === current) return resolve13(start);
     current = parent;
   }
 }
@@ -5769,16 +6211,16 @@ function mergeWorkspaceConfig(global, project) {
   });
 }
 function resolveConfigPath(path, baseRoot) {
-  if (path.startsWith("~/")) return resolve11(homedir4(), path.slice(2));
+  if (path.startsWith("~/")) return resolve13(homedir4(), path.slice(2));
   if (path === "~") return homedir4();
-  return path.startsWith("/") ? resolve11(path) : resolve11(baseRoot, path);
+  return path.startsWith("/") ? resolve13(path) : resolve13(baseRoot, path);
 }
 function emptyWorkspaceConfig() {
   return { schemaVersion: 1, packages: [], registry: {}, trust: {}, profiles: {}, agents: {} };
 }
 async function readConfigPath(path) {
   if (!await pathExists(path)) return emptyWorkspaceConfig();
-  return workspaceConfigSchema.parse(JSON.parse(await readFile18(path, "utf8")));
+  return workspaceConfigSchema.parse(JSON.parse(await readFile19(path, "utf8")));
 }
 function mergeWorkspaceTrust(global, project) {
   return {
@@ -5793,23 +6235,23 @@ function sortedUnique2(values) {
 }
 
 // src/lifecycle/customization.ts
-import { appendFile, cp as cp6, mkdir as mkdir13, rm as rm8 } from "fs/promises";
-import { dirname as dirname19, join as join29 } from "path";
+import { appendFile, cp as cp6, mkdir as mkdir16, rm as rm9 } from "fs/promises";
+import { dirname as dirname22, join as join31 } from "path";
 
 // src/resolve/graph.ts
 import { createHash as createHash6 } from "crypto";
-import { mkdtemp as mkdtemp4, readdir as readdir6, readFile as readFile20, stat as stat10 } from "fs/promises";
+import { mkdtemp as mkdtemp4, readdir as readdir6, readFile as readFile21, stat as stat10 } from "fs/promises";
 import { tmpdir as tmpdir5 } from "os";
-import { basename as basename16, extname as extname4, join as join28 } from "path";
+import { basename as basename18, extname as extname4, join as join30 } from "path";
 
 // src/resolve/identity.ts
 import { homedir as homedir6 } from "os";
-import { resolve as resolve13 } from "path";
+import { resolve as resolve15 } from "path";
 
 // src/registry/client.ts
-import { readFile as readFile19, rm as rm7, stat as stat9 } from "fs/promises";
+import { readFile as readFile20, rm as rm8, stat as stat9 } from "fs/promises";
 import { homedir as homedir5 } from "os";
-import { dirname as dirname18, join as join27, resolve as resolve12 } from "path";
+import { dirname as dirname21, join as join29, resolve as resolve14 } from "path";
 import { fileURLToPath } from "url";
 
 // src/model/registry.ts
@@ -5820,6 +6262,12 @@ var registryEntrySchema = z7.object({
   type: z7.enum(["package", "skill", "plugin", "mcp", "adapter"]).default("package"),
   description: z7.string().default(""),
   tags: z7.array(z7.string().min(1)).default([]),
+  select: z7.array(z7.string().min(1)).optional(),
+  skills: z7.array(z7.string().min(1)).optional(),
+  homepageUrl: z7.string().min(1).optional(),
+  homepageLinkLabel: z7.string().min(1).optional(),
+  sourceUrl: z7.string().min(1).optional(),
+  sourceLinkLabel: z7.string().min(1).optional(),
   openpack: z7.object({
     schemaVersion: z7.number().int().positive().optional(),
     specVersion: z7.string().min(1).optional()
@@ -5884,7 +6332,7 @@ var RegistryClient = class {
     );
   }
   async clearCache() {
-    await rm7(this.cachePath, { force: true });
+    await rm8(this.cachePath, { force: true });
   }
   async getSources() {
     if (this.options.sources?.length) return this.options.sources;
@@ -5907,7 +6355,7 @@ var RegistryClient = class {
   }
   async readCache() {
     if (!await pathExists(this.cachePath)) return void 0;
-    return registryCacheSchema.parse(JSON.parse(await readFile19(this.cachePath, "utf8")));
+    return registryCacheSchema.parse(JSON.parse(await readFile20(this.cachePath, "utf8")));
   }
   isExpired(cache, ttlMs) {
     return this.now().getTime() - new Date(cache.fetchedAt).getTime() > ttlMs;
@@ -5924,12 +6372,12 @@ var RegistryClient = class {
     }
     const filePath = source.startsWith("file:") ? fileURLToPath(source) : source;
     if (await pathExists(filePath)) {
-      const fullPath = resolve12(filePath);
+      const fullPath = resolve14(filePath);
       const stats = await stat9(fullPath);
-      return readFile19(stats.isDirectory() ? join27(fullPath, "index.json") : fullPath, "utf8");
+      return readFile20(stats.isDirectory() ? join29(fullPath, "index.json") : fullPath, "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");
+    const resolved = await this.git.fetch(await this.git.resolve(source, { cacheRoot: join29(dirname21(this.cachePath), "registry-repos") }));
+    return readFile20(join29(resolved.resolvedPath, "index.json"), "utf8");
   }
   warnCompatibility(entries) {
     for (const entry of entries) {
@@ -5943,17 +6391,20 @@ var RegistryClient = class {
   }
 };
 async function resolvePackageSource(source, workspaceRoot, options = {}) {
-  const { isExplicitSource } = await import("./identify-TXIDGMNL.js");
+  const { isExplicitSource } = await import("./identify-T4RE5RBD.js");
   if (await isExplicitSource(source)) return { source };
   const entry = await new RegistryClient({ workspaceRoot, offline: options.offline, warn: options.warn }).resolve(source);
   if (!entry) {
     if (options.offline) {
       throw new Error(`Offline cannot refresh registry indexes (entry not found in cache: ${source}). Run without --offline first.`);
     }
-    throw new Error(`Registry entry not found: ${source}. Use an explicit path/git/skillkit/vercel source to bypass the registry.`);
+    throw new Error(`Registry entry not found: ${source}. Use an explicit path/git/skillkit/vercel/mcp-registry/clawhub source to bypass the registry.`);
   }
   return { source: entry.source, registryEntry: entry };
 }
+function selectorsFromRegistryEntry(entry) {
+  return normalizeArtifactSelectors(entry?.select, entry?.skills);
+}
 function mergeIndexes(indexes) {
   const merged = /* @__PURE__ */ new Map();
   for (const index of indexes) {
@@ -5964,7 +6415,7 @@ function mergeIndexes(indexes) {
   return [...merged.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 function defaultRegistryCachePath() {
-  return join27(homedir5(), ".agentwheel", "registry-cache.json");
+  return join29(homedir5(), ".agentwheel", "registry-cache.json");
 }
 function sameSources(a, b) {
   return a.length === b.length && a.every((source, index) => source === b[index]);
@@ -6021,7 +6472,23 @@ async function normalizeDependencySource(source, options) {
       driver: "vercel-skills"
     };
   }
-  throw new Error(`Unsupported dependency source: ${source}. Use registry:<name>, ./, ../, local:, github:, git:, skillkit:, or vercel:.`);
+  if (trimmed.startsWith("mcp-registry:")) {
+    const spec = normalizeLiteralProviderSpec(trimmed, "mcp-registry:");
+    return {
+      source: spec,
+      normalizedSource: spec,
+      driver: "mcp-registry"
+    };
+  }
+  if (trimmed.startsWith("clawhub:")) {
+    const spec = normalizeLiteralProviderSpec(trimmed, "clawhub:");
+    return {
+      source: spec,
+      normalizedSource: spec,
+      driver: "clawhub"
+    };
+  }
+  throw new Error(`Unsupported dependency source: ${source}. Use registry:<name>, ./, ../, local:, github:, git:, skillkit:, vercel:, mcp-registry:, or clawhub:.`);
 }
 function isBareRegistryName(source) {
   return !source.includes(":") && !isLocalSource(source);
@@ -6034,16 +6501,16 @@ function localSourcePath(source) {
 }
 function resolveLocalPath(path, declaringPackageRoot) {
   if (path === "~") return homedir6();
-  if (path.startsWith("~/")) return resolve13(homedir6(), path.slice(2));
-  if (path.startsWith("/")) return resolve13(path);
-  return resolve13(declaringPackageRoot, path);
+  if (path.startsWith("~/")) return resolve15(homedir6(), path.slice(2));
+  if (path.startsWith("/")) return resolve15(path);
+  return resolve15(declaringPackageRoot, path);
 }
 async function normalizeRegistrySource(name, options) {
   const client = options.registryClient ?? new RegistryClient({ workspaceRoot: options.workspaceRoot });
   const entry = await client.resolve(name);
   if (!entry) {
     throw new Error(
-      `Registry entry not found: ${name}. Bare dependency names are registry-only inside package manifests; use ./, ../, local:, github:, git:, skillkit:, or vercel: for explicit sources.`
+      `Registry entry not found: ${name}. Bare dependency names are registry-only inside package manifests; use ./, ../, local:, github:, git:, skillkit:, vercel:, mcp-registry:, or clawhub: for explicit sources.`
     );
   }
   const resolved = await normalizeDependencySource(entry.source, {
@@ -6102,6 +6569,11 @@ function normalizeProviderSpec(spec, declaringPackageRoot) {
   }
   return spec.trim();
 }
+function normalizeLiteralProviderSpec(source, prefix) {
+  const spec = source.slice(prefix.length).trim();
+  if (!spec) throw new Error(`Provider dependency source must include a spec: ${prefix}<name>`);
+  return `${prefix}${spec}`;
+}
 
 // src/resolve/semver.ts
 var semverPattern = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
@@ -6193,7 +6665,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 mkdtemp4(join28(tmpdir5(), "agentwheel-graph-"));
+  const graphRoot = await mkdtemp4(join30(tmpdir5(), "agentwheel-graph-"));
   const fetchCache = /* @__PURE__ */ new Map();
   const nodesByKey = /* @__PURE__ */ new Map();
   const rootResults = [];
@@ -6213,7 +6685,9 @@ async function resolveDependencyGraph(roots, options) {
       useLock: root.useLock ?? options.lockedResolution,
       depth: 0,
       optional: false,
-      chain: [`workspace:${rootId}`]
+      chain: [`workspace:${rootId}`],
+      includeSuggestions: root.includeSuggestions ?? options.includeSuggestions,
+      suggestionAliases: sortedUnique3([...root.suggestionAliases ?? [], ...options.suggestionAliases ?? []])
     };
   });
   let iterations = 0;
@@ -6341,13 +6815,18 @@ Run without ${lockLabel === "Offline" ? "--offline" : "--frozen-lock"} first.`
         selectionReasons: /* @__PURE__ */ new Map(),
         processedNeeds: /* @__PURE__ */ new Set(),
         processedPackageAliases: /* @__PURE__ */ new Set(),
+        processedSuggestions: /* @__PURE__ */ new Set(),
         depth: requirement.depth,
-        fullPackageSelected: false
+        fullPackageSelected: false,
+        includeSuggestions: false,
+        suggestionAliases: /* @__PURE__ */ new Set()
       };
       nodesByKey.set(nodeKey, state);
     }
     state.depth = Math.min(state.depth, requirement.depth);
     state.fullPackageSelected = state.fullPackageSelected || requirement.select === void 0;
+    state.includeSuggestions = state.includeSuggestions || requirement.includeSuggestions === true;
+    for (const alias of requirement.suggestionAliases ?? []) state.suggestionAliases.add(alias);
     state.requiredBy.add(requirement.requiredBy);
     for (const selector of selected) addSelectedSelector(state, selector, requirement.selectionReason);
     refreshNode(state);
@@ -6394,10 +6873,13 @@ Dependency chain: ${requirement.chain.join(" -> ")}`);
 async function collectDependencyNeeds(state, fetched, options, chain) {
   if (fetched.manifest?.schemaVersion !== 2) return [];
   const dependencies = fetched.manifest.requires ?? {};
+  const suggestions = fetched.manifest.suggests ?? {};
   const dependencyEntries = Object.entries(dependencies).sort(([a], [b]) => a.localeCompare(b));
+  const suggestionEntries = Object.entries(suggestions).sort(([a], [b]) => a.localeCompare(b));
+  const suggestionOptions = suggestionOptionsForState(state, options);
   const requirements = [];
   if (options.noDeps) {
-    warnNoDepsOnce(state, dependencyEntries.map(([alias]) => alias), options.warn);
+    warnNoDepsOnce(state, [...dependencyEntries.map(([alias]) => alias), ...suggestionEntries.map(([alias]) => alias)], options.warn);
   } else {
     for (const [alias, dependency] of dependencyEntries) {
       if (state.processedPackageAliases.has(alias)) continue;
@@ -6406,6 +6888,14 @@ async function collectDependencyNeeds(state, fetched, options, chain) {
       if (!dependencyTargetsRuntime(dependency.runtimes, options.runtime, state.node.id, alias, options.warn)) continue;
       requirements.push(dependencyRequirement(state, fetched, alias, dependency, dependency.select, chain, options.lockedResolution === true));
     }
+    for (const [alias, suggestion] of suggestionEntries) {
+      if (state.processedSuggestions.has(alias)) continue;
+      if (!shouldIncludeSuggestionAlias(alias, suggestionOptions, state.fullPackageSelected)) continue;
+      if (!suggestion.select?.length && !(state.fullPackageSelected && suggestion.select === void 0) && !explicitSuggestionAlias(alias, suggestionOptions)) continue;
+      state.processedSuggestions.add(alias);
+      if (!dependencyTargetsRuntime(suggestion.runtimes, options.runtime, state.node.id, alias, options.warn)) continue;
+      requirements.push(suggestionRequirement(state, fetched, alias, suggestion, suggestion.select, chain, suggestionOptions));
+    }
   }
   const artifactsBySelector = new Map(fetched.artifacts.map((artifact) => [artifactSelectorKey(artifact), artifact]));
   const artifactsByRelativePath = new Map(fetched.artifacts.map((artifact) => [artifact.relativePath.replaceAll("\\", "/"), artifact]));
@@ -6449,6 +6939,28 @@ async function collectDependencyNeeds(state, fetched, options, chain) {
         }
         addSelectedSelector(state, parsed.selector, `required by ${parentSelector}`);
       }
+      for (const suggestion of artifact.suggests ?? []) {
+        const parsed = parseArtifactSuggestion(suggestion);
+        if (!shouldIncludeSuggestionAlias(parsed.alias, suggestionOptions, true)) continue;
+        if (!requirementTargetsRuntime(parsed.runtimes, options.runtime, `${state.node.id}:${parentSelector} -> ${parsed.raw}`, options.warn)) continue;
+        if (options.noDeps) {
+          warnNoDepsOnce(state, [parsed.alias], options.warn);
+          continue;
+        }
+        const packageSuggestion = suggestionForAlias(suggestions, state.node.id, parsed.alias);
+        if (!dependencyTargetsRuntime(packageSuggestion.runtimes, options.runtime, state.node.id, parsed.alias, options.warn)) continue;
+        requirements.push(suggestionRequirement(
+          state,
+          fetched,
+          parsed.alias,
+          packageSuggestion,
+          combinedSelectors(packageSuggestion.select, parsed.select),
+          chain,
+          suggestionOptions,
+          parsed.optional || shouldTreatSuggestionAsOptional(parsed.alias, packageSuggestion, suggestionOptions),
+          `suggested by ${parentSelector}`
+        ));
+      }
       for (const include of await collectIncludeNeeds(artifact, artifactsByRelativePath)) {
         if (!include.alias) continue;
         if (options.noDeps) {
@@ -6490,9 +7002,24 @@ function dependencyRequirement(state, fetched, alias, dependency, select, chain,
     chain: [...chain, `${state.node.id}:${alias}`],
     version: dependency.version,
     integrity: dependency.integrity,
-    selectionReason
+    selectionReason,
+    includeSuggestions: state.includeSuggestions,
+    suggestionAliases: sortedUnique3([...state.suggestionAliases])
   };
 }
+function suggestionRequirement(state, fetched, alias, suggestion, select, chain, options, optional = shouldTreatSuggestionAsOptional(alias, suggestion, options), selectionReason) {
+  return dependencyRequirement(
+    state,
+    fetched,
+    alias,
+    suggestion,
+    select,
+    chain,
+    options.lockedResolution === true,
+    optional,
+    selectionReason
+  );
+}
 function dependencyForAlias(dependencies, nodeId, alias) {
   const dependency = dependencies[alias];
   if (!dependency) {
@@ -6500,6 +7027,13 @@ function dependencyForAlias(dependencies, nodeId, alias) {
   }
   return dependency;
 }
+function suggestionForAlias(suggestions, nodeId, alias) {
+  const suggestion = suggestions[alias];
+  if (!suggestion) {
+    throw new Error(`Suggestion alias not found in ${nodeId}: ${alias}`);
+  }
+  return suggestion;
+}
 function warnNoDepsOnce(state, aliases, warn) {
   const unique = sortedUnique3(aliases.filter(Boolean));
   if (unique.length === 0 || state.processedPackageAliases.has("__noDepsWarned")) return;
@@ -6517,6 +7051,45 @@ function parseArtifactRequirement(requirement) {
     runtimes: typeof requirement === "string" ? void 0 : requirement.runtimes
   };
 }
+function parseArtifactSuggestion(suggestion) {
+  if (typeof suggestion === "string") {
+    return {
+      raw: suggestion,
+      alias: suggestion,
+      optional: false
+    };
+  }
+  return {
+    raw: suggestion.alias,
+    alias: suggestion.alias,
+    select: suggestion.select,
+    optional: suggestion.optional === true,
+    runtimes: suggestion.runtimes
+  };
+}
+function shouldIncludeSuggestionAlias(alias, options, includeWhenAllSuggestions) {
+  const aliases = new Set(options.suggestionAliases ?? []);
+  if (aliases.has(alias)) return true;
+  return options.includeSuggestions === true && includeWhenAllSuggestions;
+}
+function suggestionOptionsForState(state, options) {
+  return {
+    ...options,
+    includeSuggestions: state.includeSuggestions || options.includeSuggestions === true,
+    suggestionAliases: sortedUnique3([...options.suggestionAliases ?? [], ...state.suggestionAliases])
+  };
+}
+function explicitSuggestionAlias(alias, options) {
+  return (options.suggestionAliases ?? []).includes(alias);
+}
+function shouldTreatSuggestionAsOptional(alias, suggestion, options) {
+  if (suggestion.optional === true) return true;
+  return options.includeSuggestions === true && !(options.suggestionAliases ?? []).includes(alias);
+}
+function combinedSelectors(base, extra) {
+  const values = [...base ?? [], ...extra ?? []];
+  return values.length > 0 ? sortedUnique3(values) : void 0;
+}
 function parseDependencySelector(value) {
   const cleaned = value.trim();
   const slash = cleaned.indexOf("/");
@@ -6555,7 +7128,7 @@ async function collectIncludeNeeds(artifact, artifactsByRelativePath) {
     const file = stack.shift();
     if (scanned.has(file)) continue;
     scanned.add(file);
-    const content = await readFile20(file, "utf8");
+    const content = await readFile21(file, "utf8");
     for (const include of extractOpenPackIncludeSelectors(content)) {
       await collectIncludeSelector(include.raw, include.optional, artifactsByRelativePath, scanned, stack, needs);
     }
@@ -6598,7 +7171,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 = join28(dir, entry.name);
+      const full = join30(dir, entry.name);
       if (entry.isDirectory()) {
         await walk2(full);
       } else if (entry.isFile() && extname4(entry.name).toLowerCase() === ".md") {
@@ -6633,7 +7206,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 ?? join28(options.workspaceRoot, ".agentwheel", "cache"),
+      cacheRoot: options.cacheRoot ?? join30(options.workspaceRoot, ".agentwheel", "cache"),
       mode,
       ref: refOverride ?? normalized.requestedRef,
       frozenLock: hardLockedCheckout
@@ -6643,7 +7216,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 ?? basename16(exported.resolvedPath);
+    const name = manifest?.name ?? exported.packageName ?? basename18(exported.resolvedPath);
     const version = manifest?.version ?? exported.packageVersion ?? "0.0.0";
     const sourceHash = exported.sourceHash ?? await hashPath(exported.resolvedPath);
     return {
@@ -6727,7 +7300,7 @@ function shouldCheckLockedRootSource(requirement) {
 }
 function isExplicitNonRegistrySource(source) {
   const trimmed = source.trim();
-  return trimmed === "~" || trimmed.startsWith("~/") || trimmed.startsWith("./") || trimmed.startsWith("../") || trimmed.startsWith("/") || trimmed.startsWith("local:") || trimmed.startsWith("github:") || trimmed.startsWith("git:") || trimmed.startsWith("skillkit:") || trimmed.startsWith("vercel:");
+  return trimmed === "~" || trimmed.startsWith("~/") || trimmed.startsWith("./") || trimmed.startsWith("../") || trimmed.startsWith("/") || trimmed.startsWith("local:") || trimmed.startsWith("github:") || trimmed.startsWith("git:") || trimmed.startsWith("skillkit:") || trimmed.startsWith("vercel:") || trimmed.startsWith("mcp-registry:") || trimmed.startsWith("clawhub:");
 }
 function lockedRootSourceDrifted(declared, locked) {
   return declared.normalizedSource !== locked.normalizedSource || declared.requestedRef !== locked.requestedRef;
@@ -6750,8 +7323,8 @@ function verifyIntegrity(integrity, sourceHash, label) {
 async function withCachePathLock(path, fn) {
   const previous = cacheLocks.get(path) ?? Promise.resolve();
   let release = () => void 0;
-  const current = previous.then(() => new Promise((resolve19) => {
-    release = resolve19;
+  const current = previous.then(() => new Promise((resolve21) => {
+    release = resolve21;
   }));
   cacheLocks.set(path, current);
   await previous;
@@ -6840,8 +7413,8 @@ async function mapLimit(items, limit, fn) {
 
 // src/lifecycle/customization.ts
 async function remember(workspaceRoot, runtime, text) {
-  const overlayPath = join29(workspaceRoot, ".agentwheel", "overlays", runtime, "instructions.local.md");
-  await mkdir13(dirname19(overlayPath), { recursive: true });
+  const overlayPath = join31(workspaceRoot, ".agentwheel", "overlays", runtime, "instructions.local.md");
+  await mkdir16(dirname22(overlayPath), { recursive: true });
   await appendFile(overlayPath, `${text.trim()}
 `, "utf8");
   return { overlayPath };
@@ -6864,9 +7437,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 = join29(workspaceRoot, ".agentwheel", "ejected", ...ejectedIdentity.split("/"), parsed.type, parsed.name);
-    await mkdir13(dirname19(ejectedPath), { recursive: true });
-    await rm8(ejectedPath, { recursive: true, force: true });
+    const ejectedPath = join31(workspaceRoot, ".agentwheel", "ejected", ...ejectedIdentity.split("/"), parsed.type, parsed.name);
+    await mkdir16(dirname22(ejectedPath), { recursive: true });
+    await rm9(ejectedPath, { recursive: true, force: true });
     await cp6(artifact.stagedPath ?? artifact.sourcePath, ejectedPath, { recursive: artifact.kind === "dir", dereference: true });
     return {
       ...parsed,
@@ -6877,7 +7450,7 @@ async function ejectArtifact(workspaceRoot, item) {
       ejectedPath
     };
   } finally {
-    await Promise.all(candidates.map((candidate) => rm8(candidate.bundle.root, { recursive: true, force: true })));
+    await Promise.all(candidates.map((candidate) => rm9(candidate.bundle.root, { recursive: true, force: true })));
   }
 }
 function parseEjectItem(item) {
@@ -6907,7 +7480,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: join29(workspaceRoot, ".agentwheel", "cache"),
+    cacheRoot: join31(workspaceRoot, ".agentwheel", "cache"),
     mode: pkg.mode,
     ref: normalized.requestedRef ?? pkg.requestedRef
   });
@@ -6954,12 +7527,12 @@ function ejectCommands(candidates, parsed) {
 }
 
 // src/lifecycle/profile.ts
-import { rm as rm9 } from "fs/promises";
+import { rm as rm10 } from "fs/promises";
 
 // src/lifecycle/source-plan.ts
 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";
+import { mkdir as mkdir18 } from "fs/promises";
+import { dirname as dirname24, join as join34, resolve as resolve16 } from "path";
 
 // src/resolve/graph-diff.ts
 function diffGraphLocks(previous, next) {
@@ -7081,11 +7654,11 @@ function short(hash) {
 
 // src/resolve/render.ts
 import { createHash as createHash7 } from "crypto";
-import { readFile as readFile21, mkdtemp as mkdtemp5 } from "fs/promises";
+import { readFile as readFile22, mkdtemp as mkdtemp5 } from "fs/promises";
 import { tmpdir as tmpdir6 } from "os";
-import { join as join30 } from "path";
+import { join as join32 } from "path";
 async function renderGraphForTarget(graph, targetContext = {}) {
-  const root = await mkdtemp5(join30(tmpdir6(), "agentwheel-render-"));
+  const root = await mkdtemp5(join32(tmpdir6(), "agentwheel-render-"));
   const artifacts = [];
   const stagedNodes = /* @__PURE__ */ new Map();
   const includeEdges = /* @__PURE__ */ new Map();
@@ -7205,7 +7778,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 readFile21(artifact.stagedPath ?? artifact.sourcePath, "utf8"));
+    out.set(artifact.relativePath.replaceAll("\\", "/"), await readFile22(artifact.stagedPath ?? artifact.sourcePath, "utf8"));
   }
   return out;
 }
@@ -7468,9 +8041,9 @@ function lockArtifactFor(artifact) {
 }
 
 // src/lifecycle/trust.ts
-import { mkdir as mkdir14, readFile as readFile22 } from "fs/promises";
+import { mkdir as mkdir17, readFile as readFile23 } from "fs/promises";
 import { homedir as homedir7 } from "os";
-import { dirname as dirname20, join as join31 } from "path";
+import { dirname as dirname23, join as join33 } from "path";
 import { z as z8 } from "zod";
 var trustStoreSchema = z8.object({
   version: z8.literal(1),
@@ -7544,14 +8117,14 @@ function sortedUnique4(values) {
 }
 async function readTrustStore(path) {
   if (!await pathExists(path)) return { version: 1, acceptedSources: [] };
-  return trustStoreSchema.parse(JSON.parse(await readFile22(path, "utf8")));
+  return trustStoreSchema.parse(JSON.parse(await readFile23(path, "utf8")));
 }
 async function writeTrustStore(path, store) {
-  await mkdir14(dirname20(path), { recursive: true });
+  await mkdir17(dirname23(path), { recursive: true });
   await writeJsonAtomic(path, trustStoreSchema.parse(store));
 }
 function defaultTrustStorePath() {
-  return process.env.AGENTWHEEL_TRUST_STORE ?? join31(homedir7(), ".agentwheel", "trust.json");
+  return process.env.AGENTWHEEL_TRUST_STORE ?? join33(homedir7(), ".agentwheel", "trust.json");
 }
 
 // src/lifecycle/source-plan.ts
@@ -7589,9 +8162,11 @@ async function createGraphSourcePlan(options) {
   const registryClient = new RegistryClient({ workspaceRoot, offline: lockMode, offlineLabel: lockLabel, warn });
   const graph = await resolveDependencyGraph(options.roots, {
     workspaceRoot,
-    cacheRoot: join32(workspaceRoot, ".agentwheel", "cache"),
+    cacheRoot: join34(workspaceRoot, ".agentwheel", "cache"),
     registryClient,
     noDeps: options.noDeps,
+    includeSuggestions: options.includeSuggestions,
+    suggestionAliases: options.suggestionAliases,
     lockedResolution: options.lockedResolution,
     frozenLock: lockMode,
     offline: options.offline,
@@ -7687,7 +8262,7 @@ async function readExistingGraphLock(path) {
   return readGraphLock(path);
 }
 function pathForGraphLock(workspaceRoot, targetKey, adapter, targetFingerprint) {
-  return join32(workspaceRoot, ".agentwheel", "locks", sanitizePathSegment(targetKey), sanitizePathSegment(adapter), `${targetFingerprint}.graph-lock.json`);
+  return join34(workspaceRoot, ".agentwheel", "locks", sanitizePathSegment(targetKey), sanitizePathSegment(adapter), `${targetFingerprint}.graph-lock.json`);
 }
 function sanitizePathSegment(value) {
   return value.replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "") || "default";
@@ -7696,7 +8271,7 @@ function digestGraphLock(lock) {
   return createHash8("sha256").update(canonicalGraphLockJson(lock)).digest("hex");
 }
 function workspaceOwnerId(workspaceRoot) {
-  return `workspace-root:${resolve14(workspaceRoot)}`;
+  return `workspace-root:${resolve16(workspaceRoot)}`;
 }
 function assertFrozenGraph(previousLock, graph, frozen, label) {
   if (!frozen) return;
@@ -7751,7 +8326,7 @@ ${sources.map((source) => `- ${source}`).join("\n")}`);
 }
 
 // src/runtime/target.ts
-import { basename as basename17, dirname as dirname22, join as join33, resolve as resolve15 } from "path";
+import { basename as basename19, dirname as dirname25, join as join35, resolve as resolve17 } from "path";
 var runtimeMarkers = [
   { adapter: "openclaw", dirs: [".openclaw", ".clawdbot", ".moltbot"] },
   { adapter: "claude", dirs: [".claude"] },
@@ -7760,9 +8335,9 @@ var runtimeMarkers = [
   { adapter: "copilot", dirs: [".github"] }
 ];
 async function resolveRuntimeTarget(request = {}) {
-  const cwd = resolve15(request.cwd ?? process.cwd());
+  const cwd = resolve17(request.cwd ?? process.cwd());
   if (request.targetRoot) {
-    const targetRoot = resolve15(request.targetRoot);
+    const targetRoot = resolve17(request.targetRoot);
     return {
       adapter: request.adapter ?? "openclaw",
       installationType: request.installationType,
@@ -7793,7 +8368,7 @@ async function resolveRuntimeTarget(request = {}) {
 async function resolveAllRuntimeTargets(request = {}) {
   if (request.targetRoot) return [await resolveRuntimeTarget(request)];
   if (request.agent) return [await resolveRuntimeTarget(request)];
-  const cwd = resolve15(request.cwd ?? process.cwd());
+  const cwd = resolve17(request.cwd ?? process.cwd());
   const workspaceRoot = await findWorkspaceRoot(cwd);
   const config = await readMergedWorkspaceConfig(workspaceRoot, { globalRoot: request.globalRoot });
   const targets = Object.entries(config.agents).map(([name]) => targetFromAgent(name, config, workspaceRoot, request.installationType));
@@ -7803,8 +8378,8 @@ async function resolveAllRuntimeTargets(request = {}) {
   return targets;
 }
 async function resolveProfileRuntimeTargets(request) {
-  const cwd = resolve15(request.cwd ?? process.cwd());
-  const workspaceRoot = request.targetRoot ? resolve15(request.targetRoot) : await findWorkspaceRoot(cwd);
+  const cwd = resolve17(request.cwd ?? process.cwd());
+  const workspaceRoot = request.targetRoot ? resolve17(request.targetRoot) : await findWorkspaceRoot(cwd);
   const config = await readMergedWorkspaceConfig(workspaceRoot, { globalRoot: request.globalRoot });
   const profile = config.profiles[request.profile];
   if (!profile) {
@@ -7857,14 +8432,14 @@ async function detectRuntimeTarget(cwd = process.cwd(), adapterFilter) {
   return unique[0];
 }
 async function detectRuntimeTargets(cwd = process.cwd(), adapterFilter) {
-  const root = resolve15(cwd);
+  const root = resolve17(cwd);
   const matches = [];
   for (const marker of runtimeMarkers) {
     if (adapterFilter && marker.adapter !== adapterFilter) continue;
     for (const dir of marker.dirs) {
-      if (basename17(root) === dir) {
-        matches.push({ adapter: marker.adapter, targetRoot: dirname22(root) });
-      } else if (await pathExists(join33(root, dir))) {
+      if (basename19(root) === dir) {
+        matches.push({ adapter: marker.adapter, targetRoot: dirname25(root) });
+      } else if (await pathExists(join35(root, dir))) {
         matches.push({ adapter: marker.adapter, targetRoot: root });
       }
     }
@@ -7901,9 +8476,9 @@ function dedupeTargets(matches) {
   return [...byKey.values()];
 }
 function runtimeScanRoot(request) {
-  const root = resolve15(request.targetRoot ?? request.cwd ?? process.cwd());
+  const root = resolve17(request.targetRoot ?? request.cwd ?? process.cwd());
   if (request.targetRoot) return root;
-  return runtimeMarkers.some((marker) => marker.dirs.includes(basename17(root))) ? dirname22(root) : root;
+  return runtimeMarkers.some((marker) => marker.dirs.includes(basename19(root))) ? dirname25(root) : root;
 }
 
 // src/lifecycle/profile.ts
@@ -7940,7 +8515,9 @@ async function syncProfile(options) {
         ref: pkg.requestedRef,
         select: selected ?? normalizeArtifactSelectors(pkg.select, pkg.skills),
         aliases: pkg.aliases,
-        overrides: pkg.overrides
+        overrides: pkg.overrides,
+        includeSuggestions: options.includeSuggestions === true || pkg.withSuggestions === true,
+        suggestionAliases: combinedSuggestionAliases(pkg.suggestions, options.suggestionAliases)
       })),
       targetRoot: target.targetRoot,
       workspaceRoot: options.workspaceRoot,
@@ -7960,6 +8537,8 @@ async function syncProfile(options) {
       },
       installationType,
       noDeps: options.noDeps,
+      includeSuggestions: options.includeSuggestions,
+      suggestionAliases: options.suggestionAliases,
       lockedResolution: options.lockedResolution,
       frozenLock: options.frozenLock,
       offline: options.offline,
@@ -7989,7 +8568,7 @@ async function syncProfile(options) {
         });
       }
     } finally {
-      await rm9(graphPlan.bundle.root, { recursive: true, force: true });
+      await rm10(graphPlan.bundle.root, { recursive: true, force: true });
     }
   }
   return results;
@@ -8000,6 +8579,7 @@ async function packageFromSource(source, options) {
     warn: options.warn
   });
   const driver = options.driver ?? inferSourceDriverName(resolved.source);
+  const selectedArtifacts = normalizeArtifactSelectors(options.select, options.skills) ?? selectorsFromRegistryEntry(resolved.registryEntry);
   return {
     name: resolved.registryEntry?.name ?? source,
     source: resolved.source,
@@ -8007,15 +8587,184 @@ async function packageFromSource(source, options) {
     adapter: "openclaw",
     installationType: options.installationType,
     mode: options.mode ?? "pinned",
-    select: options.select,
-    skills: options.skills
+    select: selectedArtifacts,
+    withSuggestions: options.includeSuggestions === true ? true : void 0,
+    suggestions: options.suggestionAliases
   };
 }
+function combinedSuggestionAliases(packageAliases, optionAliases) {
+  const aliases = [...packageAliases ?? [], ...optionAliases ?? []].map((item) => item.trim()).filter(Boolean);
+  return aliases.length > 0 ? [...new Set(aliases)].sort((a, b) => a.localeCompare(b)) : void 0;
+}
+
+// src/registry/publish.ts
+var DEFAULT_REGISTRY_SUBMISSION_URL = "https://github.com/NestDevLab/agentwheel-registry/issues/new";
+var registryEntryTypes = ["package", "skill", "plugin", "mcp", "adapter"];
+var explicitSourcePrefixes = ["github:", "git:", "skillkit:", "vercel:", "mcp-registry:", "clawhub:"];
+function createRegistryPublishDraft(sourceInput, options = {}) {
+  const source = normalizeCatalogueSource(sourceInput);
+  const entry = {
+    name: normalizeRegistryName(options.name ?? inferRegistryName(source)),
+    source,
+    type: options.type ? parseRegistryEntryType(options.type) : inferRegistryEntryType(source),
+    description: options.description?.trim() ?? "",
+    tags: normalizeTags(options.tags ?? [])
+  };
+  const selectors = normalizeArtifactSelectors(options.select, options.skills);
+  if (selectors?.length) entry.select = selectors;
+  if (options.skills?.length) entry.skills = normalizeSkillNames(options.skills);
+  const installCommand = installCommandForEntry(entry);
+  return {
+    entry,
+    installCommand,
+    issueUrl: registrySubmissionUrl(entry, installCommand, options.submissionUrl ?? DEFAULT_REGISTRY_SUBMISSION_URL)
+  };
+}
+function normalizeCatalogueSource(sourceInput) {
+  const source = sourceInput.trim();
+  if (!source) throw new Error("Catalogue source is required.");
+  const unprefixedGitUrl = source.startsWith("git+http://") || source.startsWith("git+https://") ? source.slice("git+".length) : source;
+  const githubSource = normalizeGitHubUrl(unprefixedGitUrl);
+  if (githubSource) return githubSource;
+  if (isHttpUrl(unprefixedGitUrl)) return `git:${unprefixedGitUrl}`;
+  if (explicitSourcePrefixes.some((prefix) => source.startsWith(prefix))) return source;
+  if (source.startsWith(".") || source.startsWith("/") || source.startsWith("local:")) {
+    throw new Error("Catalogue submissions must use a public source, not a local path.");
+  }
+  const shorthand = normalizeOwnerRepoShorthand(source);
+  if (shorthand) return shorthand;
+  throw new Error(`Unsupported catalogue source: ${sourceInput}. Use a GitHub URL, github:owner/repo, git:https://..., skillkit:, vercel:, mcp-registry:, or clawhub:.`);
+}
+function inferRegistryEntryType(source) {
+  if (source.startsWith("mcp-registry:")) return "mcp";
+  if (source.startsWith("clawhub:")) return "plugin";
+  if (source.startsWith("skillkit:") || source.startsWith("vercel:")) return "skill";
+  return "package";
+}
+function parseRegistryEntryType(value) {
+  const normalized = value.trim().toLowerCase();
+  if (registryEntryTypes.includes(normalized)) return normalized;
+  throw new Error(`Unsupported registry entry type: ${value}. Use ${registryEntryTypes.join(", ")}.`);
+}
+function installCommandForEntry(entry) {
+  const base = ["agentwheel", "install", entry.source, ...selectorArgsForEntry(entry)];
+  if (entry.type === "mcp") return [...base, "--adapter", "claude", "--local", "--dry-run"].map(shellQuoteArg).join(" ");
+  if (entry.source.startsWith("clawhub:") || entry.type === "plugin") {
+    return [...base, "--adapter", "openclaw", "--local", "--dry-run"].map(shellQuoteArg).join(" ");
+  }
+  return [...base, "--adapter", "codex", "--local", "--dry-run"].map(shellQuoteArg).join(" ");
+}
+function registrySubmissionUrl(entry, installCommand, baseUrl) {
+  const url = new URL(baseUrl);
+  url.searchParams.set("title", `Catalogue submission: ${entry.name}`);
+  url.searchParams.set("body", registrySubmissionBody(entry, installCommand));
+  return url.toString();
+}
+function registrySubmissionBody(entry, installCommand) {
+  const descriptionNote = entry.description ? [] : ["", "Note: add a concise description before submitting."];
+  return [
+    "## Agentwheel catalogue submission",
+    "",
+    "Please review this generated registry entry:",
+    "",
+    "```json",
+    JSON.stringify(entry, null, 2),
+    "```",
+    "",
+    "## Verification",
+    "",
+    `Source: \`${entry.source}\``,
+    `Suggested check: \`${installCommand}\``,
+    "",
+    "## Checklist",
+    "",
+    "- [ ] The source is public and installable.",
+    "- [ ] The description is concise and factual.",
+    "- [ ] Tags help discovery.",
+    ...descriptionNote
+  ].join("\n");
+}
+function normalizeGitHubUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return void 0;
+  }
+  if (url.hostname.toLowerCase() !== "github.com") return void 0;
+  const segments = url.pathname.split("/").filter(Boolean).map((segment) => decodeURIComponent(segment));
+  const [owner, repoSegment] = segments;
+  if (!owner || !repoSegment) return void 0;
+  const repo = repoSegment.replace(/\.git$/i, "");
+  let ref = url.hash ? decodeURIComponent(url.hash.slice(1)) : "";
+  if (segments[2] === "tree" && segments.length > 3) {
+    ref = segments.slice(3).join("/");
+  }
+  return `github:${owner}/${repo}${ref ? `#${ref}` : ""}`;
+}
+function normalizeOwnerRepoShorthand(value) {
+  const match = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)(#[^\s]+)?$/.exec(value);
+  if (!match) return void 0;
+  return `github:${match[1]}/${match[2]}${match[3] ?? ""}`;
+}
+function inferRegistryName(source) {
+  const withoutRef = source.split("#", 1)[0];
+  if (withoutRef.startsWith("github:")) return lastPathSegment(withoutRef.slice("github:".length));
+  if (withoutRef.startsWith("git:")) return nameFromGitUrl(withoutRef.slice("git:".length));
+  if (withoutRef.startsWith("skillkit:")) return lastPathSegment(withoutRef.slice("skillkit:".length));
+  if (withoutRef.startsWith("vercel:")) return lastPathSegment(withoutRef.slice("vercel:".length));
+  if (withoutRef.startsWith("mcp-registry:")) return lastPathSegment(withoutRef.slice("mcp-registry:".length));
+  if (withoutRef.startsWith("clawhub:")) return lastPathSegment(withoutRef.slice("clawhub:".length));
+  return withoutRef;
+}
+function nameFromGitUrl(value) {
+  try {
+    return lastPathSegment(new URL(value).pathname);
+  } catch {
+    return lastPathSegment(value);
+  }
+}
+function lastPathSegment(value) {
+  const trimmed = value.replace(/\.git$/i, "").replace(/\/+$/g, "");
+  const segments = trimmed.split("/").filter(Boolean);
+  return segments.at(-1) ?? trimmed;
+}
+function normalizeRegistryName(value) {
+  const name = slugify(value);
+  if (!name) throw new Error("Registry entry name could not be inferred. Pass --name <short-name>.");
+  return name;
+}
+function normalizeTags(tags) {
+  const normalized = tags.flatMap((tag) => tag.split(",")).map((tag) => slugify(tag)).filter(Boolean);
+  return [...new Set(normalized)];
+}
+function normalizeSkillNames(skills) {
+  return [...new Set(skills.flatMap((skill) => skill.split(",")).map((skill) => skill.trim()).filter(Boolean))];
+}
+function selectorArgsForEntry(entry) {
+  if (entry.skills?.length) return entry.skills.flatMap((skill) => ["--skill", skill]);
+  return (entry.select ?? []).flatMap((selector) => ["--select", selector]);
+}
+function slugify(value) {
+  return value.trim().toLowerCase().replace(/\.git$/i, "").replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function isHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function shellQuoteArg(value) {
+  if (/^[A-Za-z0-9_./:@=-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
 
 // src/cli/update-check.ts
-import { mkdir as mkdir16, readFile as readFile23, writeFile as writeFile14 } from "fs/promises";
+import { mkdir as mkdir19, readFile as readFile24, writeFile as writeFile17 } from "fs/promises";
 import { homedir as homedir8 } from "os";
-import { dirname as dirname23, join as join34 } from "path";
+import { dirname as dirname26, join as join36 } from "path";
 var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
 var DEFAULT_TIMEOUT_MS = 300;
 var REGISTRY_URL = "https://registry.npmjs.org/agentwheel";
@@ -8023,7 +8772,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 ?? join34(homedir8(), ".agentwheel", "update-check.json");
+  const cachePath = options.cachePath ?? join36(homedir8(), ".agentwheel", "update-check.json");
   try {
     const cached = await readCache(cachePath);
     if (cached && now.getTime() - Date.parse(cached.checkedAt) < ttlMs) {
@@ -8060,7 +8809,7 @@ async function fetchLatestVersion(fetchImpl, timeoutMs) {
 }
 async function readCache(path) {
   try {
-    const parsed = JSON.parse(await readFile23(path, "utf8"));
+    const parsed = JSON.parse(await readFile24(path, "utf8"));
     if (typeof parsed.checkedAt !== "string" || typeof parsed.latest !== "string") return void 0;
     return { checkedAt: parsed.checkedAt, latest: parsed.latest };
   } catch {
@@ -8068,8 +8817,8 @@ async function readCache(path) {
   }
 }
 async function writeCache(path, cache) {
-  await mkdir16(dirname23(path), { recursive: true });
-  await writeFile14(path, `${JSON.stringify(cache, null, 2)}
+  await mkdir19(dirname26(path), { recursive: true });
+  await writeFile17(path, `${JSON.stringify(cache, null, 2)}
 `, "utf8");
 }
 function warnIfNewer(latest, current, stderr = process.stderr) {
@@ -8092,9 +8841,9 @@ function normalizeVersion(version) {
 
 // src/model/package-validate.ts
 import { stat as stat11 } from "fs/promises";
-import { resolve as resolve16 } from "path";
+import { resolve as resolve18 } from "path";
 async function validatePackage(root) {
-  const packageRoot = resolve16(root);
+  const packageRoot = resolve18(root);
   const findings = [];
   const manifestPath = await findPackageManifestPath(packageRoot);
   if (!manifestPath) {
@@ -8141,6 +8890,14 @@ function validateDeclaredSelectors(manifest, findings, manifestPath) {
         validateSelector(selector, `requires.${alias}.select`, findings, manifestPath, { localOnly: true });
       }
     }
+    for (const [alias, suggestion] of Object.entries(manifest.suggests ?? {})) {
+      if (!alias.trim()) {
+        findings.push({ level: "error", message: "Suggestion alias must be non-empty", path: manifestPath });
+      }
+      for (const selector of suggestion.select ?? []) {
+        validateSelector(selector, `suggests.${alias}.select`, findings, manifestPath, { localOnly: true });
+      }
+    }
   }
   for (const [provideIndex, provide] of manifest.provides.entries()) {
     if (!("items" in provide) || !provide.items) continue;
@@ -8149,6 +8906,15 @@ function validateDeclaredSelectors(manifest, findings, manifestPath) {
         const selector = typeof requirement === "string" ? requirement : requirement.selector;
         validateSelector(selector, `provides[${provideIndex}].items.${itemName}.requires`, findings, manifestPath, { aliases: manifest.schemaVersion === 2 ? Object.keys(manifest.requires ?? {}) : [] });
       }
+      for (const suggestion of item.suggests ?? []) {
+        const alias = typeof suggestion === "string" ? suggestion : suggestion.alias;
+        if (manifest.schemaVersion === 2 && !Object.keys(manifest.suggests ?? {}).includes(alias)) {
+          findings.push({ level: "error", message: `provides[${provideIndex}].items.${itemName}.suggests: suggestion alias not declared: ${alias}`, path: manifestPath });
+        }
+        for (const selector of typeof suggestion === "string" ? [] : suggestion.select ?? []) {
+          validateSelector(selector, `provides[${provideIndex}].items.${itemName}.suggests.${alias}.select`, findings, manifestPath, { localOnly: true });
+        }
+      }
       for (const entry of item.compose ?? []) {
         validateSelector(entry.include, `provides[${provideIndex}].items.${itemName}.compose.include`, findings, manifestPath, {
           aliases: manifest.schemaVersion === 2 ? Object.keys(manifest.requires ?? {}) : [],
@@ -8162,7 +8928,7 @@ async function validateManifestComposeInclude(packageRoot, selector, optional, f
   try {
     validateSelector(selector, "compose.include", findings, manifestPath, { fragmentsOnly: true, aliases });
     if (isCrossPackageSelector(selector)) return;
-    const full = resolve16(packageRoot, selector);
+    const full = resolve18(packageRoot, selector);
     if (full !== packageRoot && !full.startsWith(`${packageRoot}/`)) {
       findings.push({ level: "error", message: `Compose include escapes package root: ${selector}`, path: manifestPath });
       return;
@@ -8215,13 +8981,13 @@ function isCrossPackageSelector(value) {
 }
 
 // src/model/package-migrate.ts
-import { readFile as readFile24, rename as rename4, writeFile as writeFile15 } from "fs/promises";
-import { join as join36, resolve as resolve17 } from "path";
+import { readFile as readFile25, rename as rename4, writeFile as writeFile18 } from "fs/promises";
+import { join as join38, resolve as resolve19 } from "path";
 import { applyEdits, modify, parse as parse4 } from "jsonc-parser";
 async function migratePackageManifest(root) {
-  const packageRoot = resolve17(root);
+  const packageRoot = resolve19(root);
   for (const name of openPackManifestNames) {
-    const path = join36(packageRoot, name);
+    const path = join38(packageRoot, name);
     if (await pathExists(path)) {
       return { changed: false, to: path, message: `Package already uses ${name}.` };
     }
@@ -8230,18 +8996,18 @@ async function migratePackageManifest(root) {
   if (!legacyName) {
     throw new Error(`No legacy package manifest found at ${packageRoot}`);
   }
-  const from = join36(packageRoot, legacyName);
+  const from = join38(packageRoot, legacyName);
   const toName = legacyName.endsWith(".jsonc") ? "openpack.jsonc" : "openpack.json";
-  const to = join36(packageRoot, toName);
-  const content = await readFile24(from, "utf8");
+  const to = join38(packageRoot, toName);
+  const content = await readFile25(from, "utf8");
   const updated = updateSchemaVersion(content);
   await rename4(from, to);
-  await writeFile15(to, updated, "utf8");
+  await writeFile18(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(join36(root, name))) return name;
+    if (await pathExists(join38(root, name))) return name;
   }
   return void 0;
 }
@@ -8259,20 +9025,20 @@ function updateSchemaVersion(content) {
 
 // src/cli/version.ts
 import { readFileSync } from "fs";
-import { dirname as dirname24, join as join37 } from "path";
+import { dirname as dirname27, join as join39 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var FALLBACK_VERSION = "0.0.0";
 function resolveCliVersion() {
-  let dir = dirname24(fileURLToPath2(import.meta.url));
+  let dir = dirname27(fileURLToPath2(import.meta.url));
   while (true) {
     try {
-      const pkg = JSON.parse(readFileSync(join37(dir, "package.json"), "utf8"));
+      const pkg = JSON.parse(readFileSync(join39(dir, "package.json"), "utf8"));
       if (pkg.name === "agentwheel" && typeof pkg.version === "string") {
         return pkg.version;
       }
     } catch {
     }
-    const parent = dirname24(dir);
+    const parent = dirname27(dir);
     if (parent === dir) return FALLBACK_VERSION;
     dir = parent;
   }
@@ -8308,7 +9074,7 @@ program.command("init").description("initialize an agentwheel workspace or packa
   if (bootstrapPackage) console.log("Auto-added the agentwheel bootstrap skill for openclaw.");
   console.log(nextInstallNudge());
 });
-program.command("add").description("add a package to .agentwheel/config.json without touching runtimes").argument("<source>", "package source").option("--driver <driver>", "source driver (local, git, skillkit, or vercel-skills)").option("--adapter <adapter>", "built-in adapter", "openclaw").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("--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).option("-t, --target-root <path>", "workspace root").option("--mode <mode>", "pinned or tracking", "pinned").option("--name <name>", "package alias").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--override <source-or-package::type/name>", "allow this package to replace a colliding artifact (repeatable)", collectOverrideOption, []).action(async (source, options) => {
+program.command("add").description("add a package to .agentwheel/config.json without touching runtimes").argument("<source>", "package source").option("--driver <driver>", "source driver (local, git, skillkit, vercel-skills, mcp-registry, or clawhub)").option("--adapter <adapter>", "built-in adapter", "openclaw").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("--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).option("-t, --target-root <path>", "workspace root").option("--mode <mode>", "pinned or tracking", "pinned").option("--name <name>", "package alias").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots on future installs", false).option("--suggestion <alias>", "include one suggested companion alias on future installs (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "allow this package to replace a colliding artifact (repeatable)", collectOverrideOption, []).action(async (source, options) => {
   const normalizedOptions = normalizeRuntimeScopeOptions(options);
   const targetRoot = normalizeTargetRoot(normalizedOptions.targetRoot ?? process.cwd());
   const entry = await packageEntryFromSource(source, targetRoot, normalizedOptions);
@@ -8317,10 +9083,10 @@ program.command("add").description("add a package to .agentwheel/config.json wit
 });
 program.command("list").description("list artifacts exposed by a package source").argument("<source>", "package source").option("--driver <driver>", "source driver").option("-t, --target-root <path>", "workspace root", process.cwd()).option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).action(async (source, options) => {
   const targetRoot = normalizeTargetRoot(options.targetRoot);
-  const selectedArtifacts = selectedArtifactsFromOptions(options);
   const resolvedInput = await resolvePackageSource(source, targetRoot);
+  const selectedArtifacts = selectedArtifactsFromOptionsOrRegistry(options, resolvedInput.registryEntry);
   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: join38(targetRoot, ".agentwheel", "cache") }))));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join40(targetRoot, ".agentwheel", "cache") }))));
   const artifacts = filterArtifactsBySelection(await driver.list(resolved), selectedArtifacts);
   for (const artifact of artifacts) {
     console.log(`${artifact.type}	${artifact.name}	${artifact.relativePath}`);
@@ -8330,7 +9096,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: join38(targetRoot, ".agentwheel", "cache") }))));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join40(targetRoot, ".agentwheel", "cache") }))));
   const result = await driver.scan(resolved);
   if (result.findings.length === 0) {
     console.log("Scan ok: no findings");
@@ -8341,17 +9107,17 @@ program.command("scan").description("scan a package source for validation findin
   }
   if (!result.ok) process.exitCode = 1;
 });
-program.command("plan").description("preview what install would reconcile without writing").argument("[name-or-source]", "configured package name/source or package source to preview").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").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("--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).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--override <source-or-package::type/name>", "for source previews, allow the source to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--dry-run", "accepted for symmetry; plan never writes", false).option("--force-drift", "replace drifted managed artifacts during install planning", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "with a source argument, exclude configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (source, options) => {
+program.command("plan").description("preview what install would reconcile without writing").argument("[name-or-source]", "configured package name/source or package source to preview").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").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("--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).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "for source previews, allow the source to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--dry-run", "accepted for symmetry; plan never writes", false).option("--force-drift", "replace drifted managed artifacts during install planning", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "with a source argument, exclude configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (source, options) => {
   await runInstallCommand(source, { ...options, dryRun: true }, { apply: false });
 });
-program.command("install").description("install configured packages into runtime targets").argument("[name-or-source]", "configured package name/source or package source to add and install").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").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("--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).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--override <source-or-package::type/name>", "when adding a source, allow it to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plan without writing", false).option("--force-drift", "replace drifted managed artifacts", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "with a source argument, exclude configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).addHelpText("after", "\nScoped install never removes files owned only by other configured packages; run a full install to reconcile those removals.\n").action(async (source, options) => {
+program.command("install").description("install configured packages into runtime targets").argument("[name-or-source]", "configured package name/source or package source to add and install").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").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("--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).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "when adding a source, allow it to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plan without writing", false).option("--force-drift", "replace drifted managed artifacts", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "with a source argument, exclude configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).addHelpText("after", "\nScoped install never removes files owned only by other configured packages; run a full install to reconcile those removals.\n").action(async (source, options) => {
   await runInstallCommand(source, options, { apply: !options.dryRun });
 });
-program.command("sync", { hidden: true }).argument("[name-or-source]", "configured package name/source or package source").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").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("--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).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--override <source-or-package::type/name>", "when adding a source, allow it to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plan without writing", false).option("--force-drift", "replace drifted managed artifacts", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "with a source argument, exclude configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (source, options) => {
+program.command("sync", { hidden: true }).argument("[name-or-source]", "configured package name/source or package source").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").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("--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).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "when adding a source, allow it to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plan without writing", false).option("--force-drift", "replace drifted managed artifacts", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "with a source argument, exclude configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (source, options) => {
   console.error("warning: 'agentwheel sync' is deprecated and will be removed in 0.10. Use 'agentwheel install'.");
   await runInstallCommand(source, options, { apply: !options.dryRun });
 });
-program.command("update").description("re-resolve tracking packages, then apply the result").argument("[name]", "configured package name or source to update").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").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>", "workspace root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plans without writing", false).option("--force-drift", "replace drifted managed artifacts", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--allow-adapter-code", "allow loading local adapter code from configured packages", false).option("--select <type/name>", "temporarily select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "temporarily select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (name, options) => {
+program.command("update").description("re-resolve tracking packages, then apply the result").argument("[name]", "configured package name or source to update").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").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>", "workspace root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plans without writing", false).option("--force-drift", "replace drifted managed artifacts", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--allow-adapter-code", "allow loading local adapter code from configured packages", false).option("--select <type/name>", "temporarily select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "temporarily select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (name, options) => {
   const normalizedOptions = normalizeRuntimeScopeOptions(options);
   const targets = await resolveCliTargets(normalizedOptions, { preferAllProfile: true });
   for (const target of targets) {
@@ -8359,7 +9125,7 @@ program.command("update").description("re-resolve tracking packages, then apply
   }
 });
 program.command("deps").description("inspect the OpenPack dependency graph").addCommand(
-  new Command("tree").description("print the OpenPack dependency graph").argument("[source]", "optional package source to resolve").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").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("--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).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (source, options) => {
+  new Command("tree").description("print the OpenPack dependency graph").argument("[source]", "optional package source to resolve").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").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("--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).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (source, options) => {
     const normalizedOptions = normalizeRuntimeScopeOptions(options, { defaultUser: shouldDefaultUserInstall(source, options) });
     const targets = await resolveCliTargets(normalizedOptions);
     for (const target of targets) {
@@ -8372,7 +9138,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 rm10(result.bundle.root, { recursive: true, force: true });
+          await rm11(result.bundle.root, { recursive: true, force: true });
         }
         continue;
       }
@@ -8409,6 +9175,29 @@ program.command("registry").description("manage optional registry indexes").addC
     const client = new RegistryClient({ workspaceRoot: normalizeTargetRoot(options.targetRoot), warn: (message) => console.warn(message) });
     printRegistryEntries(await client.search(query));
   })
+).addCommand(
+  new Command("publish").description("draft a catalogue submission for a public source").argument("<source>", "public resource source or GitHub URL").option("--name <name>", "registry short name").option("--type <type>", "entry type (package, skill, plugin, mcp, or adapter)").option("--description <text>", "short catalogue description").option("--tag <tag>", "search tag (repeatable or comma-separated)", collectTagOption, []).option("--select <type/name>", "selected artifact inside a larger package (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "selected skill inside a larger package (repeatable or comma-separated)", collectSkillOption, []).option("--json", "print only the registry entry JSON", false).action(async (source, options) => {
+    const draft = createRegistryPublishDraft(source, {
+      name: options.name,
+      type: options.type,
+      description: options.description,
+      tags: options.tag,
+      select: options.select,
+      skills: options.skill
+    });
+    if (options.json) {
+      console.log(JSON.stringify(draft.entry, null, 2));
+      return;
+    }
+    console.log("Draft registry entry:");
+    console.log(JSON.stringify(draft.entry, null, 2));
+    console.log("");
+    console.log(`Verify: ${draft.installCommand}`);
+    if (!draft.entry.description) console.log('Tip: add --description "..." or fill the description before submitting.');
+    console.log("");
+    console.log("Submit:");
+    console.log(draft.issueUrl);
+  })
 );
 program.command("trust").description("manage persisted source trust decisions").addCommand(
   new Command("forget").description("forget a persisted trusted source pattern").argument("<pattern>", "trusted source glob to revoke").option("-t, --target-root <path>", "workspace root", process.cwd()).action(async (pattern, options) => {
@@ -8493,7 +9282,7 @@ 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) => {
+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).option("--skill <name>", "check a specific skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--source <source>", "source to use in suggested install commands").option("--json", "print machine-readable doctor report", false).action(async (options) => {
   const normalizedOptions = normalizeRuntimeScopeOptions(options);
   const target = await resolveRuntimeTarget({
     targetRoot: normalizedOptions.targetRoot,
@@ -8527,6 +9316,8 @@ async function runInstallCommand(nameOrSource, options, behavior) {
       forceConflict: normalizedOptions.forceConflict,
       replaceConflict: normalizedOptions.replaceConflict,
       noDeps: noDepsFromOptions(normalizedOptions),
+      includeSuggestions: normalizedOptions.withSuggestions,
+      suggestionAliases: suggestionAliasesFromOptions(normalizedOptions),
       lockedResolution: true,
       frozenLock: normalizedOptions.frozenLock,
       offline: normalizedOptions.offline,
@@ -8576,7 +9367,7 @@ async function runInstallCommand(nameOrSource, options, behavior) {
         });
         console.log(`Applied ${result.plan.adapter} at ${result.plan.targetRoot}.`);
       }
-      await rm10(result.bundle.root, { recursive: true, force: true });
+      await rm11(result.bundle.root, { recursive: true, force: true });
       if (result.plan.hasBlockingChanges) process.exitCode = 1;
     }
     if (behavior.apply && extraPackage && !targetOptions.onlySource) {
@@ -8585,10 +9376,10 @@ async function runInstallCommand(nameOrSource, options, behavior) {
   }
 }
 async function packageEntryFromSource(source, targetRoot, options) {
-  const selectedArtifacts = selectedArtifactsFromOptions(options);
   const lockMode = options.frozenLock === true || options.offline === true;
   const resolvedInput = await resolvePackageSource(source, targetRoot, { offline: lockMode });
   const resolvedSource = resolvedInput.source;
+  const selectedArtifacts = selectedArtifactsFromOptionsOrRegistry(options, resolvedInput.registryEntry);
   const driverName = options.driver ?? inferSourceDriverName(resolvedSource);
   const driver = getSourceDriver(driverName);
   const adapter = await resolveAdapter({
@@ -8602,7 +9393,7 @@ async function packageEntryFromSource(source, targetRoot, options) {
   const bundle = await stageSource(driver, resolvedSource, {
     workspaceRoot: targetRoot,
     adapter,
-    cacheRoot: join38(targetRoot, ".agentwheel", "cache"),
+    cacheRoot: join40(targetRoot, ".agentwheel", "cache"),
     mode: options.mode,
     frozenLock: lockMode,
     select: selectedArtifacts
@@ -8621,10 +9412,12 @@ async function packageEntryFromSource(source, targetRoot, options) {
       mode: options.mode ?? "pinned",
       requestedRef: bundle.source.requestedRef,
       select: selectedArtifacts,
+      withSuggestions: options.withSuggestions === true ? true : void 0,
+      suggestions: suggestionAliasesFromOptions(options),
       overrides: overrideArtifactsFromOptions(options)
     };
   } finally {
-    await rm10(bundle.root, { recursive: true, force: true });
+    await rm11(bundle.root, { recursive: true, force: true });
   }
 }
 function findConfiguredPackage(packages, value) {
@@ -8765,7 +9558,7 @@ async function runConfiguredGraphPackages(target, options, behavior) {
       });
       console.log(`Applied ${result.plan.adapter} at ${result.plan.targetRoot}.`);
     }
-    await rm10(result.bundle.root, { recursive: true, force: true });
+    await rm11(result.bundle.root, { recursive: true, force: true });
     if (result.plan.hasBlockingChanges) process.exitCode = 1;
   }
 }
@@ -8830,6 +9623,8 @@ async function buildGraphPlansForTarget(target, source, options, behavior) {
           select: selectedArtifacts && packageIsScoped ? selectedArtifacts : normalizeArtifactSelectors(pkg.select, pkg.skills),
           aliases: pkg.aliases,
           overrides: pkg.overrides,
+          includeSuggestions: targetOptions.withSuggestions === true || pkg.withSuggestions === true,
+          suggestionAliases: packageSuggestionAliases(pkg, targetOptions),
           useLock: behavior.mode === "install" ? true : !updateThisPackage
         };
       }),
@@ -8854,6 +9649,8 @@ async function buildGraphPlansForTarget(target, source, options, behavior) {
       targetFingerprintParts: targetFingerprintParts(group.target, adapter, group.adapterOptions, group.installationType),
       installationType: group.installationType,
       noDeps: noDepsFromOptions(targetOptions),
+      includeSuggestions: targetOptions.withSuggestions,
+      suggestionAliases: suggestionAliasesFromOptions(targetOptions),
       lockedResolution: behavior.mode === "install",
       frozenLock: targetOptions.frozenLock,
       offline: targetOptions.offline,
@@ -8954,7 +9751,7 @@ function keepManifestEntryOperation(entry, targetRoot, rootId, operation, option
     artifactType: entry.artifactType,
     artifactName: entry.artifactName,
     kind: entry.kind,
-    destPath: operation?.destPath ?? join38(targetRoot, entry.path),
+    destPath: operation?.destPath ?? join40(targetRoot, entry.path),
     relativeDestPath: entry.path,
     desiredHash: entry.sourceHash,
     currentHash: operation?.currentHash ?? entry.hash,
@@ -9019,7 +9816,9 @@ async function uninstallConfiguredPackage(target, packageName, options) {
           ref: pkg2.requestedRef,
           select: normalizeArtifactSelectors(pkg2.select, pkg2.skills),
           aliases: pkg2.aliases,
-          overrides: pkg2.overrides
+          overrides: pkg2.overrides,
+          includeSuggestions: options.withSuggestions === true || pkg2.withSuggestions === true,
+          suggestionAliases: packageSuggestionAliases(pkg2, options)
         })),
         targetRoot: remainingGroup.target.targetRoot,
         workspaceRoot: remainingGroup.target.workspaceRoot,
@@ -9028,6 +9827,8 @@ async function uninstallConfiguredPackage(target, packageName, options) {
         targetKey: targetKeyForTarget(remainingGroup.target, remainingAdapter.name),
         targetFingerprintParts: targetFingerprintParts(remainingGroup.target, remainingAdapter, remainingGroup.adapterOptions, remainingGroup.installationType),
         installationType: remainingGroup.installationType,
+        includeSuggestions: options.withSuggestions,
+        suggestionAliases: suggestionAliasesFromOptions(options),
         lockedResolution: true,
         frozenLock: options.frozenLock,
         offline: options.offline,
@@ -9065,7 +9866,7 @@ async function uninstallConfiguredPackage(target, packageName, options) {
     if (!options.dryRun) {
       console.log(formatUninstallResult(result));
     }
-    if (renderedRoot) await rm10(renderedRoot, { recursive: true, force: true });
+    if (renderedRoot) await rm11(renderedRoot, { recursive: true, force: true });
     if (plan.hasBlockingChanges) process.exitCode = 1;
   }
 }
@@ -9193,7 +9994,7 @@ 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) => rm10(result.bundle.root, { recursive: true, force: true })));
+    await Promise.all(results.map((result) => rm11(result.bundle.root, { recursive: true, force: true })));
   }
 }
 async function printDoctor(target, options) {
@@ -9204,33 +10005,113 @@ async function printDoctor(target, options) {
   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}`);
+  const transport = transportForTarget(target);
+  const state = installStateForTarget(target, adapter, adapterOptions, installationType);
+  const manifest = await readInstallManifest(state.installRoot, adapter.name, transport, state);
+  const requestedSkills = doctorSkillRequests(target, options);
+  const skills = [];
+  for (const request of requestedSkills) {
+    const skillPath = join40(state.installRoot, targetMapping.dest, request.name);
+    const exists = await pathExists(skillPath);
+    const manifestEntry = manifest?.entries.find((entry) => {
+      if (entry.artifactType !== "skills") return false;
+      const legacyInstallName = "installName" in entry && typeof entry.installName === "string" ? entry.installName : void 0;
+      return entry.artifactName === request.name || legacyInstallName === request.name || entry.path === join40(targetMapping.dest, request.name);
+    });
+    const status = manifestEntry ? "managed" : exists ? "present-unmanaged" : "missing";
+    skills.push({
+      name: request.name,
+      source: request.source,
+      label: request.label,
+      status,
+      path: skillPath,
+      managed: Boolean(manifestEntry),
+      present: exists,
+      suggestedCommands: status === "missing" ? {
+        dryRun: skillInstallCommand(adapter.name, installationType, options, request, { dryRun: true }),
+        apply: skillInstallCommand(adapter.name, installationType, options, request)
+      } : void 0
+    });
+  }
+  const report = {
+    adapter: adapter.name,
+    installationType,
+    targetRoot: target.targetRoot,
+    installRoot: state.installRoot,
+    manifest: manifest ? { entries: manifest.entries.length, revision: manifest.revision } : null,
+    skills
+  };
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
     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)}`);
+  console.log(`Doctor for ${adapter.name}/${installationType} at ${state.installRoot}`);
+  for (const skill of skills) {
+    const statusLabel = skill.status === "managed" ? "installed" : skill.status === "present-unmanaged" ? "installed (unmanaged)" : "missing";
+    console.log(`${skill.label}: ${statusLabel} at ${skill.path}`);
+  }
+  const missing = skills.filter((skill) => skill.status === "missing");
+  if (missing.length > 0) {
+    console.log("Suggested commands:");
+    for (const skill of missing) {
+      console.log(`  ${skill.suggestedCommands?.dryRun}`);
+      console.log(`  ${skill.suggestedCommands?.apply}`);
+    }
+  }
+}
+function doctorSkillRequests(target, options) {
+  const explicitSkills = normalizeDoctorSkillNames(options.skill ?? []);
+  if (explicitSkills.length > 0) {
+    return explicitSkills.map((name) => ({
+      name,
+      source: options.source ?? defaultSourceForSkill(name),
+      label: doctorSkillLabel(name)
+    }));
+  }
+  const requests = [{
+    name: COMPANION_SKILL_NAME,
+    source: COMPANION_SKILL_SOURCE,
+    label: "Agentwheel companion skill"
+  }];
+  if (isSyncwheelWorkspace(target.targetRoot)) {
+    requests.push({
+      name: "syncwheel",
+      source: "github:NestDevLab/syncwheel",
+      label: "Syncwheel skill"
+    });
+  }
+  return requests;
+}
+function normalizeDoctorSkillNames(skills) {
+  return [...new Set(skills.flatMap(splitSelectorList).map((item) => item.trim()).filter(Boolean))];
+}
+function defaultSourceForSkill(name) {
+  if (name === COMPANION_SKILL_NAME) return COMPANION_SKILL_SOURCE;
+  if (name === "syncwheel") return "github:NestDevLab/syncwheel";
+  return `github:NestDevLab/${name}`;
 }
-function companionSkillInstallCommand(adapter, installationType, options, behavior = {}) {
+function doctorSkillLabel(name) {
+  if (name === COMPANION_SKILL_NAME) return "Agentwheel companion skill";
+  if (name === "syncwheel") return "Syncwheel skill";
+  return `${name} skill`;
+}
+function isSyncwheelWorkspace(targetRoot) {
+  return existsSync(join40(targetRoot, ".syncwheel", "manifest.json"));
+}
+function skillInstallCommand(adapter, installationType, options, skill, behavior = {}) {
   const args = [
     "agentwheel",
     "install",
-    COMPANION_SKILL_SOURCE,
+    skill.source,
     "--adapter",
     adapter,
     ...installationTypeCommandArgs(installationType),
     ...targetRootCommandArgs(options),
     "--skill",
-    COMPANION_SKILL_NAME
+    skill.name
   ];
   if (behavior.dryRun) args.push("--dry-run");
-  return args.map(shellQuoteArg).join(" ");
+  return args.map(shellQuoteArg2).join(" ");
 }
 function installationTypeCommandArgs(installationType) {
   if (installationType === "user") return ["--user"];
@@ -9240,7 +10121,7 @@ function installationTypeCommandArgs(installationType) {
 function targetRootCommandArgs(options) {
   return options.targetRoot && options.installationType !== "user" ? ["--target-root", options.targetRoot] : [];
 }
-function shellQuoteArg(value) {
+function shellQuoteArg2(value) {
   if (/^[A-Za-z0-9_./:@=-]+$/.test(value)) return value;
   return `'${value.replaceAll("'", `'"'"'`)}'`;
 }
@@ -9250,12 +10131,18 @@ function collectSelectOption(value, previous) {
 function collectSkillOption(value, previous) {
   return [...previous, ...splitSelectorList(value)];
 }
+function collectSuggestionOption(value, previous) {
+  return [...previous, ...splitSelectorList(value)];
+}
 function collectTrustOption(value, previous) {
   return [...previous, value];
 }
 function collectOverrideOption(value, previous) {
   return [...previous, ...splitSelectorList(value)];
 }
+function collectTagOption(value, previous) {
+  return [...previous, ...splitSelectorList(value)];
+}
 function normalizeRuntimeScopeOptions(options, behavior = {}) {
   if (options.user && options.local) {
     throw new Error("Choose either --user or --local.");
@@ -9292,11 +10179,11 @@ function looksLikeSourceSpecifier(value) {
 }
 function normalizeCliPath(value) {
   if (value === "~") return homedir9();
-  if (value.startsWith("~/")) return resolve18(homedir9(), value.slice(2));
-  return resolve18(value);
+  if (value.startsWith("~/")) return resolve20(homedir9(), value.slice(2));
+  return resolve20(value);
 }
 function isHomePath(path) {
-  return resolve18(path) === resolve18(homedir9());
+  return resolve20(path) === resolve20(homedir9());
 }
 function adapterListFromOption(adapter) {
   if (!adapter) return [];
@@ -9310,6 +10197,18 @@ function adapterListFromOption(adapter) {
 function selectedArtifactsFromOptions(options) {
   return normalizeArtifactSelectors(options.select, options.skills ?? options.skill);
 }
+function selectedArtifactsFromOptionsOrRegistry(options, registryEntry) {
+  return selectedArtifactsFromOptions(options) ?? selectorsFromRegistryEntry(registryEntry);
+}
+function suggestionAliasesFromOptions(options) {
+  const values = options.suggestions ?? options.suggestion;
+  if (!values?.length) return void 0;
+  return [...new Set(values.flatMap(splitSelectorList).map((item) => item.trim()).filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}
+function packageSuggestionAliases(pkg, options) {
+  const aliases = [...pkg.suggestions ?? [], ...suggestionAliasesFromOptions(options) ?? []].map((item) => item.trim()).filter(Boolean);
+  return aliases.length > 0 ? [...new Set(aliases)].sort((a, b) => a.localeCompare(b)) : void 0;
+}
 function overrideArtifactsFromOptions(options) {
   const values = options.overrides ?? options.override;
   return values && values.length > 0 ? values : void 0;
@@ -9339,10 +10238,10 @@ function filterUninstallPlanBySelection(plan, selected) {
   };
 }
 async function initPackage(root) {
-  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");
+  await mkdir20(join40(root, "instructions"), { recursive: true });
+  await mkdir20(join40(root, "rules"), { recursive: true });
+  await mkdir20(join40(root, "skills"), { recursive: true });
+  const manifestPath = join40(root, "openpack.json");
   const manifest = {
     schemaVersion: 2,
     name: "example/agentwheel-package",
@@ -9353,12 +10252,12 @@ async function initPackage(root) {
       { type: "skills", path: "skills" }
     ]
   };
-  await writeFile16(manifestPath, `${JSON.stringify(manifest, null, 2)}
+  await writeFile19(manifestPath, `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
-  await writeFile16(join38(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
+  await writeFile19(join40(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
 }
 async function defaultBootstrapPackage(_root) {
-  const packageRoot = await findAgentwheelPackageRoot(dirname25(fileURLToPath3(import.meta.url)));
+  const packageRoot = await findAgentwheelPackageRoot(dirname28(fileURLToPath3(import.meta.url)));
   if (!packageRoot) return void 0;
   return {
     name: "agentwheel",
@@ -9402,10 +10301,10 @@ function withFleetExample(config) {
   };
 }
 async function findAgentwheelPackageRoot(start) {
-  let current = resolve18(start);
+  let current = resolve20(start);
   while (true) {
     if (await findPackageManifestPath(current, { warnLegacy: false })) return current;
-    const parent = dirname25(current);
+    const parent = dirname28(current);
     if (parent === current) return void 0;
     current = parent;
   }