nodmix 2026.5.25

package/docs/tools/exec.md

@@ -0,0 +1,282 @@
+---
+summary: "Exec tool usage, stdin modes, and TTY support"
+read_when:
+  - Using or modifying the exec tool
+  - Debugging stdin or TTY behavior
+title: "Exec tool"
+---
+
+Run shell commands in the workspace. `exec` is a mutating shell surface: commands can create, edit, or delete files wherever the selected host or sandbox filesystem permits. Disabling Nodmix filesystem tools such as `write`, `edit`, or `apply_patch` does not make `exec` read-only.
+
+Supports foreground + background execution via `process`. If `process` is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
+Background sessions are scoped per agent; `process` only sees sessions from the same agent.
+
+## Parameters
+
+<ParamField path="command" type="string" required>
+Shell command to run.
+</ParamField>
+
+<ParamField path="workdir" type="string" default="cwd">
+Working directory for the command.
+</ParamField>
+
+<ParamField path="env" type="object">
+Key/value environment overrides merged on top of the inherited environment.
+</ParamField>
+
+<ParamField path="yieldMs" type="number" default="10000">
+Auto-background the command after this delay (ms).
+</ParamField>
+
+<ParamField path="background" type="boolean" default="false">
+Background the command immediately instead of waiting for `yieldMs`.
+</ParamField>
+
+<ParamField path="timeout" type="number" default="tools.exec.timeoutSec">
+Override the configured exec timeout for this call. Set `timeout: 0` only when the command should run without the exec process timeout.
+</ParamField>
+
+<ParamField path="pty" type="boolean" default="false">
+Run in a pseudo-terminal when available. Use for TTY-only CLIs, coding agents, and terminal UIs.
+</ParamField>
+
+<ParamField path="host" type="'auto' | 'sandbox' | 'gateway' | 'node'" default="auto">
+Where to execute. `auto` resolves to `sandbox` when a sandbox runtime is active and `gateway` otherwise.
+</ParamField>
+
+<ParamField path="security" type="'deny' | 'allowlist' | 'full'">
+Ignored for normal tool calls. `gateway` / `node` security is controlled by
+`tools.exec.security` and `~/.nodmix/exec-approvals.json`; elevated mode can
+force `security=full` only when the operator explicitly grants elevated access.
+</ParamField>
+
+<ParamField path="ask" type="'off' | 'on-miss' | 'always'">
+Approval prompt behavior for `gateway` / `node` execution.
+</ParamField>
+
+<ParamField path="node" type="string">
+Node id/name when `host=node`.
+</ParamField>
+
+<ParamField path="elevated" type="boolean" default="false">
+Request elevated mode — escape the sandbox onto the configured host path. `security=full` is forced only when elevated resolves to `full`.
+</ParamField>
+
+Notes:
+
+- `host` defaults to `auto`: sandbox when sandbox runtime is active for the session, otherwise gateway.
+- `host` only accepts `auto`, `sandbox`, `gateway`, or `node`. It is not a hostname selector; hostname-like values are rejected before the command runs.
+- `auto` is the default routing strategy, not a wildcard. Per-call `host=node` is allowed from `auto`; per-call `host=gateway` is only allowed when no sandbox runtime is active.
+- With no extra config, `host=auto` still "just works": no sandbox means it resolves to `gateway`; a live sandbox means it stays in the sandbox.
+- `elevated` escapes the sandbox onto the configured host path: `gateway` by default, or `node` when `tools.exec.host=node` (or the session default is `host=node`). It is only available when elevated access is enabled for the current session/provider.
+- `gateway`/`node` approvals are controlled by `~/.nodmix/exec-approvals.json`.
+- `node` requires a paired node (companion app or headless node host).
+- If multiple nodes are available, set `exec.node` or `tools.exec.node` to select one.
+- `exec host=node` is the only shell-execution path for nodes; the legacy `nodes.run` wrapper has been removed.
+- `timeout` applies to foreground, background, `yieldMs`, gateway, sandbox, and node `system.run` execution. If omitted, Nodmix uses `tools.exec.timeoutSec`; explicit `timeout: 0` disables the exec process timeout for that call.
+- On non-Windows hosts, exec uses `SHELL` when set; if `SHELL` is `fish`, it prefers `bash` (or `sh`)
+  from `PATH` to avoid fish-incompatible scripts, then falls back to `SHELL` if neither exists.
+- On Windows hosts, exec prefers PowerShell 7 (`pwsh`) discovery (Program Files, ProgramW6432, then PATH),
+  then falls back to Windows PowerShell 5.1.
+- Host execution (`gateway`/`node`) rejects `env.PATH` and loader overrides (`LD_*`/`DYLD_*`) to
+  prevent binary hijacking or injected code.
+- Nodmix sets `NODMIX_SHELL=exec` in the spawned command environment (including PTY and sandbox execution) so shell/profile rules can detect exec-tool context.
+- `nodmix channels login` is blocked from `exec` because it is an interactive channel-auth flow; run it in a terminal on the gateway host, or use the channel-native login tool from chat when one exists.
+- Important: sandboxing is **off by default**. If sandboxing is off, implicit `host=auto`
+  resolves to `gateway`. Explicit `host=sandbox` still fails closed instead of silently
+  running on the gateway host. Enable sandboxing or use `host=gateway` with approvals.
+- Script preflight checks (for common Python/Node shell-syntax mistakes) only inspect files inside the
+  effective `workdir` boundary. If a script path resolves outside `workdir`, preflight is skipped for
+  that file.
+- For long-running work that starts now, start it once and rely on automatic
+  completion wake when it is enabled and the command emits output or fails.
+  Use `process` for logs, status, input, or intervention; do not emulate
+  scheduling with sleep loops, timeout loops, or repeated polling.
+- For work that should happen later or on a schedule, use cron instead of
+  `exec` sleep/delay patterns.
+
+## Config
+
+- `tools.exec.notifyOnExit` (default: true): when true, backgrounded exec sessions enqueue a system event and request a heartbeat on exit.
+- `tools.exec.approvalRunningNoticeMs` (default: 10000): emit a single "running" notice when an approval-gated exec runs longer than this (0 disables).
+- `tools.exec.timeoutSec` (default: 1800): default per-command exec timeout in seconds. Per-call `timeout` overrides it; per-call `timeout: 0` disables the exec process timeout.
+- `tools.exec.host` (default: `auto`; resolves to `sandbox` when sandbox runtime is active, `gateway` otherwise)
+- `tools.exec.security` (default: `deny` for sandbox, `full` for gateway + node when unset)
+- `tools.exec.ask` (default: `off`)
+- No-approval host exec is the default for gateway + node. If you want approvals/allowlist behavior, tighten both `tools.exec.*` and the host `~/.nodmix/exec-approvals.json`; see [Exec approvals](/tools/exec-approvals#yolo-mode-no-approval).
+- YOLO comes from the host-policy defaults (`security=full`, `ask=off`), not from `host=auto`. If you want to force gateway or node routing, set `tools.exec.host` or use `/exec host=...`.
+- In `security=full` plus `ask=off` mode, host exec follows the configured policy directly; there is no extra heuristic command-obfuscation prefilter or script-preflight rejection layer.
+- `tools.exec.node` (default: unset)
+- `tools.exec.strictInlineEval` (default: false): when true, inline interpreter eval forms such as `python -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `lua -e`, and `osascript -e` always require explicit approval. `allow-always` can still persist benign interpreter/script invocations, but inline-eval forms still prompt each time.
+- `tools.exec.commandHighlighting` (default: false): when true, approval prompts can highlight parser-derived command spans in the command text. Set to `true` globally or per agent to enable command text highlighting without changing exec approval policy.
+- `tools.exec.pathPrepend`: list of directories to prepend to `PATH` for exec runs (gateway + sandbox only).
+- `tools.exec.safeBins`: stdin-only safe binaries that can run without explicit allowlist entries. For behavior details, see [Safe bins](/tools/exec-approvals-advanced#safe-bins-stdin-only).
+- `tools.exec.safeBinTrustedDirs`: additional explicit directories trusted for `safeBins` path checks. `PATH` entries are never auto-trusted. Built-in defaults are `/bin` and `/usr/bin`.
+- `tools.exec.safeBinProfiles`: optional custom argv policy per safe bin (`minPositional`, `maxPositional`, `allowedValueFlags`, `deniedFlags`).
+
+Example:
+
+```json5
+{
+  tools: {
+    exec: {
+      pathPrepend: ["~/bin", "/opt/oss/bin"],
+    },
+  },
+}
+```
+
+### PATH handling
+
+- `host=gateway`: merges your login-shell `PATH` into the exec environment. `env.PATH` overrides are
+  rejected for host execution. The daemon itself still runs with a minimal `PATH`:
+  - macOS: `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`
+  - Linux: `/usr/local/bin`, `/usr/bin`, `/bin`
+    - To prevent user shell configuration (like `~/.zshenv` or `/etc/zshenv`) from overriding priority paths during startup, `tools.exec.pathPrepend` entries are securely prepended to the final `PATH` inside the shell command right before execution.
+- `host=sandbox`: runs `sh -lc` (login shell) inside the container, so `/etc/profile` may reset `PATH`.
+  Nodmix prepends `env.PATH` after profile sourcing via an internal env var (no shell interpolation);
+  `tools.exec.pathPrepend` applies here too.
+- `host=node`: only non-blocked env overrides you pass are sent to the node. `env.PATH` overrides are
+  rejected for host execution and ignored by node hosts. If you need additional PATH entries on a node,
+  configure the node host service environment (systemd/launchd) or install tools in standard locations.
+
+Per-agent node binding (use the agent list index in config):
+
+```bash
+nodmix config get agents.list
+nodmix config set agents.list[0].tools.exec.node "node-id-or-name"
+```
+
+Control UI: the Nodes tab includes a small "Exec node binding" panel for the same settings.
+
+## Session overrides (`/exec`)
+
+Use `/exec` to set **per-session** defaults for `host`, `security`, `ask`, and `node`.
+Send `/exec` with no arguments to show the current values.
+
+Example:
+
+```
+/exec host=auto security=allowlist ask=on-miss node=mac-1
+```
+
+## Authorization model
+
+`/exec` is only honored for **authorized senders** (channel allowlists/pairing plus `commands.useAccessGroups`).
+It updates **session state only** and does not write config. To hard-disable exec, deny it via tool
+policy (`tools.deny: ["exec"]` or per-agent). Host approvals still apply unless you explicitly set
+`security=full` and `ask=off`.
+
+## Exec approvals (companion app / node host)
+
+Sandboxed agents can require per-request approval before `exec` runs on the gateway or node host.
+See [Exec approvals](/tools/exec-approvals) for the policy, allowlist, and UI flow.
+
+When approvals are required, the exec tool returns immediately with
+`status: "approval-pending"` and an approval id. Once approved (or denied / timed out),
+the Gateway emits system events (`Exec finished` / `Exec denied`). If the command is still
+running after `tools.exec.approvalRunningNoticeMs`, a single `Exec running` notice is emitted.
+On channels with native approval cards/buttons, the agent should rely on that
+native UI first and only include a manual `/approve` command when the tool
+result explicitly says chat approvals are unavailable or manual approval is the
+only path.
+
+## Allowlist + safe bins
+
+Manual allowlist enforcement matches resolved binary path globs and bare command-name
+globs. Bare names match only commands invoked through PATH, so `rg` can match
+`/opt/homebrew/bin/rg` when the command is `rg`, but not `./rg` or `/tmp/rg`.
+When `security=allowlist`, shell commands are auto-allowed only if every pipeline
+segment is allowlisted or a safe bin. Chaining (`;`, `&&`, `||`) and redirections
+are rejected in allowlist mode unless every top-level segment satisfies the
+allowlist (including safe bins). Redirections remain unsupported.
+Durable `allow-always` trust does not bypass that rule: a chained command still requires every
+top-level segment to match.
+
+`autoAllowSkills` is a separate convenience path in exec approvals. It is not the same as
+manual path allowlist entries. For strict explicit trust, keep `autoAllowSkills` disabled.
+
+Use the two controls for different jobs:
+
+- `tools.exec.safeBins`: small, stdin-only stream filters.
+- `tools.exec.safeBinTrustedDirs`: explicit extra trusted directories for safe-bin executable paths.
+- `tools.exec.safeBinProfiles`: explicit argv policy for custom safe bins.
+- allowlist: explicit trust for executable paths.
+
+Do not treat `safeBins` as a generic allowlist, and do not add interpreter/runtime binaries (for example `python3`, `node`, `ruby`, `bash`). If you need those, use explicit allowlist entries and keep approval prompts enabled.
+`nodmix security audit` warns when interpreter/runtime `safeBins` entries are missing explicit profiles, and `nodmix doctor --fix` can scaffold missing custom `safeBinProfiles` entries.
+`nodmix security audit` and `nodmix doctor` also warn when you explicitly add broad-behavior bins such as `jq` back into `safeBins`.
+If you explicitly allowlist interpreters, enable `tools.exec.strictInlineEval` so inline code-eval forms still require a fresh approval.
+
+For full policy details and examples, see [Exec approvals](/tools/exec-approvals-advanced#safe-bins-stdin-only) and [Safe bins versus allowlist](/tools/exec-approvals-advanced#safe-bins-versus-allowlist).
+
+## Examples
+
+Foreground:
+
+```json
+{ "tool": "exec", "command": "ls -la" }
+```
+
+Background + poll:
+
+```json
+{"tool":"exec","command":"npm run build","yieldMs":1000}
+{"tool":"process","action":"poll","sessionId":"<id>"}
+```
+
+Polling is for on-demand status, not waiting loops. If automatic completion wake
+is enabled, the command can wake the session when it emits output or fails.
+
+Send keys (tmux-style):
+
+```json
+{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
+{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
+{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}
+```
+
+Submit (send CR only):
+
+```json
+{ "tool": "process", "action": "submit", "sessionId": "<id>" }
+```
+
+Paste (bracketed by default):
+
+```json
+{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
+```
+
+## apply_patch
+
+`apply_patch` is a subtool of `exec` for structured multi-file edits.
+It is enabled by default for OpenAI and OpenAI Codex models. Use config only
+when you want to disable it or restrict it to specific models:
+
+```json5
+{
+  tools: {
+    exec: {
+      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.5"] },
+    },
+  },
+}
+```
+
+Notes:
+
+- Only available for OpenAI/OpenAI Codex models.
+- Tool policy still applies; `allow: ["write"]` implicitly allows `apply_patch`.
+- `deny: ["write"]` does not deny `apply_patch`; deny `apply_patch` explicitly or use `deny: ["group:fs"]` when patch writes should also be blocked.
+- Config lives under `tools.exec.applyPatch`.
+- `tools.exec.applyPatch.enabled` defaults to `true`; set it to `false` to disable the tool for OpenAI models.
+- `tools.exec.applyPatch.workspaceOnly` defaults to `true` (workspace-contained). Set it to `false` only if you intentionally want `apply_patch` to write/delete outside the workspace directory.
+
+## Related
+
+- [Exec Approvals](/tools/exec-approvals) — approval gates for shell commands
+- [Sandboxing](/gateway/sandboxing) — running commands in sandboxed environments
+- [Background Process](/gateway/background-process) — long-running exec and process tool
+- [Security](/gateway/security) — tool policy and elevated access

package/docs/tools/firecrawl.md

@@ -0,0 +1,155 @@
+---
+summary: "Firecrawl search, scrape, and web_fetch fallback"
+read_when:
+  - You want Firecrawl-backed web extraction
+  - You need a Firecrawl API key
+  - You want Firecrawl as a web_search provider
+  - You want anti-bot extraction for web_fetch
+title: "Firecrawl"
+---
+
+Nodmix can use **Firecrawl** in three ways:
+
+- as the `web_search` provider
+- as explicit plugin tools: `firecrawl_search` and `firecrawl_scrape`
+- as a fallback extractor for `web_fetch`
+
+It is a hosted extraction/search service that supports bot circumvention and caching,
+which helps with JS-heavy sites or pages that block plain HTTP fetches.
+
+## Get an API key
+
+1. Create a Firecrawl account and generate an API key.
+2. Store it in config or set `FIRECRAWL_API_KEY` in the gateway environment.
+
+## Configure Firecrawl search
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "firecrawl",
+      },
+    },
+  },
+  plugins: {
+    entries: {
+      firecrawl: {
+        enabled: true,
+        config: {
+          webSearch: {
+            apiKey: "FIRECRAWL_API_KEY_HERE",
+            baseUrl: "https://api.firecrawl.dev",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- Choosing Firecrawl in onboarding or `nodmix configure --section web` enables the bundled Firecrawl plugin automatically.
+- `web_search` with Firecrawl supports `query` and `count`.
+- For Firecrawl-specific controls like `sources`, `categories`, or result scraping, use `firecrawl_search`.
+- `baseUrl` defaults to hosted Firecrawl at `https://api.firecrawl.dev`. Self-hosted overrides are allowed only for private/internal endpoints; HTTP is accepted only for those private targets.
+- `FIRECRAWL_BASE_URL` is the shared env fallback for Firecrawl search and scrape base URLs.
+
+## Configure Firecrawl scrape + web_fetch fallback
+
+```json5
+{
+  plugins: {
+    entries: {
+      firecrawl: {
+        enabled: true,
+        config: {
+          webFetch: {
+            apiKey: "FIRECRAWL_API_KEY_HERE",
+            baseUrl: "https://api.firecrawl.dev",
+            onlyMainContent: true,
+            maxAgeMs: 172800000,
+            timeoutSeconds: 60,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- Firecrawl fallback attempts run only when an API key is available (`plugins.entries.firecrawl.config.webFetch.apiKey` or `FIRECRAWL_API_KEY`).
+- `maxAgeMs` controls how old cached results can be (ms). Default is 2 days.
+- Legacy `tools.web.fetch.firecrawl.*` config is auto-migrated by `nodmix doctor --fix`.
+- Firecrawl scrape/base URL overrides follow the same hosted/private rule as search: public hosted traffic uses `https://api.firecrawl.dev`; self-hosted overrides must resolve to private/internal endpoints.
+- `firecrawl_scrape` rejects obvious private, loopback, metadata, and non-HTTP(S) target URLs before forwarding them to Firecrawl, matching the `web_fetch` target-safety contract for explicit Firecrawl scrape calls.
+
+`firecrawl_scrape` reuses the same `plugins.entries.firecrawl.config.webFetch.*` settings and env vars.
+
+### Self-hosted Firecrawl
+
+Set `plugins.entries.firecrawl.config.webSearch.baseUrl`,
+`plugins.entries.firecrawl.config.webFetch.baseUrl`, or `FIRECRAWL_BASE_URL`
+when you run Firecrawl yourself. Nodmix accepts `http://` only for loopback,
+private-network, `.local`, `.internal`, or `.localhost` targets. Public custom
+hosts are rejected so Firecrawl API keys are not sent to arbitrary endpoints by
+accident.
+
+## Firecrawl plugin tools
+
+### `firecrawl_search`
+
+Use this when you want Firecrawl-specific search controls instead of generic `web_search`.
+
+Core parameters:
+
+- `query`
+- `count`
+- `sources`
+- `categories`
+- `scrapeResults`
+- `timeoutSeconds`
+
+### `firecrawl_scrape`
+
+Use this for JS-heavy or bot-protected pages where plain `web_fetch` is weak.
+
+Core parameters:
+
+- `url`
+- `extractMode`
+- `maxChars`
+- `onlyMainContent`
+- `maxAgeMs`
+- `proxy`
+- `storeInCache`
+- `timeoutSeconds`
+
+## Stealth / bot circumvention
+
+Firecrawl exposes a **proxy mode** parameter for bot circumvention (`basic`, `stealth`, or `auto`).
+Nodmix always uses `proxy: "auto"` plus `storeInCache: true` for Firecrawl requests.
+If proxy is omitted, Firecrawl defaults to `auto`. `auto` retries with stealth proxies if a basic attempt fails, which may use more credits
+than basic-only scraping.
+
+## How `web_fetch` uses Firecrawl
+
+`web_fetch` extraction order:
+
+1. Readability (local)
+2. Firecrawl (if selected or auto-detected as the active web-fetch fallback)
+3. Basic HTML cleanup (last fallback)
+
+The selection knob is `tools.web.fetch.provider`. If you omit it, Nodmix
+auto-detects the first ready web-fetch provider from available credentials.
+Today the bundled provider is Firecrawl.
+
+## Related
+
+- [Web Search overview](/tools/web) -- all providers and auto-detection
+- [Web Fetch](/tools/web-fetch) -- web_fetch tool with Firecrawl fallback
+- [Tavily](/tools/tavily) -- search + extract tools

package/docs/tools/gemini-search.md

@@ -0,0 +1,114 @@
+---
+summary: "Gemini web search with Google Search grounding"
+read_when:
+  - You want to use Gemini for web_search
+  - You need a GEMINI_API_KEY or models.providers.google.apiKey
+  - You want Google Search grounding
+title: "Gemini search"
+---
+
+Nodmix supports Gemini models with built-in
+[Google Search grounding](https://ai.google.dev/gemini-api/docs/grounding),
+which returns AI-synthesized answers backed by live Google Search results with
+citations.
+
+## Get an API key
+
+<Steps>
+  <Step title="Create a key">
+    Go to [Google AI Studio](https://aistudio.google.com/apikey) and create an
+    API key.
+  </Step>
+  <Step title="Store the key">
+    Set `GEMINI_API_KEY` in the Gateway environment, reuse
+    `models.providers.google.apiKey`, or configure a dedicated web-search key via:
+
+    ```bash
+    nodmix configure --section web
+    ```
+
+  </Step>
+</Steps>
+
+## Config
+
+```json5
+{
+  plugins: {
+    entries: {
+      google: {
+        config: {
+          webSearch: {
+            apiKey: "AIza...", // optional if GEMINI_API_KEY or models.providers.google.apiKey is set
+            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // optional; falls back to models.providers.google.baseUrl
+            model: "gemini-2.5-flash", // default
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "gemini",
+      },
+    },
+  },
+}
+```
+
+**Credential precedence:** Gemini web search uses
+`plugins.entries.google.config.webSearch.apiKey` first, then `GEMINI_API_KEY`,
+then `models.providers.google.apiKey`. For base URLs, the dedicated
+`plugins.entries.google.config.webSearch.baseUrl` wins before
+`models.providers.google.baseUrl`.
+
+For a gateway install, put env keys in `~/.nodmix/.env`.
+
+## How it works
+
+Unlike traditional search providers that return a list of links and snippets,
+Gemini uses Google Search grounding to produce AI-synthesized answers with
+inline citations. The results include both the synthesized answer and the source
+URLs.
+
+- Citation URLs from Gemini grounding are automatically resolved from Google
+  redirect URLs to direct URLs.
+- Redirect resolution uses the SSRF guard path (HEAD + redirect checks +
+  http/https validation) before returning the final citation URL.
+- Redirect resolution uses strict SSRF defaults, so redirects to
+  private/internal targets are blocked.
+
+## Supported parameters
+
+Gemini search supports `query`, `freshness`, `date_after`, and `date_before`.
+
+`count` is accepted for shared `web_search` compatibility, but Gemini grounding
+still returns one synthesized answer with citations rather than an N-result
+list.
+
+`freshness` accepts `day`, `week`, `month`, `year`, and the shared shortcuts
+`pd`, `pw`, `pm`, and `py`. Nodmix converts these values, or an explicit
+`date_after`/`date_before` range, into Gemini Google Search grounding's
+`timeRangeFilter`. `country`, `language`, and `domain_filter` are not supported.
+
+## Model selection
+
+The default model is `gemini-2.5-flash` (fast and cost-effective). Any Gemini
+model that supports grounding can be used via
+`plugins.entries.google.config.webSearch.model`.
+
+## Base URL overrides
+
+Set `plugins.entries.google.config.webSearch.baseUrl` when Gemini web search
+must route through an operator proxy or custom Gemini-compatible endpoint. If
+that is unset, Gemini web search reuses `models.providers.google.baseUrl`. A plain
+`https://generativelanguage.googleapis.com` value is normalized to
+`https://generativelanguage.googleapis.com/v1beta`; custom proxy paths are kept
+as provided after trimming trailing slashes.
+
+## Related
+
+- [Web Search overview](/tools/web) -- all providers and auto-detection
+- [Brave Search](/tools/brave-search) -- structured results with snippets
+- [Perplexity Search](/tools/perplexity-search) -- structured results + content extraction

package/docs/tools/grok-search.md

@@ -0,0 +1,113 @@
+---
+summary: "Grok web search via xAI web-grounded responses"
+read_when:
+  - You want to use Grok for web_search
+  - You need an XAI_API_KEY for web search
+title: "Grok search"
+---
+
+Nodmix supports Grok as a `web_search` provider, using xAI web-grounded
+responses to produce AI-synthesized answers backed by live search results
+with citations.
+
+The same xAI API key can also power the built-in `x_search` tool for X
+(formerly Twitter) post search and the `code_execution` tool. If you store the
+key under `plugins.entries.xai.config.webSearch.apiKey`, Nodmix now reuses it
+as a fallback for the bundled xAI model provider too.
+
+For post-level X metrics such as reposts, replies, bookmarks, or views, prefer
+`x_search` with the exact post URL or status ID instead of a broad search
+query.
+
+## Onboarding and configure
+
+If you choose **Grok** during:
+
+- `nodmix onboard`
+- `nodmix configure --section web`
+
+Nodmix can show a separate follow-up step to enable `x_search` with the same
+`XAI_API_KEY`. That follow-up:
+
+- only appears after you choose Grok for `web_search`
+- is not a separate top-level web-search provider choice
+- can optionally set the `x_search` model during the same flow
+
+If you skip it, you can enable or change `x_search` later in config.
+
+## Get an API key
+
+<Steps>
+  <Step title="Create a key">
+    Get an API key from [xAI](https://console.x.ai/).
+  </Step>
+  <Step title="Store the key">
+    Set `XAI_API_KEY` in the Gateway environment, or configure via:
+
+    ```bash
+    nodmix configure --section web
+    ```
+
+  </Step>
+</Steps>
+
+## Config
+
+```json5
+{
+  plugins: {
+    entries: {
+      xai: {
+        config: {
+          webSearch: {
+            apiKey: "xai-...", // optional if XAI_API_KEY is set
+            baseUrl: "https://api.x.ai/v1", // optional Responses API proxy/base URL override
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "grok",
+      },
+    },
+  },
+}
+```
+
+**Environment alternative:** set `XAI_API_KEY` in the Gateway environment.
+For a gateway install, put it in `~/.nodmix/.env`.
+
+## How it works
+
+Grok uses xAI web-grounded responses to synthesize answers with inline
+citations, similar to Gemini's Google Search grounding approach.
+
+## Supported parameters
+
+Grok search supports `query`.
+
+`count` is accepted for shared `web_search` compatibility, but Grok still
+returns one synthesized answer with citations rather than an N-result list.
+
+Provider-specific filters are not currently supported.
+
+Grok uses a provider-specific 60 second default timeout because xAI Responses
+web-grounded searches can run longer than the shared `web_search` default. Set
+`tools.web.search.timeoutSeconds` to override it.
+
+## Base URL overrides
+
+Set `plugins.entries.xai.config.webSearch.baseUrl` when Grok web search should
+route through an operator proxy or xAI-compatible Responses endpoint. Nodmix
+posts to `<baseUrl>/responses` after trimming trailing slashes. `x_search`
+uses the same `webSearch.baseUrl` fallback unless
+`plugins.entries.xai.config.xSearch.baseUrl` is set.
+
+## Related
+
+- [Web Search overview](/tools/web) -- all providers and auto-detection
+- [x_search in Web Search](/tools/web#x_search) -- first-class X search via xAI
+- [Gemini Search](/tools/gemini-search) -- AI-synthesized answers via Google grounding