agentwheel 0.14.5 → 0.14.7

package/AGENT.md

@@ -0,0 +1,95 @@
+# Agentwheel For AI Agents
+
+Agentwheel is the control plane for installing OpenPack resources into agent runtimes. Use it when a
+user wants to discover, add, install, update, remove, or publish skills, instructions, rules,
+commands, subagents, MCP, hooks, settings, plugins, or fragments.
+
+## Operating Model
+
+- `add` records desired packages in `.agentwheel/config.json`.
+- `plan` previews what would change.
+- `install` makes the declared state true.
+- `update` refreshes tracking packages, then installs.
+- `uninstall` removes managed runtime output and config entries.
+
+Runtime output directories are generated. Do not hand-edit generated skills, runtime config, or
+plugin directories to complete an Agentwheel change.
+
+## Standard Flow
+
+```bash
+agentwheel add github:owner/agent-pack --adapter codex --installation-type local --mode tracking
+agentwheel plan
+agentwheel install
+agentwheel status
+```
+
+To add and install in one step:
+
+```bash
+agentwheel install github:owner/agent-pack --adapter codex --local
+```
+
+Use explicit scope when the target matters:
+
+```bash
+agentwheel install github:owner/agent-pack --adapter claude --user
+agentwheel install github:owner/agent-pack --adapter codex --local
+agentwheel install github:owner/agent-pack --adapter openclaw --installation-type local
+```
+
+## Companion Skills
+
+Install the Agentwheel companion skill when the user wants Agentwheel guidance inside the runtime:
+
+```bash
+agentwheel doctor --adapter codex --local
+agentwheel install github:NestDevLab/agentwheel --adapter codex --local --skill agentwheel
+```
+
+In Syncwheel-managed repositories, `doctor` can also check for the Syncwheel skill:
+
+```bash
+agentwheel doctor --adapter codex --local --skill syncwheel --source github:NestDevLab/syncwheel
+agentwheel install github:NestDevLab/syncwheel --adapter codex --local --skill syncwheel
+```
+
+## Sources And Catalogue
+
+Use direct sources when known:
+
+```bash
+agentwheel install github:owner/repo --adapter codex --local
+agentwheel install skillkit:owner/skill-name --adapter claude --user
+agentwheel install vercel:owner/skill-name --adapter codex --user
+agentwheel install mcp-registry:publisher/server-name --adapter claude --local
+agentwheel install clawhub:@openclaw/package-name --adapter openclaw --local
+```
+
+Use the catalogue for browsing and copy-ready commands:
+
+```text
+https://nestdevlab.github.io/agentwheel/catalogue.html
+```
+
+Draft a public catalogue submission without editing the registry by hand:
+
+```bash
+npx agentwheel@latest registry publish https://github.com/owner/repo
+```
+
+## Safety
+
+- Prefer `agentwheel plan` or `agentwheel install --dry-run` before broad or fleet changes.
+- Stop on drift or conflict unless the user explicitly approves the exact scope.
+- Use `--adapter-module` only with `--allow-adapter-code` after the user approves local code execution.
+- Use `--execute-plugins` only after the user approves plugin execution.
+- Treat registry publishing, Git commits, pushes, and runtime restarts as separate side effects.
+
+## Key References
+
+- Install handoff: `install.md`
+- Package spec: `docs/spec/openpack.md`
+- Compatibility matrix: `docs/design/artifact-harness-compatibility.md`
+- Fleet config: `docs/fleet-config.md`
+- Catalogue: `docs/catalogue.html`

package/README.md

@@ -34,6 +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.
 
+## Install Methods
+
+**CLI install**
+
+```bash
+npm i -g agentwheel
+agentwheel init
+```
+
+Prefer pnpm? `pnpm add -g agentwheel` works too.
+
+**AI agent handoff**
+
+Give an agent [`install.md`](install.md) when you want it to install Agentwheel, verify the CLI,
+install the companion skill, and show the right catalogue flow for your runtime.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/NestDevLab/agentwheel/main/install.md
+```
+
+**Companion skill**
+
+The companion skill keeps Agentwheel commands and safety rules inside the runtime you are using:
+
+```bash
+agentwheel doctor --adapter codex --local
+agentwheel install github:NestDevLab/agentwheel --adapter codex --local --skill agentwheel
+```
+
 > **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.
@@ -46,7 +75,8 @@ for project/workspace installs and `user` for documented user-level installs. If
 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`
