agentwheel 0.10.0 → 0.14.3

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,33 @@ 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.9).** v0.9 switches the public CLI vocabulary to package-manager verbs:
-> `add`, `install`, `update`, and `uninstall`. A hidden `sync` shim remains for one release only
-> so old bootstrapped skills can self-update; use `install` in all new docs and scripts.
+> **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:
+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** — `.openclaw/`
-- **Claude Code** — `.claude/`
-- **Codex CLI** — `.codex/`
-- **GitHub Copilot** — `.github/`
-- **Hermes** — `.hermes/`
+- **OpenClaw** — workspace `skills/`, user `~/.openclaw/skills`
+- **Claude Code** — `CLAUDE.md`, `.claude/`, and user `~/.claude/`
+- **Codex CLI** — `AGENTS.md`, `.agents/skills`, `.codex/`, and user equivalents
+- **GitHub Copilot CLI** — `.github/`, user `~/.copilot/`, and documented `.agents` skill alternatives
+- **Hermes** — local instructions via `AGENTS.md`; skills are user-only at `~/.hermes/skills`
 - **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. Codex rules are command
+> execution policy, Claude rules are behavioral/path-scoped instructions, and Copilot rule-like
+> installs map to path-specific custom instructions. Unsupported rule targets require an explicit
+> custom adapter instead of an inferred folder.
 
 ## Core Commands
 
@@ -60,10 +70,10 @@ 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. |
 
 Mental model: **`install` = make what is declared true. `update` = move tracking declarations forward,
 then make them true.**
@@ -76,7 +86,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
 ```
@@ -111,10 +121,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 +142,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 +168,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 +224,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
 ```
@@ -272,6 +295,60 @@ still owned by another configured package.
 }
 ```
 
+### Source Overrides
+
+Use package-level `overrides` when a workspace intentionally wants one selected source to replace
+an artifact that arrives from another package, such as a forked skill replacing the same skill
+pulled in by a meta-package. Overrides are explicit; package array order never decides precedence.
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "packages": [
+    {
+      "name": "nestdev-must-have-core",
+      "source": "github:NestDevLab/agent-must-have#core",
+      "driver": "git",
+      "adapter": "codex",
+      "installationType": "local",
+      "mode": "tracking"
+    },
+    {
+      "name": "agent-toolkit-nestdev",
+      "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:example-upstream/agent-toolkit::rules/self-improve-on-correction.md",
+        "github:example-upstream/agent-toolkit::skills/self-improve"
+      ]
+    }
+  ]
+}
+```
+
+The `source::type/name` selector identifies the artifact to replace. `github:owner/repo` matches
+that repository at any ref; add `#main` or another ref to narrow it. The replacing package must
+select exactly one artifact with the same `type/name`, and the override must match exactly one
+losing artifact. Otherwise planning fails instead of hiding a collision.
+
+The same declaration can be created from the CLI:
+
+```bash
+agentwheel add github:example-org/agent-toolkit#main \
+  --skill self-improve \
+  --override 'github:example-upstream/agent-toolkit::skills/self-improve'
+```
+
+`agentwheel plan`, `agentwheel deps tree`, and `agentwheel deps why` print `OVERRIDE` lines for
+these decisions, and graph locks store them for review.
+
 Migrating an existing legacy package takes one command:
 
 ```bash
@@ -285,7 +362,9 @@ Drift detection blocks accidental edits to generated runtime files. Intentional
 
 - **Layer** local instructions with `agentwheel remember`.
 - **Add** separate local artifacts under `.agentwheel/additions`.
-- **Override** an upstream item under `.agentwheel/overrides`.
+- **Override content** for an upstream item under `.agentwheel/overrides`.
+- **Override source precedence** with package `overrides` when a forked source should replace a
+  colliding artifact from another package.
 - **Eject** an item into `.agentwheel/ejected` when you want local ownership.
 
 ## Custom And Private Runtimes
@@ -297,9 +376,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" }
+    }
   }
 }
 ```
@@ -316,18 +402,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/`; `user: ~/.openclaw/skills`; plugins require runtime-specific config |
+| **Claude Code** | `local: CLAUDE.md, .claude/skills, .claude/rules, .claude/commands, .claude/agents, .mcp.json, .claude/settings.json`; `user: ~/.claude/...` except project MCP; rules are behavioral/path-scoped |
+| **Codex CLI** | `local: AGENTS.md, .agents/skills, .codex/rules, .codex/agents, .codex/config.toml, .codex/hooks.json`; `user: ~/.agents/skills, ~/.codex/...`; rules are command execution policy; subagents are TOML custom agents |
+| **Hermes** | `local: AGENTS.md`; `user: ~/.hermes/skills`; rules require explicit adapter config |
+| **GitHub Copilot CLI** | `local: .github/copilot-instructions.md, .github/instructions, .github/prompts, .github/skills, .github/agents, .github/mcp.json, .github/hooks`; `user: ~/.copilot/copilot-instructions.md, ~/.copilot/instructions, ~/.copilot/skills, ~/.copilot/agents, ~/.copilot/mcp-config.json, ~/.copilot/hooks`; 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