vilvona 1.0.0

package/docs/tools/btw.md

@@ -0,0 +1,159 @@
+---
+summary: "Ephemeral side questions with /btw"
+read_when:
+  - You want to ask a quick side question about the current session
+  - You are implementing or debugging BTW behavior across clients
+title: "BTW side questions"
+---
+
+`/btw` lets you ask a quick side question about the **current session** without
+turning that question into normal conversation history. `/side` is an alias.
+
+It is modeled after Claude Code's `/btw` behavior, but adapted to OpenClaw's
+Gateway and multi-channel architecture.
+
+## What it does
+
+When you send:
+
+```text
+/btw what changed?
+```
+
+OpenClaw:
+
+1. snapshots the current session context,
+2. runs a separate ephemeral side query,
+3. answers only the side question,
+4. leaves the main run alone,
+5. does **not** write the BTW question or answer to session history,
+6. emits the answer as a **live side result** rather than a normal assistant message.
+
+The important mental model is:
+
+- same session context
+- separate one-shot side query
+- same native harness transport when the session uses a native harness
+- no future context pollution
+- no transcript persistence
+
+For Codex harness sessions, BTW stays inside Codex by forking the active
+app-server thread as an ephemeral side thread. That keeps Codex OAuth and native
+thread behavior intact while still isolating the side answer from the parent
+transcript. Like Codex `/side`, the side thread keeps the current Codex
+permissions and native tool surface, with guardrails that tell the model not to
+treat inherited parent-thread work as active instructions. Non-Codex runtimes
+keep the older direct one-shot path.
+
+## What it does not do
+
+`/btw` does **not**:
+
+- create a new durable session,
+- continue the unfinished main task,
+- write BTW question/answer data to transcript history,
+- appear in `chat.history`,
+- survive a reload.
+
+It is intentionally **ephemeral**.
+
+## How context works
+
+BTW uses the current session as **background context only**.
+
+If the main run is currently active, OpenClaw snapshots the current message
+state and includes the in-flight main prompt as background context, while
+explicitly telling the model:
+
+- answer only the side question,
+- do not resume or complete the unfinished main task,
+- do not steer the parent conversation.
+
+That keeps BTW isolated from the main run while still making it aware of what
+the session is about.
+
+## Delivery model
+
+BTW is **not** delivered as a normal assistant transcript message.
+
+At the Gateway protocol level:
+
+- normal assistant chat uses the `chat` event
+- BTW uses the `chat.side_result` event
+
+This separation is intentional. If BTW reused the normal `chat` event path,
+clients would treat it like regular conversation history.
+
+Because BTW uses a separate live event and is not replayed from
+`chat.history`, it disappears after reload.
+
+## Surface behavior
+
+### TUI
+
+In TUI, BTW is rendered inline in the current session view, but it remains
+ephemeral:
+
+- visibly distinct from a normal assistant reply
+- dismissible with `Enter` or `Esc`
+- not replayed on reload
+
+### External channels
+
+On channels like Telegram, WhatsApp, and Discord, BTW is delivered as a
+clearly labeled one-off reply because those surfaces do not have a local
+ephemeral overlay concept.
+
+The answer is still treated as a side result, not normal session history.
+
+### Control UI / web
+
+The Gateway emits BTW correctly as `chat.side_result`, and BTW is not included
+in `chat.history`, so the persistence contract is already correct for web.
+
+The current Control UI still needs a dedicated `chat.side_result` consumer to
+render BTW live in the browser. Until that client-side support lands, BTW is a
+Gateway-level feature with full TUI and external-channel behavior, but not yet
+a complete browser UX.
+
+## When to use BTW
+
+Use `/btw` when you want:
+
+- a quick clarification about the current work,
+- a factual side answer while a long run is still in progress,
+- a temporary answer that should not become part of future session context.
+
+Examples:
+
+```text
+/btw what file are we editing?
+/side what changed while the main run continued?
+/btw what does this error mean?
+/btw summarize the current task in one sentence
+/btw what is 17 * 19?
+```
+
+## When not to use BTW
+
+Do not use `/btw` when you want the answer to become part of the session's
+future working context.
+
+In that case, ask normally in the main session instead of using BTW.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Slash commands" href="/tools/slash-commands" icon="terminal">
+    Native command catalog and chat directives.
+  </Card>
+  <Card title="Thinking levels" href="/tools/thinking" icon="brain">
+    Reasoning effort levels for the side-question model call.
+  </Card>
+  <Card title="Session" href="/concepts/session" icon="comments">
+    Session keys, history, and persistence semantics.
+  </Card>
+  <Card title="Steer command" href="/tools/steer" icon="arrow-right">
+    Inject a steering message into the active run without ending it.
+  </Card>
+</CardGroup>

