agentwheel 0.11.0 → 0.14.4

package/README.md

@@ -26,7 +26,7 @@ forward explicitly; installs make the current declaration true.
 ```bash
 npm i -g agentwheel
 agentwheel init
-agentwheel add github:your-org/agent-pack --adapter codex --mode tracking
+agentwheel add github:your-org/agent-pack --adapter codex --installation-type local --mode tracking
 agentwheel plan
 agentwheel install
 ```
@@ -34,23 +34,35 @@ agentwheel install
 No lock-in. No central gatekeeper. Packages live in plain git repos or local folders, customizations
 live in your workspace, and runtimes stay generated output.
 
-> **Status: early (v0.11).** The public CLI vocabulary is package-manager style:
+> **Status: early (v0.12).** The public CLI vocabulary is package-manager style:
 > `add`, `install`, `update`, and `uninstall`. A hidden `sync` shim remains for old bootstrapped
 > skills; use `install` in all new docs and scripts.
 
 ## Supported runtimes & resources
 
-agentwheel installs OpenPack resources into five built-in runtimes and into custom harnesses:
-
-- **OpenClaw** — `.openclaw/`
-- **Claude Code** — `.claude/`
-- **Codex CLI** — `.codex/`
-- **GitHub Copilot** — `.github/`
-- **Hermes** — `.hermes/`
+agentwheel installs OpenPack resources into five built-in runtimes and into custom harnesses.
+Every built-in target is scoped by `--installation-type <type>`; built-ins currently use `local`
+for project/workspace installs and `user` for documented user-level installs. If a package can be
+installed in more than one type, agentwheel requires `--installation-type` instead of guessing.
+
+- **OpenClaw** — workspace `skills/`, local plugin directories; user `~/.openclaw/skills`,
+  `~/.openclaw/workspace/AGENTS.md`, and `~/.openclaw/openclaw.json`
+- **Claude Code** — `CLAUDE.md`, `.claude/`, `.mcp.json`, and user `~/.claude/`
+- **Codex CLI** — `AGENTS.md`, `.agents/skills`, `plugins/`, `.codex/`, and user equivalents
+- **GitHub Copilot CLI** — `.github/`, user `~/.copilot/`, and documented `.agents` skill alternatives
+- **Hermes** — local `AGENTS.md`; user `~/.hermes/SOUL.md`, `~/.hermes/skills`,
+  `~/.hermes/plugins`, and `~/.hermes/config.yaml`
 - **Bring your own** — JSONC config adapters with `--adapter-config`, or programmatic adapters with `--adapter-module`
 
 Supported resource types include instructions, rules, skills, commands, subagents, MCP, hooks,
-settings, plugins, and fragments; see the full per-runtime target table below.
+settings, plugins, and fragments. Runtime compatibility is per artifact and per installation type;
+see [`docs/design/artifact-harness-compatibility.md`](docs/design/artifact-harness-compatibility.md).
+Fragments are Agentwheel composition inputs, not runtime file-drop targets.
+
+> `rules` is an OpenPack artifact kind, not a portable runtime concept. Claude rules are
+> behavioral/path-scoped instructions, Copilot rule-like installs map to custom instructions, and
+> Codex `.codex/rules` command policy is intentionally outside the built-in behavioral `rules`
+> target. Unsupported rule targets require an explicit custom adapter instead of an inferred folder.
 
 ## Core Commands
 
@@ -60,10 +72,11 @@ settings, plugins, and fragments; see the full per-runtime target table below.
 | `agentwheel plan [name-or-source]` | Preview what `install` would reconcile without writing. |
 | `agentwheel install` | Reconcile configured packages into the current target or selected fleet. Uses the graph lock as input by default. |
 | `agentwheel install <name-or-source>` | Ensure semantics: configured name/source scopes the install; a new source is added and installed. |
-| `agentwheel update [name]` | Re-resolve tracking packages, then apply. Pinned packages stay locked. |
+| `agentwheel update [name]` | Re-resolve tracking packages, then apply. Pinned packages stay locked. Use `--profile <name>` for profile-managed fleets. |
 | `agentwheel uninstall <name-or-source>` | Remove a configured package from runtimes and config. |
 | `agentwheel uninstall <name> --keep-files` | Remove from config/manifest while leaving runtime files unmanaged. |
