agentwheel 0.4.1 → 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.4).** 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, 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,50 @@ 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:
+
+```jsonc
+{
+  "type": "skills",
+  "path": "skills",
+  "assets": [
+    {
+      "from": "packages/tmux-bridge/bin",
+      "into": "bin",
+      "include": ["*.sh"],
+      "mode": "preserve"
+    }
+  ]
+}
+```
+
+`mode: "preserve"` keeps executable bits on copied scripts. The composed files are included in
+the skill directory hash, so idempotency and drift detection work as if the assets had always
+belonged to the skill.
+
 Publish by pushing to any git host. A registry exists only for short names and discovery — it's
 optional, and `agentwheel add <url|path>` always works without it.
 
@@ -221,6 +270,8 @@ clear conversion format.
 - [x] **v0.2** — git source driver; `update` (pinned & tracking); overlays/additive/override/eject; `init`; hermes + copilot adapters; commands/mcp/hooks artifacts; OpenClaw semantic plugin planning.
 - [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
@@ -34,6 +34,12 @@ var artifactTypeSchema = z.enum([
   "plugins"
 ]);
 var fileKindSchema = z.enum(["file", "dir"]);
+var packageAssetSchema = z.object({
+  from: z.string().min(1),
+  into: z.string().min(1),
+  include: z.array(z.string().min(1)).optional(),
+  mode: z.enum(["preserve", "copy"]).default("preserve")
+});
 var artifactSchema = z.object({
   type: artifactTypeSchema,
   name: z.string().min(1),
@@ -43,7 +49,9 @@ var artifactSchema = z.object({
   kind: fileKindSchema,
   hash: z.string().min(16),
   packageName: z.string().min(1).optional(),
-  channel: z.enum(["managed", "overlay", "addition", "override", "ejected"]).default("managed")
+  channel: z.enum(["managed", "overlay", "addition", "override", "ejected"]).default("managed"),
+  assets: z.array(packageAssetSchema).optional(),
+  required: z.boolean().optional()
 });
 
 // src/model/adapter.ts
@@ -469,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) {
@@ -476,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,
@@ -484,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,
@@ -739,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
       });
     }
   }
@@ -804,7 +817,9 @@ import { parse as parse2, printParseErrorCode as printParseErrorCode2 } from "js
 import { z as z4 } from "zod";
 var packageProvideSchema = z4.object({
   type: artifactTypeSchema,
-  path: z4.string().min(1)
+  path: z4.string().min(1),
+  assets: z4.array(packageAssetSchema).optional(),
+  required: z4.boolean().optional()
 });
 var packageManifestSchema = z4.object({
   schemaVersion: z4.literal(1),
@@ -973,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));
+        artifacts.push(await artifactForFile(provide.type, basename(full), full, provide.path, packageName, provide.assets, provide.required));
       }
       continue;
     }
@@ -981,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));
+          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));
+          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));
+          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));
+      artifacts.push(await artifactForFile(provide.type, basename(full), full, provide.path, packageName, provide.assets, provide.required));
     }
   }
   return artifacts;
@@ -1007,7 +1022,7 @@ async function listGenericArtifacts(type, dir, relativeRoot, packageName) {
   }
   return artifacts;
 }