package/docs/tools/capability-cookbook.md

@@ -0,0 +1,12 @@
+---
+summary: "Redirect to /plugins/adding-capabilities"
+title: "Adding capabilities (redirect)"
+redirect: /plugins/adding-capabilities
+---
+
+This contributor guide moved to [Adding capabilities](/plugins/adding-capabilities).
+
+## Related
+
+- [Plugin internals](/plugins/architecture)
+- [Building plugins](/plugins/building-plugins)

package/docs/tools/clawhub.md

@@ -0,0 +1,5 @@
+---
+summary: "Redirect to /clawhub"
+title: "ClawHub (redirect)"
+redirect: /clawhub
+---

package/docs/tools/code-execution.md

@@ -0,0 +1,173 @@
+---
+summary: "code_execution: run sandboxed remote Python analysis with xAI"
+read_when:
+  - You want to enable or configure code_execution
+  - You want remote analysis without local shell access
+  - You want to combine x_search or web_search with remote Python analysis
+title: "Code execution"
+---
+
+`code_execution` runs sandboxed remote Python analysis on xAI's Responses API. It is registered by the bundled `xai` plugin (under the `tools` contract) and dispatches to the same `https://api.x.ai/v1/responses` endpoint used by `x_search`.
+
+| Property           | Value                                                                             |
+| ------------------ | --------------------------------------------------------------------------------- |
+| Tool name          | `code_execution`                                                                  |
+| Provider plugin    | `xai` (bundled, `enabledByDefault: true`)                                         |
+| Auth               | xAI auth profile, `XAI_API_KEY`, or `plugins.entries.xai.config.webSearch.apiKey` |
+| Default model      | `grok-4-1-fast`                                                                   |
+| Default timeout    | 30 seconds                                                                        |
+| Default `maxTurns` | unset (xAI applies its own internal limit)                                        |
+
+This is different from local [`exec`](/tools/exec):
+
+- `exec` runs shell commands on your machine or paired node.
+- `code_execution` runs Python in xAI's remote sandbox.
+
+Use `code_execution` for:
+
+- Calculations.
+- Tabulation.
+- Quick statistics.
+- Chart-style analysis.
+- Analyzing data returned by `x_search` or `web_search`.
+
+Do **not** use it when you need local files, your shell, your repo, or paired devices. Use [`exec`](/tools/exec) for that.
+
+## Setup
+
+<Steps>
+  <Step title="Provide xAI credentials">
+    Sign in with Grok OAuth using an eligible SuperGrok or X Premium subscription,
+    use the remote-friendly device-code flow, or store an API key. OAuth works
+    for `code_execution` and `x_search`; `XAI_API_KEY` or plugin web-search
+    config can also power Grok `web_search`.
+
+    ```bash
+    openclaw models auth login --provider xai --method oauth
+    openclaw models auth login --provider xai --device-code
+    ```
+
+    During a fresh install, the same auth choices are available inside
+    onboarding:
+
+    ```bash
+    openclaw onboard --install-daemon
+    openclaw onboard --install-daemon --auth-choice xai-device-code
+    ```
+
+    Or use an API key:
+
+    ```bash
+    openclaw models auth login --provider xai --method api-key
+    export XAI_API_KEY=xai-...
+    ```
+
+    Or via config:
+
+    ```json5
+    {
+      plugins: {
+        entries: {
+          xai: {
+            config: {
+              webSearch: {
+                apiKey: "xai-...",
+              },
+            },
+          },
+        },
+      },
+    }
+    ```
+
+  </Step>
+
+  <Step title="Enable and tune code_execution">
+    `code_execution` is available when xAI credentials are available. Set
+    `plugins.entries.xai.config.codeExecution.enabled` to `false` to disable it,
+    or use the same block to tune the model and timeout.
+
+    ```json5
+    {
+      plugins: {
+        entries: {
+          xai: {
+            config: {
+              codeExecution: {
+                enabled: true,
+                model: "grok-4-1-fast", // override the default xAI code-execution model
+                maxTurns: 2,            // optional cap on internal tool turns
+                timeoutSeconds: 30,     // request timeout (default: 30)
+              },
+            },
+          },
+        },
+      },
+    }
+    ```
+
+  </Step>
+
+  <Step title="Restart the Gateway">
+    ```bash
+    openclaw gateway restart
+    ```
+
+    `code_execution` shows up in the agent's tool list once the xAI plugin re-registers with `enabled: true`.
+
+  </Step>
+</Steps>
+
+## How to use it
+
+Ask naturally and make the analysis intent explicit:
+
+```text
+Use code_execution to calculate the 7-day moving average for these numbers: ...
+```
+
+```text
+Use x_search to find posts mentioning OpenClaw this week, then use code_execution to count them by day.
+```
+
+```text
+Use web_search to gather the latest AI benchmark numbers, then use code_execution to compare percent changes.
+```
+
+The tool takes a single `task` parameter internally, so the agent should send the full analysis request and any inline data in one prompt.
+
+## Errors
+
+When the tool runs without auth, it returns a structured `missing_xai_api_key` error pointing at the auth-profile, env var, and config options. The error is JSON, not a thrown exception, so the agent can self-correct:
+
+```json
+{
+  "error": "missing_xai_api_key",
+  "message": "code_execution needs xAI credentials. Run `openclaw onboard --auth-choice xai-oauth` to sign in with Grok, run `openclaw onboard --auth-choice xai-api-key`, set `XAI_API_KEY` in the Gateway environment, or configure `plugins.entries.xai.config.webSearch.apiKey`.",
+  "docs": "https://docs.openclaw.ai/tools/code-execution"
+}
+```
+
+## Limits
+
+- This is remote xAI execution, not local process execution.
+- Treat results as ephemeral analysis, not a persistent notebook session.
+- Do not assume access to local files or your workspace.
+- For fresh X data, use [`x_search`](/tools/web#x_search) first and pipe the result into `code_execution`.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Exec tool" href="/tools/exec" icon="terminal">
+    Local shell execution on your machine or paired node.
+  </Card>
+  <Card title="Exec approvals" href="/tools/exec-approvals" icon="shield">
+    Allow/deny policy for shell execution.
+  </Card>
+  <Card title="Web tools" href="/tools/web" icon="globe">
+    `web_search`, `x_search`, and `web_fetch`.
+  </Card>
+  <Card title="xAI provider" href="/providers/xai" icon="microchip">
+    Grok models, web/x search, and code execution config.
+  </Card>
+</CardGroup>

package/docs/tools/creating-skills.md

@@ -0,0 +1,271 @@
+---
+title: "Creating skills"
+sidebarTitle: "Creating skills"
+summary: "Build, test, and publish custom SKILL.md workspace skills for your OpenClaw agents."
+read_when:
+  - You are creating a new custom skill
+  - You need a quick starter workflow for SKILL.md-based skills
+  - You want to use Skill Workshop to propose a skill for agent review
+---
+
+Skills teach the agent how and when to use tools. Each skill is a directory
+containing a `SKILL.md` file with YAML frontmatter and markdown instructions.
+OpenClaw loads skills from several roots in a defined [precedence order](/tools/skills#loading-order).
+
+## Create your first skill
+
+<Steps>
+  <Step title="Create the skill directory">
+    Skills live in your workspace `skills/` folder. Create a directory for your
+    new skill:
+
+    ```bash
+    mkdir -p ~/.openclaw/workspace/skills/hello-world
+    ```
+
+    You can group skills in subfolders for organization — the skill is still
+    named by the `SKILL.md` frontmatter, not the folder path:
+
+    ```bash
+    mkdir -p ~/.openclaw/workspace/skills/personal/hello-world
+    # skill name is still "hello-world", invoked as /hello-world
+    ```
+
+  </Step>
+
+  <Step title="Write SKILL.md">
+    Create `SKILL.md` inside the directory. The frontmatter defines metadata;
+    the body gives the agent instructions.
+
+    ```markdown
+    ---
+    name: hello-world
+    description: A simple skill that prints a greeting.
+    ---
+
+    # Hello World
+
+    When the user asks for a greeting, use the `exec` tool to run:
+
+    ```bash
+    echo "Hello from your custom skill!"
+    ```
+    ```
+
+    Naming rules:
+    - Use lowercase letters, digits, and hyphens for `name`.
+    - Keep the directory name and frontmatter `name` aligned.
+    - `description` is shown to the agent and in slash-command discovery —
+      keep it one line and under 160 characters.
+
+  </Step>
+
+  <Step title="Verify the skill loaded">
+    ```bash
+    openclaw skills list
+    ```
+
+    OpenClaw watches `SKILL.md` files under skills roots by default. If the
+    watcher is disabled or you are continuing an existing session, start a new
+    one so the agent receives the refreshed list:
+
+    ```bash
+    # From chat — archive current session and start fresh
+    /new
+
+    # Or restart the gateway
+    openclaw gateway restart
+    ```
+
+  </Step>
+
+  <Step title="Test it">
+    Send a message that should trigger the skill:
+
+    ```bash
+    openclaw agent --message "give me a greeting"
+    ```
+
+    Or open a chat and ask the agent directly. Use `/skill hello-world` to
+    invoke it explicitly by name.
+
+  </Step>
+</Steps>
+
+## SKILL.md reference
+
+### Required fields
+
+| Field         | Description                                                     |
+| ------------- | --------------------------------------------------------------- |
+| `name`        | Unique slug using lowercase letters, digits, and hyphens        |
+| `description` | One-line description shown to the agent and in discovery output |
+
+### Optional frontmatter keys
+
+| Field                      | Default | Description                                                                      |
+| -------------------------- | ------- | -------------------------------------------------------------------------------- |
+| `user-invocable`           | `true`  | Expose the skill as a user slash command                                         |
+| `disable-model-invocation` | `false` | Keep the skill out of the agent's system prompt (still runs via `/skill`)        |
+| `command-dispatch`         | —       | Set to `tool` to route the slash command directly to a tool, bypassing the model |
+| `command-tool`             | —       | Tool name to invoke when `command-dispatch: tool` is set                         |
+| `command-arg-mode`         | `raw`   | For tool dispatch, forwards the raw args string to the tool                      |
+| `homepage`                 | —       | URL shown as "Website" in the macOS Skills UI                                    |
+
+For gating fields (`requires.bins`, `requires.env`, etc.) see
+[Skills — Gating](/tools/skills#gating).
+
+### Using `{baseDir}`
+
+Use `{baseDir}` in the skill body to reference files inside the skill
+directory without hardcoding paths:
+
+```markdown
+Run the helper script at `{baseDir}/scripts/run.sh`.
+```
+
+## Adding conditional activation
+
+Gate your skill so it only loads when its dependencies are available:
+
+```markdown
+---
+name: gemini-search
+description: Search using Gemini CLI.
+metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }
+---
+```
+
+<AccordionGroup>
+  <Accordion title="Gating options">
+    | Key | Description |
+    | --- | --- |
+    | `requires.bins` | All binaries must exist on `PATH` |
+    | `requires.anyBins` | At least one binary must exist on `PATH` |
+    | `requires.env` | Each env var must exist in the process or config |
+    | `requires.config` | Each `openclaw.json` path must be truthy |
+    | `os` | Platform filter: `["darwin"]`, `["linux"]`, `["win32"]` |
+    | `always` | Set `true` to skip all gates and always include the skill |
+
+    Full reference: [Skills — Gating](/tools/skills#gating).
+
+  </Accordion>
+  <Accordion title="Environment and API keys">
+    Wire an API key to a skill entry in `openclaw.json`:
+
+    ```json5
+    {
+      skills: {
+        entries: {
+          "gemini-search": {
+            enabled: true,
+            apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
+          },
+        },
+      },
+    }
+    ```
+
+    The key is injected into the host process for that agent turn only.
+    It does not reach the sandbox — see
+    [sandboxed env vars](/tools/skills-config#sandboxed-skills-and-env-vars).
+
+  </Accordion>
+</AccordionGroup>
+
+## Propose via Skill Workshop
+
+For agent-drafted skills or when you want operator review before a skill goes
+live, use [Skill Workshop](/tools/skill-workshop) proposals instead of writing
+`SKILL.md` directly.
+
+```bash
+# Propose a brand-new skill
+openclaw skills workshop propose-create \
+  --name "hello-world" \
+  --description "A simple skill that prints a greeting." \
+  --proposal ./PROPOSAL.md
+
+# Propose an update to an existing skill
+openclaw skills workshop propose-update hello-world \
+  --proposal ./PROPOSAL.md \
+  --description "Updated greeting skill"
+```
+
+Use `--proposal-dir` when the proposal includes support files:
+
+```bash
+openclaw skills workshop propose-create \
+  --name "hello-world" \
+  --description "A simple skill that prints a greeting." \
+  --proposal-dir ./hello-world-proposal/
+```
+
+The directory must contain `PROPOSAL.md`. Support files can go in `assets/`,
+`examples/`, `references/`, `scripts/`, or `templates/`.
+
+After review:
+
+```bash
+openclaw skills workshop inspect <proposal-id>
+openclaw skills workshop apply <proposal-id>
+```
+
+See [Skill Workshop](/tools/skill-workshop) for the full proposal lifecycle.
+
+## Publishing to ClawHub
+
+<Steps>
+  <Step title="Ensure your SKILL.md is complete">
+    Make sure `name`, `description`, and any `metadata.openclaw` gating fields
+    are set. Add a `homepage` URL if you have a project page.
+  </Step>
+  <Step title="Install the ClawHub skill">
+    The ClawHub skill documents the current publish command shape and required
+    metadata:
+
+    ```bash
+    openclaw skills install clawhub-publish
+    ```
+
+  </Step>
+  <Step title="Publish">
+    ```bash
+    clawhub publish
+    ```
+
+    See [ClawHub — Publishing](/clawhub/publishing) for the full flow.
+
+  </Step>
+</Steps>
+
+## Best practices
+
+<Tip>
+  - **Be concise** — instruct the model on *what* to do, not how to be an AI.
+  - **Safety first** — if your skill uses `exec`, ensure prompts do not allow
+    arbitrary command injection from untrusted input.
+  - **Test locally** — use `openclaw agent --message "..."` before sharing.
+  - **Use ClawHub** — browse community skills at [clawhub.ai](https://clawhub.ai)
+    before building from scratch.
+</Tip>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Skills reference" href="/tools/skills" icon="puzzle-piece">
+    Loading order, gating, allowlists, and SKILL.md format.
+  </Card>
+  <Card title="Skill Workshop" href="/tools/skill-workshop" icon="flask">
+    Proposal queue for agent-drafted skills.
+  </Card>
+  <Card title="Skills config" href="/tools/skills-config" icon="gear">
+    Full `skills.*` config schema.
+  </Card>
+  <Card title="ClawHub" href="/clawhub" icon="cloud">
+    Browse and publish skills on the public registry.
+  </Card>
+  <Card title="Building plugins" href="/plugins/building-plugins" icon="plug">
+    Plugins can ship skills alongside the tools they document.
+  </Card>
+</CardGroup>