fengming 0.3.9 → 0.3.11

package/docs/tools/image-generation.md

@@ -1,493 +0,0 @@
----
-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:
-FengMing records a background task, returns the task id immediately, and wakes
-the agent when the provider finishes. The completion agent follows the
-session's normal visible-reply mode: automatic final reply delivery when
-configured, or `message(action="send")` when the session requires the message
-tool. If the requester session is inactive or its active wake fails, and some
-generated images are still missing from the completion reply, FengMing sends an
-idempotent direct fallback with only the missing images.
-
-<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 ChatGPT/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,
-          },
-        },
-      },
-    }
-    ```
-
-    ChatGPT/Codex OAuth uses the same `openai/gpt-image-2` model ref. When an
-    `openai` OAuth profile is configured, FengMing 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 ChatGPT/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`                    |
-| fal Krea 2 expressive/style-directed generation      | `fal/krea/v2/medium/text-to-image`                 | `FAL_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.
-For Krea 2 models on fal, those references are sent as style references
-instead of edit inputs.
-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 ChatGPT/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; Krea style refs: 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 or style-reference models (up to 10
-  through the shared tool; provider-specific limits still apply).
-</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`, `2.35:1`, `3:4`, `4:3`, `4:5`,
-  `5:4`, `9:16`, `16:9`, `21:9`, `4:1`, `1:4`, `8:1`, `1:8`. Providers
-  validate their model-specific subset.
-</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>
-<ParamField path="fal.creativity" type='"raw" | "low" | "medium" | "high"'>
-  fal Krea 2 creativity control. Defaults to `medium`.
-</ParamField>
-
-<Note>
-Not all providers support all parameters. When a fallback provider supports a
-nearby geometry option instead of the exact requested one, FengMing 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
-
-FengMing 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 FengMing 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, and configured defaults override plugin-authored provider
-    defaults. Google and OpenRouter hosted image providers use 180 second
-    defaults; xAI and Azure OpenAI image generation use 600 seconds. Codex
-    dynamic-tool calls use a 120 second `image_generate` bridge default and
-    honor the same timeout budget when configured, bounded by FengMing'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. Krea 2 models on fal use the same `image` / `images` fields
-as style references instead of edit inputs. 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, up to 10 style references for Krea 2, 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` OAuth profile is configured, FengMing 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. FengMing
-    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.
-    FengMing forwards `prompt`, `count`, `size`, `quality`, `outputFormat`,
-    and reference images to OpenAI. OpenAI does **not** receive
-    `aspectRatio` or `resolution` directly; when possible FengMing 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. FengMing routes default
-    `gpt-image-2` transparent-background requests to `gpt-image-1.5`.
-    `openai.outputCompression` applies to JPEG/WebP outputs and is ignored
-    for PNG 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",
-          },
-        },
-      },
-    }
-    ```
-
-    FengMing 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="fal Krea 2">
-    Krea 2 models on fal use fal's native Krea schema instead of the generic
-    `image_size` schema used by Flux. FengMing sends:
-
-    - `aspect_ratio` for aspect-ratio hints
-    - `creativity`, defaulting to `medium`
-    - `image_style_references` when `image` or `images` are supplied
-
-    Select Krea 2 Medium for faster expressive illustration and Krea 2 Large
-    for slower, more detailed photoreal and textured looks:
-
-    ```json5
-    {
-      agents: {
-        defaults: {
-          imageGenerationModel: {
-            primary: "fal/krea/v2/medium/text-to-image",
-          },
-        },
-      },
-    }
-    ```
-
-    Krea 2 currently returns one image per request. Prefer `aspectRatio` for
-    Krea; FengMing maps `size` to the closest supported Krea aspect ratio and
-    rejects `resolution` for Krea rather than dropping it. Use `fal.creativity`
-    when you want a native Krea creativity level:
-
-    ```json
-    {
-      "model": "fal/krea/v2/medium/text-to-image",
-      "prompt": "A cyber zine portrait with risograph texture",
-      "aspectRatio": "9:16",
-      "fal": {
-        "creativity": "high"
-      }
-    }
-    ```
-
-  </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 FengMing-managed image attachments
-
-    FengMing 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 FengMing 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
-fengming 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>
-  <Tab title="Krea style references">
-```text
-/tool image_generate action=generate model=fal/krea/v2/medium/text-to-image prompt="An expressive editorial portrait using this color palette and print texture" images='["/path/to/palette.png","/path/to/texture.jpg"]' aspectRatio=9:16 fal='{"creativity":"high"}'
-```
-  </Tab>
-</Tabs>
-
-The same `--output-format` and `--background` flags are available on
-`fengming 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

@@ -1,178 +0,0 @@
----
-doc-schema-version: 1
-summary: "FengMing tools, skills, and plugins overview: what agents can call and how to extend them"
-read_when:
-  - You want to understand what tools FengMing 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 FengMing 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 FengMing
-    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 FengMing 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`, `goal`   | [Goal](/tools/goal), [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 FengMing 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 FengMing 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 FengMing 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 FengMing 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 FengMing tool catalog discovery