nodmix 2026.5.25

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 Nodmix's
+Gateway and multi-channel architecture.
+
+## What it does
+
+When you send:
+
+```text
+/btw what changed?
+```
+
+Nodmix:
+
+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, Nodmix 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
+    nodmix models auth login --provider xai --method oauth
+    nodmix models auth login --provider xai --device-code
+    ```
+
+    During a fresh install, the same auth choices are available inside
+    onboarding:
+
+    ```bash
+    nodmix onboard --install-daemon
+    nodmix onboard --install-daemon --auth-choice xai-device-code
+    ```
+
+    Or use an API key:
+
+    ```bash
+    nodmix 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
+    nodmix 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 Nodmix 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 `nodmix onboard --auth-choice xai-oauth` to sign in with Grok, run `nodmix 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.nodmix.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,120 @@
+---
+summary: "Build and test custom workspace skills with SKILL.md"
+title: "Creating skills"
+read_when:
+  - You are creating a new custom skill in your workspace
+  - You need a quick starter workflow for SKILL.md-based skills
+---
+
+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.
+
+For how skills are loaded and prioritized, see [Skills](/tools/skills).
+
+## Create your first skill
+
+<Steps>
+  <Step title="Create the skill directory">
+    Skills live in your workspace. Create a new folder:
+
+    ```bash
+    mkdir -p ~/.nodmix/workspace/skills/hello-world
+    ```
+
+  </Step>
+
+  <Step title="Write SKILL.md">
+    Create `SKILL.md` inside that directory. The frontmatter defines metadata,
+    and the markdown body contains instructions for the agent.
+
+    ```markdown
+    ---
+    name: hello-world
+    description: A simple skill that says hello.
+    ---
+
+    # Hello World Skill
+
+    When the user asks for a greeting, use the `echo` tool to say
+    "Hello from your custom skill!".
+    ```
+
+    Use hyphen-case with lowercase letters, digits, and hyphens for the skill
+    `name`. Keep the folder name and frontmatter `name` aligned.
+
+  </Step>
+
+  <Step title="Add tools (optional)">
+    You can define custom tool schemas in the frontmatter or instruct the agent
+    to use existing system tools (like `exec` or `browser`). Skills can also
+    ship inside plugins alongside the tools they document.
+
+  </Step>
+
+  <Step title="Load the skill">
+    Start a new session so Nodmix picks up the skill:
+
+    ```bash
+    # From chat
+    /new
+
+    # Or restart the gateway
+    nodmix gateway restart
+    ```
+
+    Verify the skill loaded:
+
+    ```bash
+    nodmix skills list
+    ```
+
+  </Step>
+
+  <Step title="Test it">
+    Send a message that should trigger the skill:
+
+    ```bash
+    nodmix agent --message "give me a greeting"
+    ```
+
+    Or just chat with the agent and ask for a greeting.
+
+  </Step>
+</Steps>
+
+## Skill metadata reference
+
+The YAML frontmatter supports these fields:
+
+| Field                               | Required | Description                                                    |
+| ----------------------------------- | -------- | -------------------------------------------------------------- |
+| `name`                              | Yes      | Unique identifier using lowercase letters, digits, and hyphens |
+| `description`                       | Yes      | One-line description shown to the agent                        |
+| `metadata.nodmix.os`              | No       | OS filter (`["darwin"]`, `["linux"]`, etc.)                    |
+| `metadata.nodmix.requires.bins`   | No       | Required binaries on PATH                                      |
+| `metadata.nodmix.requires.config` | No       | Required config keys                                           |
+
+## Best practices
+
+- **Be concise** — instruct the model on _what_ to do, not how to be an AI
+- **Safety first** — if your skill uses `exec`, ensure prompts don't allow arbitrary command injection from untrusted input
+- **Test locally** — use `nodmix agent --message "..."` to test before sharing
+- **Use ClawHub** — browse and contribute skills at [ClawHub](https://clawhub.ai)
+
+## Where skills live
+
+| Location                        | Precedence | Scope                 |
+| ------------------------------- | ---------- | --------------------- |
+| `\<workspace\>/skills/`         | Highest    | Per-agent             |
+| `\<workspace\>/.agents/skills/` | High       | Per-workspace agent   |
+| `~/.agents/skills/`             | Medium     | Shared agent profile  |
+| `~/.nodmix/skills/`           | Medium     | Shared (all agents)   |
+| Bundled (shipped with Nodmix) | Low        | Global                |
+| `skills.load.extraDirs`         | Lowest     | Custom shared folders |
+
+## Related
+
+- [Skills reference](/tools/skills) — loading, precedence, and gating rules
+- [Skills config](/tools/skills-config) — `skills.*` config schema
+- [ClawHub](/clawhub) — public skill registry
+- [Building Plugins](/plugins/building-plugins) — plugins can ship skills