+  `~/.openclaw/workspace/AGENTS.md`, `~/.openclaw/workspace-subagents/<name>/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
@@ -76,7 +106,7 @@ Fragments are Agentwheel composition inputs, not runtime file-drop targets.
 | `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. 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. |
+| `agentwheel doctor` | Check runtime setup and suggest explicit companion/selected skill install commands when they are missing. |
 
 Mental model: **`install` = make what is declared true. `update` = move tracking declarations forward,
 then make them true.**
@@ -86,15 +116,45 @@ to reconcile those removals.
 ## Quick Start
 
 ```bash
-npm i -g agentwheel
-
 agentwheel init
 agentwheel add github:your-org/agent-pack --adapter openclaw --installation-type local --mode tracking
 agentwheel plan
 agentwheel install
 ```
 
-Prefer pnpm? `pnpm add -g agentwheel` works too.
+## Source Inputs
+
+Agentwheel can install from explicit local paths, Git sources, catalogue short names, provider
+indexes, and generated OpenPack wrappers:
+
+```bash
+agentwheel install ./my-pack --adapter codex --local
+agentwheel install github:your-org/agent-pack --adapter codex --user
+agentwheel install skillkit:owner/skill-name --adapter claude --user
+agentwheel install vercel:owner/skill-name --adapter codex --user
+agentwheel install mcp-registry:publisher/server-name --adapter claude --local
+agentwheel install clawhub:@openclaw/whatsapp --adapter openclaw --local
+```
+
+`mcp-registry:<server-name>` reads the public MCP Registry and stages a generated OpenPack package
+only when the server exposes a safe unauthenticated `streamable-http` remote. Entries that require
+secret headers or only publish native package instructions remain discovery-only until they are
+wrapped by an explicit OpenPack source.
+
+`clawhub:<package-name>` reads ClawHub package metadata and stages a generated OpenPack plugin
+wrapper for OpenClaw. The generated artifact plans `openclaw plugins install --force clawhub:<name>`;
+plugin execution remains opt-in through Agentwheel's plugin execution controls.
+
+Submit a public resource to the catalogue without editing `index.json` by hand:
+
+```bash
+npx agentwheel@latest registry publish https://github.com/owner/repo \
+  --description "Reusable skills and rules for coding agents." \
+  --tag skills,rules
+```
+
+The command normalizes the source, drafts the registry JSON, prints a verification command, and
+prints a prefilled GitHub submission URL you can review before sending.
 
 Contributor install from source:
 
@@ -122,7 +182,7 @@ the skill keeps Agentwheel commands, setup guidance, safety rules, and operation
 inside your agent runtime instead of forcing you to leave the flow and look them up elsewhere.
 
 The CLI never installs the companion skill silently into runtime folders. Use `doctor` to check the
-selected runtime and print the exact preview and install commands when the skill is missing:
+selected runtime and print the exact preview and install commands when a skill is missing:
 
 ```bash
 agentwheel doctor --adapter copilot --user
@@ -130,6 +190,16 @@ agentwheel install github:NestDevLab/agentwheel --adapter copilot --user --skill
 agentwheel install github:NestDevLab/agentwheel --adapter copilot --user --skill agentwheel
 ```
 
+`doctor` also accepts explicit skill checks and machine-readable output. In Syncwheel-managed
+workspaces, it automatically includes the Syncwheel skill so Git/worktree maintenance guidance can
+be installed into the active agent runtime when needed.
+
+```bash
+agentwheel doctor --adapter codex --local --skill syncwheel --source github:NestDevLab/syncwheel --json
+agentwheel install github:NestDevLab/syncwheel --adapter codex --local --skill syncwheel --dry-run
+agentwheel install github:NestDevLab/syncwheel --adapter codex --local --skill syncwheel
+```
+
 Run the dry-run first when you want to inspect the target path and conflict status before writing.
 
 ## Runtime Targeting
