vilvona 1.0.0

package/docs/concepts/experimental-features.md

@@ -0,0 +1,111 @@
+---
+summary: "What experimental flags mean in OpenClaw and which ones are currently documented"
+title: "Experimental features"
+read_when:
+  - You see an `.experimental` config key and want to know whether it is stable
+  - You want to try preview runtime features without confusing them with normal defaults
+  - You want one place to find the currently documented experimental flags
+---
+
+Experimental features in OpenClaw are **opt-in preview surfaces**. They are
+behind explicit flags because they still need real-world mileage before they
+deserve a stable default or a long-lived public contract.
+
+Treat them differently from normal config:
+
+- Keep them **off by default** unless the related doc tells you to try one.
+- Expect **shape and behavior to change** faster than stable config.
+- Prefer the stable path first when one already exists.
+- If you are rolling OpenClaw out broadly, test experimental flags in a smaller
+  environment before baking them into a shared baseline.
+
+## Currently documented flags
+
+| Surface                  | Key                                                                                        | Use it when                                                                                                                       | More                                                                                          |
+| ------------------------ | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Local model runtime      | `agents.defaults.experimental.localModelLean`, `agents.list[].experimental.localModelLean` | A smaller or stricter local backend chokes on OpenClaw's full default tool surface                                                | [Local Models](/gateway/local-models)                                                         |
+| Memory search            | `agents.defaults.memorySearch.experimental.sessionMemory`                                  | You want `memory_search` to index prior session transcripts and accept the extra storage/indexing cost                            | [Memory configuration reference](/reference/memory-config#session-memory-search-experimental) |
+| Codex harness            | `plugins.entries.codex.config.appServer.experimental.sandboxExecServer`                    | You want native Codex app-server 0.132.0 or newer to target an OpenClaw sandbox-backed exec-server instead of disabling Code Mode | [Codex harness reference](/plugins/codex-harness-reference#sandboxed-native-execution)        |
+| Structured planning tool | `tools.experimental.planTool`                                                              | You want the structured `update_plan` tool exposed for multi-step work tracking in compatible runtimes and UIs                    | [Gateway configuration reference](/gateway/config-tools#toolsexperimental)                    |
+
+## Local model lean mode
+
+`agents.defaults.experimental.localModelLean: true` is a pressure-release valve for weaker local-model setups. When it is on, OpenClaw drops three default tools — `browser`, `cron`, and `message` — from the agent's tool surface for every turn. It also defaults that run to structured Tool Search controls when `tools.toolSearch` is not explicitly configured, so larger plugin, MCP, or client tool catalogs stay behind `tool_search`, `tool_describe`, and `tool_call` instead of being dumped into the prompt. Runs that require direct `message` delivery keep that tool direct instead of enabling the lean-mode Tool Search default. Use `agents.list[].experimental.localModelLean` to enable or disable the same behavior for one configured agent.
+
+### Why these three tools
+
+These three tools have the largest descriptions and the most parameter shapes in the default OpenClaw runtime. On a small-context or stricter OpenAI-compatible backend that is the difference between:
+
+- Tool schemas fitting cleanly in the prompt vs. crowding out conversation history.
+- The model picking the right tool vs. emitting malformed tool calls because there are too many similar-looking schemas.
+- The Chat Completions adapter staying inside the server's structured-output limits vs. tripping a 400 on tool-call payload size.
+
+Removing them does not silently rewire OpenClaw — it just makes the direct tool list shorter. The model still has `read`, `write`, `edit`, `exec`, `apply_patch`, web search/fetch (when configured), memory, and session/agent tools available. Extra catalogs remain callable through Tool Search unless you explicitly set `tools.toolSearch: false`.
+
+### When to turn it on
+
+Enable lean mode when you have already proved the model can talk to the Gateway but full agent turns misbehave. The typical signal chain is:
+
+1. `openclaw infer model run --gateway --model <ref> --prompt "Reply with exactly: pong"` succeeds.
+2. A normal agent turn fails with malformed tool calls, oversized prompts, or the model ignoring its tools.
+3. Toggling `localModelLean: true` clears the failure.
+
+### When to leave it off
+
+If your backend handles the full default runtime cleanly, leave this off. Lean mode is a workaround, not a default. It exists because some local stacks need a smaller tool surface to behave; hosted models and well-resourced local rigs do not.
+
+Lean mode also does not replace `tools.profile`, `tools.allow`/`tools.deny`, or the model `compat.supportsTools: false` escape hatch. If you need a permanent narrower tool surface for a specific agent, prefer those stable knobs over the experimental flag.
+
+If you already tune Tool Search globally, OpenClaw leaves that operator config alone. Set `tools.toolSearch: false` to opt out of the lean-mode Tool Search default.
+
+### Enable
+
+```json5
+{
+  agents: {
+    defaults: {
+      experimental: {
+        localModelLean: true,
+      },
+    },
+  },
+}
+```
+
+For one agent only:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "local",
+        model: "lmstudio/gemma-4-e4b-it",
+        experimental: {
+          localModelLean: true,
+        },
+      },
+    ],
+  },
+}
+```
+
+Restart the Gateway after changing the flag, then confirm the trimmed tool list with:
+
+```bash
+openclaw status --deep
+```
+
+The deep status output lists the active agent tools; `browser`, `cron`, and `message` should be absent when lean mode is on unless the current delivery mode forces direct `message` replies.
+
+## Experimental does not mean hidden
+
+If a feature is experimental, OpenClaw should say so plainly in docs and in the
+config path itself. What it should **not** do is smuggle preview behavior into a
+stable-looking default knob and pretend that is normal. That's how config
+surfaces get messy.
+
+## Related
+
+- [Features](/concepts/features)
+- [Release channels](/install/development-channels)

package/docs/concepts/features.md

@@ -0,0 +1,91 @@
+---
+summary: "OpenClaw capabilities across channels, routing, media, and UX."
+read_when:
+  - You want a full list of what OpenClaw supports
+title: "Features"
+---
+
+## Highlights
+
+<Columns>
+  <Card title="Channels" icon="message-square" href="/channels">
+    Discord, iMessage, Signal, Slack, Telegram, WhatsApp, WebChat, and more with a single Gateway.
+  </Card>
+  <Card title="Plugins" icon="plug" href="/tools/plugin">
+    Bundled plugins add Matrix, Nextcloud Talk, Nostr, Twitch, Zalo, and more without separate installs in normal current releases.
+  </Card>
+  <Card title="Routing" icon="route" href="/concepts/multi-agent">
+    Multi-agent routing with isolated sessions.
+  </Card>
+  <Card title="Media" icon="image" href="/nodes/images">
+    Images, audio, video, documents, and image/video generation.
+  </Card>
+  <Card title="Apps and UI" icon="monitor" href="/platforms">
+    Windows Hub, Web Control UI, macOS app, and mobile nodes.
+  </Card>
+  <Card title="Mobile nodes" icon="smartphone" href="/nodes">
+    iOS and Android nodes with pairing, voice/chat, and rich device commands.
+  </Card>
+</Columns>
+
+## Full list
+
+**Channels:**
+
+- Built-in channels include Discord, Google Chat, iMessage, IRC, Signal, Slack, Telegram, WebChat, and WhatsApp
+- Bundled plugin channels include Feishu, LINE, Matrix, Mattermost, Microsoft Teams, Nextcloud Talk, Nostr, QQ Bot, Synology Chat, Tlon, Twitch, Zalo, and Zalo Personal
+- Optional separately installed channel plugins include Voice Call and third-party packages such as WeChat
+- Third-party channel plugins can extend the Gateway further, such as WeChat
+- Group chat support with mention-based activation
+- DM safety with allowlists and pairing
+
+**Agent:**
+
+- Embedded agent runtime with tool streaming
+- Multi-agent routing with isolated sessions per workspace or sender
+- Sessions: direct chats collapse into shared `main`; groups are isolated
+- Streaming and chunking for long responses
+
+**Auth and providers:**
+
+- 35+ model providers (Anthropic, OpenAI, Google, and more)
+- Subscription auth via OAuth (e.g. OpenAI Codex)
+- Custom and self-hosted provider support (vLLM, SGLang, Ollama, and any OpenAI-compatible or Anthropic-compatible endpoint)
+
+**Media:**
+
+- Images, audio, video, and documents in and out
+- Shared image generation and video generation capability surfaces
+- Voice note transcription
+- Text-to-speech with multiple providers
+
+**Apps and interfaces:**
+
+- WebChat and browser Control UI
+- macOS menu bar companion app
+- iOS node with pairing, Canvas, camera, screen recording, location, and voice
+- Android node with pairing, chat, voice, Canvas, camera, and device commands
+
+**Tools and automation:**
+
+- Browser automation, exec, sandboxing
+- Web search (Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily)
+- Cron jobs and heartbeat scheduling
+- Skills, plugins, and workflow pipelines (Lobster)
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Experimental features" href="/concepts/experimental-features" icon="flask">
+    Opt-in features that have not yet shipped to the default surface.
+  </Card>
+  <Card title="Agent runtime" href="/concepts/agent" icon="robot">
+    Agent runtime model and how runs are dispatched.
+  </Card>
+  <Card title="Channels" href="/channels" icon="message-square">
+    Connect Telegram, WhatsApp, Discord, Slack, and more from one Gateway.
+  </Card>
+  <Card title="Plugins" href="/tools/plugin" icon="plug">
+    Bundled and third-party plugins that extend OpenClaw.
+  </Card>
+</CardGroup>

package/docs/concepts/mantis-slack-desktop-runbook.md

@@ -0,0 +1,231 @@
+---
+summary: "Operator runbook for Mantis Slack desktop QA: GitHub dispatch, local CLI, warm VNC leases, hydrate modes, timing interpretation, artifacts, and failure handling."
+read_when:
+  - Running Mantis Slack desktop QA from GitHub or locally
+  - Debugging slow Mantis Slack desktop runs
+  - Choosing source, prehydrated, or warm-lease mode
+  - Posting screenshot and video evidence to a PR
+title: "Mantis Slack desktop runbook"
+---
+
+Mantis Slack desktop QA is the real-UI lane for Slack-class bugs that need a
+Linux desktop, VNC rescue, Slack Web, a real OpenClaw gateway, screenshots,
+videos, and a PR evidence comment.
+
+Use it when unit tests or the headless Slack live lane cannot prove the bug.
+
+## Storage model
+
+Mantis uses three different storage layers:
+
+- Provider image: owned by Crabbox and stored in the cloud provider account.
+  It contains machine capabilities such as Chrome/Chromium, ffmpeg, scrot,
+  Node/corepack/pnpm, native build tools, and empty cache directories.
+- Warm lease state: owned by the current operator session. It can contain a
+  logged-in browser profile, `/var/cache/crabbox/pnpm`, and a prepared source
+  checkout while the lease is alive.
+- Mantis artifacts: owned by the OpenClaw run. They live under
+  `.artifacts/qa-e2e/mantis/...`, then GitHub Actions uploads them and the
+  Mantis GitHub App comments inline evidence on the PR.
+
+Never put secrets, browser cookies, Slack login state, repository checkouts,
+`node_modules`, or `dist/` into a prebaked provider image.
+
+## GitHub dispatch
+
+Run the workflow from `main`:
+
+```bash
+gh workflow run mantis-slack-desktop-smoke.yml \
+  --ref main \
+  -f candidate_ref=<trusted-ref-or-sha> \
+  -f pr_number=<pr-number> \
+  -f scenario_id=slack-canary \
+  -f crabbox_provider=aws \
+  -f keep_vm=false \
+  -f hydrate_mode=source
+```
+
+Allowed `candidate_ref` values are intentionally narrow because the workflow
+uses live credentials: current `main` ancestry, release tags, or an open PR head
+from `openclaw/openclaw`.
+
+The workflow writes:
+
+- uploaded artifact: `mantis-slack-desktop-smoke-<run-id>-<attempt>`;
+- inline PR comment from the Mantis GitHub App;
+- `slack-desktop-smoke.png`;
+- `slack-desktop-smoke.mp4`;
+- `slack-desktop-smoke-preview.gif`;
+- `slack-desktop-smoke-change.mp4`;
+- `mantis-slack-desktop-smoke-summary.json`;
+- `mantis-slack-desktop-smoke-report.md`;
+- remote logs such as `slack-desktop-command.log`, `openclaw-gateway.log`,
+  `chrome.log`, and `ffmpeg.log`.
+
+The PR comment is updated in place by the hidden
+`<!-- mantis-slack-desktop-smoke -->` marker.
+
+## Local CLI
+
+Cold source proof:
+
+```bash
+pnpm openclaw qa mantis slack-desktop-smoke \
+  --provider aws \
+  --class standard \
+  --gateway-setup \
+  --credential-source convex \
+  --credential-role maintainer \
+  --provider-mode live-frontier \
+  --model openai/gpt-5.4 \
+  --alt-model openai/gpt-5.4 \
+  --scenario slack-canary \
+  --hydrate-mode source
+```
+
+Keep the VM for VNC rescue:
+
+```bash
+pnpm openclaw qa mantis slack-desktop-smoke \
+  --provider aws \
+  --class standard \
+  --gateway-setup \
+  --scenario slack-canary \
+  --keep-lease
+```
+
+Open VNC:
+
+```bash
+crabbox vnc --provider aws --id <cbx_id> --open
+```
+
+Reuse a warm lease:
+
+```bash
+pnpm openclaw qa mantis slack-desktop-smoke \
+  --provider aws \
+  --lease-id <cbx_id-or-slug> \
+  --gateway-setup \
+  --scenario slack-canary \
+  --hydrate-mode source
+```
+
+Use `--hydrate-mode prehydrated` only when the reused remote workspace already
+has `node_modules` and a built `dist/`. Mantis fails closed if those are
+missing.
+
+Prove native Slack approval UI:
+
+```bash
+pnpm openclaw qa mantis slack-desktop-smoke \
+  --provider aws \
+  --class standard \
+  --approval-checkpoints \
+  --credential-source convex \
+  --credential-role maintainer \
+  --hydrate-mode source
+```
+
+Approval checkpoint mode is mutually exclusive with `--gateway-setup`. It runs
+the opt-in `slack-approval-exec-native` and `slack-approval-plugin-native`
+scenarios unless you pass explicit approval checkpoint `--scenario` flags; other
+Slack scenarios are rejected before the VM starts. The Slack QA runner writes
+each checkpoint JSON file from the real Slack API message it observed, then the
+remote watcher renders that message snapshot into
+`approval-checkpoints/<scenario>-pending.png` and
+`approval-checkpoints/<scenario>-resolved.png`. The run fails if any checkpoint
+JSON, message evidence, ack JSON, or rendered screenshot is missing or empty.
+
+Cold GitHub Actions leases do not have Slack Web cookies, so their browser
+capture can land on Slack sign-in. For approval checkpoint proof, trust the
+rendered checkpoint images and Slack QA artifacts rather than
+`slack-desktop-smoke.png`. Use a kept warm lease with a manually logged-in Slack
+Web profile only when the browser screenshot itself must show Slack Web.
+
+## Hydrate modes
+
+| Mode          | Use when                                  | Remote behavior                                                                       | Tradeoff                                                 |
+| ------------- | ----------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `source`      | Normal PR proof, cold machines, CI        | Runs `pnpm install --frozen-lockfile --prefer-offline` and `pnpm build` inside the VM | Slowest, strongest source-checkout proof                 |
+| `prehydrated` | You intentionally prepared a reused lease | Requires existing `node_modules` and `dist/`; skips install/build                     | Fast, but only valid for operator-controlled warm leases |
+
+GitHub Actions always prepares the candidate checkout before the VM run. Its
+pnpm store is cached by OS, Node version, and lockfile. The VM source run also
+uses `/var/cache/crabbox/pnpm` when present.
+
+## Timing interpretation
+
+`mantis-slack-desktop-smoke-report.md` includes phase timings:
+
+- `crabbox.warmup`: cloud provider boot, desktop/browser readiness, and SSH.
+- `crabbox.inspect`: lease metadata lookup.
+- `credentials.prepare`: Convex credential lease acquisition.
+- `crabbox.remote_run`: sync, browser launch, OpenClaw install/build or
+  hydrate validation, gateway startup, screenshot, and video capture.
+- `artifacts.copy`: rsync back from the VM.
+
+`crabbox.remote_run` can be marked `accepted` when Crabbox returns a non-zero
+remote status after Mantis has copied metadata proving that either the OpenClaw
+gateway setup completed or the Slack QA command itself exited successfully.
+Treat `accepted` as pass-with-explanation, not a failed scenario.
+
+If the run is slow:
+
+- warmup dominates: prebake or promote a better Crabbox provider image;
+- remote_run dominates in `source`: use a warm lease, improve pnpm store reuse,
+  or move machine prerequisites into the provider image;
+- remote_run dominates in `prehydrated`: the remote workspace was not actually
+  ready, or the gateway/browser/Slack setup is slow;
+- artifact copy dominates: inspect video size and artifact directory contents.
+
+## Evidence checklist
+
+A good PR comment should show:
+
+- scenario id and candidate SHA;
+- GitHub Actions run URL;
+- artifact URL;
+- inline approval checkpoint screenshot, or a Slack Web screenshot from a
+  logged-in warm lease;
+- inline animated preview when available;
+- full MP4 and trimmed MP4 links;
+- pass/fail status;
+- timing summary in the attached report.
+
+Do not commit screenshots or videos into the repository. Keep them in GitHub
+Actions artifacts or the PR comment.
+
+## Failure handling
+
+If the workflow fails before the VM run, inspect the Actions job first. Typical
+causes are untrusted `candidate_ref`, missing environment secrets, or candidate
+install/build failure.
+
+If the VM run fails but screenshots were copied back, inspect:
+
+```bash
+cat mantis-slack-desktop-smoke-report.md
+cat mantis-slack-desktop-smoke-summary.json
+cat slack-desktop-command.log
+cat openclaw-gateway.log
+cat chrome.log
+cat ffmpeg.log
+```
+
+If the run kept the lease, open VNC with the report's `crabbox vnc ...` command.
+Stop the lease when done:
+
+```bash
+crabbox stop --provider aws <cbx_id-or-slug>
+```
+
+If Slack login expired, repair it in VNC on a kept lease and rerun with
+`--lease-id`. Do not bake that browser profile into a provider image.
+
+## Related
+
+- [QA overview](/concepts/qa-e2e-automation)
+- [Slack channel](/channels/slack)
+- [Testing](/help/testing)