agentwheel 0.5.0 → 0.6.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.6).** 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, rich JSON 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:
 
@@ -244,6 +271,7 @@ 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.
 
 ## 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 mkdir8, rm as rm8, writeFile as writeFile5 } 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
@@ -476,6 +477,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 +485,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 +494,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,
@@ -746,11 +749,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
       });
     }
   }
@@ -812,7 +818,8 @@ 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),
@@ -981,7 +988,7 @@ 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;
     }
@@ -989,16 +996,16 @@ async function listFromManifest(root, packageName) {
       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));
+          artifacts.push(await artifactForDir(provide.type, entry.name, child, join6(provide.path, entry.name), packageName, provide.assets, provide.required));
         } else if (provide.type === "plugins" && entry.isDirectory()) {
-          artifacts.push(await artifactForDir(provide.type, entry.name, child, join6(provide.path, entry.name), packageName, provide.assets));
+          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 +1022,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 +1032,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 +1046,8 @@ async function artifactForDir(type, name, sourcePath, relativePath, packageName,
     hash: await hashPath(sourcePath),
     packageName,
     channel: "managed",
-    assets
+    assets,
+    required
   };
 }
 
@@ -1583,6 +1592,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))));
@@ -1601,12 +1650,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,
@@ -1731,7 +1781,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(),
@@ -2040,7 +2092,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 +2128,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 +2145,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);
@@ -2201,9 +2259,86 @@ function dedupeTargets(matches) {
   return [...byKey.values()];
 }
 
+// src/cli/update-check.ts
+import { mkdir as mkdir7, readFile as readFile10, writeFile as writeFile4 } from "fs/promises";
+import { homedir as homedir5 } from "os";
+import { dirname as dirname10, 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 readFile10(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 mkdir7(dirname10(path), { recursive: true });
+  await writeFile4(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.6.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 +2352,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 +2370,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 +2384,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 +2406,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 +2417,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 +2426,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 +2435,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 +2467,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 +2500,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 +2509,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 +2527,9 @@ async function buildPlan(source, target, options) {
     workspaceRoot: target.workspaceRoot,
     adapter,
     driver: options.driver,
-    mode: options.mode
+    mode: options.mode,
+    select: options.select ?? selectedArtifactsFromOptions(options),
+    skills: options.skills
   });
   return { plan: result.plan, bundle: result.bundle };
 }
@@ -2413,6 +2555,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 +2576,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 +2590,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 mkdir8(join20(root, "instructions"), { recursive: true });
+  await mkdir8(join20(root, "rules"), { recursive: true });
+  await mkdir8(join20(root, "skills"), { recursive: true });
+  const manifestPath = join20(root, "agentwheel.json");
   const manifest = {
     schemaVersion: 1,
     name: "example/agentwheel-package",
@@ -2460,9 +2638,9 @@ async function initPackage(root) {
       { type: "skills", path: "skills" }
     ]
   };
-  await writeFile4(manifestPath, `${JSON.stringify(manifest, null, 2)}
+  await writeFile5(manifestPath, `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
-  await writeFile4(join19(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
+  await writeFile5(join20(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
 }
 function formatUninstallResult(result) {
   const removedLabel = result.removed === 1 ? "managed file" : "managed files";
@@ -2480,7 +2658,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.6.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.6.0",
   "description": "Weave skills, rules, and instructions across every AI agent.",
   "type": "module",
   "license": "MIT",