@@ -261,6 +331,17 @@ be deselected:
 }
 ```
 
+Package authors can also declare suggested companion packages. Suggestions are not installed by
+default; users opt in with `--with-suggestions` for all suggestions relevant to selected artifacts,
+or `--suggestion <alias>` for one named suggestion. The choice is saved when used with `add` or
+`install <source>`.
+
+```bash
+agentwheel add github:your-org/agent-pack --skill triage --with-suggestions --adapter codex --local
+agentwheel plan --skill triage --with-suggestions
+agentwheel install github:your-org/agent-pack --skill triage --suggestion brainstorming --adapter codex --local
+```
+
 ## Dependencies And Composition
 
 OpenPack packages can depend on other packages and compose shared markdown fragments:
@@ -277,9 +358,22 @@ OpenPack packages can depend on other packages and compose shared markdown fragm
       "select": ["rules/safe-actions.md", "fragments/risk.md"]
     }
   },
+  "suggests": {
+    "brainstorming": {
+      "source": "vercel:skills.sh/example/agent-skills",
+      "select": ["skills/brainstorming"],
+      "reason": "Generate options before converging."
+    }
+  },
   "provides": [
     { "type": "fragments", "path": "fragments" },
-    { "type": "skills", "path": "skills" }
+    {
+      "type": "skills",
+      "path": "skills",
+      "items": {
+        "triage": { "suggests": ["brainstorming"] }
+      }
+    }
   ]
 }
 ```
@@ -293,6 +387,10 @@ OpenPack packages can depend on other packages and compose shared markdown fragm
   `core:fragments/risk.md`.
 - **Trust.** New transitive sources prompt before install. Pre-approve with `--trust <glob>` or
   `--yes`, set a workspace trust policy, and manage persisted decisions with `agentwheel trust`.
+- **Suggested companions.** `suggests` uses the same source/selection shape as `requires`, but it
+  is opt-in. `--with-suggestions` pulls all relevant suggestions as non-blocking optional edges;
+  `--suggestion <alias>` pulls a specific suggestion and fails if that explicit suggestion cannot
+  resolve.
 - **Offline & frozen installs.** `--offline` guarantees zero network; `--frozen-lock` hard-fails if
   resolution would differ from the lock.
 - **Introspection.** `agentwheel deps tree` prints the resolved graph; `agentwheel deps why
@@ -425,7 +523,7 @@ Built-in runtime targets:
 
 | Runtime | Native supported targets |
 |---|---|
-| **OpenClaw** | `local: skills/, .openclaw/plugins/`; `user: ~/.openclaw/workspace/AGENTS.md, ~/.openclaw/skills, ~/.openclaw/openclaw.json`; no built-in `rules` target |
+| **OpenClaw** | `local: skills/, .openclaw/plugins/`; `user: ~/.openclaw/workspace/AGENTS.md, ~/.openclaw/workspace-subagents/<name>/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 |
@@ -433,6 +531,9 @@ Built-in runtime targets:
 
 ## Docs
 
+- [`install.md`](install.md) — AI-agent handoff for installing Agentwheel and the companion skill.
+- [`AGENT.md`](AGENT.md) — concise operating guide for AI agents using Agentwheel.
+- [`llms.txt`](llms.txt) — LLM-oriented map of the public 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.

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

@@ -87,12 +87,14 @@ async function writeJsonAtomic(path, data) {
 
 // src/source/identify.ts
 function inferSourceDriverName(source) {
+  if (source.startsWith("clawhub:")) return "clawhub";
+  if (source.startsWith("mcp-registry:")) return "mcp-registry";
   if (source.startsWith("skillkit:")) return "skillkit";
   if (source.startsWith("vercel:")) return "vercel-skills";
   return source.startsWith("github:") || source.startsWith("git:") ? "git" : "local";
 }
 async function isExplicitSource(source) {
-  if (source.startsWith("github:") || source.startsWith("git:") || source.startsWith("skillkit:") || source.startsWith("vercel:")) {
+  if (source.startsWith("github:") || source.startsWith("git:") || source.startsWith("skillkit:") || source.startsWith("vercel:") || source.startsWith("mcp-registry:") || source.startsWith("clawhub:")) {
     return true;
   }
   if (source.startsWith("./") || source.startsWith("../") || source.startsWith("/") || source.startsWith("~/")) {

package/dist/{identify-TXIDGMNL.js → identify-T4RE5RBD.js}

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