agentwheel 0.14.8 → 0.14.13

package/install.md

@@ -98,6 +98,13 @@ Install a ClawHub plugin into OpenClaw only when the user approves plugin execut
 agentwheel install clawhub:@openclaw/package-name --adapter openclaw --local --execute-plugins
 ```
 
+If a fleet profile declares runtime `reloadCommands`, run reloads or service restarts only when
+explicitly approved:
+
+```bash
+agentwheel install --profile extra-message-policy --execute-plugins --reload-runtimes
+```
+
 Draft a catalogue submission for a public repository:
 
 ```bash

package/openpack.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "name": "NestDevLab/agentwheel",
-  "version": "0.14.6",
+  "version": "0.14.13",
   "provides": [
     { "type": "skills", "path": "skills" }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.14.8",
+  "version": "0.14.13",
   "description": "Weave skills, rules, and instructions across every AI agent.",
   "type": "module",
   "license": "MIT",
@@ -42,6 +42,7 @@
   },
   "scripts": {
     "build": "tsup && chmod +x dist/index.js",
+    "check-release-version": "node scripts/check-release-version.mjs",
     "prepack": "pnpm build",
     "sync-site-version": "node scripts/sync-site-version.mjs",
     "test": "vitest run",
@@ -60,5 +61,8 @@
     "tsup": "8.5.1",
     "vitest": "4.0.15"
   },
-  "packageManager": "pnpm@10.23.0"
+  "packageManager": "pnpm@10.23.0",
+  "optionalDependencies": {
+    "mermaid": "^11.16.0"
+  }
 }

package/skills/agentwheel/SKILL.md

@@ -2,6 +2,10 @@
 name: agentwheel
 description: Use agentwheel to discover, add, install, update, customize, eject, and uninstall agent skills, rules, instructions, commands, MCP, hooks, settings, and plugin artifacts across runtimes.
 allowed-tools: [Bash]
+license: MIT
+metadata:
+  author: NestDevLab
+  version: "0.14.13"
 ---
 
 # agentwheel
@@ -22,7 +26,7 @@ Mental model:
 - Prefer `agentwheel plan ...` or `agentwheel install --dry-run` before applying changes.
 - Do not hand-edit generated runtime files such as `skills/`, `.agents/skills`, `.claude/skills`, `.github/skills`, `~/.hermes/skills`, or generated instructions.
 - If a plan reports `drift` or `conflict`, stop and explain it. Do not use `--force` unless the user explicitly approves that scope.
-- Gmail, Drive, registry publishing, git commits, pushes, and runtime restarts are separate external side effects. Get explicit approval for them.
+- Gmail, Drive, registry publishing, git commits, pushes, and runtime reloads/restarts are separate external side effects. Get explicit approval for them.
 - Programmatic adapters execute local code. Use `--adapter-module` only with `--allow-adapter-code` after the user approves that local code execution.
 - OpenClaw plugin artifacts are only planned by default. Use `--execute-plugins` only after explicit approval.
 
@@ -214,6 +218,23 @@ Apply configured packages:
 agentwheel install
 ```
 
+Execute semantic plugin installs only after approval:
+
+```bash
+agentwheel install --execute-plugins
+```
+
+If an agent or profile runtime declares structured `reloadCommands`, run them after executed semantic
+plugin changes only with a separate explicit gate:
+
+```bash
+agentwheel install --execute-plugins --reload-runtimes
+```
+
+### Hermes plugin rollout checks
+
+When delivering a Hermes plugin, do not equate source package presence or `plugins.enabled` config with a working runtime install. Verify the gateway host has `$HERMES_HOME/plugins/<plugin-name>/` with the expected `plugin.yaml`/code files, the Agentwheel install manifest contains the plugin artifact, and a canary exercises the middleware path. Use `--execute-plugins` for plugin artifacts when applying, after dry-run and explicit approval.
+
 Preview or apply one configured package:
 
 ```bash
