agentwheel 0.5.0 → 0.7.0

package/README.md

@@ -33,9 +33,10 @@ No lock-in. No central gatekeeper. Your packages live in plain git repos, your c
 
 ---
 
-> **Status: early (v0.5).** The lifecycle core is real and tested — local/git/skillkit/vercel
+> **Status: early (v0.7).** The lifecycle core is real and tested — local/git/skillkit/vercel
 > sources, optional registry discovery, plan/sync/update/drift/uninstall, overlays, eject/remember,
-> profiles, runtime auto-detection, fleet targeting, asset-includes, rich JSON merge, and pluggable adapters.
+> profiles, runtime auto-detection, fleet targeting, asset-includes, selective installs,
+> update notifications, full Claude/Codex adapters, rich JSON/TOML merge, and pluggable adapters.
 > Expect sharp edges.
 
 ## What it does
@@ -75,6 +76,10 @@ pnpm link --global
 `uninstall` removes clean managed files by default and keeps drifted files in place with a warning.
 Use `agentwheel uninstall --force` only when you also want to remove drifted managed files.
 
+agentwheel checks npm for newer versions at most once every 24 hours and prints a non-blocking
+stderr warning when an update is available. Disable it with `--no-update-check` or
+`AGENTWHEEL_NO_UPDATE_CHECK=1`.
+
 ## Runtime targeting
 
 Normal use no longer needs `--target-root`. Run agentwheel inside a runtime folder and it detects
