diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md
index 17f349ae3cf..941f5503ed6 100644
--- a/docs/gateway/configuration-reference.md
+++ b/docs/gateway/configuration-reference.md
@@ -970,12 +970,12 @@ Time format in system prompt. Default: `auto` (OS preference).
   - Also used as fallback routing when the selected/default model cannot accept image input.
 - `imageGenerationModel`: accepts either a string (`"provider/model"`) or an object (`{ primary, fallbacks }`).
   - Used by the shared image-generation capability and any future tool/plugin surface that generates images.
-  - Typical values: `google/gemini-3-pro-image-preview` for native Gemini image generation, `fal/fal-ai/flux/dev` for fal, or `openai/gpt-image-1` for OpenAI Images.
+  - Typical values: `google/gemini-3.1-flash-image-preview` for native Gemini image generation, `fal/fal-ai/flux/dev` for fal, or `openai/gpt-image-1` for OpenAI Images.
   - If you select a provider/model directly, configure the matching provider auth/API key too (for example `GEMINI_API_KEY` or `GOOGLE_API_KEY` for `google/*`, `OPENAI_API_KEY` for `openai/*`, `FAL_KEY` for `fal/*`).
-  - If omitted, `image_generate` can still infer a best-effort provider default from compatible auth-backed image-generation providers.
+  - If omitted, `image_generate` can still infer an auth-backed provider default. It tries the current default provider first, then the remaining registered image-generation providers in provider-id order.
 - `pdfModel`: accepts either a string (`"provider/model"`) or an object (`{ primary, fallbacks }`).
   - Used by the `pdf` tool for model routing.
-  - If omitted, the PDF tool falls back to `imageModel`, then to best-effort provider defaults.
+  - If omitted, the PDF tool falls back to `imageModel`, then to the resolved session/default model.
 - `pdfMaxBytesMb`: default PDF size limit for the `pdf` tool when `maxBytesMb` is not passed at call time.
 - `pdfMaxPages`: default maximum pages considered by extraction fallback mode in the `pdf` tool.
 - `verboseDefault`: default verbose level for agents. Values: `"off"`, `"on"`, `"full"`. Default: `"off"`.
diff --git a/docs/tools/image-generation.md b/docs/tools/image-generation.md
index 890b078d1fc..9554bac6106 100644
--- a/docs/tools/image-generation.md
+++ b/docs/tools/image-generation.md
@@ -75,7 +75,7 @@ Not all providers support all parameters. The tool passes what each provider sup
   agents: {
     defaults: {
       // String form: primary model only
-      imageGenerationModel: "google/gemini-3-pro-image-preview",
+      imageGenerationModel: "google/gemini-3.1-flash-image-preview",
 
       // Object form: primary + ordered fallbacks
       imageGenerationModel: {
@@ -94,10 +94,19 @@ When generating an image, OpenClaw 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** — queries all registered providers for defaults, preferring: configured primary provider, then OpenAI, then Google, then others
+4. **Auto-detection** — uses 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 candidate is tried automatically. If all fail, the error includes details from each attempt.
 
+Notes:
+
+- Auto-detection is auth-aware. A provider default only enters the candidate list
+  when OpenClaw can actually authenticate that provider.
+- Use `action: "list"` to inspect the currently registered providers, their
+  default models, and auth env-var hints.
+
 ### Image editing
 
 OpenAI, Google, fal, and MiniMax support editing reference images. Pass a reference image path or URL:
diff --git a/docs/tools/skills-config.md b/docs/tools/skills-config.md
index 4d958c7f34f..1c9ce800918 100644
--- a/docs/tools/skills-config.md
+++ b/docs/tools/skills-config.md
@@ -50,7 +50,7 @@ auth/API key. Typical examples: `GEMINI_API_KEY` or `GOOGLE_API_KEY` for
 
 Examples:
 
-- Native Nano Banana-style setup: `agents.defaults.imageGenerationModel.primary: "google/gemini-3-pro-image-preview"`
+- Native Nano Banana-style setup: `agents.defaults.imageGenerationModel.primary: "google/gemini-3.1-flash-image-preview"`
 - Native fal setup: `agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"`
 
 ## Agent skill allowlists