-async function artifactForFile(type, name, sourcePath, relativePath, packageName) {
+async function artifactForFile(type, name, sourcePath, relativePath, packageName, assets, required) {
   return {
     type,
     name,
@@ -1016,10 +1031,12 @@ async function artifactForFile(type, name, sourcePath, relativePath, packageName
     kind: "file",
     hash: await hashPath(sourcePath),
     packageName,
-    channel: "managed"
+    channel: "managed",
+    assets,
+    required
   };
 }
-async function artifactForDir(type, name, sourcePath, relativePath, packageName) {
+async function artifactForDir(type, name, sourcePath, relativePath, packageName, assets, required) {
   return {
     type,
     name,
@@ -1028,7 +1045,9 @@ async function artifactForDir(type, name, sourcePath, relativePath, packageName)
     kind: "dir",
     hash: await hashPath(sourcePath),
     packageName,
-    channel: "managed"
+    channel: "managed",
+    assets,
+    required
   };
 }
 
@@ -1463,8 +1482,8 @@ function getSourceDriver(name = "local") {
 }
 
 // src/staging/staging.ts
-import { cp as cp3, mkdir as mkdir5, mkdtemp } from "fs/promises";
-import { dirname as dirname5, join as join12 } from "path";
+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 { tmpdir as tmpdir2 } from "os";
 
 // src/staging/customize.ts
@@ -1573,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))));
@@ -1583,6 +1642,7 @@ async function stageSource(driver, source, options = {}) {
     const stagedPath = join12(root, artifact.relativePath);
     await mkdir5(dirname5(stagedPath), { recursive: true });
     await cp3(artifact.sourcePath, stagedPath, { recursive: artifact.kind === "dir", dereference: true });
+    await composeAssets(artifact, resolved.resolvedPath, stagedPath);
     stagedArtifacts.push({
       ...artifact,
       stagedPath,
@@ -1590,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,
@@ -1623,11 +1684,93 @@ async function stageSource(driver, source, options = {}) {
     }
   };
 }
+async function composeAssets(artifact, packageRoot, stagedPath) {
+  if (!artifact.assets?.length) return;
+  if (artifact.kind !== "dir") {
+    throw new Error(`Asset includes require a directory artifact: ${artifact.type}/${artifact.name}`);
+  }
+  for (const asset of artifact.assets) {
+    const source = resolvePackagePath(packageRoot, asset.from);
+    const dest = join12(stagedPath, asset.into);
+    await copyAsset(asset, source, dest);
+  }
+}
+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 copyAssetFile(source, join12(dest, basename7(source)), asset);
+    }
+    return;
+  }
+  if (!sourceStats.isDirectory()) {
+    throw new Error(`Asset include source is not a file or directory: ${source}`);
+  }
+  if (!asset.include?.length) {
+    await mkdir5(dirname5(dest), { recursive: true });
+    await cp3(source, dest, { recursive: true, dereference: true });
+    if (asset.mode === "copy") await normalizeCopiedModes(dest);
+    return;
+  }
+  for (const file of await listFiles(source)) {
+    const rel = relative2(source, file).replaceAll("\\", "/");
+    if (!matchesAny(rel, asset.include) && !matchesAny(basename7(file), asset.include)) continue;
+    await copyAssetFile(file, join12(dest, rel), asset);
+  }
+}
+async function copyAssetFile(source, dest, asset) {
+  await mkdir5(dirname5(dest), { recursive: true });
+  await cp3(source, dest, { dereference: true });
+  if (asset.mode === "copy") await chmod(dest, 420);
+}
+function resolvePackagePath(packageRoot, path) {
+  const resolved = resolve8(packageRoot, path);
+  const root = resolve8(packageRoot);
+  if (resolved !== root && !resolved.startsWith(`${root}${sep}`)) {
+    throw new Error(`Asset include escapes package root: ${path}`);
+  }
+  return resolved;
+}
+async function listFiles(root) {
+  const out = [];
+  async function walk2(dir) {
+    for (const entry of (await readdir4(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = join12(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk2(full);
+      } else if (entry.isFile()) {
+        out.push(full);
+      }
+    }
+  }
+  await walk2(root);
+  return out;
+}
+async function normalizeCopiedModes(path) {
+  const stats = await stat6(path);
+  if (stats.isFile()) {
+    await chmod(path, 420);
+    return;
+  }
+  if (!stats.isDirectory()) return;
+  for (const entry of await readdir4(path, { withFileTypes: true })) {
+    await normalizeCopiedModes(join12(path, entry.name));
+  }
+}
+function matchesAny(path, patterns) {
+  if (!patterns?.length) return true;
+  return patterns.some((pattern) => matchesGlob(path, pattern));
+}
+function matchesGlob(path, pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp(`^${escaped}$`).test(path);
+}
 
 // src/model/workspace.ts
 import { readFile as readFile8 } from "fs/promises";
 import { homedir as homedir3 } from "os";
-import { dirname as dirname6, join as join13, resolve as resolve8 } from "path";
+import { dirname as dirname6, join as join13, resolve as resolve9 } from "path";
 import { z as z5 } from "zod";
 var workspacePackageSchema = z5.object({
   name: z5.string().min(1),
@@ -1638,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(),
@@ -1687,11 +1832,11 @@ function globalWorkspaceConfigPath(globalRoot = homedir3()) {
   return join13(globalRoot, ".agentwheel", "config.json");
 }
 async function findWorkspaceRoot(start = process.cwd()) {
-  let current = resolve8(start);
+  let current = resolve9(start);
   while (true) {
     if (await pathExists(workspaceConfigPath(current))) return current;
     const parent = dirname6(current);
-    if (parent === current) return resolve8(start);
+    if (parent === current) return resolve9(start);
     current = parent;
   }
 }
@@ -1715,9 +1860,9 @@ function mergeWorkspaceConfig(global, project) {
   });
 }
 function resolveConfigPath(path, baseRoot) {
-  if (path.startsWith("~/")) return resolve8(homedir3(), path.slice(2));
+  if (path.startsWith("~/")) return resolve9(homedir3(), path.slice(2));
   if (path === "~") return homedir3();
-  return path.startsWith("/") ? resolve8(path) : resolve8(baseRoot, path);
+  return path.startsWith("/") ? resolve9(path) : resolve9(baseRoot, path);
 }
 function emptyWorkspaceConfig() {
   return { schemaVersion: 1, packages: [], registry: {}, profiles: {}, agents: {} };
@@ -1781,9 +1926,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 stat6 } from "fs/promises";
+import { readFile as readFile9, rm as rm6, stat as stat7 } from "fs/promises";
 import { homedir as homedir4 } from "os";
-import { dirname as dirname8, join as join15, resolve as resolve9 } from "path";
+import { dirname as dirname8, join as join15, resolve as resolve10 } from "path";
 import { fileURLToPath } from "url";
 
 // src/model/registry.ts
@@ -1886,8 +2031,8 @@ var RegistryClient = class {
     }
     const filePath = source.startsWith("file:") ? fileURLToPath(source) : source;
     if (await pathExists(filePath)) {
-      const fullPath = resolve9(filePath);
-      const stats = await stat6(fullPath);
+      const fullPath = resolve10(filePath);
+      const stats = await stat7(fullPath);
       return readFile9(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") }));
@@ -1947,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));
@@ -1981,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
   };
 }
 
