docs: fix stale defaults, wrong tool names, and missing CLI flags

docs/concepts/models/index.md

@@ -108,13 +108,13 @@ See the [Model Providers]({{ '/providers/overview/' | relative_url }}) section f
 
 Control how much the model "thinks" before responding:
 
-| Provider   | Format     | Values                                | Default      |
-| ---------- | ---------- | ------------------------------------- | ------------ |
-| OpenAI     | string     | `minimal`, `low`, `medium`, `high`    | `medium`     |
-| Anthropic  | int        | 1024–32768 tokens                     | 8192         |
-| Gemini 2.5 | int        | 0 (off), -1 (dynamic), or token count | -1 (dynamic) |
-| Gemini 3   | string     | `minimal`, `low`, `medium`, `high`    | varies       |
-| All        | string/int | `none` or `0` to disable              | —            |
+| Provider   | Format     | Values                                       | Default                          |
+| ---------- | ---------- | -------------------------------------------- | -------------------------------- |
+| OpenAI     | string     | `minimal`, `low`, `medium`, `high`, `xhigh`  | `medium` (always-reasoning models only) |
+| Anthropic  | int        | 1024–32768 tokens                            | off                              |
+| Gemini 2.5 | int        | 0 (off), -1 (dynamic), or token count        | -1 (dynamic)                     |
+| Gemini 3   | string     | `minimal`, `low`, `medium`, `high`           | varies                           |
+| All        | string/int | `none` or `0` to disable                     | —                                |
 
 ```yaml
 models:

docs/configuration/models/index.md

@@ -220,14 +220,15 @@ See [`examples/task_budget.yaml`](https://github.com/docker/docker-agent/blob/ma
 
 ## Interleaved Thinking
 
-For Anthropic and Bedrock Claude models, interleaved thinking allows tool calls during model reasoning. This is enabled by default:
+For Anthropic and Bedrock Claude models, interleaved thinking allows tool calls during model reasoning. It is auto-enabled whenever a thinking budget is configured:
 
 ```yaml
 models:
   claude:
     provider: anthropic
     model: claude-sonnet-4-5
-    # interleaved_thinking defaults to true
+    thinking_budget: 8192
+    # interleaved_thinking is auto-enabled when thinking_budget is set
     provider_opts:
       interleaved_thinking: false # disable if needed
 ```

docs/configuration/overview/index.md

@@ -16,7 +16,7 @@ A docker-agent config has these main sections:
 
 ```bash
 # 1. Version — configuration schema version (optional but recommended)
-version: 8
+version: 10
 
 # 2. Metadata — optional agent metadata for distribution
 metadata:
