nodmix 2026.5.25

package/docs/tools/image-generation.md

@@ -0,0 +1,433 @@
+---
+summary: "Generate and edit images via image_generate across OpenAI, Google, fal, MiniMax, ComfyUI, DeepInfra, OpenRouter, LiteLLM, xAI, Vydra"
+read_when:
+  - Generating or editing images via the agent
+  - Configuring image-generation providers and models
+  - Understanding the image_generate tool parameters
+title: "Image generation"
+sidebarTitle: "Image generation"
+---
+
+The `image_generate` tool lets the agent create and edit images using your
+configured providers. In chat sessions, image generation runs asynchronously:
+Nodmix records a background task, returns the task id immediately, and wakes
+the agent when the provider finishes. The completion agent must send generated
+images through the `message` tool; Nodmix does not auto-post a private final
+reply as a fallback.
+
+<Note>
+The tool only appears when at least one image-generation provider is
+available. If you do not see `image_generate` in your agent's tools,
+configure `agents.defaults.imageGenerationModel`, set up a provider API key,
+or sign in with OpenAI Codex OAuth.
+</Note>
+
+## Quick start
+
+<Steps>
+  <Step title="Configure auth">
+    Set an API key for at least one provider (for example `OPENAI_API_KEY`,
+    `GEMINI_API_KEY`, `OPENROUTER_API_KEY`) or sign in with OpenAI Codex OAuth.
+  </Step>
+  <Step title="Pick a default model (optional)">
+    ```json5
+    {
+      agents: {
+        defaults: {
+          imageGenerationModel: {
+            primary: "openai/gpt-image-2",
+            timeoutMs: 180_000,
+          },
+        },
+      },
+    }
+    ```
+
+    Codex OAuth uses the same `openai/gpt-image-2` model ref. When an
+    `openai-codex` OAuth profile is configured, Nodmix routes image
+    requests through that OAuth profile instead of first trying
+    `OPENAI_API_KEY`. Explicit `models.providers.openai` config (API key,
+    custom/Azure base URL) opts back into the direct OpenAI Images API
+    route.
+
+  </Step>
+  <Step title="Ask the agent">
+    _"Generate an image of a friendly robot mascot."_
+
+    The agent calls `image_generate` automatically. No tool allow-listing
+    needed - it is enabled by default when a provider is available. The tool
+    returns a background task id, then the completion agent sends the generated
+    attachment through the `message` tool when it is ready.
+
+  </Step>
+</Steps>
+
+<Warning>
+For OpenAI-compatible LAN endpoints such as LocalAI, keep the custom
+`models.providers.openai.baseUrl` and explicitly opt in with
+`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`. Private and
+internal image endpoints remain blocked by default.
+</Warning>
+
+## Common routes
+
+| Goal                                                 | Model ref                                          | Auth                                   |
+| ---------------------------------------------------- | -------------------------------------------------- | -------------------------------------- |
+| OpenAI image generation with API billing             | `openai/gpt-image-2`                               | `OPENAI_API_KEY`                       |
+| OpenAI image generation with Codex subscription auth | `openai/gpt-image-2`                               | OpenAI Codex OAuth                     |
+| OpenAI transparent-background PNG/WebP               | `openai/gpt-image-1.5`                             | `OPENAI_API_KEY` or OpenAI Codex OAuth |
+| DeepInfra image generation                           | `deepinfra/black-forest-labs/FLUX-1-schnell`       | `DEEPINFRA_API_KEY`                    |
+| OpenRouter image generation                          | `openrouter/google/gemini-3.1-flash-image-preview` | `OPENROUTER_API_KEY`                   |
+| LiteLLM image generation                             | `litellm/gpt-image-2`                              | `LITELLM_API_KEY`                      |
+| Google Gemini image generation                       | `google/gemini-3.1-flash-image-preview`            | `GEMINI_API_KEY` or `GOOGLE_API_KEY`   |
+
+The same `image_generate` tool handles text-to-image and reference-image
+editing. Use `image` for one reference or `images` for multiple references.
+Provider-supported output hints such as `quality`, `outputFormat`, and
+`background` are forwarded when available and reported as ignored when a
+provider does not support them. Bundled transparent-background support is
+OpenAI-specific; other providers may still preserve PNG alpha if their
+backend emits it.
+
+## Supported providers
+
+| Provider   | Default model                           | Edit support                       | Auth                                                  |
+| ---------- | --------------------------------------- | ---------------------------------- | ----------------------------------------------------- |
+| ComfyUI    | `workflow`                              | Yes (1 image, workflow-configured) | `COMFY_API_KEY` or `COMFY_CLOUD_API_KEY` for cloud    |
+| DeepInfra  | `black-forest-labs/FLUX-1-schnell`      | Yes (1 image)                      | `DEEPINFRA_API_KEY`                                   |
+| fal        | `fal-ai/flux/dev`                       | Yes (model-specific limits)        | `FAL_KEY`                                             |
+| Google     | `gemini-3.1-flash-image-preview`        | Yes                                | `GEMINI_API_KEY` or `GOOGLE_API_KEY`                  |
+| LiteLLM    | `gpt-image-2`                           | Yes (up to 5 input images)         | `LITELLM_API_KEY`                                     |
+| MiniMax    | `image-01`                              | Yes (subject reference)            | `MINIMAX_API_KEY` or MiniMax OAuth (`minimax-portal`) |
+| OpenAI     | `gpt-image-2`                           | Yes (up to 4 images)               | `OPENAI_API_KEY` or OpenAI Codex OAuth                |
+| OpenRouter | `google/gemini-3.1-flash-image-preview` | Yes (up to 5 input images)         | `OPENROUTER_API_KEY`                                  |
+| Vydra      | `grok-imagine`                          | No                                 | `VYDRA_API_KEY`                                       |
+| xAI        | `grok-imagine-image`                    | Yes (up to 5 images)               | `XAI_API_KEY`                                         |
+
+Use `action: "list"` to inspect available providers and models at runtime:
+
+```text
+/tool image_generate action=list
+```
+
+Use `action: "status"` to inspect the active image-generation task for the
+current session:
+
+```text
+/tool image_generate action=status
+```
+
+## Provider capabilities
+
+| Capability            | ComfyUI            | DeepInfra | fal                       | Google         | MiniMax               | OpenAI         | Vydra | xAI            |
+| --------------------- | ------------------ | --------- | ------------------------- | -------------- | --------------------- | -------------- | ----- | -------------- |
+| Generate (max count)  | Workflow-defined   | 4         | 4                         | 4              | 9                     | 4              | 1     | 4              |
+| Edit / reference      | 1 image (workflow) | 1 image   | Flux: 1; GPT: 10; NB2: 14 | Up to 5 images | 1 image (subject ref) | Up to 5 images | -     | Up to 5 images |
+| Size control          | -                  | ✓         | ✓                         | ✓              | -                     | Up to 4K       | -     | -              |
+| Aspect ratio          | -                  | -         | ✓                         | ✓              | ✓                     | -              | -     | ✓              |
+| Resolution (1K/2K/4K) | -                  | -         | ✓                         | ✓              | -                     | -              | -     | 1K, 2K         |
+
+## Tool parameters
+
+<ParamField path="prompt" type="string" required>
+  Image generation prompt. Required for `action: "generate"`.
+</ParamField>
+<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
+  Use `"status"` to inspect the active session task or `"list"` to inspect
+  available providers and models at runtime.
+</ParamField>
+<ParamField path="model" type="string">
+  Provider/model override (e.g. `openai/gpt-image-2`). Use
+  `openai/gpt-image-1.5` for transparent OpenAI backgrounds.
+</ParamField>
+<ParamField path="image" type="string">
+  Single reference image path or URL for edit mode.
+</ParamField>
+<ParamField path="images" type="string[]">
+  Multiple reference images for edit mode (up to 5 on supporting providers).
+</ParamField>
+<ParamField path="size" type="string">
+  Size hint: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`.
+</ParamField>
+<ParamField path="aspectRatio" type="string">
+  Aspect ratio: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
+</ParamField>
+<ParamField path="resolution" type='"1K" | "2K" | "4K"'>Resolution hint.</ParamField>
+<ParamField path="quality" type='"low" | "medium" | "high" | "auto"'>
+  Quality hint when the provider supports it.
+</ParamField>
+<ParamField path="outputFormat" type='"png" | "jpeg" | "webp"'>
+  Output format hint when the provider supports it.
+</ParamField>
+<ParamField path="background" type='"transparent" | "opaque" | "auto"'>
+  Background hint when the provider supports it. Use `transparent` with
+  `outputFormat: "png"` or `"webp"` for transparency-capable providers.
+</ParamField>
+<ParamField path="count" type="number">Number of images to generate (1-4).</ParamField>
+<ParamField path="timeoutMs" type="number">
+  Optional provider request timeout in milliseconds. When Codex calls
+  `image_generate` through dynamic tools, this per-call value still overrides
+  the configured default and is capped at 600000 ms.
+</ParamField>
+<ParamField path="filename" type="string">Output filename hint.</ParamField>
+<ParamField path="openai" type="object">
+  OpenAI-only hints: `background`, `moderation`, `outputCompression`, and `user`.
+</ParamField>
+
+<Note>
+Not all providers support all parameters. When a fallback provider supports a
+nearby geometry option instead of the exact requested one, Nodmix remaps to
+the closest supported size, aspect ratio, or resolution before submission.
+Unsupported output hints are dropped for providers that do not declare
+support and reported in the tool result. Tool results report the applied
+settings; `details.normalization` captures any requested-to-applied
+translation.
+</Note>
+
+## Configuration
+
+### Model selection
+
+```json5
+{
+  agents: {
+    defaults: {
+      imageGenerationModel: {
+        primary: "openai/gpt-image-2",
+        timeoutMs: 180_000,
+        fallbacks: [
+          "openrouter/google/gemini-3.1-flash-image-preview",
+          "google/gemini-3.1-flash-image-preview",
+          "fal/fal-ai/flux/dev",
+        ],
+      },
+    },
+  },
+}
+```
+
+### Provider selection order
+
+Nodmix tries providers in this order:
+
+1. **`model` parameter** from the tool call (if the agent specifies one).
+2. **`imageGenerationModel.primary`** from config.
+3. **`imageGenerationModel.fallbacks`** in order.
+4. **Auto-detection** - auth-backed provider defaults only:
+   - current default provider first;
+   - remaining registered image-generation providers in provider-id order.
+
+If a provider fails (auth error, rate limit, etc.), the next configured
+candidate is tried automatically. If all fail, the error includes details
+from each attempt.
+
+<AccordionGroup>
+  <Accordion title="Per-call model overrides are exact">
+    A per-call `model` override tries only that provider/model and does
+    not continue to configured primary/fallback or auto-detected providers.
+  </Accordion>
+  <Accordion title="Auto-detection is auth-aware">
+    A provider default only enters the candidate list when Nodmix can
+    actually authenticate that provider. Set
+    `agents.defaults.mediaGenerationAutoProviderFallback: false` to use only
+    explicit `model`, `primary`, and `fallbacks` entries.
+  </Accordion>
+  <Accordion title="Timeouts">
+    Set `agents.defaults.imageGenerationModel.timeoutMs` for slow image
+    backends. A per-call `timeoutMs` tool parameter overrides the configured
+    default. Google, OpenRouter, and xAI hosted image providers use 180 second
+    defaults; Azure OpenAI image generation uses 600 seconds. Codex dynamic-tool
+    calls use a 120 second `image_generate` bridge default and honor the same
+    timeout budget when configured, bounded by Nodmix's 600000 ms dynamic-tool
+    bridge maximum.
+  </Accordion>
+  <Accordion title="Inspect at runtime">
+    Use `action: "list"` to inspect the currently registered providers,
+    their default models, and auth env-var hints.
+  </Accordion>
+</AccordionGroup>
+
+### Image editing
+
+OpenAI, OpenRouter, Google, DeepInfra, fal, MiniMax, ComfyUI, and xAI support editing
+reference images. Pass a reference image path or URL:
+
+```text
+"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"
+```
+
+OpenAI, OpenRouter, Google, and xAI support up to 5 reference images via the
+`images` parameter. fal supports 1 reference image for Flux image-to-image, up
+to 10 for GPT Image 2 edits, and up to 14 for Nano Banana 2 edits. MiniMax and
+ComfyUI support 1.
+
+## Provider deep dives
+
+<AccordionGroup>
+  <Accordion title="OpenAI gpt-image-2 (and gpt-image-1.5)">
+    OpenAI image generation defaults to `openai/gpt-image-2`. If an
+    `openai-codex` OAuth profile is configured, Nodmix reuses the same
+    OAuth profile used by Codex subscription chat models and sends the
+    image request through the Codex Responses backend. Legacy Codex base
+    URLs such as `https://chatgpt.com/backend-api` are canonicalized to
+    `https://chatgpt.com/backend-api/codex` for image requests. Nodmix
+    does **not** silently fall back to `OPENAI_API_KEY` for that request -
+    to force direct OpenAI Images API routing, configure
+    `models.providers.openai` explicitly with an API key, custom base URL,
+    or Azure endpoint.
+
+    The `openai/gpt-image-1.5`, `openai/gpt-image-1`, and
+    `openai/gpt-image-1-mini` models can still be selected explicitly. Use
+    `gpt-image-1.5` for transparent-background PNG/WebP output; the current
+    `gpt-image-2` API rejects `background: "transparent"`.
+
+    `gpt-image-2` supports both text-to-image generation and
+    reference-image editing through the same `image_generate` tool.
+    Nodmix forwards `prompt`, `count`, `size`, `quality`, `outputFormat`,
+    and reference images to OpenAI. OpenAI does **not** receive
+    `aspectRatio` or `resolution` directly; when possible Nodmix maps
+    those into a supported `size`, otherwise the tool reports them as
+    ignored overrides.
+
+    OpenAI-specific options live under the `openai` object:
+
+    ```json
+    {
+      "quality": "low",
+      "outputFormat": "jpeg",
+      "openai": {
+        "background": "opaque",
+        "moderation": "low",
+        "outputCompression": 60,
+        "user": "end-user-42"
+      }
+    }
+    ```
+
+    `openai.background` accepts `transparent`, `opaque`, or `auto`;
+    transparent outputs require `outputFormat` `png` or `webp` and a
+    transparency-capable OpenAI image model. Nodmix routes default
+    `gpt-image-2` transparent-background requests to `gpt-image-1.5`.
+    `openai.outputCompression` applies to JPEG/WebP outputs.
+
+    The top-level `background` hint is provider-neutral and currently maps
+    to the same OpenAI `background` request field when the OpenAI provider
+    is selected. Providers that do not declare background support return
+    it in `ignoredOverrides` instead of receiving the unsupported parameter.
+
+    To route OpenAI image generation through an Azure OpenAI deployment
+    instead of `api.openai.com`, see
+    [Azure OpenAI endpoints](/providers/openai#azure-openai-endpoints).
+
+  </Accordion>
+  <Accordion title="OpenRouter image models">
+    OpenRouter image generation uses the same `OPENROUTER_API_KEY` and
+    routes through OpenRouter's chat completions image API. Select
+    OpenRouter image models with the `openrouter/` prefix:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          imageGenerationModel: {
+            primary: "openrouter/google/gemini-3.1-flash-image-preview",
+          },
+        },
+      },
+    }
+    ```
+
+    Nodmix forwards `prompt`, `count`, reference images, and
+    Gemini-compatible `aspectRatio` / `resolution` hints to OpenRouter.
+    Current built-in OpenRouter image model shortcuts include
+    `google/gemini-3.1-flash-image-preview`,
+    `google/gemini-3-pro-image-preview`, and `openai/gpt-5.4-image-2`. Use
+    `action: "list"` to see what your configured plugin exposes.
+
+  </Accordion>
+  <Accordion title="MiniMax dual-auth">
+    MiniMax image generation is available through both bundled MiniMax
+    auth paths:
+
+    - `minimax/image-01` for API-key setups
+    - `minimax-portal/image-01` for OAuth setups
+
+  </Accordion>
+  <Accordion title="xAI grok-imagine-image">
+    The bundled xAI provider uses `/v1/images/generations` for prompt-only
+    requests and `/v1/images/edits` when `image` or `images` is present.
+
+    - Models: `xai/grok-imagine-image`, `xai/grok-imagine-image-quality`
+    - Count: up to 4
+    - References: one `image` or up to five `images`
+    - Aspect ratios: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`
+    - Resolutions: `1K`, `2K`
+    - Outputs: returned as Nodmix-managed image attachments
+
+    Nodmix intentionally does not expose xAI-native `quality`, `mask`,
+    `user`, or extra native-only aspect ratios until those controls exist
+    in the shared cross-provider `image_generate` contract.
+
+  </Accordion>
+</AccordionGroup>
+
+## Examples
+
+<Tabs>
+  <Tab title="Generate (4K landscape)">
+```text
+/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for Nodmix image generation" size=3840x2160 count=1
+```
+  </Tab>
+  <Tab title="Generate (transparent PNG)">
+```text
+/tool image_generate action=generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent
+```
+
+Equivalent CLI:
+
+```bash
+nodmix infer image generate \
+  --model openai/gpt-image-1.5 \
+  --output-format png \
+  --background transparent \
+  --prompt "A simple red circle sticker on a transparent background" \
+  --json
+```
+
+  </Tab>
+  <Tab title="Generate (two square)">
+```text
+/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2
+```
+  </Tab>
+  <Tab title="Edit (one reference)">
+```text
+/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536
+```
+  </Tab>
+  <Tab title="Edit (multiple references)">
+```text
+/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024
+```
+  </Tab>
+</Tabs>
+
+The same `--output-format` and `--background` flags are available on
+`nodmix infer image edit`; `--openai-background` remains as an
+OpenAI-specific alias. Bundled providers other than OpenAI do not declare
+explicit background control today, so `background: "transparent"` is reported
+as ignored for them.
+
+## Related
+
+- [Tools overview](/tools) - all available agent tools
+- [ComfyUI](/providers/comfy) - local ComfyUI and Comfy Cloud workflow setup
+- [fal](/providers/fal) - fal image and video provider setup
+- [Google (Gemini)](/providers/google) - Gemini image provider setup
+- [MiniMax](/providers/minimax) - MiniMax image provider setup
+- [OpenAI](/providers/openai) - OpenAI Images provider setup
+- [Vydra](/providers/vydra) - Vydra image, video, and speech setup
+- [xAI](/providers/xai) - Grok image, video, search, code execution, and TTS setup
+- [Configuration reference](/gateway/config-agents#agent-defaults) - `imageGenerationModel` config
+- [Models](/concepts/models) - model configuration and failover

package/docs/tools/index.md

@@ -0,0 +1,178 @@
+---
+doc-schema-version: 1
+summary: "Nodmix tools, skills, and plugins overview: what agents can call and how to extend them"
+read_when:
+  - You want to understand what tools Nodmix provides
+  - You are deciding between built-in tools, skills, and plugins
+  - You need the right docs entry point for tool policy, automation, or agent coordination
+title: "Overview"
+---
+
+Use this page to choose the right Capabilities surface. **Tools** are callable
+actions, **skills** teach agents how to work, and **plugins** add runtime
+capabilities such as tools, providers, channels, hooks, and packaged skills.
+
+This is an overview and routing page. For exhaustive tool policy, defaults,
+group membership, provider restrictions, and configuration fields, use
+[Tools and custom providers](/gateway/config-tools).
+
+## Start here
+
+For most agents, start with the built-in tool categories, then adjust policy
+only when the agent should see fewer tools or needs explicit host access.
+
+| If you need to...                           | Use this first                                 | Then read                                                               |
+| ------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
+| Let an agent act with existing capabilities | [Built-in tools](#built-in-tool-categories)    | [Tool categories](#built-in-tool-categories)                            |
+| Control what an agent can call              | [Tool policy](#configure-access-and-approvals) | [Tools and custom providers](/gateway/config-tools)                     |
+| Teach an agent a workflow                   | [Skills](#choose-tools-skills-or-plugins)      | [Skills](/tools/skills) and [Creating skills](/tools/creating-skills)   |
+| Add a new integration or runtime surface    | [Plugins](#extend-capabilities)                | [Plugins](/tools/plugin) and [Build plugins](/plugins/building-plugins) |
+| Run work later or in the background         | [Automation](/automation)                      | [Automation overview](/automation)                                      |
+| Coordinate multiple agents or harnesses     | [Sub-agents](/tools/subagents)                 | [ACP agents](/tools/acp-agents) and [Agent send](/tools/agent-send)     |
+| Search a large PI tool catalog              | [Tool Search](/tools/tool-search)              | [Tool Search](/tools/tool-search)                                       |
+
+## Choose tools, skills, or plugins
+
+<Steps>
+  <Step title="Use a tool when the agent needs to act">
+    A tool is a typed function the agent can call, such as `exec`, `browser`,
+    `web_search`, `message`, or `image_generate`. Use tools when the agent
+    needs to read data, change files, send messages, call a provider, or operate
+    another system. Visible tools are sent to the model as structured function
+    definitions.
+
+    The model only sees tools that survive the active profile, allow/deny
+    policy, provider restrictions, sandbox state, channel permissions, and
+    plugin availability.
+
+  </Step>
+
+  <Step title="Use a skill when the agent needs instructions">
+    A skill is a `SKILL.md` instruction pack loaded into the agent prompt. Use a
+    skill when the agent already has the tools it needs, but needs a repeatable
+    workflow, review rubric, command sequence, or operating constraint.
+
+    Skills can live in a workspace, shared skill directory, managed Nodmix
+    skill root, or plugin package.
+
+    [Skills](/tools/skills) | [Creating skills](/tools/creating-skills) | [Skills config](/tools/skills-config)
+
+  </Step>
+
+  <Step title="Use a plugin when Nodmix needs a new capability">
+    A plugin can add tools, skills, channels, model providers, speech, realtime
+    voice, media generation, web search, web fetch, hooks, and other runtime
+    capabilities. Use a plugin when the capability has code, credentials,
+    lifecycle hooks, manifest metadata, or installable packaging. Existing
+    plugins can be installed from ClawHub, npm, git, local directories, or
+    archives.
+
+    [Install and configure plugins](/tools/plugin) | [Build plugins](/plugins/building-plugins) | [Plugin SDK](/plugins/sdk-overview)
+
+  </Step>
+</Steps>
+
+## Built-in tool categories
+
+The table lists representative tools so you can recognize the surface. It is
+not the full policy reference. For exact groups, defaults, and allow/deny
+semantics, use [Tools and custom providers](/gateway/config-tools).
+
+| Category               | Use when the agent needs to...                                                | Representative tools                                                 | Read next                                                              |
+| ---------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Runtime                | Run commands, manage processes, or use provider-backed Python analysis        | `exec`, `process`, `code_execution`                                  | [Exec](/tools/exec), [Code execution](/tools/code-execution)           |
+| Files                  | Read and change workspace files                                               | `read`, `write`, `edit`, `apply_patch`                               | [Apply patch](/tools/apply-patch)                                      |
+| Web                    | Search the web, search X posts, or fetch readable page content                | `web_search`, `x_search`, `web_fetch`                                | [Web tools](/tools/web), [Web fetch](/tools/web-fetch)                 |
+| Browser                | Operate a browser session                                                     | `browser`                                                            | [Browser](/tools/browser)                                              |
+| Messaging and channels | Send replies or channel actions                                               | `message`                                                            | [Agent send](/tools/agent-send)                                        |
+| Sessions and agents    | Inspect sessions, delegate work, steer another run, or report status          | `sessions_*`, `subagents`, `agents_list`, `session_status`           | [Sub-agents](/tools/subagents), [Session tool](/concepts/session-tool) |
+| Automation             | Schedule work or respond to background events                                 | `cron`, `heartbeat_respond`                                          | [Automation](/automation)                                              |
+| Gateway and nodes      | Inspect Gateway state or paired target devices                                | `gateway`, `nodes`                                                   | [Gateway configuration](/gateway/configuration), [Nodes](/nodes)       |
+| Media                  | Analyze, generate, or speak media                                             | `image`, `image_generate`, `music_generate`, `video_generate`, `tts` | [Media overview](/tools/media-overview)                                |
+| Large PI catalogs      | Search and call many eligible tools without sending every schema to the model | `tool_search_code`, `tool_search`, `tool_describe`                   | [Tool Search](/tools/tool-search)                                      |
+
+<Note>
+Tool Search is an experimental PI-agent surface. Codex harness runs use
+Codex-native code mode, native tool search, deferred dynamic tools, and nested
+tool calls instead of `tools.toolSearch`.
+</Note>
+
+## Plugin-provided tools
+
+Plugins can register additional tools. Plugin authors wire tools through
+`api.registerTool(...)` and the manifest's `contracts.tools`; use
+[Plugin SDK](/plugins/sdk-overview) and [Plugin manifest](/plugins/manifest)
+for contract details.
+
+Common plugin-provided tools include:
+
+- [Diffs](/tools/diffs) for rendering file and markdown diffs
+- [LLM Task](/tools/llm-task) for JSON-only workflow steps
+- [Lobster](/tools/lobster) for typed workflows with resumable approvals
+- [Tokenjuice](/tools/tokenjuice) for compacting noisy `exec` and `bash` tool
+  output
+- [Tool Search](/tools/tool-search) for discovering and calling large tool
+  catalogs without putting every schema in the prompt
+- [Canvas](/plugins/reference/canvas) for node Canvas control and A2UI
+  rendering
+
+## Configure access and approvals
+
+Tool policy is enforced before the model call. If policy removes a tool, the
+model does not receive that tool's schema for the turn. A run can lose tools
+because of global config, per-agent config, channel policy, provider
+restrictions, sandbox rules, channel/runtime policy, or plugin availability.
+
+- [Tools and custom providers](/gateway/config-tools) documents tool profiles,
+  allow/deny lists, provider-specific restrictions, loop detection, and
+  provider-backed tool settings.
+- [Exec approvals](/tools/exec-approvals) documents host command approval
+  policy.
+- [Elevated exec](/tools/elevated) documents controlled execution outside the
+  sandbox.
+- [Sandbox vs tool policy vs elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) explains which layer controls file and process access.
+- [Per-agent sandbox and tool restrictions](/tools/multi-agent-sandbox-tools)
+  documents agent-specific restrictions for delegated runs.
+
+## Extend capabilities
+
+Choose the extension path by the job you need Nodmix to do:
+
+- Install or manage an existing plugin with [Plugins](/tools/plugin).
+- Build a new integration, provider, channel, tool, or hook with
+  [Build plugins](/plugins/building-plugins).
+- Add or tune reusable agent instructions with [Skills](/tools/skills) and
+  [Creating skills](/tools/creating-skills).
+- Package reusable workflow material with
+  [Skill workshop](/plugins/skill-workshop) when the workflow belongs in a
+  plugin-distributed skill bundle.
+- Use [Plugin SDK](/plugins/sdk-overview) and [Plugin manifest](/plugins/manifest) when you need implementation contracts.
+
+## Troubleshoot missing tools
+
+If the model cannot see or call a tool, start with the effective policy for the
+current turn:
+
+1. Check the active profile, `tools.allow`, and `tools.deny` in
+   [Tools and custom providers](/gateway/config-tools).
+2. Check provider-specific restrictions in
+   [Tools and custom providers](/gateway/config-tools) and confirm the selected
+   [model provider](/concepts/model-providers) supports the tool shape.
+3. Check channel permissions, sandbox state, and elevated access with
+   [Sandbox vs tool policy vs elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) and [Elevated exec](/tools/elevated).
+4. Check whether the owning plugin is installed and enabled in
+   [Plugins](/tools/plugin).
+5. For delegated runs, check per-agent restrictions in
+   [Per-agent sandbox and tool restrictions](/tools/multi-agent-sandbox-tools).
+6. For large PI catalogs, confirm whether the run uses direct tool exposure or
+   [Tool Search](/tools/tool-search).
+
+## Related
+
+- [Automation](/automation) for cron, tasks, heartbeat, commitments, hooks, standing orders, and Task Flow
+- [Agents](/concepts/agent) for the agent model, sessions, memory, and multi-agent coordination
+- [Tools and custom providers](/gateway/config-tools) for the canonical tool policy reference
+- [Plugins](/tools/plugin) for plugin installation and management
+- [Plugin SDK](/plugins/sdk-overview) for plugin author reference
+- [Skills](/tools/skills) for skill load order, gating, and config
+- [Tool Search](/tools/tool-search) for compact PI tool catalog discovery