-| `agentwheel status` | Show configured packages, manifest/lock presence, and install state. |
+| `agentwheel status` | Show configured packages, manifest/lock presence, and install state. Use `--profile <name>` for profile-managed fleets; `status --all` uses profile `all` when present. |
+| `agentwheel doctor` | Check runtime setup and suggest the explicit companion skill install command when it is missing. |
 
 Mental model: **`install` = make what is declared true. `update` = move tracking declarations forward,
 then make them true.**
@@ -76,7 +89,7 @@ to reconcile those removals.
 npm i -g agentwheel
 
 agentwheel init
-agentwheel add github:your-org/agent-pack --adapter openclaw --mode tracking
+agentwheel add github:your-org/agent-pack --adapter openclaw --installation-type local --mode tracking
 agentwheel plan
 agentwheel install
 ```
@@ -101,6 +114,18 @@ agentwheel checks npm for newer versions at most once every 24 hours and prints
 stderr warning when an update is available. Disable it with `--no-update-check` or
 `AGENTWHEEL_NO_UPDATE_CHECK=1`.
 
+## Companion Skill Doctor
+
+Agentwheel ships its own companion skill in `github:NestDevLab/agentwheel` as `skills/agentwheel`.
+The CLI never installs it silently into runtime folders. Use `doctor` to check the selected runtime
+and print the exact preview and install commands when the skill is missing:
+
+```bash
+agentwheel doctor --adapter copilot --user
+agentwheel install github:NestDevLab/agentwheel --adapter copilot --user --skill agentwheel --dry-run
+agentwheel install github:NestDevLab/agentwheel --adapter copilot --user --skill agentwheel
+```
+
 ## Runtime Targeting
 
 Normal use does not need `--target-root`. Run agentwheel inside a runtime folder and it detects the
@@ -111,10 +136,20 @@ cd ~/.openclaw
 agentwheel install
 ```
 
-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.
+Explicit source installs with an explicit adapter default to user-level artifacts, so this works as
+a global install:
+
+```bash
+agentwheel install github:your-org/agent-pack --adapter codex,claude
+```
+
+Use `--local` for the current directory or `-t/--target-root <project>` for another
+project/workspace. Use `--user`, `--local`, or `-i/--installation-type <type>` when you want the
+scope to be explicit. For example, Codex local skills install into `.agents/skills`, while Codex user
+skills install into `~/.agents/skills`.
+
+When adding a new source this way, Agentwheel saves one package entry per adapter so later installs
+do not collapse Codex and Claude state into the same config entry.
 
 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.
@@ -122,10 +157,11 @@ For a control-plane setup, define named agents in config. Global config lives at
 ```jsonc
 {
   "agents": {
-    "lab-openclaw": { "adapter": "openclaw", "root": "/Users/me/.openclaw-home", "transport": "local" },
+    "lab-openclaw": { "adapter": "openclaw", "installationType": "local", "root": "$HOME/.openclaw-home", "transport": "local" },
     "remote-codex": {
       "adapter": "codex",
-      "root": "/home/agent/project",
+      "installationType": "local",
+      "root": "/workspace/project",
       "transport": "ssh",
       "host": "agent-host.example",
       "user": "agent",
@@ -147,7 +183,9 @@ For a control-plane setup, define named agents in config. Global config lives at
 ```bash
 agentwheel install --agent lab-openclaw
 agentwheel install --all
+agentwheel update --profile daily --dry-run
 agentwheel install --profile daily
+agentwheel status --profile daily
 agentwheel install --all-detected
 ```
 
@@ -201,7 +239,7 @@ Install only part of a package with `--select <type>/<name>`. `--skill <name>` i
 `update` runs.
 
 ```bash