@@ -345,6 +366,20 @@ agentwheel update team-agent-pack --dry-run
 agentwheel update team-agent-pack
 ```
 
+Named package updates preserve artifacts owned by other configured roots, including unrelated drift.
+
+Advance one tracking dependency while unrelated graph nodes remain locked:
+
+```bash
+agentwheel update --dependency shared-core --dry-run
+agentwheel update --dependency shared-core
+agentwheel update --dependency github:your-org/shared-core --agent lab-codex
+```
+
+The selector must uniquely match a locked tracking dependency by name, alias, node id, or source.
+Its required tracking closure also advances. Configured selections stay unchanged; this mode
+rejects package arguments, `--select`, `--skill`, `--frozen-lock`, and `--offline`.
+
 `install` uses the graph lock as input when present. `update` re-resolves tracking packages and writes a new lock. Pinned packages stay on the locked graph unless their declaration changes.
 
 ## Drift And Customization
@@ -476,3 +511,16 @@ If npm update checks are noisy:
 agentwheel --no-update-check install --dry-run
 AGENTWHEEL_NO_UPDATE_CHECK=1 agentwheel install --dry-run
 ```
+
+If install fails with `Locked install cache missing or stale for locked graph node`, or a pinned
+dependency snapshot lacks a selected artifact:
+
+```bash
+agentwheel list <source> --select <artifact>
+```
+
+The native fetch refreshes the source cache. If the refreshed content hash matches the lock, stop —
+nothing else is stale. If it differs, regenerate only the affected graph locks (lock-only) and
+leave them uncommitted: lock commits belong to the approved install. `update --dependency` cannot
+recompute an edge whose root node id changed (e.g. after renaming the root package's artifacts);
+regenerate the locks instead.

package/skills/agentwheel/references/ct111-selfhost-instruction-activation.md

@@ -0,0 +1,24 @@
+# CT111 self-hosted instruction activation
+
+Use when adding a small always-loaded behavior rule to YehonalBot/Drassil on CT111 without importing unrelated core-private skills.
+
+Facts/pitfall:
+- CT111 (`ct111-openclaw`) owns its own AgentWheel plane under `/root/src/nestdevlab/fleet-control/profiles/ct111-selfhost`; do not install to CT111 from CT107.
+- OpenClaw instruction artifacts often target the same runtime file: `/root/.openclaw/workspace/AGENTS.md`.
+- Adding a second selected `instructions/<rule>.md` artifact from `agent-core-toolkit-private` can create duplicate instruction targets with different content. AgentWheel may skip one duplicate or report drift on the managed block.
+
+Preferred pattern:
+1. Keep the broad source package selected narrowly; do not add all of `agent-core-toolkit-private` just to deliver one rule.
+2. If the target already has a domain/persona `instructions/AGENTS.md` artifact, compose the new small behavior fragment into that existing artifact instead of adding a separate instruction artifact to the same destination.
+3. Put the behavior text in the domain toolkit, e.g. `agent-drassil-toolkit-private/fragments/self-improve-activation.md`.
+4. Add one compose include near the top of the domain `AGENTS.md` composition, usually immediately after `core:fragments/core-base.md` and before role overlays:
+   ```json
+   { "include": "fragments/self-improve-activation.md" }
+   ```
+5. Validate JSON/OpenPack selection, then run CT111 dry-run in place:
+   ```bash
+   ssh ct111-openclaw 'cd /root/src/nestdevlab/fleet-control/profiles/ct111-selfhost && npx --yes agentwheel@latest install --profile ct111-selfhost --dry-run --yes'
+   ```
+6. Treat `UPDATE instructions/AGENTS.md -> .openclaw/workspace/AGENTS.md` as the expected dry-run signal. Do not apply if unrelated drift/plugin operations are present unless the user approves that exact scope.
+
+This pattern preserves narrow delivery: the future runtime receives the behavior inside its existing AGENTS managed block without importing unrelated core-private skills or creating competing instruction blocks.

package/skills/agentwheel/references/fleet-control-cleanup-ct107-node-and-effective-adapters.md

@@ -0,0 +1,39 @@
+# Fleet control cleanup: CT107 node vs runtime targets, and effective adapters
+
+Use this reference when cleaning or explaining an AgentWheel fleet-control `.agentwheel/config.json` that targets multiple runtimes/profiles.
+
+## Durable lessons
+
+- Do not model CT107/nestdev as `ct107-openclaw` unless there is an explicitly declared, full OpenClaw runtime home to manage. In Joseph's current CT107/CT110 layout, CT107 is a local node/workspace with Claude/Codex homes; OpenClaw gateway/profile targets live on CT110 or profile-specific users.
+- If a target name implies a real runtime install that does not exist, remove it from `agents` and from every `profiles.*.runtimes[]` entry rather than leaving it as a misleading alias.
+- For profile installs, AgentWheel chooses the effective adapter from each runtime target in the selected profile. The package entry's `adapter` field can be source/default metadata and is not a reliable answer to “which adapters are targeted by this pack under profile all”.
+- When the user asks “per pack, which adapters are targeted?”, compute it as: selected profile runtimes → each runtime's adapter or adapterConfig name → package roots fanned out to that set. Then separately note artifact-type limitations, especially plugin targets.
+
+## Safe cleanup shape
+
+1. Read `.agentwheel/config.json` and list:
+   - `agents` entries,
+   - each profile's runtime list,
+   - any `adapterConfig` paths.
+2. Identify misleading/nonexistent runtime targets by user/domain knowledge first. Ask or preserve if unsure; do not rename targets silently.
+3. Remove the bad agent entry and all profile runtime references to it.
+4. Remove only generated lock directories for the removed target, e.g. `.agentwheel/locks/<removed-agent>/`; do not bulk-delete unrelated locks.
+5. Update `docs/fleet.md` with:
+   - canonical meaning of the fleet,
+   - current agents table,
+   - profile membership,
+   - effective adapter-targeting table per profile and per package.
+6. Validate with JSON parsing and a grep that the removed target no longer appears in config/docs.
+7. Run `agentwheel install --profile <profile> --dry-run` when credentials/cache allow. If a private GitHub fetch blocks dry-run, report it as a credential/cache blocker, not as proof the config is bad.
+
+## Reporting style for Joseph
+
+Keep it short and operational:
+
+- what was removed/changed,
+- exact files touched,
+- current profile membership,
+- validation result,
+- any dry-run blocker.
+
+Avoid over-explaining AgentWheel internals unless he asks; he wants the concrete fleet shape and whether it is clean.

package/skills/agentwheel/references/fleet-plugin-rollouts.md

@@ -0,0 +1,69 @@
+# Fleet plugin rollouts with AgentWheel
+
+Use this when a fleet-control repository manages plugin installation across multiple runtime harnesses.
+
+## Pattern
+
+1. Add the plugin package to `.agentwheel/config.json` as a normal package.
+2. Select every runtime-specific artifact exposed by the OpenPack package, for example:
+   - `plugins/extra-message-policy`
+   - `plugins/hermes-extra-message-policy`
+   - shared `rules/...`
+   - runtime settings such as `settings/hermes-extra-message-policy.json`
+3. Add a dedicated rollout profile instead of immediately folding it into `all`, for example:
+
+```json
+"extra-message-policy": {
+  "runtimes": [
+    { "agent": "ct110-openclaw" },
+    {
+      "agent": "ct110-hermes",
+      "adapterConfig": "/absolute/path/to/fleet-control/adapters/hermes-with-plugins.jsonc"
+    },
+    { "agent": "ct110-tirrenia" }
+  ]
+}
+```
+
+4. Run a dry-run first:
+
+```bash
+npx --yes agentwheel@latest install --profile extra-message-policy --dry-run
+```
+
+5. Apply only after reviewing drift/conflict/plugin operations. For OpenClaw semantic plugin installs, include:
+
+```bash
+npx --yes agentwheel@latest install --profile extra-message-policy --execute-plugins
+```
+
+6. Verify the dry-run uses copy/materialized OpenClaw plugin commands, not symlinks:
+
+```bash
+agentwheel install --profile extra-message-policy --dry-run | tee /tmp/plugin-dry-run.txt
+! grep -q -- '--link' /tmp/plugin-dry-run.txt
+```
+
+Fleet-managed OpenClaw plugins should plan `openclaw plugins install <staged-plugin-path>`. If the plan contains `openclaw plugins install --link ...`, stop and update AgentWheel/OpenClaw plugin command generation before applying.
+
+## Profile scoping pitfall
+
+AgentWheel profiles select runtimes, not packages. If a fleet-control repo's root `.agentwheel/config.json` contains many packages and you need a narrow plugin-only rollout, create a separate workspace/profile directory with its own `.agentwheel/config.json` containing only those plugin packages. Then run the dry-run from that profile workspace.
+
+## Important pitfall: custom adapter config placement
+
+For profile installs, `adapterConfig` must be on the profile runtime entry, not only on the named agent. The current workspace agent schema may not preserve `adapterConfig` under `agents.*`, while profile runtimes do support it.
+
+Use an absolute adapter config path when the runtime is remote/SSH or when relative resolution might happen from the target root rather than the fleet repository.
+
+## Hermes plugin artifacts
+
+If the built-in Hermes adapter does not install plugin artifacts, keep a declarative adapter config in the fleet repo, e.g. `adapters/hermes-with-plugins.jsonc`, with a `plugins` target pointing at `.hermes/plugins`.
+
+## Verification checklist
+
+- `agentwheel list <source>` shows all expected runtime-specific artifacts.
+- Direct Hermes dry-run with the custom adapter creates `.hermes/plugins/<plugin>`.
+- Fleet profile dry-run creates the Hermes plugin, rule, and settings.
+- OpenClaw profile dry-run shows `PLUGIN ... semantic plugin install planned`.
+- Do not restart runtimes as part of the AgentWheel install unless the user explicitly asks.

package/skills/agentwheel/references/harness-path-map-rules-2026-06-13.md

@@ -0,0 +1,98 @@
+# Harness path-map rules pattern — 2026-06-13
+
+Use this when Joseph asks to make CT107/CT110 workspace/harness topology visible to all agents through AgentWheel.
+
+## Durable pattern
+
+- Put detailed machine-readable topology in the shared docs root:
+  - `/home/administrator/env/workspace/itermodus/brain-shared/mappings/harnesses.yaml`
+- Put the short, always-installed instruction in the private core toolkit:
+  - `/home/administrator/env/workspace/itermodus/nestdevlab/agent-core-toolkit-private/rules/harness-path-map.md`
+- The `agent-core-toolkit-private` package exposes `rules/` via `openpack.json`, so any new file under `rules/` is discoverable by `agentwheel list .` and installable by configured runtimes.
+
+## Content split
+
+- Rule file: concise operational policy and pointers. Avoid a huge topology dump.
+- YAML file: detailed host/path/mount map, legacy path status, canonical runtime homes.
+
+## Current canonical layout
+
+```text
+/home/administrator/env/workspace/itermodus/brain-shared   # shared docs/memory/maps/runbooks
+/home/administrator/env/workspace/itermodus/nestdevlab     # AgentWheel/OpenPack/plugin/source repos
+/home/administrator/.hermes                                # Hermes harness home
+/home/administrator/.openclaw                              # OpenClaw harness home
+/home/administrator/.codex                                 # Codex harness home
+/home/administrator/.claude                                # Claude harness home
+/home/administrator/.agentwheel                            # AgentWheel home
+```
+
+CT107 `/home/administrator/env/ai-agents` is a technical SSHFS view of `CT110:/home`, not the canonical docs root. Do not propose active CT110 harness state under `/root`; treat `/root` paths as legacy/backup/compatibility until audited.
+
+## Verification
+
+From the package root:
+
+```bash
+agentwheel list .
+```
+
+Expected: it lists both existing and newly added `rules/*.md` artifacts.
+
+Before applying to runtimes, prefer:
+
+```bash
+agentwheel install --dry-run
+```
+
+Apply only after Joseph approves runtime/generated-file changes.
+
+## Completion pattern for fleet propagation
+
+When Joseph approves completing propagation of this rule, do not only run a source-scoped install. Make the package part of durable AgentWheel desired state, then apply both configured remote agents and locally detected runtimes.
+
+1. Add the private core toolkit rule to AgentWheel global config once:
+
+```bash
+sudo -u administrator -H bash -lc 'agentwheel add /home/administrator/env/workspace/itermodus/nestdevlab/agent-core-toolkit-private \
+  --name NestDevLab/agent-core-toolkit-private \
+  --driver local \
+  --adapter openclaw \
+  --mode tracking \
+  --select rules/harness-path-map.md'
+```
+
+2. Preview/apply configured named agents, including SSH targets such as CT110 OpenClaw/Hermes/Tirrenia:
+
+```bash
+sudo -u administrator -H bash -lc 'agentwheel install --all --dry-run'
+sudo -u administrator -H bash -lc 'agentwheel install --all'
+```
+
+3. Separately preview/apply runtimes auto-detected on the current host. `--all` only covers configured agents; it does not cover local auto-detected `.openclaw`, `.claude`, or `.codex` directories unless those are named agents.
+
+```bash
+sudo -u administrator -H bash -lc 'agentwheel install --all-detected --dry-run'
+sudo -u administrator -H bash -lc 'agentwheel install --all-detected'
+```
+
+4. Verify with checksums against the package source and final dry-runs. A clean completion has identical hashes for source/generated rule files and summaries with `drift 0, conflict 0`.
+
+```bash
+sha256sum /home/administrator/env/workspace/itermodus/nestdevlab/agent-core-toolkit-private/rules/harness-path-map.md \
+  /home/administrator/.openclaw/rules/harness-path-map.md \
+  /home/administrator/.claude/rules/harness-path-map.md \
+  /home/administrator/.codex/rules/harness-path-map.md
+
+ssh root@192.168.1.110 'sha256sum \
+  /home/administrator/env/workspace/itermodus/nestdevlab/agent-core-toolkit-private/rules/harness-path-map.md \
+  /home/administrator/.openclaw/rules/harness-path-map.md \
+  /home/administrator/.hermes/rules/harness-path-map.md \
+  /home/openclaw-tirrenia/.openclaw/rules/harness-path-map.md'
+```
+
+## Pitfalls
+
+- Use `--only-source` when doing an ad-hoc source-scoped dry-run; otherwise AgentWheel may try to apply the current workspace's configured packages and report irrelevant selected-artifact errors.
+- A failed apply may leave a pending journal that AgentWheel can recover on the next run. Fix the underlying issue and rerun `agentwheel install`; do not hand-edit generated files unless ownership/permissions block AgentWheel itself.
+- If remote Hermes rule directories are owned by `root`, fix ownership of the directory and rerun AgentWheel instead of copying the file manually, e.g. `chown administrator:administrator /home/administrator/.hermes/rules` on CT110.

package/skills/agentwheel/references/hermes-background-review-routing.md

@@ -0,0 +1,98 @@
+# Hermes background review vs AgentWheel-managed skills
+
+Use when Hermes' automatic self-improvement review patches skills or the user asks to redirect those writes through AgentWheel.
+
+## Facts
+
+- Hermes' automatic self-improvement is core code, not a `self-improve` skill: `/usr/local/lib/hermes-agent/agent/background_review.py`.
+- It runs a forked agent after eligible turns and can call only memory + skill tools.
+- Skill writes arrive as normal `skill_manage` calls with write origin `background_review` (`tools.skill_provenance.is_background_review()`).
+- The user-visible event is `💾 Self-improvement review: ...`, e.g. `Patched SKILL.md in skill 'agentwheel'`.
+- Existing Hermes guards block background writes to pinned, bundled, hub-installed, or external-dir skills, but may not know AgentWheel runtime ownership.
+
+## Immediate mitigation
+
+Enable staged review before runtime mutation:
+
+```bash
+hermes config set skills.write_approval true
+```
+
+Then review with:
+
+```text
+/skills pending
+/skills diff <id>
+/skills approve <id>
+/skills reject <id>
+```
+
+This prevents silent runtime patches, but the standard approval path still applies the pending write to the runtime skill unless another router handles it.
+
+## Preferred router shape
+
+Use a Hermes plugin or core patch at `tool_execution`/`skill_manage` level:
+
+1. Intercept `tool_name == "skill_manage"`.
+2. If `is_background_review()` is false, pass through.
+3. For background `patch`/`edit`/`write_file`/`remove_file`/`delete`, resolve runtime skill path to AgentWheel provenance.
+4. If AgentWheel-managed, do not call the original runtime write.
+5. Stage or apply a source-package patch proposal in the OpenPack repo, then roll out with AgentWheel dry-run/install.
+6. Return a clear JSON tool result so the review agent reports that the source-first proposal was created, not that runtime was patched.
+
+Minimal plugin skeleton:
+
+```python
+def register(ctx):
+    ctx.register_middleware("tool_execution", route_skill_manage)
+
+def route_skill_manage(tool_name, args, next_call, **kw):
+    if tool_name != "skill_manage":
+        return next_call(args)
+    from tools.skill_provenance import is_background_review
+    if not is_background_review():
+        return next_call(args)
+    if args.get("action") not in {"patch", "edit", "write_file", "remove_file", "delete"}:
+        return next_call(args)
+    # Resolve AgentWheel provenance; if managed, create source patch/pending and return JSON.
+    # Otherwise pass through or stage via skills.write_approval policy.
+```
+
+## Implemented plugin pattern
+
+A working Hermes-only plugin implementation can live as an OpenPack package under fleet-control, e.g.:
+
+```text
+profiles/agentwheel-skill-router/
+  openpack.json
+  plugins/hermes/agentwheel-skill-router/plugin.yaml
+  plugins/hermes/agentwheel-skill-router/__init__.py
+```
+
+Recommended behavior:
+
+- register `tool_execution` middleware;
+- intercept only `tool_name == "skill_manage"` with `tools.skill_provenance.is_background_review() == True`;
+- restrict interception to write actions: `patch`, `edit`, `write_file`, `remove_file`, `delete`;
+- resolve target skill ownership from AgentWheel `~/.agentwheel/hermes*.install-manifest.json` entries where `artifactType == "skills"`, `artifactName == <skill>`, `channel == "managed"`, and `path` matches `.hermes/skills/<skill>` for the active Hermes home;
+- if managed, do **not** call `next_call(args)`; stage a proposal JSON under `$HERMES_HOME/pending/agentwheel-skill-router/` containing the original args and AgentWheel provenance;
+- if unmanaged or foreground, pass through unchanged.
+
+Validation pattern for this plugin class:
+
+1. Syntax-check the plugin without creating `__pycache__` in managed runtime output: `compile(Path("__init__.py").read_text(), path, "exec")`.
+2. Dry-run a scoped Hermes install with the custom Hermes+plugins adapter and `--execute-plugins`.
+3. Apply scoped install only after the plan shows no drift/conflict outside the plugin.
+4. In a fresh Hermes Python process, call `discover_plugins(force=True)`, set `set_current_write_origin("background_review")`, run `run_tool_execution_middleware("skill_manage", ...)`, and verify:
+   - plugin is loaded;
+   - `tool_execution` middleware count increases;
+   - downstream `next_call` is **not** called for a managed skill;
+   - target runtime skill hash is unchanged;
+   - a proposal JSON is created;
+   - foreground calls still invoke `next_call`.
+
+Pitfall: a scoped `agentwheel install <source> --only-source` can rewrite the target graph-lock to contain only that source. For durable fleet registration, add the plugin package to the fleet `.agentwheel/config.json`, but avoid committing a narrowed graph-lock produced by one-source install unless that is intended.
+
+## Durable rule
+
+Background review should never be allowed to mutate AgentWheel-generated runtime skill files directly. It must either stage for human approval or route the proposed diff to the AgentWheel/OpenPack source and require a scoped dry-run before install.

package/skills/agentwheel/references/hermes-plugin-rollout-source-routing.md

@@ -0,0 +1,20 @@
+# Hermes plugin rollout and source-routing canary
+
+Session learning: a Hermes plugin can appear in `plugins.enabled` and still not be installed as a runtime plugin. Treat config enablement, source package existence, and runtime plugin installation as separate facts.
+
+Use this checklist when validating an Agentwheel-delivered Hermes plugin, especially one meant to intercept skill/self-improvement writes:
+
+1. Identify the owning source package or fleet profile. Do not treat `~/.hermes/plugins/` or `~/.hermes/skills/` as canonical source.
+2. Dry-run from fleet-control or the approved workspace:
+   - `agentwheel install <source-or-profile> --dry-run`
+   - include `--execute-plugins` when plugin artifacts must actually materialize.
+3. Verify runtime materialization on the gateway host, not only the shell host:
+   - config mentions the plugin under `plugins.enabled`;
+   - runtime directory exists: `$HERMES_HOME/plugins/<plugin-name>/`;
+   - expected files exist, usually `plugin.yaml` and `__init__.py`;
+   - latest Agentwheel install manifest has the plugin artifact entry.
+4. Restart/reload the relevant Hermes gateway only after explicit approval when needed for plugin load.
+5. Run a canary that exercises the middleware path. For self-improvement source routing, a managed runtime skill write should be blocked from direct runtime mutation and should create a pending/source-first proposal with clear logs.
+6. If proposals are staged but not drained, inspect proposal JSON and reconciler logs. Do not report end-to-end success until the proposal reaches source or the blocker is named.
+
+Common false-positive: `plugins.enabled: [plugin-name]` plus old log lines that mention the plugin only proves it was configured or previously loaded. It does not prove the current runtime directory exists or that the auto-delivery path is healthy.

package/skills/agentwheel/references/hermes-profile-scoped-skill-rollout.md

@@ -0,0 +1,43 @@
+# Hermes profile-scoped skill rollout
+
+Use when adding one new shared toolkit skill to Hermes default/Karan plus a Hermes profile such as `odino` without reconciling the whole generated skill tree.
+
+## Pattern
+
+1. Put the skill in the class-level toolkit source, e.g. `agent-core-toolkit-private/skills/<skill>/SKILL.md`.
+2. In that toolkit `openpack.json`, restrict the skill item to Hermes if it must not install to OpenClaw/Codex/Claude:
+   ```json
+   {
+     "type": "skills",
+     "path": "skills",
+     "items": {
+       "<skill>": { "runtimes": ["hermes"] }
+     }
+   }
+   ```
+3. Add `skills/<skill>` to the relevant fleet selector.
+4. Dry-run with a scoped source install so AgentWheel does not try to adopt/reconcile every existing runtime skill:
+   ```bash
+   AGENTWHEEL_NO_UPDATE_CHECK=1 npx --yes agentwheel install \
+     /path/to/toolkit --driver local \
+     --agent ct110-hermes \
+     --select skills/<skill> \
+     --only-source --dry-run
+   ```
+5. For a Hermes profile target such as Odino, pass the custom profile adapter config explicitly; otherwise the built-in Hermes adapter may reject `profile-odino` for skills as unsupported:
+   ```bash
+   AGENTWHEEL_NO_UPDATE_CHECK=1 npx --yes agentwheel install \
+     /path/to/toolkit --driver local \
+     --agent ct110-hermes-odino \
+     --adapter-config adapters/hermes-odino.jsonc \
+     --select skills/<skill> \
+     --only-source --dry-run
+   ```
+6. Apply the same commands without `--dry-run` after the plan shows only the intended `CREATE`/`UPDATE` and `conflict 0`.
+7. Verify on the remote host by checking both paths and hashes, then optionally `hermes skills list` and `hermes --profile odino skills list`.
+
+## Pitfalls
+
+- A broad `agentwheel install --agent ct110-hermes` can surface many unrelated conflicts for existing unmanaged skills. Use scoped source install for one-skill rollouts.
+- `--agent ct110-hermes-odino` may not automatically apply the profile adapter config in all CLI shapes; pass `--adapter-config adapters/hermes-odino.jsonc` explicitly for profile skill installs.
+- Keep source ownership and deploy ownership separate: toolkit repo owns the skill; fleet-control owns selectors/locks/deploy docs.

package/skills/agentwheel/references/hermes-self-improve-runtime-drift.md

@@ -0,0 +1,25 @@
+# Hermes self-improve vs AgentWheel-managed skills
+
+Use this reference when diagnosing why Hermes skill edits and AgentWheel installs conflict.
+
+## Pattern
+
+Hermes `skill_manage`/`self-improve` edits the installed runtime skill under `~/.hermes/skills/...`. AgentWheel treats runtime skill directories as generated output and tracks ownership/hash in `.agentwheel/*.install-manifest.json` plus graph locks. If a generated runtime skill is patched directly, the source package remains unchanged and later AgentWheel runs can report `drift` or `destination exists but is not managed`.
+
+## Diagnostic checks
+
+- Compare runtime skill path with package source, e.g. `~/.hermes/skills/<name>/SKILL.md` vs the OpenPack source `skills/<name>/SKILL.md`.
+- Inspect AgentWheel dry-run output before applying: `agentwheel plan|install ... --dry-run`.
+- Look for plan lines such as:
+  - `DRIFT ... managed destination changed outside agentwheel`
+  - `CONFLICT ... destination exists but is not managed`
+  - `SKIP ... force adopting unmanaged destination with matching hash`
+- Check whether a scoped install is using the same target, installation type, adapter config, and state key/fingerprint as the manifest that originally managed the file.
+
+## Safe remediation shape
+
+1. Treat `~/.hermes/skills`, `.agents/skills`, `.claude/skills`, `.openclaw/skills`, etc. as generated if AgentWheel owns them.
+2. Move the durable edit into the OpenPack/source repo that provides the skill.
+3. If the runtime content already matches desired source content but the manifest no longer owns it, use a scoped dry-run with `--force-conflict` to confirm it only adopts matching content; apply only after approval.
+4. If runtime content differs from source, do not use `--replace-conflict` casually. First port the desired diff to source, then roll out.
+5. Prefer narrow commands with `--only-source --select skills/<name>` for one-skill rollouts into populated Hermes profiles.

package/skills/agentwheel/references/multi-runtime-plugin-packs.md

@@ -0,0 +1,83 @@
+# Multi-runtime plugin packs with AgentWheel
+
+Use this when converting a runtime-specific plugin into one OpenPack package that targets multiple agent runtimes (for example OpenClaw + Hermes) while keeping runtime-specific adapters separate.
+
+## Recommended shape
+
+```text
+openpack.json
+plugins/
+  openclaw/<plugin-name>/
+  hermes/<plugin-name>/
+settings/
+  <runtime-settings>.json
+rules/
+  <shared-policy>.md
+adapters/
+  <runtime-with-extra-targets>.jsonc
+```
+
+Manifest pattern:
+
+```json
+{
+  "schemaVersion": 2,
+  "name": "Owner/agent-plugin-name",
+  "version": "0.1.0",
+  "provides": [
+    { "type": "plugins", "path": "plugins/openclaw", "runtimes": ["openclaw"], "required": true },
+    { "type": "plugins", "path": "plugins/hermes", "runtimes": ["hermes"], "required": true },
+    { "type": "settings", "path": "settings/hermes.json", "runtimes": ["hermes"] },
+    { "type": "rules", "path": "rules", "runtimes": ["openclaw", "hermes"] }
+  ]
+}
+```
+
+Keep the plugin directory names distinct across runtimes when both are exposed as `plugins/*` artifacts. Example: `plugins/openclaw/extra-message-policy` and `plugins/hermes/hermes-extra-message-policy`. This avoids ambiguous list/install output where two artifacts share `plugins/<same-name>` but target different runtimes.
+
+## Hermes plugin target caveat
+
+AgentWheel/OpenPack supports `type: "plugins"`, but some AgentWheel versions have a built-in Hermes adapter that does not expose a `plugins` target. In that case ship a declarative adapter config in the package, e.g. `adapters/hermes-with-plugins.jsonc`:
+
+```jsonc
+{
+  "name": "hermes",
+  "displayName": "Hermes + plugins",
+  "targets": {
+    "instructions": { "enabled": true, "dest": ".hermes/AGENTS.md" },
+    "rules": { "enabled": true, "dest": ".hermes/rules" },
+    "skills": { "enabled": true, "dest": ".hermes/skills" },
+    "commands": { "enabled": true, "dest": ".hermes/commands" },
+    "mcp": { "enabled": true, "dest": ".hermes/mcp", "merge": "json-deep" },
+    "hooks": { "enabled": true, "dest": ".hermes/hooks", "merge": "json-deep" },
+    "settings": { "enabled": true, "dest": ".hermes/settings.json", "merge": "json-deep" },
+    "plugins": { "enabled": true, "dest": ".hermes/plugins" }
+  }
+}
+```
+
+Install/dry-run with:
+
+```bash
+agentwheel install /abs/path/to/pack --driver local \
+  --adapter-config /abs/path/to/pack/adapters/hermes-with-plugins.jsonc \
+  --target-root /abs/runtime/root --dry-run
+```
+
+Use absolute paths for local sources and adapter configs when `--target-root` differs from the package directory; relative paths are resolved from the target/workspace context and can fail.
+
+## Validation flow
+
+1. Build/test each runtime implementation directly.
+2. `agentwheel list /abs/path/to/pack --driver local` and confirm runtime artifacts are named distinctly.
+3. Dry-run each target runtime separately:
+   - OpenClaw plugin dry-run: add `--execute-plugins` so semantic plugin operations are visible.
+   - Hermes plugin dry-run: use the custom adapter config if needed.
+4. Check for `drift` and `conflict` before applying. Do not force drift without explicit approval.
+5. For plugin installs, remember that runtime restart/reload is a separate side effect.
+
+## Pitfalls
+
+- `python3 -m py_compile` inside a managed Hermes plugin directory creates `__pycache__`, which AgentWheel reports as drift. Prefer `compile(Path(...).read_text(), path, "exec")` for syntax checks, or delete `__pycache__` before status/dry-run.
+- Comparing only package versions is insufficient when live runtime copies were hotfixed. Compare important file hashes or `diff -ru --exclude=node_modules` before overwriting existing plugin copies.
+- GitHub publishing is separate from local package authoring. If `gh`/SSH auth is unavailable, leave a clean local commit and report that the repo was not pushed.