@@ -1996,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);
@@ -2021,7 +2172,7 @@ function shouldUpdatePackage(pkg, lock) {
 }
 
 // src/runtime/target.ts
-import { basename as basename7, dirname as dirname9, join as join18, resolve as resolve10 } from "path";
+import { basename as basename8, dirname as dirname9, join as join18, resolve as resolve11 } from "path";
 var runtimeMarkers = [
   { adapter: "openclaw", dirs: [".openclaw", ".clawdbot", ".moltbot"] },
   { adapter: "claude", dirs: [".claude"] },
@@ -2030,9 +2181,9 @@ var runtimeMarkers = [
   { adapter: "copilot", dirs: [".github"] }
 ];
 async function resolveRuntimeTarget(request = {}) {
-  const cwd = resolve10(request.cwd ?? process.cwd());
+  const cwd = resolve11(request.cwd ?? process.cwd());
   if (request.targetRoot) {
-    const targetRoot = resolve10(request.targetRoot);
+    const targetRoot = resolve11(request.targetRoot);
     return {
       adapter: request.adapter ?? "openclaw",
       targetRoot,
@@ -2059,7 +2210,7 @@ async function resolveRuntimeTarget(request = {}) {
 async function resolveAllRuntimeTargets(request = {}) {
   if (request.targetRoot) return [await resolveRuntimeTarget(request)];
   if (request.agent) return [await resolveRuntimeTarget(request)];
-  const cwd = resolve10(request.cwd ?? process.cwd());
+  const cwd = resolve11(request.cwd ?? process.cwd());
   const workspaceRoot = await findWorkspaceRoot(cwd);
   const config = await readMergedWorkspaceConfig(workspaceRoot, { globalRoot: request.globalRoot });
   const targets = Object.entries(config.agents).map(([name]) => targetFromAgent(name, config, workspaceRoot));
@@ -2069,12 +2220,12 @@ async function resolveAllRuntimeTargets(request = {}) {
   return targets;
 }
 async function detectRuntimeTarget(cwd = process.cwd(), adapterFilter) {
-  const root = resolve10(cwd);
+  const root = resolve11(cwd);
   const matches = [];
   for (const marker of runtimeMarkers) {
     if (adapterFilter && marker.adapter !== adapterFilter) continue;
     for (const dir of marker.dirs) {
-      if (basename7(root) === dir) {
+      if (basename8(root) === dir) {
         matches.push({ adapter: marker.adapter, targetRoot: dirname9(root) });
       } else if (await pathExists(join18(root, dir))) {
         matches.push({ adapter: marker.adapter, targetRoot: root });
@@ -2108,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.4.1");
+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") {
@@ -2124,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);
@@ -2141,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 = {
@@ -2154,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}`);
   }
@@ -2174,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");
@@ -2185,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);
@@ -2194,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({
@@ -2203,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,
@@ -2234,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 });
@@ -2267,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);
@@ -2276,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) {
@@ -2294,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 };
 }
@@ -2320,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, {
@@ -2340,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));
@@ -2352,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",
@@ -2367,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";
@@ -2387,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.4.1",
+  "version": "0.6.0",
   "description": "Weave skills, rules, and instructions across every AI agent.",
   "type": "module",
   "license": "MIT",