-agentwheel add github:NestDevLab/agent-mesh --skill codex-tmux --adapter codex
+agentwheel add github:NestDevLab/agent-mesh --skill codex-tmux --adapter codex --installation-type local
 agentwheel plan
 agentwheel install
 ```
@@ -287,21 +325,23 @@ pulled in by a meta-package. Overrides are explicit; package array order never d
       "source": "github:NestDevLab/agent-must-have#core",
       "driver": "git",
       "adapter": "codex",
+      "installationType": "local",
       "mode": "tracking"
     },
     {
       "name": "agent-toolkit-nestdev",
-      "source": "github:Yehonal/agent-toolkit#main",
+      "source": "github:example-org/agent-toolkit#main",
       "driver": "git",
       "adapter": "codex",
+      "installationType": "local",
       "mode": "tracking",
       "select": [
         "rules/self-improve-on-correction.md",
         "skills/self-improve"
       ],
       "overrides": [
-        "github:FrancescoBorzi/agent-toolkit::rules/self-improve-on-correction.md",
-        "github:FrancescoBorzi/agent-toolkit::skills/self-improve"
+        "github:example-upstream/agent-toolkit::rules/self-improve-on-correction.md",
+        "github:example-upstream/agent-toolkit::skills/self-improve"
       ]
     }
   ]
@@ -316,9 +356,9 @@ losing artifact. Otherwise planning fails instead of hiding a collision.
 The same declaration can be created from the CLI:
 
 ```bash
-agentwheel add github:Yehonal/agent-toolkit#main \
+agentwheel add github:example-org/agent-toolkit#main \
   --skill self-improve \
-  --override 'github:FrancescoBorzi/agent-toolkit::skills/self-improve'
+  --override 'github:example-upstream/agent-toolkit::skills/self-improve'
 ```
 
 `agentwheel plan`, `agentwheel deps tree`, and `agentwheel deps why` print `OVERRIDE` lines for
@@ -351,9 +391,16 @@ published:
 {
   "name": "myco-internal",
   "targets": {
-    "instructions": { "dest": ".myco/context/AGENTS.md" },
-    "rules": { "dest": ".myco/policy/rules" },
-    "skills": { "dest": ".myco/lib/skills" }
+    "instructions": {
+      "local": { "dest": ".myco/context/AGENTS.md" }
+    },
+    "rules": {
+      "local": { "dest": ".myco/policy/rules" }
+    },
+    "skills": {
+      "local": { "dest": ".myco/lib/skills" },
+      "user": { "root": "home", "dest": ".myco/skills" }
+    }
   }
 }
 ```
@@ -370,18 +417,19 @@ agentwheel install ./my-pack --adapter-module ./myco-adapter.js
 
 Built-in runtime targets:
 
-| Runtime | Main targets |
+| Runtime | Native supported targets |
 |---|---|
-| **OpenClaw** | `.openclaw/AGENTS.md`, `.openclaw/skills`, `.openclaw/rules`, `.openclaw/commands`, `.openclaw/agents`, MCP/hooks/settings, semantic plugin planning |
-| **Claude Code** | `.claude/CLAUDE.md`, `.claude/skills`, `.claude/commands`, `.claude/agents`, `.claude/rules`, `.claude/.mcp.json`, `.claude/settings.json` |
-| **Codex CLI** | `.codex/AGENTS.md`, `.codex/skills`, `.codex/commands`, `.codex/agents`, `.codex/rules`, `.codex/config.toml`, `.codex/hooks.json` |
-| **Hermes** | `.hermes/AGENTS.md`, `.hermes/skills`, `.hermes/rules`, `.hermes/commands`, `.hermes/agents`, MCP/hooks/settings |
-| **GitHub Copilot** | `.github/copilot-instructions.md`, `.github/instructions`, `.github/prompts`, `.github/skills`, `.github/agents`, `.vscode/mcp.json` |
+| **OpenClaw** | `local: skills/, .openclaw/plugins/`; `user: ~/.openclaw/workspace/AGENTS.md, ~/.openclaw/skills, ~/.openclaw/openclaw.json`; no built-in `rules` target |
+| **Claude Code** | `local: CLAUDE.md, .claude/skills, .claude/rules, .claude/commands, .claude/agents, .claude/plugins, .mcp.json, .claude/settings.json`; `user: ~/.claude/...` except project MCP; rules are behavioral/path-scoped |
+| **Codex CLI** | `local: AGENTS.md, .agents/skills, plugins/, .codex/agents, .codex/config.toml, .codex/hooks.json`; `user: ~/.codex/AGENTS.md, ~/.agents/skills, ~/.codex/plugins, ~/.codex/agents, ~/.codex/config.toml, ~/.codex/hooks.json`; no built-in `rules` target; generic settings are planned, not implemented |
+| **Hermes** | `local: AGENTS.md`; `user: ~/.hermes/SOUL.md, ~/.hermes/skills, ~/.hermes/plugins, ~/.hermes/config.yaml`; rules require explicit adapter config |
+| **GitHub Copilot CLI** | `local: .github/copilot-instructions.md, .github/instructions, .github/prompts, .github/skills, .github/plugins, .github/agents, .github/mcp.json, .github/hooks, .github/settings.json`; `user: ~/.copilot/copilot-instructions.md, ~/.copilot/instructions, ~/.copilot/skills, ~/.copilot/plugins, ~/.copilot/agents, ~/.copilot/mcp-config.json, ~/.copilot/hooks, ~/.copilot/settings.json`; rule-like artifacts map to instructions |
 
 ## Docs
 
 - [`docs/spec/openpack.md`](docs/spec/openpack.md) — OpenPack package spec.
 - [`docs/fleet-config.md`](docs/fleet-config.md) — named agents, SSH targets, and profiles.
