agentwheel 0.14.4 → 0.14.6

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.
@@ -76,7 +105,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 +115,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:
 
@@ -117,8 +176,12 @@ stderr warning when an update is available. Disable it with `--no-update-check`
 ## 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:
+Installing it is optional, but strongly recommended if you want to get the most out of Agentwheel:
+the skill keeps Agentwheel commands, setup guidance, safety rules, and operational patterns available
+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 a skill is missing:
 
 ```bash
 agentwheel doctor --adapter copilot --user
@@ -126,6 +189,18 @@ 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
 
 Normal use does not need `--target-root`. Run agentwheel inside a runtime folder and it detects the
@@ -255,6 +330,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:
@@ -271,9 +357,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"] }
+      }
+    }
   ]
 }
 ```
@@ -287,6 +386,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
@@ -427,6 +530,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