@@ -304,10 +304,10 @@ For YAML editor autocompletion and validation, use the [Docker Agent JSON Schema
 
 ## Config Versioning
 
-docker-agent configs are versioned. The current version is `8`. Add the version at the top of your config:
+docker-agent configs are versioned. The current version is `10`. Add the version at the top of your config:
 
 ```yaml
-version: 8
+version: 10
 
 agents:
   root:

docs/features/a2a/index.md

@@ -37,7 +37,7 @@ $ docker agent serve a2a agentcatalog/pirate
 | Flag                              | Default          | Description                                                                                                          |
 | --------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- |
 | `-l, --listen <addr>`             | `127.0.0.1:8082` | Address to listen on.                                                                                                |
-| `-a, --agent <name>`              | `root`           | Name of the agent to expose when the config contains multiple agents.                                                |
+| `-a, --agent <name>`              | (first agent)    | Name of the agent to expose when the config contains multiple agents. Defaults to the team's first agent.            |
 | `--working-dir <path>`            | current dir      | Working directory the agent runs in.                                                                                 |
 | `--env-from-file <file>`          | (none)           | Load additional environment variables from a `.env` file (repeatable).                                               |
 | `--models-gateway <url>`          | (none)           | Route all provider traffic through a models gateway URL.                                                             |

docs/features/cli/index.md

@@ -41,6 +41,8 @@ $ docker agent run [config] [message...] [flags]
 | `--app-name <name>`                     | Override the application name label shown in the TUI (status bar, window title, "/exit" notifications).                                   |
 | `--sidebar`                             | Control sidebar visibility. Set to `--sidebar=false` to hide the sidebar and disable the Ctrl+B toggle (default: `true`).                 |
 | `--disable-commands <list>`             | Hide and disable specific slash commands in the TUI. Accepts a comma-separated list of command names (leading slash optional, case-insensitive). E.g. `--disable-commands="/cost,/eval,/model"`. |
+| `--theme <name>`                        | Preselect a TUI theme by name (overrides the theme from user config; ignored outside the interactive TUI)                                 |
+| `--on-event <type>=<cmd>`               | Run a shell command when an event of the given type fires (`*=<cmd>` matches any event). Repeatable.                                      |
 | `--json`                                | Output results as newline-delimited JSON (use with `--exec`)                                                                              |
 | `--hide-tool-calls`                     | Hide tool calls in the output                                                                                                             |
 | `--hide-tool-results`                   | Hide tool call results in the output                                                                                                      |
@@ -220,8 +222,11 @@ $ docker agent serve mcp <config> [flags]
 | Flag                   | Default            | Description                                                                                       |
 | ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------- |
 | `-a, --agent <name>`   | (all agents)       | Name of the agent to expose. If omitted, every agent in the config is exposed as a separate tool. |
+| `--tool-name <name>`   | (agent name)       | Override the MCP tool identifier clients call; only valid when exposing a single agent.           |
 | `--http`               | `false`            | Use streaming HTTP transport instead of stdio.                                                    |
 | `-l, --listen <addr>`  | `127.0.0.1:8081`   | Address to listen on (only used with `--http`).                                                   |
+| `--mcp-keepalive <dur>`| `0` (disabled)     | Interval between MCP keep-alive pings (e.g. `30s`).                                               |
+| `--attach [target]`    | (none)             | Attach to a running TUI run by pid, address, or session id; given without a value, selects the most recent run.   |
 
 All [runtime configuration flags](#runtime-configuration-flags) are also accepted.
 

docs/features/tui/index.md

@@ -70,6 +70,7 @@ Type `/` during a session to see available commands, or press <kbd>Ctrl</kbd>+<k
 | `/eval`            | Create an evaluation report                                                          |
 | `/pause`           | Pause/resume the runtime loop after the current request                              |
 | `/tools`           | Show every toolset (with lifecycle state) and the tools they expose                  |
+| `/skills`          | List skills available to the current agent                                           |
 | `/toolset-restart` | Force a supervisor-driven reconnect of the named toolset (`/toolset-restart <name>`) |
 | `/permissions`     | Inspect and edit tool permission rules                                               |
 | `/split-diff`      | Toggle split-diff view for file edits                                                |

docs/guides/thinking/index.md

@@ -126,16 +126,17 @@ thinking_budget: none   # or 0
 
 ### Interleaved thinking
 
-By default, thinking is non-interleaved (the model reasons once before answering). Enable interleaved thinking to allow reasoning during tool calls — useful for complex agentic tasks:
+Interleaved thinking lets the model reason between tool calls — useful for complex agentic tasks. docker-agent auto-enables it whenever a thinking budget is configured on a Claude model, so you only need to set it explicitly to turn it off:
 
 ```yaml
 models:
   claude-interleaved:
     provider: anthropic
     model: claude-sonnet-4-5
     thinking_budget: 16384
+    # interleaved_thinking is auto-enabled; disable it explicitly if needed:
     provider_opts:
-      interleaved_thinking: true
+      interleaved_thinking: false
 ```
 
 <div class="callout callout-info" markdown="1">
@@ -247,13 +248,13 @@ models:
     thinking_budget: high
     provider_opts:
       region: us-east-1
-      interleaved_thinking: true
+      # interleaved_thinking is auto-enabled when thinking_budget is set
 ```
 
 <div class="callout callout-warning" markdown="1">
 <div class="callout-title">Bedrock thinking requirements
 </div>
-  <p>Bedrock Claude requires <code>thinking_budget</code> to be ≥ 1024 and less than <code>max_tokens</code>. docker-agent logs a warning and ignores the budget if either condition is violated. Interleaved thinking requires the <code>interleaved-thinking-2025-05-14</code> beta header, which docker-agent adds automatically when <code>interleaved_thinking: true</code> is set.</p>
+  <p>Bedrock Claude requires <code>thinking_budget</code> to be ≥ 1024 and less than <code>max_tokens</code>. docker-agent logs a warning and ignores the budget if either condition is violated. Interleaved thinking requires the <code>interleaved-thinking-2025-05-14</code> beta header, which docker-agent adds automatically; it is auto-enabled whenever a thinking budget is set on a Bedrock-hosted Claude model.</p>
 </div>
 
 ## xAI (Grok) and Mistral

docs/providers/anthropic/index.md

@@ -98,13 +98,13 @@ models:
 | Model ID            | Description                                         |
 | ------------------- | --------------------------------------------------- |
 | `claude-opus-4-7`   | Highest-capability Opus model; supports task budget |
-| `claude-sonnet-4-5` | Most capable Sonnet, extended thinking (default)    |
+| `claude-sonnet-4-5` | Most capable Sonnet; supports extended thinking     |
 | `claude-sonnet-4-0` | Previous Sonnet generation, still supported         |
 | `claude-haiku-4-5`  | Fast and inexpensive, good for tight loops          |
 
 ## Thinking Budget
 
-Anthropic uses integer token budgets (1024–32768). Defaults to 8192 with interleaved thinking enabled:
+Anthropic uses integer token budgets (1024–32768). Thinking is off unless you set `thinking_budget`; when set, interleaved thinking is auto-enabled:
 
 ```yaml
 models:
@@ -116,7 +116,7 @@ models:
 
 ## Interleaved Thinking
 
-Enabled by default. Allows tool calls during model reasoning for more integrated problem-solving:
+Auto-enabled whenever a thinking budget is configured on a Claude model. Allows tool calls during model reasoning for more integrated problem-solving:
 
 ```yaml
 models:

docs/providers/bedrock/index.md

@@ -80,7 +80,7 @@ models:
 | `role_session_name`      | string | docker-agent-bedrock-session | Session name for assumed role        |
 | `external_id`            | string | —                      | External ID for role assumption      |
 | `endpoint_url`           | string | —                      | Custom endpoint (VPC/testing)        |
-| `interleaved_thinking`   | bool   | false                  | Allow reasoning between tool calls (Claude); adds the required beta header automatically |
+| `interleaved_thinking`   | bool   | auto                   | Allow reasoning between tool calls (Claude); auto-enabled when a thinking budget is set on a Claude model; adds the required beta header automatically |
 | `disable_prompt_caching` | bool   | false                  | Disable automatic prompt caching     |
 
 ## Inference Profiles
@@ -144,10 +144,10 @@ models:
     thinking_budget: high
     provider_opts:
       region: us-east-1
-      interleaved_thinking: true
+      # interleaved_thinking is auto-enabled when thinking_budget is set
 ```
 
-docker-agent automatically adds the `interleaved-thinking-2025-05-14` beta header when `interleaved_thinking: true` is set. If you set `interleaved_thinking: false` while a thinking budget is active, a warning is logged because the budget may be ignored by Bedrock without the beta header.
+docker-agent auto-enables `interleaved_thinking` whenever a thinking budget is configured on a Bedrock-hosted Claude model and automatically adds the `interleaved-thinking-2025-05-14` beta header. If you set `interleaved_thinking: false` while a thinking budget is active, a warning is logged because the budget may be ignored by Bedrock without the beta header.
 
 See the [Thinking / Reasoning guide]({{ '/guides/thinking/' | relative_url }}) for a full cross-provider overview.
 

docs/tools/filesystem/index.md

@@ -84,7 +84,7 @@ restriction visible to the model so it can adjust its plan.
 
 ### Post-Edit Hooks
 
-Automatically run formatting, linting, or other commands after the agent edits a file. The command fires once per file after each edit operation (including `write_file`, `patch_file`, and similar mutations). Use `${file}` as a placeholder for the absolute path of the edited file.
+Automatically run formatting, linting, or other commands after the agent edits a file. The command fires once per file after each edit operation (`write_file` and `edit_file`). Use `${file}` as a placeholder for the absolute path of the edited file.
 
 ```yaml
 toolsets:

docs/tools/model-picker/index.md

@@ -31,7 +31,7 @@ toolsets:
 
 ## How It Works
 
-When the model picker toolset is enabled, the agent gets a `pick_model` tool it can call to switch to a different model for the next turn. The agent decides which model to use based on the complexity of the task, cost considerations, or other factors you describe in its instruction.
+When the model picker toolset is enabled, the agent gets two tools: `change_model` to switch to one of the configured models, and `revert_model` to return to its default model. The agent decides which model to use based on the complexity of the task, cost considerations, or other factors you describe in its instruction.
 
 ## Example
 
@@ -59,10 +59,16 @@ agents:
 
 ## Tool Interface
 
-The toolset exposes a single tool, `pick_model`, with one parameter:
+The toolset exposes two tools:
+
+### `change_model`
 
 | Parameter | Type   | Required | Description                                                                 |
 | --------- | ------ | -------- | --------------------------------------------------------------------------- |
-| `model`   | string | ✓        | The model to use for the next turn. Must be one of the configured models.   |
+| `model`   | string | ✓        | The model to switch to. Must be one of the configured models.               |
+
+### `revert_model`
+
+Takes no parameters. Reverts the agent to its original/default model.
 
-The model switch takes effect on the **next** turn — the current turn continues with the model that was active when `pick_model` was called.
+The switch takes effect immediately: the next inference call — including the remainder of the current agentic loop — uses the new model.

docs/tools/rag/index.md

@@ -56,7 +56,7 @@ strategies:
     similarity_metric: cosine_similarity
     threshold: 0.5
     limit: 10
-    batch_size: 50
+    embedding_batch_size: 50
     chunking:
       size: 1000
       overlap: 100
@@ -212,9 +212,9 @@ Look for log tags: `[RAG Manager]`, `[Chunked-Embeddings Strategy]`, `[BM25 Stra
 | `similarity_metric`         | string | `cosine_similarity` | Similarity metric                                            |
 | `threshold`                 | float  | `0.5`               | Minimum similarity score (0–1)                               |
 | `limit`                     | int    | `5`                 | Max results from this strategy                               |
-| `batch_size`                | int    | `50`                | Chunks per embedding request                                 |
+| `embedding_batch_size`      | int    | `50`                | Chunks per embedding request                                 |
 | `max_embedding_concurrency` | int    | `3`                 | Max concurrent embedding requests                            |
-| `chunking.size`             | int    | `1000`              | Chunk size in characters                                     |
+| `chunking.size`             | int    | `1500`              | Chunk size in characters (`4000` when `code_aware` is set)   |
 | `chunking.overlap`          | int    | `75`                | Overlap between chunks in characters                         |
 | `chunking.code_aware`       | bool   | `false`             | AST-based chunking (Go files only)                           |
 
@@ -231,7 +231,7 @@ Look for log tags: `[RAG Manager]`, `[Chunked-Embeddings Strategy]`, `[BM25 Stra
 | `threshold`                | float  | `0.5`      | Minimum similarity score (0–1)                                     |
 | `limit`                    | int    | `5`        | Max results                                                        |
 | `max_indexing_concurrency` | int    | `3`        | Max concurrent file indexing                                       |
-| `chunking.size`            | int    | `1000`     | Chunk size in characters                                           |
+| `chunking.size`            | int    | `1500`     | Chunk size in characters (`4000` when `code_aware` is set)         |
 | `chunking.overlap`         | int    | `75`       | Overlap between chunks                                             |
 | `chunking.code_aware`      | bool   | `false`    | AST-based chunking                                                 |
 
@@ -244,7 +244,7 @@ Look for log tags: `[RAG Manager]`, `[Chunked-Embeddings Strategy]`, `[BM25 Stra
 | `b`                | float  | `0.75`  | Length normalization (0–1)                      |
 | `threshold`        | float  | `0.0`   | Minimum BM25 score                              |
 | `limit`            | int    | `5`     | Max results                                     |
-| `chunking.size`    | int    | `1000`  | Chunk size in characters                        |
+| `chunking.size`    | int    | `1500`  | Chunk size in characters                        |
 | `chunking.overlap` | int    | `75`    | Overlap between chunks                          |
 
 ### Results (Post-Processing)
@@ -258,6 +258,6 @@ Look for log tags: `[RAG Manager]`, `[Chunked-Embeddings Strategy]`, `[BM25 Stra
 | `include_score`       | bool   | `false` | Include relevance scores in results                         |
 | `return_full_content` | bool   | `false` | Return full document content instead of just matched chunks |
 | `reranking.model`     | string | —       | Reranking model reference                                   |
-| `reranking.top_k`     | int    | (all)   | Only rerank top K results                                   |
+| `reranking.top_k`     | int    | (`limit`) | Only rerank top K results. Defaults to the results `limit` when set.  |
 | `reranking.threshold` | float  | `0.5`   | Minimum relevance score after reranking                     |
 | `reranking.criteria`  | string | —       | Custom relevance guidance for the reranking model           |