+- [`docs/design/artifact-harness-compatibility.md`](docs/design/artifact-harness-compatibility.md) — artifact/harness compatibility matrix and rule semantics.
 - Resource catalogue: https://nestdevlab.github.io/agentwheel/catalogue.html.
 - [`DESIGN.md`](DESIGN.md) — architecture and module layout.
 - [`LIFECYCLE.md`](LIFECYCLE.md) — publish, install, update, and customization model.

package/dist/{chunk-N2LZY7LO.js → chunk-B3FMBTWC.js}

@@ -18,6 +18,8 @@ import {
   writeFile
 } from "fs/promises";
 import { dirname, join, relative } from "path";
+var IGNORED_ENTRY_NAMES = /* @__PURE__ */ new Set([".git", "node_modules", "__pycache__", ".DS_Store"]);
+var IGNORED_SUFFIXES = [".pyc", ".pyo"];
 async function pathExists(path) {
   try {
     await stat(path);
@@ -48,7 +50,7 @@ async function listFiles(root) {
   async function walk(dir) {
     const entries = await readdir(dir, { withFileTypes: true });
     for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-      if (entry.name === ".git" || entry.name === "node_modules") continue;
+      if (isIgnoredGeneratedEntry(entry.name)) continue;
       const full = join(dir, entry.name);
       if (entry.isDirectory()) {
         await walk(full);
@@ -60,6 +62,9 @@ async function listFiles(root) {
   await walk(root);
   return out;
 }
+function isIgnoredGeneratedEntry(name) {
+  return IGNORED_ENTRY_NAMES.has(name) || IGNORED_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
 async function atomicCopy(source, dest, kind) {
   await mkdir(dirname(dest), { recursive: true });
   const temp = `${dest}.agentwheel-tmp-${process.pid}-${Date.now()}`;
@@ -67,7 +72,7 @@ async function atomicCopy(source, dest, kind) {
   if (kind === "file") {
     await copyFile(source, temp);
   } else {
-    await cp(source, temp, { recursive: true, dereference: true });
+    await cp(source, temp, { recursive: true, dereference: true, filter: (path) => !isIgnoredGeneratedEntry(path.split(/[\\/]/).at(-1) ?? "") });
   }
   await rm(dest, { recursive: true, force: true });
   await rename(temp, dest);
@@ -104,6 +109,7 @@ function resolveLocalPath(source) {
 export {
   pathExists,
   hashPath,
+  isIgnoredGeneratedEntry,
   atomicCopy,
   writeJsonAtomic,
   inferSourceDriverName,

package/dist/{identify-7SEBWCNQ.js → identify-TXIDGMNL.js}

@@ -2,7 +2,7 @@
 import {
   inferSourceDriverName,
   isExplicitSource
-} from "./chunk-N2LZY7LO.js";
+} from "./chunk-B3FMBTWC.js";
 export {
   inferSourceDriverName,
   isExplicitSource