@@ -147,6 +152,28 @@ A package is a git repo (or folder) with a JSON manifest and a canonical layout:
 }
 ```
 
+Install only part of a package with `--select <type>/<name>`. `--skill <name>` is a shortcut for
+`--select skills/<name>`, and selections saved during `add` are reused by later `sync` and `update`
+runs.
+
+```bash
+agentwheel add github:NestDevLab/agent-mesh --skill codex-tmux --adapter openclaw
+agentwheel sync --dry-run
+
+agentwheel sync github:your-org/agent-pack --select rules/safe-actions.md --select commands/build.md
+```
+
+Package authors can mark dependencies as required. Required artifacts are always installed and
+cannot be deselected:
+
+```jsonc
+{
+  "type": "rules",
+  "path": "rules/core-safety.md",
+  "required": true
+}
+```
+
 Packages can compose shared files into each directory artifact at staging time. This keeps one
 canonical copy in the package repo while installing self-contained skills:
 
@@ -233,6 +260,20 @@ agentwheel sync ./my-pack --adapter-config ./myco-internal.jsonc
 Built-in adapters ship for common runtimes; declarative adapters need no code and stay private.
 Programmatic adapters, for private runtime logic beyond file placement, require explicit `--allow-adapter-code`.
 
+Built-in runtime targets:
+
+| Runtime | Main targets |
+|---|---|
+| **OpenClaw** | `.openclaw/AGENTS.md`, `.openclaw/skills`, `.openclaw/rules`, `.openclaw/commands`, MCP/hooks/settings, semantic plugin planning |
+| **Claude Code** | `.claude/CLAUDE.md`, `.claude/skills`, `.claude/commands`, `.claude/agents`, `.claude/rules`, `.claude/.mcp.json`, `.claude/settings.json` |
+| **Codex CLI** | `.codex/AGENTS.md`, `.codex/skills`, `.codex/commands`, `.codex/agents`, `.codex/rules`, `.codex/config.toml`, `.codex/hooks.json` |
+| **Hermes** | `.hermes/AGENTS.md`, `.hermes/skills`, `.hermes/rules`, `.hermes/commands`, MCP/hooks/settings |
+| **GitHub Copilot** | `.github/copilot-instructions.md`, `.github/instructions`, `.github/prompts` |
+
+Claude MCP and hooks/settings are merged as JSON. Codex MCP entries are merged into
+`[mcp_servers]` in `.codex/config.toml` without deleting unrelated user config; hooks use
+`.codex/hooks.json`.
+
 Copilot support is intentionally file-drop only: instructions, rules, and prompt/command files are
 placed in GitHub-native locations, while raw `SKILL.md` directories stay disabled until there is a
 clear conversion format.
@@ -244,6 +285,8 @@ clear conversion format.
 - [x] **v0.3** — skillkit/vercel source drivers; optional registry & federation; programmatic adapters behind `--allow-adapter-code`; rich JSON merge for mcp/hooks/settings; profiles.
 - [x] **v0.4** — runtime auto-detection; no `--target-root` needed for normal use; fleet config with named agents; global + project config merge; `--agent` and `--all`.
 - [x] **v0.5** — asset-includes compose shared files into skills at install time; executable bits preserved; hashes include composed assets.
+- [x] **v0.6** — selective installs with `--select`/`--skill`; required artifacts; cached npm update notifier.
+- [x] **v0.7** — full Claude/Codex adapters; Codex TOML MCP merge; subagent enumeration; `--skill` selector fix.
 
 ## Design docs
 

package/dist/index.js

@@ -8,8 +8,8 @@ import {
 } from "./chunk-N2LZY7LO.js";
 
 // src/cli/index.ts
-import { mkdir as mkdir7, rm as rm8, writeFile as writeFile4 } from "fs/promises";
-import { join as join19 } from "path";
+import { mkdir as mkdir9, rm as rm8, writeFile as writeFile6 } from "fs/promises";
+import { join as join20 } from "path";
 import { Command } from "commander";
 
 // src/adapters/resolve.ts
@@ -50,7 +50,8 @@ var artifactSchema = z.object({
   hash: z.string().min(16),
   packageName: z.string().min(1).optional(),
   channel: z.enum(["managed", "overlay", "addition", "override", "ejected"]).default("managed"),
-  assets: z.array(packageAssetSchema).optional()
+  assets: z.array(packageAssetSchema).optional(),
+  required: z.boolean().optional()
 });
 
 // src/model/adapter.ts
@@ -58,7 +59,7 @@ var targetMappingSchema = z2.object({
   dest: z2.string().min(1),
   enabled: z2.boolean().default(true),
   semantic: z2.enum(["openclaw-plugin"]).optional(),
-  merge: z2.enum(["json-deep"]).optional()
+  merge: z2.enum(["json-deep", "codex-toml-mcp"]).optional()
 });
 var adapterSchema = z2.object({
   name: z2.string().min(1),
@@ -85,8 +86,17 @@ async function loadAdapterConfig(path) {
 // src/adapters/claude.ts
 var claudeAdapter = {
   name: "claude",
-  displayName: "Claude",
-  targets: {}
+  displayName: "Claude Code",
+  targets: {
+    instructions: { enabled: true, dest: ".claude/CLAUDE.md" },
+    rules: { enabled: true, dest: ".claude/rules" },
+    skills: { enabled: true, dest: ".claude/skills" },
+    commands: { enabled: true, dest: ".claude/commands" },
+    subagents: { enabled: true, dest: ".claude/agents" },
+    mcp: { enabled: true, dest: ".claude/.mcp.json", merge: "json-deep" },
+    hooks: { enabled: true, dest: ".claude/settings.json", merge: "json-deep" },
+    settings: { enabled: true, dest: ".claude/settings.json", merge: "json-deep" }
+  }
 };
 
 // src/adapters/copilot.ts
@@ -106,8 +116,17 @@ var copilotAdapter = {
 // src/adapters/codex.ts
 var codexAdapter = {
   name: "codex",
-  displayName: "Codex",
-  targets: {}
+  displayName: "Codex CLI",
+  targets: {
+    instructions: { enabled: true, dest: ".codex/AGENTS.md" },
+    rules: { enabled: true, dest: ".codex/rules" },
+    skills: { enabled: true, dest: ".codex/skills" },
+    commands: { enabled: true, dest: ".codex/commands" },
+    subagents: { enabled: true, dest: ".codex/agents" },
+    mcp: { enabled: true, dest: ".codex/config.toml", merge: "codex-toml-mcp" },
+    hooks: { enabled: true, dest: ".codex/hooks.json", merge: "json-deep" },
+    settings: { enabled: true, dest: ".codex/settings.json", merge: "json-deep" }
+  }
 };
 
 // src/adapters/hermes.ts
@@ -281,7 +300,7 @@ var manifestEntrySchema = z3.object({
   packageName: z3.string().min(1).optional(),
   semanticCommand: z3.array(z3.string()).optional(),
   executed: z3.boolean().optional(),
-  mergeStrategy: z3.enum(["json-deep"]).optional()
+  mergeStrategy: z3.enum(["json-deep", "codex-toml-mcp"]).optional()
 });
 var installManifestSchema = z3.object({
   version: z3.literal(1),
@@ -354,6 +373,94 @@ function normalizeTargetRoot(path) {
   return resolve3(path);
 }
 
+// src/install/toml-merge.ts
+import { mkdir as mkdir2, readFile as readFile5, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname2 } from "path";
+async function mergeCodexTomlMcp(sourcePath, destPath) {
+  const source = JSON.parse(await readFile5(sourcePath, "utf8"));
+  const servers = extractMcpServers(source);
+  const current = await pathExists(destPath) ? await readFile5(destPath, "utf8") : "";
+  const withoutManaged = removeManagedMcpSections(current, Object.keys(servers));
+  const merged = appendMcpServers(withoutManaged, servers);
+  await mkdir2(dirname2(destPath), { recursive: true });
+  await writeFile3(destPath, merged, "utf8");
+}
+function extractMcpServers(source) {
+  const raw = isRecord2(source.mcpServers) ? source.mcpServers : source;
+  const servers = {};
+  for (const [name, value] of Object.entries(raw)) {
+    if (!isRecord2(value)) continue;
+    servers[name] = value;
+  }
+  if (Object.keys(servers).length === 0) {
+    throw new Error("Codex MCP TOML merge needs a JSON object with mcpServers");
+  }
+  return servers;
+}
+function removeManagedMcpSections(content, serverNames) {
+  if (serverNames.length === 0 || content.trim() === "") return content;
+  const names = new Set(serverNames);
+  const lines = content.split(/\r?\n/);
+  const kept = [];
+  let skipping = false;
+  for (const line of lines) {
+    const section = line.match(/^\s*\[([^\]]+)]\s*$/)?.[1];
+    if (section) {
+      const match = section.match(/^mcp_servers\.([^.\]]+)(?:\.|$)/);
+      skipping = match ? names.has(unquoteTomlKey(match[1] ?? "")) : false;
+    }
+    if (!skipping) kept.push(line);
+  }
+  return kept.join("\n").replace(/\n{3,}$/g, "\n\n");
+}
+function appendMcpServers(content, servers) {
+  const blocks = Object.entries(servers).sort(([a], [b]) => a.localeCompare(b)).map(([name, server]) => formatMcpServer(name, server));
+  const prefix = content.trimEnd();
+  return `${prefix ? `${prefix}
+
+` : ""}${blocks.join("\n\n")}
+`;
+}
+function formatMcpServer(name, server) {
+  const env = isRecord2(server.env) ? server.env : void 0;
+  const lines = [`[mcp_servers.${quoteTomlKey(name)}]`];
+  for (const [key, value] of Object.entries(server)) {
+    if (key === "env" || value === void 0) continue;
+    lines.push(`${quoteTomlKey(key)} = ${formatTomlValue(value)}`);
+  }
+  if (env && Object.keys(env).length > 0) {
+    lines.push("", `[mcp_servers.${quoteTomlKey(name)}.env]`);
+    for (const [key, value] of Object.entries(env)) {
+      lines.push(`${quoteTomlKey(key)} = ${formatTomlValue(value)}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatTomlValue(value) {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return `[${value.map(formatTomlValue).join(", ")}]`;
+  if (isRecord2(value)) {
+    const entries = Object.entries(value).map(([key, child]) => `${quoteTomlKey(key)} = ${formatTomlValue(child)}`);
+    return `{ ${entries.join(", ")} }`;
+  }
+  return '""';
+}
+function quoteTomlKey(key) {
+  return /^[A-Za-z0-9_-]+$/.test(key) ? key : JSON.stringify(key);
+}
+function unquoteTomlKey(key) {
+  if (!key.startsWith('"')) return key;
+  try {
+    return JSON.parse(key);
+  } catch {
+    return key;
+  }
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // src/install/apply.ts
 var execFileAsync = promisify(execFile);
 async function applyInstallPlan(plan, sourceLock, options = {}) {
@@ -419,6 +526,8 @@ async function applyInstallPlan(plan, sourceLock, options = {}) {
       }
       if (operation.mergeStrategy === "json-deep") {
         await mergeJsonFile(operation.sourcePath, operation.destPath);
+      } else if (operation.mergeStrategy === "codex-toml-mcp") {
+        await mergeCodexTomlMcp(operation.sourcePath, operation.destPath);
       } else {
         await atomicCopy(operation.sourcePath, operation.destPath, operation.kind);
       }
@@ -444,7 +553,7 @@ async function applyInstallPlan(plan, sourceLock, options = {}) {
         artifactType: operation.artifactType,
         artifactName: operation.artifactName,
         kind: operation.kind,
-        hash: operation.mergeStrategy === "json-deep" && operation.currentHash ? operation.currentHash : operation.desiredHash,
+        hash: operation.mergeStrategy && operation.currentHash ? operation.currentHash : operation.desiredHash,
         sourceHash: operation.desiredHash,
         updatedAt: now,
         channel: operation.channel,
@@ -476,6 +585,7 @@ async function uninstall(plan, options = {}) {
   }
   const removable = plan.operations.filter((operation) => operation.action === "remove" || resolvedOptions.force && operation.action === "keep");
   const kept = resolvedOptions.force ? [] : plan.operations.filter((operation) => operation.action === "keep");
+  const skipped = plan.operations.filter((operation) => operation.action === "skip");
   const removedDrifted = resolvedOptions.force ? plan.operations.filter((operation) => operation.action === "keep").length : 0;
   if (resolvedOptions.dryRun) return { removed: removable.length, kept: kept.length, removedDrifted };
   for (const operation of plan.operations) {
@@ -483,7 +593,8 @@ async function uninstall(plan, options = {}) {
       await rm2(operation.destPath, { recursive: true, force: true });
     }
   }
-  if (kept.length > 0) {
+  const preserved = [...kept, ...skipped];
+  if (preserved.length > 0) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     await writeInstallManifest({
       version: 1,
@@ -491,9 +602,9 @@ async function uninstall(plan, options = {}) {
       targetRoot: plan.targetRoot,
       generatedAt: now,
       adapterCode: plan.adapterCode,
-      entries: kept.map((operation) => {
+      entries: preserved.map((operation) => {
         if (!operation.manifestHash || !operation.desiredHash) {
-          throw new Error(`Invalid kept operation missing manifest/source hash: ${operation.relativeDestPath}`);
+          throw new Error(`Invalid preserved operation missing manifest/source hash: ${operation.relativeDestPath}`);
         }
         return {
           path: operation.relativeDestPath,
@@ -571,7 +682,7 @@ async function createInstallPlan(bundle, adapter, targetRoot, manifest) {
       }
       continue;
     }
-    if (op.mergeStrategy === "json-deep") {
+    if (op.mergeStrategy) {
       const existing2 = manifestByPath.get(op.relativeDestPath);
       const exists2 = await pathExists(op.destPath);
       if (!exists2) {
@@ -679,7 +790,7 @@ function operationForArtifact(artifact, adapter, targetRoot) {
       semanticCommand: openClawPluginInstallCommand({ path: sourcePath, dryRun: true })
     };
   }
-  const destPath = artifact.type === "instructions" || artifact.type === "settings" ? join3(targetRoot, target.dest) : join3(targetRoot, target.dest, artifact.name);
+  const destPath = artifact.type === "instructions" || artifact.type === "settings" || isFileTarget(target.dest) ? join3(targetRoot, target.dest) : join3(targetRoot, target.dest, artifact.name);
   return {
     action: "create",
     artifactType: artifact.type,
@@ -695,6 +806,9 @@ function operationForArtifact(artifact, adapter, targetRoot) {
     mergeStrategy: target.merge
   };
 }
+function isFileTarget(dest) {
+  return /\.(json|jsonc|toml|md)$/i.test(dest);
+}
 function summarizePlan(plan) {
   const summary = {
     create: 0,
@@ -746,11 +860,14 @@ async function createUninstallPlan(manifest) {
         kind: entry.kind,
         destPath,
         relativeDestPath: entry.path,
+        desiredHash: entry.sourceHash,
         currentHash,
         manifestHash: entry.hash,
         reason: "uninstall managed artifact",
         channel: entry.channel,
-        packageName: entry.packageName
+        packageName: entry.packageName,
+        semanticCommand: entry.semanticCommand,
+        mergeStrategy: entry.mergeStrategy
       });
     }
   }
@@ -799,20 +916,21 @@ function formatPlan(plan) {
 
 // src/source/git.ts
 import { execFile as execFile2 } from "child_process";
-import { mkdir as mkdir2, rm as rm3 } from "fs/promises";
+import { mkdir as mkdir3, rm as rm3 } from "fs/promises";
 import { homedir } from "os";
 import { basename as basename2, join as join7, resolve as resolve5 } from "path";
 import { promisify as promisify2 } from "util";
 
 // src/model/package.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile6 } from "fs/promises";
 import { join as join5 } from "path";
 import { parse as parse2, printParseErrorCode as printParseErrorCode2 } from "jsonc-parser";
 import { z as z4 } from "zod";
 var packageProvideSchema = z4.object({
   type: artifactTypeSchema,
   path: z4.string().min(1),
-  assets: z4.array(packageAssetSchema).optional()
+  assets: z4.array(packageAssetSchema).optional(),
+  required: z4.boolean().optional()
 });
 var packageManifestSchema = z4.object({
   schemaVersion: z4.literal(1),
@@ -830,7 +948,7 @@ async function findPackageManifestPath(root) {
 async function readPackageManifest(root) {
   const path = await findPackageManifestPath(root);
   if (!path) return void 0;
-  const content = await readFile5(path, "utf8");
+  const content = await readFile6(path, "utf8");
   const errors = [];
   const parsed = parse2(content, errors, { allowTrailingComma: true, disallowComments: false });
   if (errors.length > 0) {
@@ -932,7 +1050,7 @@ var LocalSourceDriver = class {
         }
       }
     }
-    for (const type of ["commands", "mcp", "hooks", "settings", "plugins"]) {
+    for (const type of ["commands", "subagents", "mcp", "hooks", "settings", "plugins"]) {
       const dir = join6(root, type);
       if (!await pathExists(dir)) continue;
       artifacts.push(...await listGenericArtifacts(type, dir, type, resolved.packageName));
@@ -981,24 +1099,22 @@ async function listFromManifest(root, packageName) {
     const stats = await stat2(full);
     if (provide.type === "instructions") {
       if (stats.isFile()) {
-        artifacts.push(await artifactForFile(provide.type, basename(full), full, provide.path, packageName, provide.assets));
+        artifacts.push(await artifactForFile(provide.type, basename(full), full, provide.path, packageName, provide.assets, provide.required));
       }
       continue;
     }
     if (stats.isDirectory()) {
       for (const entry of await sortedDirEntries(full)) {
         const child = join6(full, entry.name);
-        if (provide.type === "skills" && entry.isDirectory()) {
-          artifacts.push(await artifactForDir(provide.type, entry.name, child, join6(provide.path, entry.name), packageName, provide.assets));
-        } else if (provide.type === "plugins" && entry.isDirectory()) {
-          artifacts.push(await artifactForDir(provide.type, entry.name, child, join6(provide.path, entry.name), packageName, provide.assets));
+        if ((provide.type === "skills" || provide.type === "plugins" || provide.type === "subagents") && entry.isDirectory()) {
+          artifacts.push(await artifactForDir(provide.type, entry.name, child, join6(provide.path, entry.name), packageName, provide.assets, provide.required));
         } else if (entry.isFile()) {
           const name = provide.type === "rules" && entry.name.endsWith(".md") ? entry.name : entry.name;
-          artifacts.push(await artifactForFile(provide.type, name, child, join6(provide.path, entry.name), packageName, provide.assets));
+          artifacts.push(await artifactForFile(provide.type, name, child, join6(provide.path, entry.name), packageName, provide.assets, provide.required));
         }
       }
     } else if (stats.isFile()) {
-      artifacts.push(await artifactForFile(provide.type, basename(full), full, provide.path, packageName, provide.assets));
+      artifacts.push(await artifactForFile(provide.type, basename(full), full, provide.path, packageName, provide.assets, provide.required));
     }
   }
   return artifacts;
@@ -1015,7 +1131,7 @@ async function listGenericArtifacts(type, dir, relativeRoot, packageName) {
   }
   return artifacts;
 }
-async function artifactForFile(type, name, sourcePath, relativePath, packageName, assets) {
+async function artifactForFile(type, name, sourcePath, relativePath, packageName, assets, required) {
   return {
     type,
     name,
@@ -1025,10 +1141,11 @@ async function artifactForFile(type, name, sourcePath, relativePath, packageName
     hash: await hashPath(sourcePath),
     packageName,
     channel: "managed",
-    assets
+    assets,
+    required
   };
 }
-async function artifactForDir(type, name, sourcePath, relativePath, packageName, assets) {
+async function artifactForDir(type, name, sourcePath, relativePath, packageName, assets, required) {
   return {
     type,
     name,
@@ -1038,7 +1155,8 @@ async function artifactForDir(type, name, sourcePath, relativePath, packageName,
     hash: await hashPath(sourcePath),
     packageName,
     channel: "managed",
-    assets
+    assets,
+    required
   };
 }
 
@@ -1061,7 +1179,7 @@ var GitSourceDriver = class {
   }
   async fetch(resolved) {
     const parsed = parseGitSource(resolved.source);
-    await mkdir2(resolve5(resolved.resolvedPath, ".."), { recursive: true });
+    await mkdir3(resolve5(resolved.resolvedPath, ".."), { recursive: true });
     if (!await pathExists(join7(resolved.resolvedPath, ".git"))) {
       await rm3(resolved.resolvedPath, { recursive: true, force: true });
       await git(["clone", "--no-tags", parsed.url, resolved.resolvedPath]);
@@ -1132,14 +1250,14 @@ async function git(args) {
 }
 
 // src/source/skillkit.ts
-import { cp, mkdir as mkdir3, readFile as readFile6, rm as rm4 } from "fs/promises";
+import { cp, mkdir as mkdir4, readFile as readFile7, rm as rm4 } from "fs/promises";
 import { homedir as homedir2 } from "os";
-import { basename as basename4, dirname as dirname3, join as join9, resolve as resolve6 } from "path";
+import { basename as basename4, dirname as dirname4, join as join9, resolve as resolve6 } from "path";
 import * as defaultSkillKit from "@skillkit/core";
 
 // src/source/skill-artifacts.ts
 import { readdir as readdir2, stat as stat3 } from "fs/promises";
-import { basename as basename3, dirname as dirname2, extname as extname2, join as join8 } from "path";
+import { basename as basename3, dirname as dirname3, extname as extname2, join as join8 } from "path";
 async function artifactsFromSkillPaths(paths, packageName) {
   const artifacts = [];
   const seen = /* @__PURE__ */ new Set();
@@ -1176,7 +1294,7 @@ async function artifactFromSkillPath(item, packageName) {
     };
   }
   if (stats.isFile() && basename3(item.path).toLowerCase() === "skill.md") {
-    const dir = dirname2(item.path);
+    const dir = dirname3(item.path);
     const name = sanitizeSkillName(item.name ?? basename3(dir));
     return {
       type: "skills",
@@ -1259,7 +1377,7 @@ var SkillKitSourceDriver = class {
     if (!provider?.clone) {
       throw new Error("SkillKit provider API unavailable or cannot resolve source. Expected @skillkit/core detectProvider().clone().");
     }
-    await mkdir3(dirname3(resolved.resolvedPath), { recursive: true });
+    await mkdir4(dirname4(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"}`);
@@ -1305,7 +1423,7 @@ var SkillKitSourceDriver = class {
     for (const skill of this.discover(resolved.resolvedPath)) {
       const skillMd = join9(skill.path, "SKILL.md");
       if (await pathExists(skillMd)) {
-        this.core.translateSkill(await readFile6(skillMd, "utf8"), "openclaw", { sourceFilename: "SKILL.md" });
+        this.core.translateSkill(await readFile7(skillMd, "utf8"), "openclaw", { sourceFilename: "SKILL.md" });
       }
     }
     return resolved;
@@ -1473,13 +1591,13 @@ function getSourceDriver(name = "local") {
 }
 
 // src/staging/staging.ts
-import { chmod, cp as cp3, mkdir as mkdir5, mkdtemp, readdir as readdir4, stat as stat6 } from "fs/promises";
-import { basename as basename7, dirname as dirname5, join as join12, relative as relative2, resolve as resolve8, sep } from "path";
+import { chmod, cp as cp3, mkdir as mkdir6, mkdtemp, readdir as readdir4, stat as stat6 } from "fs/promises";
+import { basename as basename7, dirname as dirname6, join as join12, relative as relative2, resolve as resolve8, sep } from "path";
 import { tmpdir as tmpdir2 } from "os";
 
 // src/staging/customize.ts
-import { cp as cp2, mkdir as mkdir4, readdir as readdir3, readFile as readFile7, writeFile as writeFile3 } from "fs/promises";
-import { dirname as dirname4, join as join11 } from "path";
+import { cp as cp2, mkdir as mkdir5, readdir as readdir3, readFile as readFile8, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname5, join as join11 } from "path";
 async function applyCustomizations(artifacts, options) {
   let next = [...artifacts];
   next = await applyReplacements(next, options, "override");
@@ -1494,11 +1612,11 @@ async function applyInstructionOverlay(artifacts, options) {
   const index = artifacts.findIndex((artifact2) => artifact2.type === "instructions");
   if (index < 0) return artifacts;
   const artifact = artifacts[index];
-  const managed = await readFile7(artifact.stagedPath ?? artifact.sourcePath, "utf8");
-  const local = await readFile7(overlayPath, "utf8");
+  const managed = await readFile8(artifact.stagedPath ?? artifact.sourcePath, "utf8");
+  const local = await readFile8(overlayPath, "utf8");
   const composedPath = join11(options.stageRoot, ".agentwheel-composed", "instructions", "AGENTS.md");
-  await mkdir4(dirname4(composedPath), { recursive: true });
-  await writeFile3(
+  await mkdir5(dirname5(composedPath), { recursive: true });
+  await writeFile4(
     composedPath,
     [
       "<!-- BEGIN agentwheel managed: upstream -->",
@@ -1559,7 +1677,7 @@ async function applyReplacements(artifacts, options, channel) {
       const kind = entry.isDirectory() ? "dir" : "file";
       const existing = byKey.get(`${type}:${entry.name}`);
       const stagedPath = join11(options.stageRoot, ".agentwheel-composed", channel, type, entry.name);
-      await mkdir4(dirname4(stagedPath), { recursive: true });
+      await mkdir5(dirname5(stagedPath), { recursive: true });
       await cp2(full, stagedPath, { recursive: kind === "dir", dereference: true });
       byKey.set(`${type}:${entry.name}`, {
         type,
@@ -1583,6 +1701,46 @@ async function sortedDirEntries2(path) {
   return (await readdir3(path, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
 }
 
+// src/model/selection.ts
+function artifactSelectorKey(artifact) {
+  return `${artifact.type}/${artifact.name}`;
+}
+function normalizeArtifactSelectors(select, legacySkills) {
+  const selected = [
+    ...select ?? [],
+    ...(legacySkills ?? []).map((name) => `skills/${name}`)
+  ].flatMap(splitSelectorList);
+  if (selected.length === 0) return void 0;
+  return [...new Set(selected.map(parseArtifactSelector))];
+}
+function filterArtifactsBySelection(artifacts, selectors, legacySkills) {
+  const selected = normalizeArtifactSelectors(selectors, legacySkills);
+  if (!selected?.length) return artifacts;
+  const selectedSet = new Set(selected);
+  const available = new Set(artifacts.map(artifactSelectorKey));
+  const missing = selected.filter((selector) => !available.has(selector));
+  if (missing.length > 0) {
+    throw new Error(`Selected artifact not found in package: ${missing.join(", ")}`);
+  }
+  return artifacts.filter((artifact) => artifact.required || selectedSet.has(artifactSelectorKey(artifact)));
+}
+function splitSelectorList(value) {
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function parseArtifactSelector(value) {
+  const slash = value.indexOf("/");
+  if (slash <= 0 || slash === value.length - 1) {
+    throw new Error(`Invalid artifact selector: ${value}. Expected <type>/<name>.`);
+  }
+  const type = value.slice(0, slash);
+  const name = value.slice(slash + 1);
+  const parsedType = artifactTypeSchema.safeParse(type);
+  if (!parsedType.success) {
+    throw new Error(`Invalid artifact selector type: ${type}`);
+  }
+  return `${parsedType.data}/${name}`;
+}
+
 // src/staging/staging.ts
 async function stageSource(driver, source, options = {}) {
   const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(source, options))));
@@ -1591,7 +1749,7 @@ async function stageSource(driver, source, options = {}) {
   const stagedArtifacts = [];
   for (const artifact of artifacts) {
     const stagedPath = join12(root, artifact.relativePath);
-    await mkdir5(dirname5(stagedPath), { recursive: true });
+    await mkdir6(dirname6(stagedPath), { recursive: true });
     await cp3(artifact.sourcePath, stagedPath, { recursive: artifact.kind === "dir", dereference: true });
     await composeAssets(artifact, resolved.resolvedPath, stagedPath);
     stagedArtifacts.push({
@@ -1601,12 +1759,13 @@ async function stageSource(driver, source, options = {}) {
       channel: artifact.channel ?? "managed"
     });
   }
-  const finalArtifacts = options.workspaceRoot && options.adapter ? await applyCustomizations(stagedArtifacts, {
+  const selectedArtifacts = filterArtifactsBySelection(stagedArtifacts, options.select, options.skills);
+  const finalArtifacts = options.workspaceRoot && options.adapter ? await applyCustomizations(selectedArtifacts, {
     workspaceRoot: options.workspaceRoot,
     adapter: options.adapter,
     stageRoot: root,
     packageName: resolved.packageName
-  }) : stagedArtifacts;
+  }) : selectedArtifacts;
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
   return {
     root,
@@ -1649,7 +1808,7 @@ async function copyAsset(asset, source, dest) {
   const sourceStats = await stat6(source);
   if (sourceStats.isFile()) {
     if (matchesAny(basename7(source), asset.include)) {
-      await mkdir5(dest, { recursive: true });
+      await mkdir6(dest, { recursive: true });
       await copyAssetFile(source, join12(dest, basename7(source)), asset);
     }
     return;
@@ -1658,7 +1817,7 @@ async function copyAsset(asset, source, dest) {
     throw new Error(`Asset include source is not a file or directory: ${source}`);
   }
   if (!asset.include?.length) {
-    await mkdir5(dirname5(dest), { recursive: true });
+    await mkdir6(dirname6(dest), { recursive: true });
     await cp3(source, dest, { recursive: true, dereference: true });
     if (asset.mode === "copy") await normalizeCopiedModes(dest);
     return;
@@ -1670,7 +1829,7 @@ async function copyAsset(asset, source, dest) {
   }
 }
 async function copyAssetFile(source, dest, asset) {
-  await mkdir5(dirname5(dest), { recursive: true });
+  await mkdir6(dirname6(dest), { recursive: true });
   await cp3(source, dest, { dereference: true });
   if (asset.mode === "copy") await chmod(dest, 420);
 }
@@ -1718,9 +1877,9 @@ function matchesGlob(path, pattern) {
 }
 
 // src/model/workspace.ts
-import { readFile as readFile8 } from "fs/promises";
+import { readFile as readFile9 } from "fs/promises";
 import { homedir as homedir3 } from "os";
-import { dirname as dirname6, join as join13, resolve as resolve9 } from "path";
+import { dirname as dirname7, join as join13, resolve as resolve9 } from "path";
 import { z as z5 } from "zod";
 var workspacePackageSchema = z5.object({
   name: z5.string().min(1),
@@ -1731,7 +1890,9 @@ var workspacePackageSchema = z5.object({
   adapterModule: z5.string().min(1).optional(),
   adapterCodeHash: z5.string().min(16).optional(),
   mode: z5.enum(["pinned", "tracking"]).default("pinned"),
-  requestedRef: z5.string().min(1).optional()
+  requestedRef: z5.string().min(1).optional(),
+  select: z5.array(z5.string().min(1)).optional(),
+  skills: z5.array(z5.string().min(1)).optional()
 });
 var workspaceProfileRuntimeSchema = z5.object({
   agent: z5.string().min(1).optional(),
@@ -1765,7 +1926,7 @@ function workspaceConfigPath(workspaceRoot) {
 async function readWorkspaceConfig(workspaceRoot) {
   const path = workspaceConfigPath(workspaceRoot);
   if (!await pathExists(path)) return emptyWorkspaceConfig();
-  return workspaceConfigSchema.parse(JSON.parse(await readFile8(path, "utf8")));
+  return workspaceConfigSchema.parse(JSON.parse(await readFile9(path, "utf8")));
 }
 async function writeWorkspaceConfig(workspaceRoot, config) {
   await writeJsonAtomic(workspaceConfigPath(workspaceRoot), workspaceConfigSchema.parse(config));
@@ -1783,7 +1944,7 @@ async function findWorkspaceRoot(start = process.cwd()) {
   let current = resolve9(start);
   while (true) {
     if (await pathExists(workspaceConfigPath(current))) return current;
-    const parent = dirname6(current);
+    const parent = dirname7(current);
     if (parent === current) return resolve9(start);
     current = parent;
   }
@@ -1817,15 +1978,15 @@ function emptyWorkspaceConfig() {
 }
 async function readConfigPath(path) {
   if (!await pathExists(path)) return emptyWorkspaceConfig();
-  return workspaceConfigSchema.parse(JSON.parse(await readFile8(path, "utf8")));
+  return workspaceConfigSchema.parse(JSON.parse(await readFile9(path, "utf8")));
 }
 
 // src/lifecycle/customization.ts
-import { appendFile, cp as cp4, mkdir as mkdir6, rm as rm5 } from "fs/promises";
-import { dirname as dirname7, join as join14 } from "path";
+import { appendFile, cp as cp4, mkdir as mkdir7, rm as rm5 } from "fs/promises";
+import { dirname as dirname8, join as join14 } from "path";
 async function remember(workspaceRoot, runtime, text) {
   const overlayPath = join14(workspaceRoot, ".agentwheel", "overlays", runtime, "instructions.local.md");
-  await mkdir6(dirname7(overlayPath), { recursive: true });
+  await mkdir7(dirname8(overlayPath), { recursive: true });
   await appendFile(overlayPath, `${text.trim()}
 `, "utf8");
   return { overlayPath };
@@ -1850,7 +2011,7 @@ async function ejectArtifact(workspaceRoot, item) {
       throw new Error(`Artifact not found: ${item}`);
     }
     const ejectedPath = join14(workspaceRoot, ".agentwheel", "ejected", ...parsed.packageName.split("/"), parsed.type, parsed.name);
-    await mkdir6(dirname7(ejectedPath), { recursive: true });
+    await mkdir7(dirname8(ejectedPath), { recursive: true });
     await rm5(ejectedPath, { recursive: true, force: true });
     await cp4(artifact.stagedPath ?? artifact.sourcePath, ejectedPath, { recursive: artifact.kind === "dir", dereference: true });
     return { ...parsed, ejectedPath };
@@ -1874,9 +2035,9 @@ import { rm as rm7 } from "fs/promises";
 import { join as join16 } from "path";
 
 // src/registry/client.ts
-import { readFile as readFile9, rm as rm6, stat as stat7 } from "fs/promises";
+import { readFile as readFile10, rm as rm6, stat as stat7 } from "fs/promises";
 import { homedir as homedir4 } from "os";
-import { dirname as dirname8, join as join15, resolve as resolve10 } from "path";
+import { dirname as dirname9, join as join15, resolve as resolve10 } from "path";
 import { fileURLToPath } from "url";
 
 // src/model/registry.ts
@@ -1962,7 +2123,7 @@ var RegistryClient = class {
   }
   async readCache() {
     if (!await pathExists(this.cachePath)) return void 0;
-    return registryCacheSchema.parse(JSON.parse(await readFile9(this.cachePath, "utf8")));
+    return registryCacheSchema.parse(JSON.parse(await readFile10(this.cachePath, "utf8")));
   }
   isExpired(cache, ttlMs) {
     return this.now().getTime() - new Date(cache.fetchedAt).getTime() > ttlMs;
@@ -1981,10 +2142,10 @@ var RegistryClient = class {
     if (await pathExists(filePath)) {
       const fullPath = resolve10(filePath);
       const stats = await stat7(fullPath);
-      return readFile9(stats.isDirectory() ? join15(fullPath, "index.json") : fullPath, "utf8");
+      return readFile10(stats.isDirectory() ? join15(fullPath, "index.json") : fullPath, "utf8");
     }
-    const resolved = await this.git.fetch(await this.git.resolve(source, { cacheRoot: join15(dirname8(this.cachePath), "registry-repos") }));
-    return readFile9(join15(resolved.resolvedPath, "index.json"), "utf8");
+    const resolved = await this.git.fetch(await this.git.resolve(source, { cacheRoot: join15(dirname9(this.cachePath), "registry-repos") }));
+    return readFile10(join15(resolved.resolvedPath, "index.json"), "utf8");
   }
 };
 async function resolvePackageSource(source, workspaceRoot) {
@@ -2040,7 +2201,9 @@ async function syncProfile(options) {
         workspaceRoot: options.workspaceRoot,
         adapter,
         cacheRoot: join16(options.workspaceRoot, ".agentwheel", "cache"),
-        mode: options.mode ?? pkg.mode
+        mode: options.mode ?? pkg.mode,
+        select: options.select ?? pkg.select,
+        skills: options.select ? void 0 : pkg.skills
       });
       try {
         const plan = await createInstallPlan(bundle, adapter, target.targetRoot, await readInstallManifest(target.targetRoot, adapter.name));
@@ -2074,7 +2237,9 @@ async function packageFromSource(source, options) {
     source: resolved.source,
     driver,
     adapter: "openclaw",
-    mode: options.mode ?? "pinned"
+    mode: options.mode ?? "pinned",
+    select: options.select,
+    skills: options.skills
   };
 }
 
@@ -2089,7 +2254,9 @@ async function createSourcePlan(options) {
     workspaceRoot,
     adapter: options.adapter,
     cacheRoot: join17(workspaceRoot, ".agentwheel", "cache"),
-    mode: options.mode
+    mode: options.mode,
+    select: options.select,
+    skills: options.skills
   });
   const manifest = await readInstallManifest(options.targetRoot, options.adapter.name);
   const plan = await createInstallPlan(bundle, options.adapter, options.targetRoot, manifest);
@@ -2114,7 +2281,7 @@ function shouldUpdatePackage(pkg, lock) {
 }
 
 // src/runtime/target.ts
-import { basename as basename8, dirname as dirname9, join as join18, resolve as resolve11 } from "path";
+import { basename as basename8, dirname as dirname10, join as join18, resolve as resolve11 } from "path";
 var runtimeMarkers = [
   { adapter: "openclaw", dirs: [".openclaw", ".clawdbot", ".moltbot"] },
   { adapter: "claude", dirs: [".claude"] },
@@ -2168,7 +2335,7 @@ async function detectRuntimeTarget(cwd = process.cwd(), adapterFilter) {
     if (adapterFilter && marker.adapter !== adapterFilter) continue;
     for (const dir of marker.dirs) {
       if (basename8(root) === dir) {
-        matches.push({ adapter: marker.adapter, targetRoot: dirname9(root) });
+        matches.push({ adapter: marker.adapter, targetRoot: dirname10(root) });
       } else if (await pathExists(join18(root, dir))) {
         matches.push({ adapter: marker.adapter, targetRoot: root });
       }
@@ -2201,9 +2368,86 @@ function dedupeTargets(matches) {
   return [...byKey.values()];
 }
 
+// src/cli/update-check.ts
+import { mkdir as mkdir8, readFile as readFile11, writeFile as writeFile5 } from "fs/promises";
+import { homedir as homedir5 } from "os";
+import { dirname as dirname11, join as join19 } from "path";
+var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
+var DEFAULT_TIMEOUT_MS = 300;
+var REGISTRY_URL = "https://registry.npmjs.org/agentwheel";
+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 ?? join19(homedir5(), ".agentwheel", "update-check.json");
+  try {
+    const cached = await readCache(cachePath);
+    if (cached && now.getTime() - Date.parse(cached.checkedAt) < ttlMs) {
+      warnIfNewer(cached.latest, options.currentVersion, options.stderr);
+      return;
+    }
+    const latest = await fetchLatestVersion(options.fetchImpl ?? fetch, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    if (!latest) return;
+    await writeCache(cachePath, { checkedAt: now.toISOString(), latest });
+    warnIfNewer(latest, options.currentVersion, options.stderr);
+  } catch {
+  }
+}
+function isDisabled(options) {
+  const env = options.env ?? process.env;
+  if (env.AGENTWHEEL_NO_UPDATE_CHECK === "1" || env.AGENTWHEEL_NO_UPDATE_CHECK === "true") return true;
+  if (env.CI) return true;
+  if (options.argv?.includes("--no-update-check")) return true;
+  const isTTY = options.isTTY ?? process.stderr.isTTY === true;
+  return !isTTY;
+}
+async function fetchLatestVersion(fetchImpl, timeoutMs) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(REGISTRY_URL, { signal: controller.signal });
+    if (!response.ok) return void 0;
+    const body = await response.json();
+    return typeof body["dist-tags"]?.latest === "string" ? body["dist-tags"].latest : void 0;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function readCache(path) {
+  try {
+    const parsed = JSON.parse(await readFile11(path, "utf8"));
+    if (typeof parsed.checkedAt !== "string" || typeof parsed.latest !== "string") return void 0;
+    return { checkedAt: parsed.checkedAt, latest: parsed.latest };
+  } catch {
+    return void 0;
+  }
+}
+async function writeCache(path, cache) {
+  await mkdir8(dirname11(path), { recursive: true });
+  await writeFile5(path, `${JSON.stringify(cache, null, 2)}
+`, "utf8");
+}
+function warnIfNewer(latest, current, stderr = process.stderr) {
+  if (compareVersions(latest, current) <= 0) return;
+  stderr.write(`agentwheel ${latest} is available (you have ${current}). Update: npm i -g agentwheel
+`);
+}
+function compareVersions(a, b) {
+  const left = normalizeVersion(a);
+  const right = normalizeVersion(b);
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const diff = (left[index] ?? 0) - (right[index] ?? 0);
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  return 0;
+}
+function normalizeVersion(version) {
+  return version.replace(/^v/, "").split("-", 1)[0].split(".").map((part) => Number.parseInt(part, 10)).map((part) => Number.isFinite(part) ? part : 0);
+}
+
 // src/cli/index.ts
 var program = new Command();
-program.name("agentwheel").description("Multi-runtime agent artifact orchestrator").version("0.5.0");
+program.name("agentwheel").description("Multi-runtime agent artifact orchestrator").version("0.7.0").option("--no-update-check", "disable npm version update check", false);
 program.command("init").argument("[kind]", "workspace or package", "workspace").option("--target-root <path>", "workspace root", process.cwd()).action(async (kind, options) => {
   const root = normalizeTargetRoot(options.targetRoot);
   if (kind === "package") {
@@ -2217,8 +2461,9 @@ program.command("init").argument("[kind]", "workspace or package", "workspace").
   await writeWorkspaceConfig(root, await readWorkspaceConfig(root));
   console.log("Initialized .agentwheel/config.json.");
 });
-program.command("add").argument("<source>", "package source").option("--driver <driver>", "source driver (local, git, skillkit, or vercel-skills)").option("--adapter <adapter>", "built-in adapter", "openclaw").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("--target-root <path>", "workspace root", process.cwd()).option("--mode <mode>", "pinned or tracking", "pinned").option("--name <name>", "package alias").action(async (source, options) => {
+program.command("add").argument("<source>", "package source").option("--driver <driver>", "source driver (local, git, skillkit, or vercel-skills)").option("--adapter <adapter>", "built-in adapter", "openclaw").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("--target-root <path>", "workspace root", process.cwd()).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, []).action(async (source, options) => {
   const targetRoot = normalizeTargetRoot(options.targetRoot);
+  const selectedArtifacts = selectedArtifactsFromOptions(options);
   const resolvedInput = await resolvePackageSource(source, targetRoot);
   const resolvedSource = resolvedInput.source;
   const driverName = options.driver ?? inferSourceDriverName(resolvedSource);
@@ -2234,8 +2479,9 @@ program.command("add").argument("<source>", "package source").option("--driver <
   const bundle = await stageSource(driver, resolvedSource, {
     workspaceRoot: targetRoot,
     adapter,
-    cacheRoot: join19(targetRoot, ".agentwheel", "cache"),
-    mode: options.mode
+    cacheRoot: join20(targetRoot, ".agentwheel", "cache"),
+    mode: options.mode,
+    select: selectedArtifacts
   });
   const name = options.name ?? resolvedInput.registryEntry?.name ?? bundle.source.packageName ?? source;
   const entry = {
@@ -2247,18 +2493,20 @@ program.command("add").argument("<source>", "package source").option("--driver <
     adapterModule: options.adapterModule,
     adapterCodeHash: adapter.programmatic?.hash,
     mode: options.mode,
-    requestedRef: bundle.source.requestedRef
+    requestedRef: bundle.source.requestedRef,
+    select: selectedArtifacts
   };
   await writeWorkspaceConfig(targetRoot, upsertPackage(await readWorkspaceConfig(targetRoot), entry));
   await rm8(bundle.root, { recursive: true, force: true });
   console.log(`Added ${name}.`);
 });
-program.command("list").argument("<source>", "package source").option("--driver <driver>", "source driver").option("--target-root <path>", "workspace root", process.cwd()).action(async (source, options) => {
+program.command("list").argument("<source>", "package source").option("--driver <driver>", "source driver").option("--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 driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
-  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join19(targetRoot, ".agentwheel", "cache") }))));
-  const artifacts = await driver.list(resolved);
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join20(targetRoot, ".agentwheel", "cache") }))));
+  const artifacts = filterArtifactsBySelection(await driver.list(resolved), selectedArtifacts);
   for (const artifact of artifacts) {
     console.log(`${artifact.type}	${artifact.name}	${artifact.relativePath}`);
   }
@@ -2267,7 +2515,7 @@ program.command("scan").argument("<source>", "package source").option("--driver
   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: join19(targetRoot, ".agentwheel", "cache") }))));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join20(targetRoot, ".agentwheel", "cache") }))));
   const result = await driver.scan(resolved);
   if (result.findings.length === 0) {
     console.log("Scan ok: no findings");
@@ -2278,7 +2526,7 @@ program.command("scan").argument("<source>", "package source").option("--driver
   }
   if (!result.ok) process.exitCode = 1;
 });
-program.command("plan").argument("<source>", "source directory").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter", "openclaw").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("--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("--dry-run", "accepted for symmetry; plan never writes", false).action(async (source, options) => {
+program.command("plan").argument("<source>", "source directory").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter", "openclaw").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("--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("--dry-run", "accepted for symmetry; plan never writes", false).action(async (source, options) => {
   const targets = await resolveCliTargets(options);
   for (const target of targets) {
     const { plan, bundle } = await buildPlan(source, target, options);
@@ -2287,7 +2535,7 @@ program.command("plan").argument("<source>", "source directory").option("--drive
     if (plan.hasBlockingChanges) process.exitCode = 1;
   }
 });
-program.command("sync").argument("[source]", "source directory").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter", "openclaw").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("--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("--profile <name>", "workspace runtime profile").option("--dry-run", "show plan without writing", false).option("--execute-plugins", "execute semantic plugin installs", false).action(async (source, options) => {
+program.command("sync").argument("[source]", "source directory").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter", "openclaw").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("--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("--profile <name>", "workspace runtime profile").option("--dry-run", "show plan without writing", false).option("--execute-plugins", "execute semantic plugin installs", false).action(async (source, options) => {
   if (options.profile) {
     const target = await resolveRuntimeTarget({ targetRoot: options.targetRoot, adapter: options.adapter, agent: options.agent });
     const results = await syncProfile({
@@ -2296,6 +2544,7 @@ program.command("sync").argument("[source]", "source directory").option("--drive
       source,
       driver: options.driver,
       mode: options.mode,
+      select: selectedArtifactsFromOptions(options),
       dryRun: options.dryRun,
       executePlugins: options.executePlugins,
       allowAdapterCode: options.allowAdapterCode,
@@ -2327,7 +2576,7 @@ program.command("sync").argument("[source]", "source directory").option("--drive
     if (plan.hasBlockingChanges) process.exitCode = 1;
   }
 });
-program.command("update").option("--adapter <adapter>", "built-in adapter").option("--target-root <path>", "workspace root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--dry-run", "show plans without writing", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--allow-adapter-code", "allow loading local adapter code from configured packages", false).action(async (options) => {
+program.command("update").option("--adapter <adapter>", "built-in adapter").option("--target-root <path>", "workspace root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--dry-run", "show plans without writing", 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, []).action(async (options) => {
   const targets = await resolveCliTargets(options);
   for (const target of targets) {
     await runConfiguredPackages(target, options, { useUpdateDecision: true });
@@ -2360,7 +2609,7 @@ program.command("eject").argument("<item>", "package/type/name").option("--targe
   const result = await ejectArtifact(targetRoot, item);
   console.log(`Ejected ${item} to ${result.ejectedPath}.`);
 });
-program.command("uninstall").option("--adapter <adapter>", "adapter", "openclaw").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("--target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--dry-run", "show removals without writing", false).option("--force", "remove drifted managed files too", false).action(async (options) => {
+program.command("uninstall").option("--adapter <adapter>", "adapter", "openclaw").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("--target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--dry-run", "show removals without writing", false).option("--force", "remove drifted managed files too", false).option("--select <type/name>", "uninstall only selected artifact type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "uninstall only selected skill name (repeatable or comma-separated)", collectSkillOption, []).action(async (options) => {
   const targets = await resolveCliTargets(options);
   for (const target of targets) {
     const adapter = await resolveAdapterForTarget(target, options);
@@ -2369,7 +2618,7 @@ program.command("uninstall").option("--adapter <adapter>", "adapter", "openclaw"
       console.log(`No install manifest for ${adapter.name} at ${target.targetRoot}`);
       continue;
     }
-    const plan = await createUninstallPlan(manifest);
+    const plan = filterUninstallPlanBySelection(await createUninstallPlan(manifest), selectedArtifactsFromOptions(options));
     console.log(formatPlan(plan));
     const result = await uninstall(plan, { dryRun: options.dryRun, force: options.force });
     if (!options.dryRun) {
@@ -2387,7 +2636,8 @@ async function buildPlan(source, target, options) {
     workspaceRoot: target.workspaceRoot,
     adapter,
     driver: options.driver,
-    mode: options.mode
+    mode: options.mode,
+    select: selectedArtifactsFromOptions(options)
   });
   return { plan: result.plan, bundle: result.bundle };
 }
@@ -2413,6 +2663,7 @@ async function runConfiguredPackages(target, options, behavior) {
     console.log(`No packages configured at ${target.workspaceRoot}.`);
     return;
   }
+  const selectedArtifacts = selectedArtifactsFromOptions(options);
   for (const pkg of config.packages) {
     const targetForPackage = options.adapter || target.source !== "cwd" ? target : { ...target, adapter: pkg.adapter };
     const adapter = await resolveAdapterForTarget(targetForPackage, {
@@ -2433,7 +2684,9 @@ async function runConfiguredPackages(target, options, behavior) {
       adapterConfig: options.adapterConfig ?? pkg.adapterConfig,
       adapterModule: options.adapterModule ?? pkg.adapterModule,
       allowAdapterCode: options.allowAdapterCode,
-      mode: pkg.mode
+      mode: pkg.mode,
+      select: selectedArtifacts ?? pkg.select,
+      skills: selectedArtifacts ? void 0 : pkg.skills
     });
     console.log(`${behavior.useUpdateDecision ? "Update" : "Sync"} ${pkg.name} (${adapter.name} at ${targetForPackage.targetRoot}):`);
     console.log(formatPlan(plan));
@@ -2445,11 +2698,44 @@ async function runConfiguredPackages(target, options, behavior) {
     if (plan.hasBlockingChanges) process.exitCode = 1;
   }
 }
+function collectSelectOption(value, previous) {
+  return [...previous, ...splitSelectorList(value)];
+}
+function collectSkillOption(value, previous) {
+  return [...previous, ...splitSelectorList(value)];
+}
+function selectedArtifactsFromOptions(options) {
+  return normalizeArtifactSelectors(options.select, options.skills ?? options.skill);
+}
+function filterUninstallPlanBySelection(plan, selected) {
+  if (!selected?.length) return plan;
+  const requested = normalizeArtifactSelectors(selected) ?? [];
+  const available = new Set(plan.operations.map((operation) => `${operation.artifactType}/${operation.artifactName}`));
+  const missing = requested.filter((selector) => !available.has(selector));
+  if (missing.length > 0) {
+    throw new Error(`Selected artifact not found in install manifest: ${missing.join(", ")}`);
+  }
+  const selectedSet = new Set(requested);
+  const operations = plan.operations.map((operation) => {
+    if (selectedSet.has(`${operation.artifactType}/${operation.artifactName}`)) return operation;
+    return {
+      ...operation,
+      action: "skip",
+      desiredHash: operation.desiredHash ?? operation.manifestHash,
+      reason: "not selected for uninstall"
+    };
+  });
+  return {
+    ...plan,
+    operations,
+    hasBlockingChanges: operations.some((operation) => operation.action === "conflict")
+  };
+}
 async function initPackage(root) {
-  await mkdir7(join19(root, "instructions"), { recursive: true });
-  await mkdir7(join19(root, "rules"), { recursive: true });
-  await mkdir7(join19(root, "skills"), { recursive: true });
-  const manifestPath = join19(root, "agentwheel.json");
+  await mkdir9(join20(root, "instructions"), { recursive: true });
+  await mkdir9(join20(root, "rules"), { recursive: true });
+  await mkdir9(join20(root, "skills"), { recursive: true });
+  const manifestPath = join20(root, "agentwheel.json");
   const manifest = {
     schemaVersion: 1,
     name: "example/agentwheel-package",
@@ -2460,9 +2746,9 @@ async function initPackage(root) {
       { type: "skills", path: "skills" }
     ]
   };
-  await writeFile4(manifestPath, `${JSON.stringify(manifest, null, 2)}
+  await writeFile6(manifestPath, `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
-  await writeFile4(join19(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
+  await writeFile6(join20(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
 }
 function formatUninstallResult(result) {
   const removedLabel = result.removed === 1 ? "managed file" : "managed files";
@@ -2480,7 +2766,16 @@ function printRegistryEntries(entries) {
     console.log(`${entry.name}	${entry.type}	${entry.source}	${entry.description}${tags}`);
   }
 }
-program.parseAsync().catch((error) => {
+async function main() {
+  await maybeCheckForUpdate({
+    currentVersion: "0.7.0",
+    argv: process.argv,
+    env: process.env,
+    isTTY: process.stderr.isTTY === true
+  });
+  await program.parseAsync();
+}
+main().catch((error) => {
   console.error(error instanceof Error ? error.message : String(error));
   process.exitCode = 1;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Weave skills, rules, and instructions across every AI agent.",
   "type": "module",
   "license": "MIT",