agentwheel 0.3.1 → 0.4.0

package/README.md

@@ -24,17 +24,19 @@ So you copy-paste. You forget which agent has the latest version. You tweak a ru
 ```bash
 npm i -g agentwheel
 agentwheel add github:your-org/agent-pack
-agentwheel update --dry-run  # show me what would change
-agentwheel update            # install into configured agents
+cd ~/.openclaw
+agentwheel sync --dry-run    # show me what would change
+agentwheel sync              # install into the detected runtime
 ```
 
 No lock-in. No central gatekeeper. Your packages live in plain git repos, your customizations live in your own repo, and anything reachable by a URL just works.
 
 ---
 
-> **Status: early (v0.3).** The lifecycle core is real and tested — local/git/skillkit/vercel
+> **Status: early (v0.4).** The lifecycle core is real and tested — local/git/skillkit/vercel
 > sources, optional registry discovery, plan/sync/update/drift/uninstall, overlays, eject/remember,
-> profiles, rich JSON merge, and pluggable adapters. Expect sharp edges.
+> profiles, runtime auto-detection, fleet targeting, rich JSON merge, and pluggable adapters.
+> Expect sharp edges.
 
 ## What it does
 
@@ -51,8 +53,9 @@ npm i -g agentwheel
 
 agentwheel init
 agentwheel add github:your-org/agent-pack --adapter openclaw --mode tracking
-agentwheel update --dry-run
-agentwheel update
+cd ~/.openclaw
+agentwheel sync --dry-run
+agentwheel sync
 ```
 
 Prefer pnpm? `pnpm add -g agentwheel` works too.
@@ -69,6 +72,48 @@ pnpm link --global
 
 `plan`, `sync --dry-run`, and `update --dry-run` show exactly what would change before anything is written. They're the commands to trust.
 
+## Runtime targeting
+
+Normal use no longer needs `--target-root`. Run agentwheel inside a runtime folder and it detects
+the target:
+
+```bash
+cd ~/.openclaw
+agentwheel sync github:your-org/agent-pack
+```
+
+If the current directory is already the runtime directory (`~/.openclaw`), agentwheel uses its
+parent as the root so output lands in `~/.openclaw/skills`, not `~/.openclaw/.openclaw/skills`.
+If the current directory contains a runtime directory (`./.openclaw`), that directory is used as
+the target under the current project.
+
+For a control-plane setup, define named agents in config. Global config lives at
+`~/.agentwheel/config.json`; project config lives at `.agentwheel/config.json`; project values win.
+
+```jsonc
+{
+  "agents": {
+    "lab-openclaw": { "adapter": "openclaw", "root": "/Users/me/.openclaw-home" },
+    "docs-copilot": { "adapter": "copilot", "root": "/Users/me/projects/docs" }
+  },
+  "profiles": {
+    "daily": [
+      { "agent": "lab-openclaw" },
+      { "agent": "docs-copilot" }
+    ]
+  }
+}
+```
+
+```bash
+agentwheel sync --agent lab-openclaw
+agentwheel sync --all
+agentwheel sync --profile daily
+```
+
+Target resolution order is exact: `--target-root` wins, then `--agent`, then auto-detect from the
+current directory, then fallback to the current directory.
+
 ## Core ideas
 
 **Three places, one direction:**
@@ -172,6 +217,7 @@ clear conversion format.
 - [x] **v0.1** — install spine: local sources; openclaw/claude/codex adapters; skills/rules/instructions; `plan` · `sync` · `--dry-run` · `uninstall`; manifest + drift + idempotency.
 - [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`.
 
 ## Design docs
 

package/dist/index.js

