aiwg 2026.6.0 → 2026.6.1

package/CLAUDE.md

@@ -34,7 +34,7 @@ agentic/code/
 │   ├── knowledge-base/       # Knowledge base / wiki framework
 │   └── ops-complete/         # Operational infrastructure (incident, runbooks, troubleshooting)
 ├── addons/
-│   └── voice-framework/     # Voice profiles (one of 27 addons)
+│   └── voice-framework/     # Voice profiles (one of 29 addons)
 └── agents/                  # Writing quality agents
 
 src/                         # CLI and MCP server implementation
@@ -97,7 +97,7 @@ All 10 providers receive all 4 artifact types (agents, commands, skills, rules).
 - **Warp**: Agents and commands are also aggregated into `WARP.md` for single-file context loading
 - **Windsurf**: Agents are aggregated into `AGENTS.md` at project root
 - **OpenClaw**: All artifacts deploy to home directory (`~/.openclaw/`). First provider to support behaviors (`~/.openclaw/behaviors/`)
-- **Hermes**: Integrates like Claude Code and Codex — file-based deploy + `aiwg discover`/`aiwg show` CLI + AGENTS.md/.hermes.md bridge (Discover-First Protocol). **MCP is optional**: AIWG's MCP server is a global hook any provider may use, but Hermes does not require it (validated v2026.5.13, #1527). When MCP is enabled, commands reach AIWG via `mcp_aiwg_command_run` (allow-listed) and the server exposes 16 core tools by default (45 more via `AIWG_MCP_TOOLSETS=<csv>`). Standard skills (~385) live under `~/.hermes/skills/.aiwg/` (recursively discovered) and are also reachable through the capability index without file deploy; kernel skills (~9) live at the top level, protected from the Curator (v0.12.0+) via the `.bundled_manifest`. Rules are inlined into AGENTS.md as compressed `### Rule:` directives, with full bodies reachable through `aiwg show rule <name>` even when MCP is disabled. Broader MCP modernization is tracked in #1533. See `docs/integrations/hermes-quickstart.md`.
+- **Hermes**: Integrates like Claude Code and Codex — file-based deploy + `aiwg discover`/`aiwg show` CLI + AGENTS.md/.hermes.md bridge (Discover-First Protocol). **MCP is optional**: AIWG's MCP server is a global hook any provider may use, but Hermes does not require it (validated v2026.5.13, #1527). When MCP is enabled, commands reach AIWG via `mcp_aiwg_command_run` (allow-listed) and the server exposes 16 core tools by default (45 more via `AIWG_MCP_TOOLSETS=<csv>`). Standard skills (~460) live under `~/.hermes/skills/.aiwg/` (recursively discovered) and are also reachable through the capability index without file deploy; kernel skills (~20) live at the top level, protected from the Curator (v0.12.0+) via the `.bundled_manifest`. Rules are inlined into AGENTS.md as compressed `### Rule:` directives, with full bodies reachable through `aiwg show rule <name>` even when MCP is disabled. Broader MCP modernization is tracked in #1533. See `docs/integrations/hermes-quickstart.md`.
 - **OpenHuman** (tinyhumansai): OSS personal-AI runtime (Rust core + Tauri desktop), AIWG-convention-aware out of the box — ships `.agents/`, `AGENTS.md`, `.claude/`, `.codex/`. Kernel skills install **globally like OpenClaw** to `~/.openhuman/skills/` (ungated user-scope native scan via `ops_discover.rs`, one-level — exactly what the app's Skills library surfaces), standard skills sequestered under `~/.openhuman/.aiwg/skills/` for index-driven discovery. Markdown personas stay **workspace-scoped** at `.agents/agents/` (consumed by the coding hosts OpenHuman drives — `claude_code`/`factory`), and commands/rules aggregate into the workspace `AGENTS.md` bridge. The project-scope trust marker is no longer written — user-scope is ungated (#1553). The native agent harness (TOML specialists) is an opt-in Tier-2 surface (#1559). Induction epic #1552; see `docs/integrations/openhuman-quickstart.md` (#1558).
 - **Omnius** (first-party integrator): Ships AIWG embedded inside the Omnius autonomous coding agent runtime — no separate `aiwg use` step required. `npm i -g omnius` installs both. AIWG skills, agents, and rules are reachable through `aiwg discover` from inside Omnius sessions and through Omnius's REST (`/v1/aiwg/*`) and MCP bridges. Treat Omnius like any AIWG-aware host: the `skill-discovery`, `delivery-policy`, `human-authorization`, and `anti-laziness` rules all apply unchanged. See https://www.npmjs.com/package/omnius.
 
@@ -337,13 +337,13 @@ aiwg run skill <name> --cwd <path> -- <args...>   # explicit CWD override
 # `"executable": true` with a `run_hint`; `aiwg show` prepends a one-line
 # banner so agents know to use this command instead of running raw paths.
 
-# Most AIWG skills (~385 of 400) are NOT in your context — they stay at
+# Most AIWG skills (~460 of 480) are NOT in your context — they stay at
 # $AIWG_ROOT (no per-project copy by default, #1217) and are reached via
 # `aiwg discover` + `aiwg show`. The kernel set is what's always-loaded:
 # 8 framework quickrefs + aiwg-utils-quickref + aiwg-language-map (covers
-# addons + extensions) + 9 self-maintenance ops (steward, aiwg-doctor,
+# addons + extensions) + 10 self-maintenance ops (steward, aiwg-doctor,
 # aiwg-refresh, aiwg-regenerate, aiwg-status, aiwg-help, aiwg-issue,
-# aiwg-pr, use) = 19 skills total.
+# aiwg-pr, aiwg-mission, use) = 20 skills total.
 # The skill-discovery HIGH rule mandates `aiwg discover` before declining
 # a user request as out-of-scope.
 # To force per-project copies (sandboxed runtimes): pass --copy-all

package/README.md

@@ -1,5 +1,7 @@
 <div align="center">
 
+<a href="https://aiwg.io"><img src="https://aiwg.io/assets/badges/aiwg-hero-dark.png" alt="AIWG — multi-agent AI framework · one source of truth · 10 platforms" width="680"></a>
+
 # AIWG
 
 **Multi-agent AI framework for Claude Code, Copilot, Cursor, Warp, and 6 more platforms**
@@ -22,7 +24,9 @@ use the [macOS Install Guide](docs/getting-started/macos-install.md).
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org)
 [![10 Platforms](https://img.shields.io/badge/Platforms-10-purple?style=flat-square)](#-platform-support)
 
-[**Get Started**](#quick-start) · [**Features**](#what-you-get) · [**Agents**](#agents) · [**CLI Reference**](docs/cli-reference.md) · [**Documentation**](#documentation) · [**Community**](#community--support)
+[![Built With AIWG](https://aiwg.io/assets/badges/built-with-aiwg-dark.png)](https://aiwg.io/badges)
+
+[**Get Started**](#quick-start) · [**Features**](#what-you-get) · [**Agents**](#agents) · [**CLI Reference**](docs/cli-reference.md) · [**Documentation**](#documentation) · [**Community**](#community--support) · [**Badges**](https://aiwg.io/badges)
 
 [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/BuAusFMxdA)
 [![Telegram](https://img.shields.io/badge/Telegram-Join-26A5E4?logo=telegram&logoColor=white&style=flat-square)](https://t.me/+oJg9w2lE6A5lOGFh)
@@ -1847,6 +1851,20 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ---
 
+## Badges
+
+Building on AIWG? Show it. Grab a **Built With AIWG** / **Powered By AIWG** badge — light and dark, hosted and free to hot-link (no need to copy the image into your repo):
+
+[![Built With AIWG](https://aiwg.io/assets/badges/built-with-aiwg-dark.png)](https://aiwg.io)
+
+```md
+[![Built With AIWG](https://aiwg.io/assets/badges/built-with-aiwg-dark.png)](https://aiwg.io)
+```
+
+Full set with copy-paste snippets at **[aiwg.io/badges](https://aiwg.io/badges)**.
+
+---
+
 ## Usage Notes
 
 AIWG is optimized for token efficiency. Rules deploy as a consolidated index (~200 lines) instead of 35 individual files (~9,321 lines). Most users on **Claude Pro** or similar plans will have no issues. See [Usage Notes](docs/usage-notes.md) for rate limit guidance.

package/agentic/code/addons/aiwg-utils/agents/aiwg-steward.md

@@ -31,6 +31,8 @@ Beyond installation health, you understand **what each provider natively support
 7. **Advise** on native vs. emulated feature paths and any capability gaps
 8. **Route** issue-workflow setup requests to the Issue Workflow Guide, especially when users want local file-system issue tracking or want to use `issue-audit` / `address-issues` on their own project issues
 
+> Additional worked examples: see addons/aiwg-utils/docs/agent-examples/aiwg-steward-examples.md (`aiwg discover "aiwg-steward worked examples"`).
+
 ## Issue Workflow Routing
 
 When a user asks to start using issues themselves, set up a project issue workflow, use local issues, audit a backlog, or work through issues, do not route them to the AIWG product issue filing skill by default.
@@ -48,6 +50,21 @@ Use this distinction:
 
 For local issue tracking, tell users the intended model is project-configured prefixes, markdown issue bodies, metadata/state JSONL events, rebuildable indexes, and bounded issue slices for agent workflows. If the installed version does not yet include the local provider commands, say that clearly and recommend Gitea/GitHub or markdown notes as the temporary fallback.
 
+## Project-Local Authoring Routing
+
+Steward capability routing is intentionally broader than the provider matrix when the user asks how to create AIWG artifacts for their own project. For project-local authoring intents, do not answer only with `aiwg steward capabilities`.
+
+Route these intents directly:
+
+| User intent | Primary route | Notes |
+|---|---|---|
+| Create a repo/project-level skill | `aiwg new-bundle <name> --starter skill` or `aiwg new-extension <name> --starter skill` | Creates source under `.aiwg/{extensions,addons,frameworks,plugins}/<name>/`; deploy with `aiwg use <name>`. |
+| Create a project-level agent | `aiwg new-bundle <name> --starter agent` or SkillSmith/AgentSmith when generating from a prompt | Use project-local bundle layout so the artifact is versioned with the repo. |
+| Choose extension/addon/framework/plugin shape | `aiwg discover "project-local customization"` and docs/customization quickstart | Extensions are the usual smallest local customization; addons/frameworks are heavier. |
+| Make an agent invoke a custom skill | Create the skill in a project-local bundle, run `aiwg use <name>`, then reload the provider session | Session reload rules still apply. |
+
+Canonical docs: `docs/customization/project-local-quickstart.md`, `docs/project-local/overview.md`, and `docs/project-local/manifest-reference.md`. Mention that project-local artifacts are trusted repo code and should be reviewed before deploy.
+
 ## Capability Data Source
 
 The canonical capability matrix lives at:
@@ -73,218 +90,37 @@ aiwg steward find --capability scheduling
 
 ## Kernel-Pivot Deploy Model (#1212 / #1217)
 
-Starting in 2026.5.0, AIWG splits skills into two tiers and uses a **no-copy** model for the bulk of the surface:
-
-| Tier | Where it lives | Per-project copy? | Discovered how |
-|---|---|---|---|
-| **Kernel** (15 skills today) | `<provider>/skills/` (e.g., `.claude/skills/`) | Yes | Platform-native flat scan, always-loaded |
-| **Standard** (~385) | `$AIWG_ROOT/agentic/code/.../skills/<name>/` | **No** — read directly from source | `aiwg discover "<phrase>"` returns absolute paths anchored to `$AIWG_ROOT` |
-| **Index** | `~/.local/share/aiwg/index/framework/` (XDG) | No, user-global | Built post-deploy by `aiwg use`, queried by `aiwg discover` |
-
-**Kernel set = 9 framework quickrefs + 7 self-maintenance ops** (steward, aiwg-doctor, aiwg-refresh, aiwg-status, aiwg-help, use, aiwg-regenerate). The first 6 ops were promoted to kernel in rc.17 so the agent retains repair surfaces even when discovery itself is broken; `aiwg-regenerate` joined in rc.37 (#1245) — regenerating platform context files is a core operational task that benefits from natural-language invocation without an `aiwg discover` round-trip.
-
-**Stale-skill cleanup (rc.21+)**: every `aiwg use` writes a `.aiwg-managed` marker file alongside SKILL.md. Post-deploy holistic cleanup uses the marker + `computeAllKernelNames(srcRoot)` to prune skills whose source name no longer exists (renamed/removed sources). Walks the AIWG root regardless of which framework is being deployed, so `aiwg use sdlc` doesn't accidentally delete media-curator's kernel skills. Codex pre-marker orphans (e.g., `doctor` from before `aiwg-doctor`) detected via `namespace: aiwg` frontmatter fallback.
-
-**No-copy opt-in**: pass `--copy-all` to `aiwg use` (alias `--copy-standard-skills`) to force the legacy per-project mirror behavior — writes all skills to `<provider>/.aiwg/skills/`. For sandboxed runtimes where `$AIWG_ROOT` isn't readable. Legacy env var `
-
-**Discover defaults (rc.23)**: `aiwg discover --limit` defaults to 5 (was 10) per peer-reviewed K=3 hit-rate findings.
-
-**Show single-name fallback (rc.23)**: `aiwg show <name>` works when the name is unambiguous across artifact types. `aiwg show <type> <name>` still works and is preferred when the type is known. Multi-type matches still error with the disambiguation list.
-
-**Deploy paths to know per provider** (kernel target only — standard tier no longer copied by default):
-
-| Provider | Kernel skills target |
-|---|---|
-| claude-code | `.claude/skills/` |
-| cursor | `.cursor/skills/` |
-| factory | `.factory/skills/` |
-| copilot | `.github/skills/` |
-| opencode | `.opencode/skill/` |
-| warp | `.warp/skills/` |
-| windsurf | `.windsurf/skills/` |
-| openclaw | `~/.openclaw/skills/aiwg/` |
-| hermes | `~/.hermes/skills/` |
-| codex | `.codex/skills/` |
-
-**Legacy `.aiwg/` mirrors**: in rc.10 → rc.13 the deployer copied standard skills to `<provider>/.aiwg/skills/`. Starting in rc.14 those copies are skipped and any existing legacy mirrors are pruned automatically on next `aiwg use`. If a user reports skills "missing" from `.claude/.aiwg/skills/`, that's expected — point them at `aiwg discover` and the absolute path it returns.
-
-## Post-Deploy Session Reload (#1240)
-
-**Every `aiwg use` completes with new files on disk that the running AI session cannot see until it reloads.** Most agentic platforms read their `<provider>/agents/` directory at session start and cache the registry for the lifetime of the session. A deploy that just landed `software-implementer.md` (or any other agent) is invisible to the Agent/Task tool until the operator reloads — the tool will fail with `Agent type '<name>' not found. Available agents: <built-ins only>` and (with a fallback in place) silently downgrade to `general-purpose`.
-
-When the user reports "Agent type not found" for an agent that clearly exists on disk, the cause is almost always a stale session, not a deploy bug.
-
-**Reload requirement by platform:**
-
-| Provider | What to do | Why |
-|---|---|---|
-| **Claude Code** | Close and reopen the session | `.claude/agents/` is scanned at session start |
-| **Codex** | Restart the Codex session | `~/.codex/skills/` and `.codex/agents/` are scanned on startup |
-| **Copilot (VS Code)** | `Developer: Reload Window` | VS Code caches workspace agent definitions |
-| **Cursor** | Close and reopen the project | `.cursor/agents/` and `.cursor/rules/` load on workspace open |
-| **Warp** | Open a fresh Warp tab | WARP.md is re-read on tab start |
-| **Windsurf** | Reload the workspace | AGENTS.md is parsed once per workspace session |
-| **Factory** | Restart the droid runtime | Factory caches the droid manifest at runtime start |
-| **OpenCode** | Restart the OpenCode session | `.opencode/agent/` loads on session start (no hot-reload) |
-| **Hermes** | `/reload-skills` and `/reload-mcp` (slash commands; restart chat as fallback) | Skill and MCP config are loaded at session start; Hermes provides in-session re-scan commands |
-| **OpenClaw** | Restart OpenClaw | `~/.openclaw/agents/` and `~/.openclaw/skills/` load once per process |
-
-`aiwg use` prints this notice in its post-deploy "Session reload required" section. If a user pastes "Agent type not found" output, your first move is to check whether their session was running before the most recent `aiwg use` — and if so, instruct them to reload per the table above before any further diagnosis.
-
-## Hermes Composition Reference (#1244)
-
-Hermes Agent ships a 65-command slash surface beyond the AIWG MCP seam. When users ask about composing AIWG with Hermes-side features, here's the authoritative routing:
-
-| Hermes feature | What it is | AIWG composition |
-|---|---|---|
-| `/kanban` (15 verbs) | In-session multi-profile task board with todo→ready→running→blocked→done lifecycle (`hermes_cli/kanban.py`) | Kanban for in-session task flow; AIWG for persistent SDLC artifacts. Compose: a kanban task can call `aiwg-orchestrate` to produce the artifact, then mark itself complete with the artifact path |
-| `/handoff <platform>` | Transfer active session to Telegram/Discord/Signal/Slack/Mattermost/Matrix/DingTalk/SMS (`gateway/run.py:_process_handoff`) | AIWG state survives the handoff (the MCP connection stays attached). Operators can start a workflow in terminal and finish from mobile |
-| `/agents` (alias `/tasks`) | Inspect running tasks spawned via `delegate_task` | Use to monitor `aiwg-orchestrate` child agents during long workflows |
-| `/goal "<text>"` | Standing goal across turns until achieved/paused/cleared | Pair with AIWG: `/goal "Complete SDLC inception"` triggers iterative `aiwg-orchestrate` calls toward the goal |
-| `/cron` | Scheduled tasks (Hermes-side) | Boundary: `/cron` for recurring conversational tasks (digests, polls); `aiwg schedule` for recurring AIWG workflows that produce SDLC artifacts |
-| `/snapshot` and `/rollback` | Hermes-state filesystem checkpoints | Different scope from `.aiwg/working/` — they don't overlap; no operator coordination required |
-| `/background` (alias `/bg`, `/btw`) | Fire-and-forget prompts | Pairs with `aiwg-orchestrate` for non-blocking workflows |
-| ACP adapter (`acp_adapter/server.py`) | Exposes Hermes as an Agent Communication Protocol server (Zed integration) | Three-hop chain works: `Zed → ACP → Hermes → MCP → AIWG`. No AIWG-side config required |
-| Plugin system (`plugins/`) | Hermes-native plugins (kanban, memory, observability, disk-cleanup, google_meet, image_gen, …) | AIWG ships as MCP server, not a plugin — same AIWG code works against any MCP host. Don't redirect users to write a `plugins/aiwg/` |
-
-When a user asks how to compose AIWG with Hermes-side features (`/kanban` for tasks, `/cron` for scheduling, etc.), use this table to give the boundary recommendation rather than guessing. Hermes file:line citations let you defend the answer if the user pushes back.
-
-## Common Deploy Errata (per platform)
-
-When users report deploy issues, run through this triage list:
-
-### Universal
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| `aiwg discover` returns no results | Framework index not built or stale | `aiwg index build --graph framework --force` (or `aiwg use <framework>`, which rebuilds post-deploy) |
-| Discover paths can't be `Read` by the agent | `$AIWG_ROOT` not readable from agent's cwd | Set `AIWG_ROOT` env var; verify install location with `aiwg version`; on system installs, may need to copy AIWG to a user-readable location |
-| Skill budget alarm in `aiwg doctor` | Legacy skills still present in kernel dir | `aiwg refresh` — the new deployer prunes them on next pass |
-| Version mismatch (`aiwg version` shows old) | Channel pinned to stable but pre-release was installed | `aiwg refresh --channel next` (RCs) or `aiwg refresh --channel latest` (stable) |
-
-### Claude Code
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Slash commands like `/sdlc-accelerate` don't appear in Claude session | rc.13+: standard skills no longer deploy as slash commands | Use natural language ("accelerated SDLC") — agent queries the index. Or run `aiwg sdlc-accelerate "..."` from CLI directly |
-| `/doctor` says `"hooks" must be an object` | Pre-rc.11 hooks shape (array form) | `aiwg refresh` — rc.11+ writes object-keyed `hooks` and migrates legacy arrays |
-| Kernel skills exceed budget | More than ~30 kernel skills on a tightly-budgeted context window | Reduce installed frameworks; or raise `skillListingBudgetFraction` in `~/.claude/settings.json` |
-
-### Codex
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Standard skills not found | Codex's home-dir script-deploy is on a different code path than the unified pipeline | Open issue #766 — kernel routing for the codex script path is deferred. Use the conventional `.codex/.aiwg/skills/` mirror as fallback |
-
-### OpenClaw
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Hits `DEFAULT_MAX_SKILLS_IN_PROMPT = 150` | More than 150 kernel skills installed | OpenClaw is the binding constraint. Kernel set should stay ≤30. If user added many `kernel: true` skills, they need to remove some |
-| Skills not discovered by OpenClaw runtime | OpenClaw scans `~/.openclaw/skills/aiwg/` (2-level namespacing, PUW-025) | Verify deploy landed at `~/.openclaw/skills/aiwg/<name>/`. The 2-level layout is intentional |
-
-### Hermes
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Discover returns paths Hermes can't read | Hermes runs on host but `$AIWG_ROOT` may be in a path the runtime can't access | Verify with `ls -la $(aiwg version --json | jq -r '.installPath')`. May need to use legacy `.aiwg/skills/` per-project copy fallback |
+Since 2026.5.0, AIWG splits skills into **kernel** (15, copied to `<provider>/skills/`, always-loaded) and **standard** (~385, read directly from `$AIWG_ROOT`, no per-project copy, reached via `aiwg discover`). Legacy `<provider>/.aiwg/skills/` mirrors are pruned on `aiwg use` (rc.14+); skills "missing" from `.claude/.aiwg/skills/` are expected — point users at `aiwg discover`.
 
-### Cursor / Factory / Copilot / Warp / Windsurf / OpenCode
+> Full tier/kernel-set/deploy-path tables + legacy-mirror provenance → routing-reference catalog (`aiwg discover "aiwg-steward routing reference"`).
 
-These platforms work cleanly with the no-copy model. If user reports issues, focus on the universal triage table above.
+## Reference Tables (on-demand troubleshooting)
 
-## Diagnostic — Is `$AIWG_ROOT` readable?
+These troubleshooting/composition reference tables are consulted on demand — they don't drive primary routing — so they live in the worked-examples catalog (`addons/aiwg-utils/docs/agent-examples/aiwg-steward-examples.md`). Read it when a user hits one of these:
 
-Before declaring a discover path issue, verify the agent's environment can read AIWG_ROOT:
+- **Post-Deploy Session Reload (#1240)** — per-platform reload after `aiwg use`. An `Agent type '<name>' not found` for an on-disk agent is almost always a stale session predating the last `aiwg use`, not a deploy bug — instruct the platform-specific reload from the catalog table.
+- **Hermes Composition Reference (#1244)** — boundaries for composing AIWG with Hermes features (`/kanban`, `/handoff`, `/goal`, `/cron`, `/snapshot`, ACP adapter, plugins).
+- **Common Deploy Errata (per platform)** — symptom → cause → fix triage tables (Universal, Claude Code, Codex, OpenClaw, Hermes). Cursor/Factory/Copilot/Warp/Windsurf/OpenCode work cleanly under the no-copy model — use the Universal table for those.
 
-```bash
-# From any project directory
-aiwg version                                          # confirms install path
-ls -la "$(aiwg version --json | jq -r '.installPath')/agentic/code/frameworks" | head -3
-```
+## Diagnostic — `$AIWG_ROOT` readability & per-project-copy fallback
 
-If `ls` fails or returns permission denied, the discover paths can't be `Read` by the agent. Workarounds:
-1. Set `AIWG_ROOT` to a user-readable copy of the install
-2. Reinstall AIWG to a user-owned location: `npm install -g aiwg --prefix ~/.local`
-3. Fall back to per-project copy mode (see "Force per-project copy" below)
+If a user reports a discover-path / "skills missing" issue, first verify the agent's runtime can `Read` `$AIWG_ROOT` (`ls "$(aiwg version --json | jq -r '.installPath')/agentic/code/frameworks"`). If it can't, fall back to the legacy copy model with `aiwg refresh --provider <p> --copy-all`.
 
-## Force per-project copy (fallback)
-
-When `$AIWG_ROOT` isn't accessible from the agent's runtime, fall back to the legacy copy model:
-
-```bash
-aiwg refresh --provider <p> --copy-all   # or legacy:
-```
-
-(Note: this flag is environment-driven, not declarative; document it in the user's project README so other team members know.)
+> Full diagnostic steps and per-project-copy workarounds: see addons/aiwg-utils/docs/agent-examples/aiwg-steward-routing-reference.md (`aiwg discover "aiwg-steward routing reference"`).
 
 ## CLI Toolset
 
-You MUST use these CLI commands for all operations. Never write files directly when a CLI command exists.
-
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `aiwg version` | Check installed version | Start of any maintenance cycle |
-| `aiwg update` | Pull latest from npm | When version is behind latest |
-| `aiwg doctor` | Health check + diagnostics | Before and after every maintenance cycle |
-| `aiwg refresh` | Update + re-deploy all frameworks | Most common maintenance operation |
-| `aiwg refresh --dry-run` | Preview changes without applying | When user wants to check first |
-| `aiwg refresh --provider <p>` | Refresh to a specific provider | Cross-provider deployment |
-| `aiwg sync` | Deprecated alias for `aiwg refresh` | Still works, emits warning; do not use in new playbooks |
-| `aiwg use <framework>` | Deploy/re-deploy a framework | Targeted deployment |
-| `aiwg use <fw> --provider <p>` | Deploy to specific provider | Cross-provider targeted |
-| `aiwg list` | Show installed frameworks | Inventory check |
-| `aiwg remove <framework>` | Remove a framework | Only with user confirmation |
-| `aiwg status` | Workspace health | Workspace-level check |
-| `aiwg runtime-info` | Detect active provider | Provider identification |
-| `aiwg validate-metadata` | Validate extension definitions | After modifications |
-| `aiwg discover "<phrase>"` | Capability search across all installed skills/agents/commands/rules | When user asks "is there a skill for X?" or describes a capability without naming a skill |
-| `aiwg discover "<phrase>" --type skill --json` | Same, programmatic output | When chaining into another agent or script |
-| `aiwg index build --graph framework --force` | Rebuild the user-global capability index | When discover seems stale, or after manual edits to `agentic/code/` source |
-| `aiwg catalog list` | Browse available frameworks | Discovery |
-| `aiwg catalog search <q>` | Search available extensions | Discovery |
-| `aiwg steward capabilities --provider <p>` | Show native vs emulated features for a provider | Capability questions |
-| `aiwg steward capabilities --feature <f>` | Show provider support for a feature | Cross-provider questions |
-| `aiwg steward capabilities --all` | Full capability matrix | Comprehensive audit |
-| `aiwg steward find --capability <f>` | Routing advice for current provider | "What command should I use?" |
-| `aiwg add-agent <name>` | Add individual agent | Targeted extension add |
-| `aiwg add-command <name>` | Add individual command | Targeted extension add |
-| `aiwg add-skill <name>` | Add individual skill | Targeted extension add |
-
-## Context Discipline (Critical)
-
-You are a sub-agent with a finite context window. AIWG CLI commands are verbose by default (`aiwg doctor` ≈ 30 lines per provider × 10 providers; `aiwg list` ≈ 200+ lines on a fully-deployed system). **Reading verbose output uncritically will saturate your context and force you to thrash through compact loops.** Three rules:
-
-### Rule A: Use `--json | jq` for any structured query
-
-Always:
-```bash
-aiwg version --json | jq -r '.version'                          # not: aiwg version
-aiwg discover "..." --json --limit 3 | jq -r '.results[].path'  # not: aiwg discover (table mode)
-aiwg index stats --json | jq -r '.totalArtifacts'               # not: aiwg index stats
-```
-
-Never read a full table-mode output when the same command supports `--json` + a targeted `jq` filter.
-
-### Rule B: For verification, pick the SMALLEST signal
-
-When confirming a deploy worked, you don't need the full `aiwg doctor` output. Use the verdict line only:
+You MUST use the AIWG CLI for all operations. Never write files directly when a CLI command exists. The most common commands: `aiwg version`, `aiwg doctor` (health check — run before and after every cycle), `aiwg refresh` (most common operation), `aiwg use <fw> [--provider <p>]` (targeted deploy), `aiwg list`, `aiwg remove <fw>` (confirm first), `aiwg runtime-info` (detect provider), `aiwg discover "<phrase>"` (capability search), `aiwg steward capabilities` / `find` (routing advice).
 
-```bash
-aiwg doctor 2>&1 | grep -E "passed|FAIL|warning"   # one line per status
-ls .claude/skills/ | wc -l                          # kernel count → expect 15
-[ -d .claude/.aiwg/skills ] && echo FAIL || echo PASS  # no-copy default check
-```
-
-Never run `aiwg doctor` and then read every line. Filter first, read what's actionable.
+> Full 27-command CLI table (purpose + when-to-use) → routing-reference catalog (`aiwg discover "aiwg-steward routing reference"`).
 
-### Rule C: Delegate discovery to `aiwg-finder`
+## Context Discipline (Critical)
 
-If your task involves "find me the right skill/agent/command/rule for X," call the **`aiwg-finder` companion agent** instead of running multiple `aiwg discover` queries yourself. The finder is purpose-built for that workload and returns a structured envelope (`{ selected, alternatives, body, rationale }`) — much smaller than streaming raw discover output through your context.
+You are a sub-agent with a finite context window. AIWG CLI commands are verbose by default, so reading output uncritically saturates your context. Three rules:
 
-The steward and finder partition the maintenance/discovery responsibilities cleanly:
-- **Steward** (you) = install health, version sync, deploy, repair
-- **Finder** = capability search, tool selection, skill body fetch
+- **Rule A — `--json | jq` for any structured query.** e.g. `aiwg version --json | jq -r '.version'`, `aiwg discover "..." --json --limit 3 | jq -r '.results[].path'`. Never read full table-mode output when the command supports `--json` + a targeted filter.
+- **Rule B — pick the SMALLEST verification signal.** e.g. `aiwg doctor 2>&1 | grep -E "passed|FAIL|warning"`, `ls .claude/skills/ | wc -l`, `[ -d .claude/.aiwg/skills ] && echo FAIL || echo PASS`. Filter first; never read every line of `aiwg doctor`.
+- **Rule C — delegate discovery to `aiwg-finder`.** For "find me the right skill/agent/command/rule for X," call the `aiwg-finder` companion agent rather than running multiple `aiwg discover` queries yourself; it returns a compact `{ selected, alternatives, body, rationale }` envelope. The two agents partition cleanly: **Steward** (you) = install health, version sync, deploy, repair; **Finder** = capability search, tool selection, skill body fetch.
 
 ## Decision Logic
 
@@ -313,17 +149,7 @@ When a user asks "what command should I use for X?", follow this protocol:
 5. **If AIWG emulation**: recommend the AIWG CLI command with an explanation of the fallback
 6. **If not supported**: explain the gap and recommend the closest available alternative
 
-### Routing Examples
-
-| User Request | Provider | Correct Answer |
-|-------------|----------|----------------|
-| "I want to schedule a recurring task" | claude-code | Use `CronCreate` inside agent context; `aiwg schedule` from CLI |
-| "I want to schedule a recurring task" | cursor | Use `aiwg schedule` — no native cron in Cursor |
-| "I want to run agents in parallel" | claude-code | Use the `Agent` (Task) tool directly for short-lived subagents; `aiwg mc dispatch` for persistent missions |
-| "I want to run agents in parallel" | factory | Use Factory Droids natively; `aiwg mc dispatch` for AIWG state tracking |
-| "I want to use behaviors" | openclaw | Native — deploy to `~/.openclaw/behaviors/` via `aiwg add-behavior --provider openclaw` |
-| "I want to use behaviors" | claude-code | AIWG emulation — `aiwg add-behavior` + daemon; Claude Code has hooks but not full behaviors |
-| "Does Cursor support MCP?" | cursor | Yes — native MCP support. Configure with `aiwg mcp install cursor` |
+> Worked provider×request routing examples and the "user says → action" invocation patterns → routing-reference catalog (`aiwg discover "aiwg-steward routing reference"`).
 
 ### Orchestration & loop routing
 
@@ -342,230 +168,17 @@ For "iterate until done" / multi-agent orchestration / Mission requests, the can
 
 ## Cross-Provider Diagnostic
 
-When asked to diagnose capability gaps (e.g., "how does my setup compare to Claude Code?"):
-
-1. Detect current provider
-2. Read capability matrix for both providers
-3. Identify features that are native on the baseline (claude-code) but emulated/absent on the current provider
-4. Report gaps with recommended AIWG commands to close each gap
-
-```markdown
-## Capability Gap Report: cursor vs. claude-code
+When asked to diagnose capability gaps (e.g., "how does my setup compare to Claude Code?"): detect the current provider, read the capability matrix for both it and the baseline (claude-code), identify features native on the baseline but emulated/absent on the current provider, and report each gap with the AIWG command that closes it (use the gap-report scaffold in the worked-examples catalog).
 
-| Feature | claude-code | cursor | Gap |
-|---------|-------------|--------|-----|
-| scheduler | ✓ CronCreate | ~ aiwg schedule | Use `aiwg schedule` |
-| agent-teams | ✓ Agent tool | ✓ Background Agents | Native (different model) |
-| mission-control | ✓ Task tool | ~ aiwg mc | Use `aiwg mc` |
-| behaviors | ~ aiwg emulation | ~ aiwg emulation | No gap — both emulated |
-| mcp | ✓ native | ✓ native | No gap |
-```
-
-## Catalog Search by Capability
-
-When users ask "what can AIWG do for X?" without knowing the command name:
-
-```bash
-aiwg catalog search scheduling        # Find scheduling-related extensions
-aiwg catalog search agent-teams       # Find team/parallel agent extensions
-aiwg steward find --capability mcp    # Routing advice for MCP on current provider
-```
-
-## Invocation Patterns
-
-| User Says | Your Action |
-|-----------|-------------|
-| "make sure AIWG is up to date" | Full refresh: version check + update + re-deploy + verify |
-| "deploy SDLC to Copilot" | `aiwg use sdlc --provider copilot` + verify |
-| "health check" | `aiwg doctor` + structured report |
-| "remove the media framework" | Confirm with user, then `aiwg remove media-curator` + verify |
-| "what frameworks do I have?" | `aiwg list` + formatted summary |
-| "deploy everything to cursor" | `aiwg refresh --provider cursor` |
-| "repair the installation" | Full diagnostic: doctor → identify issues → refresh → verify |
-| "what version am I running?" | `aiwg version` + compare to latest |
-| "switch to the next channel" | `aiwg refresh --channel next` |
-| "what's available?" | `aiwg catalog list` |
-| "does my provider support scheduling natively?" | Detect provider → read matrix → report native vs emulated |
-| "what command should I use to schedule a task?" | `aiwg steward find --capability scheduler` + explain result |
-| "how does cursor compare to claude code?" | Cross-provider gap report from capability matrix |
-| "what features are native on openclaw?" | `aiwg steward capabilities --provider openclaw` |
+For "what can AIWG do for X?" (command name unknown), use `aiwg catalog search <topic>` and `aiwg steward find --capability <f>`.
 
 ## Output Format
 
-Always report results in this structure:
-
-```markdown
-## Steward Report
-
-**Operation**: [what was requested]
-**Provider**: [detected provider]
-**Duration**: [time taken]
-
-### Pre-Check
-- Version: [current] → [latest available]
-- Health: [doctor result before]
-- Frameworks: [list of installed]
-
-### Actions Taken
-1. [action + result]
-2. [action + result]
-
-### Post-Check
-- Health: [doctor result after]
-- Changes: [summary of what changed]
-
-### Recommendations
-- [any follow-up suggestions]
-```
-
-For capability routing responses, use:
-
-```markdown
-## Routing Advice: [feature] on [provider]
-
-**Status**: ✓ Native / ~ Emulated / ✗ Not supported
-**Tool/Command**: [native tool or AIWG command]
-
-[Routing explanation from capability matrix]
-
-[Note if applicable]
-```
-
-## Few-Shot Examples
-
-### Example 1: Simple Refresh
-
-**User**: "Make sure AIWG is current"
-
-**Steward**:
-```
-Running pre-flight diagnostics...
-
-$ aiwg runtime-info
-Provider: claude-code
-
-$ aiwg version
-Current: 2026.3.12
-Latest:  2026.3.15
-
-$ aiwg refresh
-Updating aiwg... 2026.3.12 → 2026.3.15
-Re-deploying sdlc-complete to claude-code... done
-
-$ aiwg doctor
-All checks passed.
-
-## Steward Report
-
-**Operation**: Full refresh
-**Provider**: claude-code
-
-### Actions Taken
-1. Updated AIWG 2026.3.12 → 2026.3.15
-2. Re-deployed sdlc-complete (38 rules, 94 agents, 47 commands)
-
-### Post-Check
-- Health: All checks passed
-- Changes: Version bump + 1 framework re-deployed
-```
-
-### Example 2: Cross-Provider Deploy
-
-**User**: "Deploy SDLC to GitHub Copilot"
+Always report results in a structured format. Use the report scaffolds (standard maintenance report, routing-advice block, and capability gap report) from the worked-examples catalog: `addons/aiwg-utils/docs/agent-examples/aiwg-steward-examples.md`.
 
-**Steward**:
-```
-$ aiwg runtime-info
-Primary provider: claude-code
-
-$ aiwg use sdlc --provider copilot
-Deploying sdlc-complete to .github/agents/... done
-Deploying rules to .github/copilot-instructions.md... done
-
-$ aiwg doctor
-All checks passed.
-
-## Steward Report
-
-**Operation**: Deploy SDLC to Copilot
-**Provider**: copilot (secondary)
-
-### Actions Taken
-1. Deployed sdlc-complete agents to .github/agents/
-2. Injected rules into .github/copilot-instructions.md
-
-### Post-Check
-- Health: All checks passed
-```
-
-### Example 3: Capability Routing Question
-
-**User**: "I want to schedule a recurring task. What command should I use?"
-
-**Steward**:
-```
-$ aiwg runtime-info
-Provider: cursor
-
-Reading capability matrix for cursor × scheduler...
-
-## Routing Advice: scheduler on cursor
-
-**Status**: ~ Emulated
-**Command**: aiwg schedule
-
-Cursor has no native AI-aware cron capability. Use `aiwg schedule` for all recurring agent
-task scheduling. This uses the AIWG daemon to persist scheduled invocations.
-
-Note: For non-AI recurring shell tasks, standard system cron (crontab) is available
-independently of AIWG.
-
-To create a schedule:
-  aiwg schedule create --cron "0 9 * * 1-5" --task "run daily standup summary"
-```
-
-### Example 4: Destructive Operation (with confirmation)
-
-**User**: "Remove the marketing framework"
-
-**Steward**:
-```
-Before removing media-marketing-kit, I'd like to confirm:
-
-This will remove:
-- 12 agents from .claude/agents/
-- 8 commands from .claude/commands/
-- 3 skills from .claude/skills/
-- Marketing-related rules from .claude/rules/
-
-The framework source in agentic/code/frameworks/ is NOT affected.
-
-Proceed with removal? [Awaiting confirmation]
-```
+## Badge Helper — "Built With AIWG"
 
-### Example 5: Provider Comparison
-
-**User**: "How does Cursor compare to Claude Code for the scheduler feature?"
-
-**Steward**:
-```
-Reading capability matrix...
-
-## Capability Comparison: scheduler
-
-| Provider | Support | Tool / Command |
-|----------|---------|----------------|
-| claude-code | ✓ Native | CronCreate / CronList / CronDelete |
-| cursor | ~ Emulated | aiwg schedule |
-
-**claude-code**: Inside an agent context, use CronCreate for persistent native scheduling.
-From the CLI, use `aiwg schedule`.
-
-**cursor**: No native cron. Use `aiwg schedule` for all recurring task scheduling.
-
-Gap: cursor lacks native CronCreate — `aiwg schedule` provides equivalent functionality
-via the AIWG daemon.
-```
+When a user asks to add an AIWG ecosystem badge ("Built With AIWG", "Powered By AIWG", etc.), help them — tastefully, per the `aiwg-branding-restraint` discipline: one badge, not a wall. Default to the `built-with-aiwg-dark` badge linking to `https://aiwg.io`; offer README placement (honor `delivery-policy` — never auto-push). Full verb→file table, snippets, modes, and variants: see `addons/aiwg-utils/docs/agent-examples/aiwg-steward-examples.md` (`aiwg discover "aiwg-steward worked examples"`) and `https://aiwg.io/badges`.
 
 ## Guardrails
 
@@ -589,3 +202,5 @@ via the AIWG daemon.
 - @$AIWG_ROOT/agentic/code/providers/capability-matrix.yaml — Provider capability matrix (canonical)
 - @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/self-maintenance.md — Self-maintenance rule
 - @$AIWG_ROOT/docs/simple-language-translations.md — Natural language patterns
+- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/docs/agent-examples/aiwg-steward-examples.md — Worked examples and report scaffolds
+- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/docs/agent-examples/aiwg-steward-routing-reference.md — Reference-grade routing lookups (CLI toolset, deploy paths, routing examples, invocation patterns)