vilvona 1.0.0

package/docs/platforms/macos.md

@@ -0,0 +1,228 @@
+---
+summary: "OpenClaw macOS companion app (menu bar + gateway broker)"
+read_when:
+  - Implementing macOS app features
+  - Changing gateway lifecycle or node bridging on macOS
+title: "macOS app"
+---
+
+The macOS app is the **menu-bar companion** for OpenClaw. It owns permissions,
+manages/attaches to the Gateway locally (launchd or manual), and exposes macOS
+capabilities to the agent as a node.
+
+## What it does
+
+- Shows native notifications and status in the menu bar.
+- Owns TCC prompts (Notifications, Accessibility, Screen Recording, Microphone,
+  Speech Recognition, Automation/AppleScript).
+- Runs or connects to the Gateway (local or remote).
+- Exposes macOS-only tools (Canvas, Camera, Screen Recording, `system.run`).
+- Starts the local node host service in **remote** mode (launchd), and stops it in **local** mode.
+- Optionally hosts **PeekabooBridge** for UI automation.
+- Installs the global CLI (`openclaw`) on request via npm, pnpm, or bun (the app prefers npm, then pnpm, then bun; Node remains the recommended Gateway runtime).
+
+## Local vs remote mode
+
+- **Local** (default): the app attaches to a running local Gateway if present;
+  otherwise it enables the launchd service via `openclaw gateway install`.
+- **Remote**: the app connects to a Gateway over SSH/Tailscale and never starts
+  a local process.
+  The app starts the local **node host service** so the remote Gateway can reach this Mac.
+  The app does not spawn the Gateway as a child process.
+  Gateway discovery now prefers Tailscale MagicDNS names over raw tailnet IPs,
+  so the Mac app recovers more reliably when tailnet IPs change.
+
+## Launchd control
+
+The app manages a per-user LaunchAgent labeled `ai.openclaw.gateway`
+(or `ai.openclaw.<profile>` when using `--profile`/`OPENCLAW_PROFILE`; legacy `com.openclaw.*` still unloads).
+
+```bash
+launchctl kickstart -k gui/$UID/ai.openclaw.gateway
+launchctl bootout gui/$UID/ai.openclaw.gateway
+```
+
+Replace the label with `ai.openclaw.<profile>` when running a named profile.
+
+If the LaunchAgent isn't installed, enable it from the app or run
+`openclaw gateway install`.
+
+If the gateway repeatedly disappears for minutes to hours and only resumes when you touch the Control UI or SSH into the host, see the troubleshooting note for macOS Maintenance Sleep / `ENETDOWN` crashes and launchd's respawn-protection gate in [Gateway troubleshooting](/gateway/troubleshooting#macos-gateway-silently-stops-responding-then-resumes-when-you-touch-the-dashboard).
+
+## Node capabilities (mac)
+
+The macOS app presents itself as a node. Common commands:
+
+- Canvas: `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*`
+- Camera: `camera.snap`, `camera.clip`
+- Screen: `screen.snapshot`, `screen.record`
+- System: `system.run`, `system.notify`
+
+The node reports a `permissions` map so agents can decide what's allowed.
+
+Node service + app IPC:
+
+- When the headless node host service is running (remote mode), it connects to the Gateway WS as a node.
+- `system.run` executes in the macOS app (UI/TCC context) over a local Unix socket; prompts + output stay in-app.
+
+Diagram (SCI):
+
+```
+Gateway -> Node Service (WS)
+                 |  IPC (UDS + token + HMAC + TTL)
+                 v
+             Mac App (UI + TCC + system.run)
+```
+
+## Exec approvals (system.run)
+
+`system.run` is controlled by **Exec approvals** in the macOS app (Settings → Exec approvals).
+Security + ask + allowlist are stored locally on the Mac in:
+
+```
+~/.openclaw/exec-approvals.json
+```
+
+Example:
+
+```json
+{
+  "version": 1,
+  "defaults": {
+    "security": "deny",
+    "ask": "on-miss"
+  },
+  "agents": {
+    "main": {
+      "security": "allowlist",
+      "ask": "on-miss",
+      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
+    }
+  }
+}
+```
+
+Notes:
+
+- `allowlist` entries are glob patterns for resolved binary paths, or bare command names for PATH-invoked commands.
+- Raw shell command text that contains shell control or expansion syntax (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) is treated as an allowlist miss and requires explicit approval (or allowlisting the shell binary).
+- Choosing "Always Allow" in the prompt adds that command to the allowlist.
+- `system.run` environment overrides are filtered (drops `PATH`, `DYLD_*`, `LD_*`, `BASHOPTS`, `FPATH`, `KSH_ENV`, `NODE_OPTIONS`, `NODE_REDIRECT_WARNINGS`, `NODE_REPL_EXTERNAL_MODULE`, `NODE_REPL_HISTORY`, `NODE_V8_COVERAGE`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`, `TCLLIBPATH`) and then merged with the app's environment.
+- For shell wrappers (`bash|sh|zsh ... -c/-lc`), request-scoped environment overrides are reduced to a small explicit allowlist (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
+- For allow-always decisions in allowlist mode, known dispatch wrappers (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) persist inner executable paths instead of wrapper paths. If unwrapping is not safe, no allowlist entry is persisted automatically.
+
+## Deep links
+
+The app registers the `openclaw://` URL scheme for local actions.
+
+### `openclaw://agent`
+
+Triggers a Gateway `agent` request.
+
+```bash
+open 'openclaw://agent?message=Hello%20from%20deep%20link'
+```
+
+Query parameters:
+
+- `message` (required)
+- `sessionKey` (optional)
+- `thinking` (optional)
+- `deliver` / `to` / `channel` (optional)
+- `timeoutSeconds` (optional)
+- `key` (optional unattended mode key)
+
+Safety:
+
+- Without `key`, the app prompts for confirmation.
+- Without `key`, the app enforces a short message limit for the confirmation prompt and ignores `deliver` / `to` / `channel`.
+- With a valid `key`, the run is unattended (intended for personal automations).
+
+## Onboarding flow (typical)
+
+1. Install and launch **OpenClaw.app**.
+2. Complete the permissions checklist (TCC prompts).
+3. Ensure **Local** mode is active and the Gateway is running.
+4. Install the CLI if you want terminal access.
+
+## State dir placement (macOS)
+
+Avoid putting your OpenClaw state dir in iCloud or other cloud-synced folders.
+Sync-backed paths can add latency and occasionally cause file-lock/sync races for
+sessions and credentials.
+
+Prefer a local non-synced state path such as:
+
+```bash
+OPENCLAW_STATE_DIR=~/.openclaw
+```
+
+If `openclaw doctor` detects state under:
+
+- `~/Library/Mobile Documents/com~apple~CloudDocs/...`
+- `~/Library/CloudStorage/...`
+
+it will warn and recommend moving back to a local path.
+
+## Build and dev workflow (native)
+
+- `cd apps/macos && swift build`
+- `swift run OpenClaw` (or Xcode)
+- Package app: `scripts/package-mac-app.sh`
+
+## Debug gateway connectivity (macOS CLI)
+
+Use the debug CLI to exercise the same Gateway WebSocket handshake and discovery
+logic that the macOS app uses, without launching the app.
+
+```bash
+cd apps/macos
+swift run openclaw-mac connect --json
+swift run openclaw-mac discover --timeout 3000 --json
+```
+
+Connect options:
+
+- `--url <ws://host:port>`: override config
+- `--mode <local|remote>`: resolve from config (default: config or local)
+- `--probe`: force a fresh health probe
+- `--timeout <ms>`: request timeout (default: `15000`)
+- `--json`: structured output for diffing
+
+Discovery options:
+
+- `--include-local`: include gateways that would be filtered as "local"
+- `--timeout <ms>`: overall discovery window (default: `2000`)
+- `--json`: structured output for diffing
+
+<Tip>
+Compare against `openclaw gateway discover --json` to see whether the macOS app's discovery pipeline (`local.` plus the configured wide-area domain, with wide-area and Tailscale Serve fallbacks) differs from the Node CLI's `dns-sd` based discovery.
+</Tip>
+
+## Remote connection plumbing (SSH tunnels)
+
+When the macOS app runs in **Remote** mode, it opens an SSH tunnel so local UI
+components can talk to a remote Gateway as if it were on localhost.
+
+### Control tunnel (Gateway WebSocket port)
+
+- **Purpose:** health checks, status, Web Chat, config, and other control-plane calls.
+- **Local port:** the Gateway port (default `18789`), always stable.
+- **Remote port:** the same Gateway port on the remote host.
+- **Behavior:** no random local port; the app reuses an existing healthy tunnel
+  or restarts it if needed.
+- **SSH shape:** `ssh -N -L <local>:127.0.0.1:<remote>` with BatchMode +
+  ExitOnForwardFailure + keepalive options.
+- **IP reporting:** the SSH tunnel uses loopback, so the gateway will see the node
+  IP as `127.0.0.1`. Use **Direct (ws/wss)** transport if you want the real client
+  IP to appear (see [macOS remote access](/platforms/mac/remote)).
+
+For setup steps, see [macOS remote access](/platforms/mac/remote). For protocol
+details, see [Gateway protocol](/gateway/protocol).
+
+## Related docs
+
+- [Gateway runbook](/gateway)
+- [Gateway (macOS)](/platforms/mac/bundled-gateway)
+- [macOS permissions](/platforms/mac/permissions)
+- [Canvas](/platforms/mac/canvas)

package/docs/platforms/oracle.md

@@ -0,0 +1,12 @@
+---
+summary: "Redirect to /install/oracle"
+title: "Oracle Cloud (platform)"
+redirect: /install/oracle
+---
+
+This page has moved to [Oracle Cloud](/install/oracle).
+
+## Related
+
+- [Install overview](/install)
+- [VPS hosting](/vps)

package/docs/platforms/raspberry-pi.md

@@ -0,0 +1,13 @@
+---
+summary: "Redirect to /install/raspberry-pi"
+title: "Raspberry Pi (platform)"
+redirect: /install/raspberry-pi
+---
+
+This page has moved to [Raspberry Pi](/install/raspberry-pi).
+
+## Related
+
+- [Install overview](/install)
+- [Linux server](/vps)
+- [Platforms](/platforms)

package/docs/platforms/windows.md

@@ -0,0 +1,304 @@
+---
+summary: "Windows support: Windows Hub, native CLI and Gateway, WSL2 gateway setup, node mode, and troubleshooting"
+read_when:
+  - Installing OpenClaw on Windows
+  - Choosing between Windows Hub, native Windows, and WSL2
+  - Setting up the Windows companion app or Windows node mode
+title: "Windows"
+---
+
+OpenClaw ships a native **Windows Hub** companion app plus Windows CLI support.
+Use Windows Hub when you want a desktop app with setup, tray status, chat,
+Command Center diagnostics, and Windows node capabilities. Use the PowerShell
+installer when you want the CLI/Gateway directly. Use WSL2 when you want the
+most Linux-compatible Gateway runtime.
+
+## Recommended: Windows Hub
+
+Windows Hub is the native WinUI companion app for Windows 10 20H2+ and Windows 11. It installs without administrator privileges and is published with signed
+x64 and ARM64 installers on OpenClaw releases.
+
+Download the latest stable installer:
+
+- [OpenClawCompanion-Setup-x64.exe](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-Setup-x64.exe)
+- [OpenClawCompanion-Setup-arm64.exe](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-Setup-arm64.exe)
+- [Checksums](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-SHA256SUMS.txt)
+
+After install, launch **OpenClaw Companion** from the Start menu or the system
+tray. The installer also adds shortcuts for Gateway Setup, Chat, Settings,
+Check for Updates, and uninstall.
+
+### What Windows Hub includes
+
+- system tray status and launch-at-login
+- first-run setup for a local app-owned WSL Gateway
+- connection settings for local, remote, and SSH-tunneled Gateways
+- native chat window plus access to the browser Control UI
+- Command Center diagnostics for sessions, usage, channels, nodes, pairing, and
+  repair commands
+- Windows node mode for agent-controlled canvas, screen, camera, notifications,
+  device status, text-to-speech, speech-to-text, and controlled `system.run`
+- local MCP server mode for MCP clients such as Claude Desktop, Claude Code, and
+  Cursor
+
+### First launch
+
+On first launch, Windows Hub opens setup when there is no usable saved Gateway.
+The fastest path is **Set up locally**, which provisions an app-owned
+`OpenClawGateway` WSL distro, installs the Gateway inside it, and pairs the app.
+This does not export or mutate your existing Ubuntu distro.
+
+Choose **Advanced setup** or open the Connections tab when you already have a
+Gateway. You can connect to:
+
+- a local Gateway on this PC
+- a WSL Gateway on this PC
+- a remote Gateway by URL and token or setup code
+- a Gateway reached through an SSH tunnel
+
+When setup finishes, the tray icon turns green. Open **Command Center** from the
+tray to confirm connection, pairing, node status, and channel health.
+
+## Windows node mode
+
+Windows Hub can register as a first-class OpenClaw node. The agent can then use
+declared Windows-native capabilities through the Gateway.
+
+Common commands include:
+
+- `canvas.present`, `canvas.hide`, `canvas.navigate`, `canvas.eval`,
+  `canvas.snapshot`
+- `screen.snapshot` and, with explicit opt-in, `screen.record`
+- `camera.list` and, with explicit opt-in, `camera.snap`, `camera.clip`
+- `system.notify`, `system.run`, `system.run.prepare`, `system.which`
+- `location.get`, `device.info`, `device.status`
+- `stt.transcribe`, `tts.speak`
+
+Node mode requires Gateway pairing. If the app shows a pairing request, approve
+it from the Gateway host:
+
+```powershell
+openclaw devices list
+openclaw devices approve <request-id>
+openclaw nodes status
+```
+
+The Gateway only forwards commands that the node declares and server policy
+allows. Privacy-sensitive commands such as `screen.record`, `camera.snap`, and
+`camera.clip` require explicit `gateway.nodes.allowCommands` opt-in.
+
+## Local MCP mode
+
+Windows Hub can expose the same Windows-native capability registry as a local
+MCP server on loopback. This is useful when you want local MCP clients to drive
+Windows capabilities without a running OpenClaw Gateway.
+
+Enable it in Windows Hub Settings under the developer/advanced section. The app
+shows the loopback endpoint and bearer token after the server is enabled.
+
+Mode matrix:
+
+| Node mode | MCP server | Behavior                           |
+| --------- | ---------- | ---------------------------------- |
+| off       | off        | Operator-only desktop app          |
+| on        | off        | Gateway-connected Windows node     |
+| off       | on         | Local MCP server only              |
+| on        | on         | Gateway node plus local MCP server |
+
+## Native Windows CLI and Gateway
+
+For terminal-first use, install OpenClaw from PowerShell:
+
+```powershell
+iwr -useb https://openclaw.ai/install.ps1 | iex
+```
+
+Verify:
+
+```powershell
+openclaw --version
+openclaw doctor
+openclaw gateway status --json
+```
+
+Native Windows CLI and Gateway flows are supported and continue to improve.
+Managed startup uses Windows Scheduled Tasks when available and falls back to a
+per-user Startup-folder login item if task creation is denied.
+
+To install the Gateway service:
+
+```powershell
+openclaw gateway install
+openclaw gateway status --json
+```
+
+If you only want CLI use without a managed Gateway service:
+
+```powershell
+openclaw onboard --non-interactive --skip-health
+openclaw gateway run
+```
+
+## WSL2 Gateway
+
+WSL2 remains the most Linux-compatible Gateway runtime on Windows. Windows Hub
+can set up an app-owned WSL Gateway for you, or you can install manually inside
+your own distro.
+
+Manual setup:
+
+```powershell
+wsl --install
+# Or pick a distro explicitly:
+wsl --list --online
+wsl --install -d Ubuntu-24.04
+```
+
+Enable systemd inside WSL:
+
+```bash
+sudo tee /etc/wsl.conf >/dev/null <<'EOF'
+[boot]
+systemd=true
+EOF
+```
+
+Restart WSL from PowerShell:
+
+```powershell
+wsl --shutdown
+```
+
+Then install OpenClaw inside WSL with the Linux quickstart:
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash
+openclaw gateway status
+```
+
+## Gateway auto-start before Windows login
+
+For headless WSL setups, ensure the full boot chain runs even when no one logs
+into Windows.
+
+Inside WSL:
+
+```bash
+sudo loginctl enable-linger "$(whoami)"
+openclaw gateway install
+```
+
+In PowerShell as Administrator:
+
+```powershell
+schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM
+```
+
+Replace `Ubuntu` with your distro name from:
+
+```powershell
+wsl --list --verbose
+```
+
+After reboot, verify from WSL:
+
+```bash
+systemctl --user is-enabled openclaw-gateway.service
+systemctl --user status openclaw-gateway.service --no-pager
+```
+
+## Expose WSL services over LAN
+
+WSL has its own virtual network. If another machine must reach a service inside
+WSL, forward a Windows port to the current WSL IP. The WSL IP can change after
+restarts, so refresh the forwarding rule when needed.
+
+Example in PowerShell as Administrator:
+
+```powershell
+$Distro = "Ubuntu-24.04"
+$ListenPort = 2222
+$TargetPort = 22
+
+$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
+if (-not $WslIp) { throw "WSL IP not found." }
+
+netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
+  connectaddress=$WslIp connectport=$TargetPort
+
+New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
+  -Protocol TCP -LocalPort $ListenPort -Action Allow
+```
+
+Notes:
+
+- SSH from another machine targets the Windows host IP, for example
+  `ssh user@windows-host -p 2222`.
+- Remote nodes must point at a reachable Gateway URL, not `127.0.0.1`.
+- Use `listenaddress=0.0.0.0` for LAN access. Use `127.0.0.1` for local-only
+  access.
+
+## Troubleshooting
+
+### The tray icon does not appear
+
+Check Task Manager for `OpenClaw.Tray.WinUI.exe`. If it is running, open the
+hidden tray-icons area and pin it. If it is not running, launch **OpenClaw
+Companion** from the Start menu.
+
+### Local setup fails
+
+Open the setup log from Windows Hub or inspect:
+
+```powershell
+notepad "$env:LOCALAPPDATA\OpenClawTray\Logs\Setup\easy-setup-latest.txt"
+```
+
+Common causes are disabled WSL, blocked virtualization, stale app-owned WSL
+state, or a network failure while installing the Gateway package.
+
+### The app says pairing is required
+
+Approve the operator or node request from the Gateway:
+
+```powershell
+openclaw devices list
+openclaw devices approve <request-id>
+```
+
+If the device already had a token, reconnect from the Connections tab after
+approval.
+
+### Web chat cannot reach a remote Gateway
+
+Remote web chat needs HTTPS or localhost. For self-signed certificates, trust
+the certificate in Windows, or use an SSH tunnel to a localhost URL.
+
+### `screen.snapshot`, camera, or audio commands fail
+
+Confirm Windows permissions for camera, microphone, screen capture, and
+notifications. Packaged installs declare the protected capabilities, but Windows
+may still prompt the first time a command uses them.
+
+### Git or GitHub connectivity fails
+
+Some networks block or throttle HTTPS to GitHub. If `git clone` or `gh auth
+login` fails, try another network, a VPN, or an HTTP/HTTPS proxy.
+
+For token-based `gh` auth in the current session:
+
+```powershell
+$env:GH_TOKEN="<your-token>"
+gh auth status
+gh auth setup-git
+```
+
+Never commit tokens or paste them into issues or pull requests.
+
+## Related
+
+- [Install overview](/install)
+- [Node.js setup](/install/node)
+- [Nodes](/nodes)
+- [Control UI](/web/control-ui)
+- [Gateway configuration](/gateway/configuration)

package/docs/plugins/adding-capabilities.md

@@ -0,0 +1,146 @@
+---
+summary: "Contributor guide for adding a new shared capability to the OpenClaw plugin system"
+read_when:
+  - Adding a new core capability and plugin registration surface
+  - Deciding whether code belongs in core, a vendor plugin, or a feature plugin
+  - Wiring a new runtime helper for channels or tools
+title: "Adding capabilities (contributor guide)"
+sidebarTitle: "Adding capabilities"
+---
+
+<Info>
+  This is a **contributor guide** for OpenClaw core developers. If you are
+  building an external plugin, see [Building plugins](/plugins/building-plugins)
+  instead. For the deep architecture reference (capability model, ownership,
+  load pipeline, runtime helpers), see [Plugin internals](/plugins/architecture).
+</Info>
+
+Use this when OpenClaw needs a new shared domain such as embeddings, image
+generation, video generation, or some future vendor-backed feature area.
+
+The rule:
+
+- **plugin** = ownership boundary
+- **capability** = shared core contract
+
+Do not start by wiring a vendor directly into a channel or a tool. Start by defining the capability.
+
+## When to create a capability
+
+Create a new capability when **all** of these are true:
+
+1. More than one vendor could plausibly implement it.
+2. Channels, tools, or feature plugins should consume it without caring about the vendor.
+3. Core needs to own fallback, policy, config, or delivery behavior.
+
+If the work is vendor-only and no shared contract exists yet, stop and define the contract first.
+
+## The standard sequence
+
+1. Define the typed core contract.
+2. Add plugin registration for that contract.
+3. Add a shared runtime helper.
+4. Wire one real vendor plugin as proof.
+5. Move feature/channel consumers onto the runtime helper.
+6. Add contract tests.
+7. Document the operator-facing config and ownership model.
+
+## What goes where
+
+**Core:**
+
+- Request/response types.
+- Provider registry + resolution.
+- Fallback behavior.
+- Config schema with propagated `title` / `description` docs metadata on nested object, wildcard, array-item, and composition nodes.
+- Runtime helper surface.
+
+**Vendor plugin:**
+
+- Vendor API calls.
+- Vendor auth handling.
+- Vendor-specific request normalization.
+- Registration of the capability implementation.
+
+**Feature/channel plugin:**
+
+- Calls `api.runtime.*` or the matching `plugin-sdk/*-runtime` helper.
+- Never calls a vendor implementation directly.
+
+## Provider and harness seams
+
+Use **provider hooks** when the behavior belongs to the model provider contract rather than the generic agent loop. Examples include provider-specific request params after transport selection, auth-profile preference, prompt overlays, and follow-up fallback routing after model/profile failover.
+
+Use **agent harness hooks** when the behavior belongs to the runtime that is executing a turn. Harnesses can classify successful-but-unusable attempt results such as empty, reasoning-only, or planning-only responses so the outer model fallback policy can make the retry decision.
+
+Keep both seams narrow:
+
+- Core owns the retry/fallback policy.
+- Provider plugins own provider-specific request/auth/routing hints.
+- Harness plugins own runtime-specific attempt classification.
+- Third-party plugins return hints, not direct mutations of core state.
+
+## File checklist
+
+For a new capability, expect to touch these areas:
+
+- `src/<capability>/types.ts`
+- `src/<capability>/...registry/runtime.ts`
+- `src/plugins/types.ts`
+- `src/plugins/registry.ts`
+- `src/plugins/captured-registration.ts`
+- `src/plugins/contracts/registry.ts`
+- `src/plugins/runtime/types-core.ts`
+- `src/plugins/runtime/index.ts`
+- `src/plugin-sdk/<capability>.ts`
+- `src/plugin-sdk/<capability>-runtime.ts`
+- One or more bundled plugin packages.
+- Config, docs, tests.
+
+## Worked example: image generation
+
+Image generation follows the standard shape:
+
+1. Core defines `ImageGenerationProvider`.
+2. Core exposes `registerImageGenerationProvider(...)`.
+3. Core exposes `runtime.imageGeneration.generate(...)`.
+4. The `openai`, `google`, `fal`, and `minimax` plugins register vendor-backed implementations.
+5. Future vendors register the same contract without changing channels/tools.
+
+The config key is intentionally separate from vision-analysis routing:
+
+- `agents.defaults.imageModel` analyzes images.
+- `agents.defaults.imageGenerationModel` generates images.
+
+Keep those separate so fallback and policy remain explicit.
+
+## Embedding providers
+
+Use `embeddingProviders` for reusable vector embedding providers. This contract
+is intentionally broader than memory: tools, search, retrieval, importers, or
+future feature plugins can consume embeddings without depending on the memory
+engine.
+
+Memory search can consume generic `embeddingProviders`. The older
+`memoryEmbeddingProviders` contract is deprecated compatibility while existing
+memory-specific providers migrate; new reusable embedding providers should use
+`embeddingProviders`.
+
+## Review checklist
+
+Before shipping a new capability, verify:
+
+- No channel/tool imports vendor code directly.
+- The runtime helper is the shared path.
+- At least one contract test asserts bundled ownership.
+- Config docs name the new model/config key.
+- Plugin docs explain the ownership boundary.
+
+If a PR skips the capability layer and hardcodes vendor behavior into a channel/tool, send it back and define the contract first.
+
+## Related
+
+- [Plugin internals](/plugins/architecture) — capability model, ownership, load pipeline, runtime helpers.
+- [Building plugins](/plugins/building-plugins) — first-plugin tutorial.
+- [SDK overview](/plugins/sdk-overview) — import map and registration API reference.
+- [Creating skills](/tools/creating-skills) — companion contributor surface.