@@ -9,7 +9,7 @@ import {
 
 // src/cli/index.ts
 import { mkdir as mkdir7, rm as rm8, writeFile as writeFile4 } from "fs/promises";
-import { join as join18 } from "path";
+import { join as join19 } from "path";
 import { Command } from "commander";
 
 // src/adapters/resolve.ts
@@ -1584,7 +1584,8 @@ async function stageSource(driver, source, options = {}) {
 
 // src/model/workspace.ts
 import { readFile as readFile8 } from "fs/promises";
-import { join as join13 } from "path";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname6, join as join13, resolve as resolve8 } from "path";
 import { z as z5 } from "zod";
 var workspacePackageSchema = z5.object({
   name: z5.string().min(1),
@@ -1598,6 +1599,7 @@ var workspacePackageSchema = z5.object({
   requestedRef: z5.string().min(1).optional()
 });
 var workspaceProfileRuntimeSchema = z5.object({
+  agent: z5.string().min(1).optional(),
   adapter: z5.string().min(1).default("openclaw"),
   adapterConfig: z5.string().min(1).optional(),
   adapterModule: z5.string().min(1).optional(),
@@ -1611,18 +1613,23 @@ var workspaceRegistrySchema = z5.object({
   sources: z5.array(z5.string().min(1)).optional(),
   ttlSeconds: z5.number().int().positive().optional()
 }).default({});
+var workspaceAgentSchema = z5.object({
+  adapter: z5.string().min(1),
+  root: z5.string().min(1)
+});
 var workspaceConfigSchema = z5.object({
   schemaVersion: z5.literal(1),
   packages: z5.array(workspacePackageSchema).default([]),
   registry: workspaceRegistrySchema,
-  profiles: z5.record(z5.string(), workspaceProfileSchema).default({})
+  profiles: z5.record(z5.string(), workspaceProfileSchema).default({}),
+  agents: z5.record(z5.string(), workspaceAgentSchema).default({})
 });
 function workspaceConfigPath(workspaceRoot) {
   return join13(workspaceRoot, ".agentwheel", "config.json");
 }
 async function readWorkspaceConfig(workspaceRoot) {
   const path = workspaceConfigPath(workspaceRoot);
-  if (!await pathExists(path)) return { schemaVersion: 1, packages: [], registry: {}, profiles: {} };
+  if (!await pathExists(path)) return emptyWorkspaceConfig();
   return workspaceConfigSchema.parse(JSON.parse(await readFile8(path, "utf8")));
 }
 async function writeWorkspaceConfig(workspaceRoot, config) {
@@ -1632,15 +1639,58 @@ function upsertPackage(config, entry) {
   const packages = config.packages.filter((candidate) => candidate.name !== entry.name);
   packages.push(entry);
   packages.sort((a, b) => a.name.localeCompare(b.name));
-  return { schemaVersion: 1, packages, registry: config.registry ?? {}, profiles: config.profiles ?? {} };
+  return { schemaVersion: 1, packages, registry: config.registry ?? {}, profiles: config.profiles ?? {}, agents: config.agents ?? {} };
+}
+function globalWorkspaceConfigPath(globalRoot = homedir3()) {
+  return join13(globalRoot, ".agentwheel", "config.json");
+}
+async function findWorkspaceRoot(start = process.cwd()) {
+  let current = resolve8(start);
+  while (true) {
+    if (await pathExists(workspaceConfigPath(current))) return current;
+    const parent = dirname6(current);
+    if (parent === current) return resolve8(start);
+    current = parent;
+  }
+}
+async function readMergedWorkspaceConfig(projectRoot, options = {}) {
+  const global = await readConfigPath(globalWorkspaceConfigPath(options.globalRoot));
+  const project = await readWorkspaceConfig(projectRoot);
+  return mergeWorkspaceConfig(global, project);
+}
+function mergeWorkspaceConfig(global, project) {
+  return workspaceConfigSchema.parse({
+    schemaVersion: 1,
+    packages: project.packages.length > 0 ? project.packages : global.packages,
+    registry: {
+      ...global.registry,
+      ...project.registry,
+      sources: project.registry.sources ?? global.registry.sources,
+      ttlSeconds: project.registry.ttlSeconds ?? global.registry.ttlSeconds
+    },
+    profiles: { ...global.profiles, ...project.profiles },
+    agents: { ...global.agents, ...project.agents }
+  });
+}
+function resolveConfigPath(path, baseRoot) {
+  if (path.startsWith("~/")) return resolve8(homedir3(), path.slice(2));
+  if (path === "~") return homedir3();
+  return path.startsWith("/") ? resolve8(path) : resolve8(baseRoot, path);
+}
+function emptyWorkspaceConfig() {
+  return { schemaVersion: 1, packages: [], registry: {}, profiles: {}, agents: {} };
+}
+async function readConfigPath(path) {
+  if (!await pathExists(path)) return emptyWorkspaceConfig();
+  return workspaceConfigSchema.parse(JSON.parse(await readFile8(path, "utf8")));
 }
 
 // src/lifecycle/customization.ts
 import { appendFile, cp as cp4, mkdir as mkdir6, rm as rm5 } from "fs/promises";
-import { dirname as dirname6, join as join14 } from "path";
+import { dirname as dirname7, join as join14 } from "path";
 async function remember(workspaceRoot, runtime, text) {
   const overlayPath = join14(workspaceRoot, ".agentwheel", "overlays", runtime, "instructions.local.md");
-  await mkdir6(dirname6(overlayPath), { recursive: true });
+  await mkdir6(dirname7(overlayPath), { recursive: true });
   await appendFile(overlayPath, `${text.trim()}
 `, "utf8");
   return { overlayPath };
@@ -1665,7 +1715,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(dirname6(ejectedPath), { recursive: true });
+    await mkdir6(dirname7(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 };
@@ -1690,8 +1740,8 @@ import { join as join16 } from "path";
 
 // src/registry/client.ts
 import { readFile as readFile9, rm as rm6, stat as stat6 } from "fs/promises";
-import { homedir as homedir3 } from "os";
-import { dirname as dirname7, join as join15, resolve as resolve8 } from "path";
+import { homedir as homedir4 } from "os";
+import { dirname as dirname8, join as join15, resolve as resolve9 } from "path";
 import { fileURLToPath } from "url";
 
 // src/model/registry.ts
@@ -1762,7 +1812,7 @@ var RegistryClient = class {
       return process.env.AGENTWHEEL_REGISTRY.split(",").map((source) => source.trim()).filter(Boolean);
     }
     if (this.options.workspaceRoot) {
-      const config = await readWorkspaceConfig(this.options.workspaceRoot);
+      const config = await readMergedWorkspaceConfig(this.options.workspaceRoot);
       if (config.registry.sources?.length) return config.registry.sources;
     }
     return [DEFAULT_REGISTRY_SOURCE];
@@ -1770,7 +1820,7 @@ var RegistryClient = class {
   async getTtlMs() {
     if (this.options.ttlMs !== void 0) return this.options.ttlMs;
     if (this.options.workspaceRoot) {
-      const config = await readWorkspaceConfig(this.options.workspaceRoot);
+      const config = await readMergedWorkspaceConfig(this.options.workspaceRoot);
       if (config.registry.ttlSeconds !== void 0) return config.registry.ttlSeconds * 1e3;
     }
     return DEFAULT_REGISTRY_TTL_MS;
@@ -1794,11 +1844,11 @@ var RegistryClient = class {
     }
     const filePath = source.startsWith("file:") ? fileURLToPath(source) : source;
     if (await pathExists(filePath)) {
-      const fullPath = resolve8(filePath);
+      const fullPath = resolve9(filePath);
       const stats = await stat6(fullPath);
       return readFile9(stats.isDirectory() ? join15(fullPath, "index.json") : fullPath, "utf8");
     }
-    const resolved = await this.git.fetch(await this.git.resolve(source, { cacheRoot: join15(dirname7(this.cachePath), "registry-repos") }));
+    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");
   }
 };
@@ -1821,7 +1871,7 @@ function mergeIndexes(indexes) {
   return [...merged.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 function defaultRegistryCachePath() {
-  return join15(homedir3(), ".agentwheel", "registry-cache.json");
+  return join15(homedir4(), ".agentwheel", "registry-cache.json");
 }
 function sameSources(a, b) {
   return a.length === b.length && a.every((source, index) => source === b[index]);
@@ -1829,7 +1879,7 @@ function sameSources(a, b) {
 
 // src/lifecycle/profile.ts
 async function syncProfile(options) {
-  const config = await readWorkspaceConfig(options.workspaceRoot);
+  const config = await readMergedWorkspaceConfig(options.workspaceRoot);
   const profile = config.profiles[options.profile];
   if (!profile) {
     throw new Error(`Unknown profile: ${options.profile}`);
@@ -1841,9 +1891,9 @@ async function syncProfile(options) {
   const results = [];
   for (const pkg of packages) {
     for (const runtime of profile.runtimes) {
-      const targetRoot = runtime.targetRoot ?? options.workspaceRoot;
+      const target = resolveProfileRuntime(runtime, config, options.workspaceRoot);
       const adapter = await resolveAdapter({
-        adapter: runtime.adapter,
+        adapter: target.adapter,
         adapterConfig: runtime.adapterConfig,
         adapterModule: runtime.adapterModule,
         allowAdapterCode: options.allowAdapterCode,
@@ -1858,8 +1908,8 @@ async function syncProfile(options) {
         mode: options.mode ?? pkg.mode
       });
       try {
-        const plan = await createInstallPlan(bundle, adapter, targetRoot, await readInstallManifest(targetRoot, adapter.name));
-        results.push({ runtime: adapter.name, packageName: pkg.name, plan });
+        const plan = await createInstallPlan(bundle, adapter, target.targetRoot, await readInstallManifest(target.targetRoot, adapter.name));
+        results.push({ runtime: adapter.name, targetRoot: target.targetRoot, packageName: pkg.name, plan });
         if (!options.dryRun) {
           await applyInstallPlan(plan, bundle.sourceLock, { executePlugins: runtime.executePlugins ?? options.executePlugins });
         }
@@ -1870,6 +1920,17 @@ async function syncProfile(options) {
   }
   return results;
 }
+function resolveProfileRuntime(runtime, config, workspaceRoot) {
+  if (runtime.agent) {
+    const agent = config.agents[runtime.agent];
+    if (!agent) throw new Error(`Unknown agent in profile: ${runtime.agent}`);
+    return { adapter: agent.adapter, targetRoot: resolveConfigPath(agent.root, workspaceRoot) };
+  }
+  return {
+    adapter: runtime.adapter,
+    targetRoot: runtime.targetRoot ? resolveConfigPath(runtime.targetRoot, workspaceRoot) : workspaceRoot
+  };
+}
 async function packageFromSource(source, options) {
   const resolved = await resolvePackageSource(source, options.workspaceRoot);
   const driver = options.driver ?? inferSourceDriverName(resolved.source);
@@ -1885,13 +1946,14 @@ async function packageFromSource(source, options) {
 // src/lifecycle/source-plan.ts
 import { join as join17 } from "path";
 async function createSourcePlan(options) {
-  const resolvedInput = await resolvePackageSource(options.source, options.targetRoot);
+  const workspaceRoot = options.workspaceRoot ?? options.targetRoot;
+  const resolvedInput = await resolvePackageSource(options.source, workspaceRoot);
   const resolvedSource = resolvedInput.source;
   const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedSource));
   const bundle = await stageSource(driver, resolvedSource, {
-    workspaceRoot: options.targetRoot,
+    workspaceRoot,
     adapter: options.adapter,
-    cacheRoot: join17(options.targetRoot, ".agentwheel", "cache"),
+    cacheRoot: join17(workspaceRoot, ".agentwheel", "cache"),
     mode: options.mode
   });
   const manifest = await readInstallManifest(options.targetRoot, options.adapter.name);
@@ -1916,9 +1978,97 @@ function shouldUpdatePackage(pkg, lock) {
   return { shouldUpdate: false, reason: "pinned source unchanged" };
 }
 
+// src/runtime/target.ts
+import { basename as basename7, dirname as dirname9, join as join18, resolve as resolve10 } from "path";
+var runtimeMarkers = [
+  { adapter: "openclaw", dirs: [".openclaw", ".clawdbot", ".moltbot"] },
+  { adapter: "claude", dirs: [".claude"] },
+  { adapter: "codex", dirs: [".codex"] },
+  { adapter: "hermes", dirs: [".hermes"] },
+  { adapter: "copilot", dirs: [".github"] }
+];
+async function resolveRuntimeTarget(request = {}) {
+  const cwd = resolve10(request.cwd ?? process.cwd());
+  if (request.targetRoot) {
+    const targetRoot = resolve10(request.targetRoot);
+    return {
+      adapter: request.adapter ?? "openclaw",
+      targetRoot,
+      workspaceRoot: targetRoot,
+      source: "target-root"
+    };
+  }
+  const workspaceRoot = await findWorkspaceRoot(cwd);
+  const config = await readMergedWorkspaceConfig(workspaceRoot, { globalRoot: request.globalRoot });
+  if (request.agent) {
+    return targetFromAgent(request.agent, config, workspaceRoot);
+  }
+  const detected = await detectRuntimeTarget(cwd, request.adapter);
+  if (detected) {
+    return { ...detected, workspaceRoot: await findWorkspaceRoot(detected.targetRoot), source: "auto-detect" };
+  }
+  return {
+    adapter: request.adapter ?? "openclaw",
+    targetRoot: cwd,
+    workspaceRoot,
+    source: "cwd"
+  };
+}
+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 workspaceRoot = await findWorkspaceRoot(cwd);
+  const config = await readMergedWorkspaceConfig(workspaceRoot, { globalRoot: request.globalRoot });
+  const targets = Object.entries(config.agents).map(([name]) => targetFromAgent(name, config, workspaceRoot));
+  if (targets.length === 0) {
+    throw new Error("No agents configured. Add agents to .agentwheel/config.json or pass --target-root.");
+  }
+  return targets;
+}
+async function detectRuntimeTarget(cwd = process.cwd(), adapterFilter) {
+  const root = resolve10(cwd);
+  const matches = [];
+  for (const marker of runtimeMarkers) {
+    if (adapterFilter && marker.adapter !== adapterFilter) continue;
+    for (const dir of marker.dirs) {
+      if (basename7(root) === dir) {
+        matches.push({ adapter: marker.adapter, targetRoot: dirname9(root) });
+      } else if (await pathExists(join18(root, dir))) {
+        matches.push({ adapter: marker.adapter, targetRoot: root });
+      }
+    }
+  }
+  const unique = dedupeTargets(matches);
+  if (unique.length > 1) {
+    throw new Error(`Multiple runtime directories detected: ${unique.map((item) => `${item.adapter} at ${item.targetRoot}`).join(", ")}. Pass --adapter or --agent.`);
+  }
+  return unique[0];
+}
+function targetFromAgent(name, config, workspaceRoot) {
+  const agent = config.agents[name];
+  if (!agent) {
+    throw new Error(`Unknown agent: ${name}`);
+  }
+  return {
+    agentName: name,
+    adapter: agent.adapter,
+    targetRoot: resolveConfigPath(agent.root, workspaceRoot),
+    workspaceRoot,
+    source: "agent"
+  };
+}
+function dedupeTargets(matches) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const match of matches) {
+    byKey.set(`${match.adapter}:${match.targetRoot}`, match);
+  }
+  return [...byKey.values()];
+}
+
 // src/cli/index.ts
 var program = new Command();
-program.name("agentwheel").description("Multi-runtime agent artifact orchestrator").version("0.3.1");
+program.name("agentwheel").description("Multi-runtime agent artifact orchestrator").version("0.4.0");
 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") {
@@ -1949,7 +2099,7 @@ program.command("add").argument("<source>", "package source").option("--driver <
   const bundle = await stageSource(driver, resolvedSource, {
     workspaceRoot: targetRoot,
     adapter,
-    cacheRoot: join18(targetRoot, ".agentwheel", "cache"),
+    cacheRoot: join19(targetRoot, ".agentwheel", "cache"),
     mode: options.mode
   });
   const name = options.name ?? resolvedInput.registryEntry?.name ?? bundle.source.packageName ?? source;
@@ -1972,7 +2122,7 @@ program.command("list").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: join18(targetRoot, ".agentwheel", "cache") }))));
+  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);
   for (const artifact of artifacts) {
     console.log(`${artifact.type}	${artifact.name}	${artifact.relativePath}`);
@@ -1982,7 +2132,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: join18(targetRoot, ".agentwheel", "cache") }))));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join19(targetRoot, ".agentwheel", "cache") }))));
   const result = await driver.scan(resolved);
   if (result.findings.length === 0) {
     console.log("Scan ok: no findings");
@@ -1993,17 +2143,20 @@ 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", process.cwd()).option("--mode <mode>", "pinned or tracking").option("--dry-run", "accepted for symmetry; plan never writes", false).action(async (source, options) => {
-  const { plan, bundle } = await buildPlan(source, options);
-  console.log(formatPlan(plan));
-  await rm8(bundle.root, { recursive: true, force: true });
-  if (plan.hasBlockingChanges) 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) => {
+  const targets = await resolveCliTargets(options);
+  for (const target of targets) {
+    const { plan, bundle } = await buildPlan(source, target, options);
+    console.log(formatPlan(plan));
+    await rm8(bundle.root, { recursive: true, force: true });
+    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", process.cwd()).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("--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 targetRoot = normalizeTargetRoot(options.targetRoot);
+    const target = await resolveRuntimeTarget({ targetRoot: options.targetRoot, adapter: options.adapter, agent: options.agent });
     const results = await syncProfile({
-      workspaceRoot: targetRoot,
+      workspaceRoot: target.workspaceRoot,
       profile: options.profile,
       source,
       driver: options.driver,
@@ -2014,66 +2167,37 @@ program.command("sync").argument("[source]", "source directory").option("--drive
       warn: (message) => console.warn(message)
     });
     for (const result of results) {
-      console.log(`Profile ${options.profile} / ${result.runtime} / ${result.packageName}:`);
+      console.log(`Profile ${options.profile} / ${result.runtime} / ${result.packageName} at ${result.targetRoot}:`);
       console.log(formatPlan(result.plan));
       if (result.plan.hasBlockingChanges) process.exitCode = 1;
     }
     if (!options.dryRun) console.log("Applied.");
     return;
   }
+  const targets = await resolveCliTargets(options);
   if (!source) {
-    throw new Error("sync requires a source unless --profile is used");
-  }
-  const { plan, bundle } = await buildPlan(source, options);
-  console.log(formatPlan(plan));
-  if (!options.dryRun) {
-    await applyInstallPlan(plan, bundle.sourceLock, { executePlugins: options.executePlugins });
-    console.log("Applied.");
-  }
-  await rm8(bundle.root, { recursive: true, force: true });
-  if (plan.hasBlockingChanges) process.exitCode = 1;
-});
-program.command("update").option("--target-root <path>", "workspace root", process.cwd()).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) => {
-  const targetRoot = normalizeTargetRoot(options.targetRoot);
-  const config = await readWorkspaceConfig(targetRoot);
-  if (config.packages.length === 0) {
-    console.log("No packages configured.");
+    for (const target of targets) {
+      await runConfiguredPackages(target, options, { useUpdateDecision: false });
+    }
     return;
   }
-  for (const pkg of config.packages) {
-    const adapter = await resolveAdapter({
-      adapter: pkg.adapter,
-      adapterConfig: pkg.adapterConfig,
-      adapterModule: pkg.adapterModule,
-      allowAdapterCode: options.allowAdapterCode,
-      baseDir: targetRoot,
-      warn: (message) => console.warn(message)
-    });
-    const lock = await readSourceLock(targetRoot, adapter.name);
-    const decision = shouldUpdatePackage(pkg, lock);
-    if (!decision.shouldUpdate) {
-      console.log(`Skipping ${pkg.name}: ${decision.reason}.`);
-      continue;
-    }
-    const { plan, bundle } = await buildPlan(pkg.source, {
-      driver: pkg.driver,
-      adapter: pkg.adapter,
-      adapterConfig: pkg.adapterConfig,
-      adapterModule: pkg.adapterModule,
-      allowAdapterCode: options.allowAdapterCode,
-      targetRoot,
-      mode: pkg.mode
-    });
-    console.log(`Update ${pkg.name}:`);
+  for (const target of targets) {
+    const { plan, bundle } = await buildPlan(source, target, options);
     console.log(formatPlan(plan));
     if (!options.dryRun) {
       await applyInstallPlan(plan, bundle.sourceLock, { executePlugins: options.executePlugins });
-      console.log(`Applied ${pkg.name}.`);
+      console.log(`Applied ${target.adapter} at ${target.targetRoot}.`);
     }
     await rm8(bundle.root, { recursive: true, force: true });
     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) => {
+  const targets = await resolveCliTargets(options);
+  for (const target of targets) {
+    await runConfiguredPackages(target, options, { useUpdateDecision: true });
+  }
+});
 program.command("registry").description("manage optional registry indexes").addCommand(
   new Command("update").description("refresh the local registry cache").option("--target-root <path>", "workspace root", process.cwd()).action(async (options) => {
     const client = new RegistryClient({ workspaceRoot: normalizeTargetRoot(options.targetRoot) });
@@ -2101,54 +2225,96 @@ 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", process.cwd()).option("--dry-run", "show removals without writing", false).action(async (options) => {
-  const targetRoot = normalizeTargetRoot(options.targetRoot);
-  const programmaticAdapter = options.adapterModule ? await resolveAdapter({
-    adapter: options.adapter,
-    adapterModule: options.adapterModule,
-    allowAdapterCode: options.allowAdapterCode,
-    baseDir: targetRoot,
-    warn: (message) => console.warn(message)
-  }) : void 0;
-  const adapterName = programmaticAdapter?.name ?? options.adapter;
-  const manifest = await readInstallManifest(targetRoot, adapterName);
-  if (!manifest) {
-    console.log(`No install manifest for ${adapterName} at ${targetRoot}`);
-    return;
-  }
-  const plan = await createUninstallPlan(manifest);
-  console.log(formatPlan(plan));
-  await uninstall(plan, options.dryRun);
-  if (!options.dryRun && programmaticAdapter) {
-    await programmaticAdapter.programmatic?.uninstall?.({ targetRoot, adapterName: programmaticAdapter.name });
+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).action(async (options) => {
+  const targets = await resolveCliTargets(options);
+  for (const target of targets) {
+    const adapter = await resolveAdapterForTarget(target, options);
+    const manifest = await readInstallManifest(target.targetRoot, adapter.name);
+    if (!manifest) {
+      console.log(`No install manifest for ${adapter.name} at ${target.targetRoot}`);
+      continue;
+    }
+    const plan = await createUninstallPlan(manifest);
+    console.log(formatPlan(plan));
+    await uninstall(plan, options.dryRun);
+    if (!options.dryRun) {
+      await adapter.programmatic?.uninstall?.({ targetRoot: target.targetRoot, adapterName: adapter.name });
+      console.log(`Uninstalled ${adapter.name} at ${target.targetRoot}.`);
+    }
+    if (plan.hasBlockingChanges) process.exitCode = 1;
   }
-  if (!options.dryRun) console.log("Uninstalled.");
-  if (plan.hasBlockingChanges) process.exitCode = 1;
 });
-async function buildPlan(source, options) {
-  const targetRoot = normalizeTargetRoot(options.targetRoot);
-  const adapter = await resolveAdapter({
-    adapter: options.adapter,
-    adapterConfig: options.adapterConfig,
-    adapterModule: options.adapterModule,
-    allowAdapterCode: options.allowAdapterCode,
-    baseDir: targetRoot,
-    warn: (message) => console.warn(message)
-  });
+async function buildPlan(source, target, options) {
+  const adapter = await resolveAdapterForTarget(target, options);
   const result = await createSourcePlan({
     source,
-    targetRoot,
+    targetRoot: target.targetRoot,
+    workspaceRoot: target.workspaceRoot,
     adapter,
     driver: options.driver,
     mode: options.mode
   });
   return { plan: result.plan, bundle: result.bundle };
 }
+async function resolveCliTargets(options) {
+  if (options.all) {
+    return resolveAllRuntimeTargets({ targetRoot: options.targetRoot, adapter: options.adapter, agent: options.agent, all: options.all });
+  }
+  return [await resolveRuntimeTarget({ targetRoot: options.targetRoot, adapter: options.adapter, agent: options.agent })];
+}
+async function resolveAdapterForTarget(target, options) {
+  return resolveAdapter({
+    adapter: target.adapter,
+    adapterConfig: options.adapterConfig,
+    adapterModule: options.adapterModule,
+    allowAdapterCode: options.allowAdapterCode,
+    baseDir: target.workspaceRoot,
+    warn: (message) => console.warn(message)
+  });
+}
+async function runConfiguredPackages(target, options, behavior) {
+  const config = await readMergedWorkspaceConfig(target.workspaceRoot);
+  if (config.packages.length === 0) {
+    console.log(`No packages configured at ${target.workspaceRoot}.`);
+    return;
+  }
+  for (const pkg of config.packages) {
+    const targetForPackage = options.adapter || target.source !== "cwd" ? target : { ...target, adapter: pkg.adapter };
+    const adapter = await resolveAdapterForTarget(targetForPackage, {
+      adapterConfig: options.adapterConfig ?? pkg.adapterConfig,
+      adapterModule: options.adapterModule ?? pkg.adapterModule,
+      allowAdapterCode: options.allowAdapterCode
+    });
+    if (behavior.useUpdateDecision) {
+      const lock = await readSourceLock(targetForPackage.targetRoot, adapter.name);
+      const decision = shouldUpdatePackage(pkg, lock);
+      if (!decision.shouldUpdate) {
+        console.log(`Skipping ${pkg.name}: ${decision.reason}.`);
+        continue;
+      }
+    }
+    const { plan, bundle } = await buildPlan(pkg.source, targetForPackage, {
+      driver: pkg.driver,
+      adapterConfig: options.adapterConfig ?? pkg.adapterConfig,
+      adapterModule: options.adapterModule ?? pkg.adapterModule,
+      allowAdapterCode: options.allowAdapterCode,
+      mode: pkg.mode
+    });
+    console.log(`${behavior.useUpdateDecision ? "Update" : "Sync"} ${pkg.name} (${adapter.name} at ${targetForPackage.targetRoot}):`);
+    console.log(formatPlan(plan));
+    if (!options.dryRun) {
+      await applyInstallPlan(plan, bundle.sourceLock, { executePlugins: options.executePlugins });
+      console.log(`Applied ${pkg.name}.`);
+    }
+    await rm8(bundle.root, { recursive: true, force: true });
+    if (plan.hasBlockingChanges) process.exitCode = 1;
+  }
+}
 async function initPackage(root) {
-  await mkdir7(join18(root, "instructions"), { recursive: true });
-  await mkdir7(join18(root, "rules"), { recursive: true });
-  await mkdir7(join18(root, "skills"), { recursive: true });
-  const manifestPath = join18(root, "agentwheel.json");
+  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");
   const manifest = {
     schemaVersion: 1,
     name: "example/agentwheel-package",
@@ -2161,7 +2327,7 @@ async function initPackage(root) {
   };
   await writeFile4(manifestPath, `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
-  await writeFile4(join18(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
+  await writeFile4(join19(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
 }
 function printRegistryEntries(entries) {
   for (const entry of entries) {

package/package.json

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