docs: clarify image_routing auto/direct behavior and backwards compatibility

- direct is the default, same as before PR #723
- auto requires observer to be enabled (not in disabled_agents)
- fix image/PDF wording (hook only handles images)
- add config examples for each acceptance test scenario

README.md

@@ -614,7 +614,7 @@ rules.
 ### Observer: The Silent Witness
 
 > [!NOTE]
-> **Why a separate agent?** If your Orchestrator model is not multimodal, enable Observer to handle images, screenshots, PDFs, and other visual files. Observer is disabled by default and gives the Orchestrator a dedicated multimodal reader without forcing you to change your main reasoning model. Set `disabled_agents: []` and an `observer` model in your configuration. The bundled `opencode-go` install preset does this automatically because its GLM Orchestrator is not multimodal. If your Orchestrator *is* multimodal, use the default `image_routing: "direct"` so attachments reach it directly. If it is *not* multimodal, set `image_routing: "auto"` to save attachments and route them to `@observer`.
+> **Why a separate agent?** If your Orchestrator model is not multimodal, enable Observer to handle images, screenshots, and other visual files. Observer is disabled by default and gives the Orchestrator a dedicated multimodal reader without forcing you to change your main reasoning model. Set `disabled_agents: []` and an `observer` model in your configuration. The bundled `opencode-go` install preset does this automatically because its GLM Orchestrator is not multimodal. If your Orchestrator *is* multimodal, leave `image_routing` unset (defaults to `"direct"`, same as before PR #723) so attachments reach it directly. If it is *not* multimodal, set `image_routing: "auto"` to save attachments and route them to `@observer`.
 
 <table>
   <tr>
@@ -628,7 +628,7 @@ rules.
 
 - Images, screenshots, diagrams → `read` tool (native image support)
 - PDFs and binary documents → `read` tool (text + structure extraction)
-- **Disabled by default** - enable with `"disabled_agents": []` and configure a vision-capable model; installing with `--preset=opencode-go` enables it with `opencode-go/kimi-k2.6`. Set `"image_routing": "auto"` to route attachments to Observer without forcing interception when the orchestrator is multimodal.
+- **Disabled by default** - enable with `"disabled_agents": []` and configure a vision-capable model; installing with `--preset=opencode-go` enables it with `opencode-go/kimi-k2.6`. Set `"image_routing": "auto"` to automatically intercept image attachments and route them to Observer (requires observer to be enabled).
 
     </td>
   </tr>

docs/configuration.md

@@ -133,7 +133,7 @@ Presets can also be switched at runtime without restarting using the `/preset` c
 | `acpAgents.<name>.permissionMode` | string | `ask` | How ACP permission requests are handled: `ask`, `allow`, or `reject` |
 | `acpAgents.<name>.timeoutMs` | integer | `0` | Timeout for a single ACP run in milliseconds. `0` disables the timeout so external agents can run indefinitely. Finite values can be up to `2147483647`ms (~24.8 days) |
 | `disabled_agents` | string[] | `["observer"]` | Agent names to disable globally. Set to `[]` to enable Observer; this is global, not per-preset |
-| `image_routing` | `"auto"` \| `"direct"` | `"direct"` | How image/PDF attachments are handled. `"direct"`: pass attachments to the orchestrator untouched; `@observer` stays available for manual `@observer` delegation. `"auto"`: save attachments to disk and nudge the orchestrator to delegate to `@observer` (requires `observer` to be enabled, i.e. not in `disabled_agents`). |
+| `image_routing` | `"auto"` \| `"direct"` | `"direct"` | How image attachments are handled. `"direct"` (default): images pass to the orchestrator untouched — same behavior as before PR #723. Use this when your orchestrator is multimodal. `"auto"`: save images to `.opencode/images/` and nudge the orchestrator to delegate to `@observer` (requires `observer` to be enabled, i.e. not in `disabled_agents`). When omitted, defaults to `"direct"` for backwards compatibility. |
 | `autoUpdate` | boolean | `true` | Automatically install plugin updates in the background; set to `false` for notification-only mode |
 | `multiplexer.type` | string | `"none"` | Multiplexer mode: `auto`, `tmux`, `zellij`, `herdr`, or `none` |
 | `multiplexer.layout` | string | `"main-vertical"` | Layout preset: `main-vertical`, `main-horizontal`, `tiled`, `even-horizontal`, `even-vertical`. Tmux applies full layouts; Zellij and Herdr map `main-vertical` to right and `main-horizontal` to down |