docs: updates for lead-worker model

documentation/docs/guides/config-file.md

@@ -11,26 +11,30 @@ Goose uses a YAML configuration file to manage settings and extensions. This fil
 * macOS/Linux: `~/.config/goose/config.yaml`
 * Windows: `%APPDATA%\Block\goose\config\config.yaml`
 
-The configuration file allows you to set default behaviors, configure language models, and manage extensions. While many settings can also be set using environment variables, the config file provides a persistent way to maintain your preferences.
+The configuration file allows you to set default behaviors, configure language models, and manage extensions. While many settings can also be set using [environment variables](/docs/guides/environment-variables), the config file provides a persistent way to maintain your preferences.
 
 ## Global Settings
 
 The following settings can be configured at the root level of your config.yaml file:
 
 | Setting | Purpose | Values | Default | Required |
 |---------|---------|---------|---------|-----------|
-| `GOOSE_PROVIDER` | Primary LLM provider | "anthropic", "openai", etc. | None | Yes |
+| `GOOSE_PROVIDER` | Primary [LLM provider](/docs/getting-started/providers) | "anthropic", "openai", etc. | None | Yes |
 | `GOOSE_MODEL` | Default model to use | Model name (e.g., "claude-3.5-sonnet", "gpt-4") | None | Yes |
 | `GOOSE_TEMPERATURE` | Model response randomness | Float between 0.0 and 1.0 | Model-specific | No |
 | `GOOSE_MODE` | Tool execution behavior | "auto", "approve", "chat", "smart_approve" | "smart_approve" | No |
-| `GOOSE_PLANNER_PROVIDER` | Provider for planning mode | Same as GOOSE_PROVIDER options | Falls back to GOOSE_PROVIDER | No |
-| `GOOSE_PLANNER_MODEL` | Model for planning mode | Model name | Falls back to GOOSE_MODEL | No |
+| `GOOSE_LEAD_PROVIDER` | Provider for lead model in [lead/worker mode](/docs/guides/environment-variables#leadworker-model-configuration) | Same as `GOOSE_PROVIDER` options | Falls back to `GOOSE_PROVIDER` | No |
+| `GOOSE_LEAD_MODEL` | Lead model for lead/worker mode | Model name | None | No |
+| `GOOSE_PLANNER_PROVIDER` | Provider for [planning mode](/docs/guides/creating-plans) | Same as `GOOSE_PROVIDER` options | Falls back to `GOOSE_PROVIDER` | No |
+| `GOOSE_PLANNER_MODEL` | Model for planning mode | Model name | Falls back to `GOOSE_MODEL` | No |
 | `GOOSE_TOOLSHIM` | Enable tool interpretation | true/false | false | No |
 | `GOOSE_TOOLSHIM_OLLAMA_MODEL` | Model for tool interpretation | Model name (e.g., "llama3.2") | System default | No |
 | `GOOSE_CLI_MIN_PRIORITY` | Tool output verbosity | Float between 0.0 and 1.0 | 0.0 | No |
 | `GOOSE_ALLOWLIST` | URL for allowed extensions | Valid URL | None | No |
 | `GOOSE_RECIPE_GITHUB_REPO` | GitHub repository for recipes | Format: "org/repo" | None | No |
 
+Additional [environment variables](/docs/guides/environment-variables) may also be supported in config.yaml.
+
 ## Example Configuration
 
 Here's a basic example of a config.yaml file:

documentation/docs/guides/creating-plans.md

@@ -31,6 +31,10 @@ The Goose CLI plan mode uses two configuration values:
 - `GOOSE_PLANNER_PROVIDER`: Which provider to use for planning
 - `GOOSE_PLANNER_MODEL`: Which model to use for planning
 
+:::tip Use Lead/Worker Mode For Automatic Model Switching
+[Lead/worker mode](/docs/guides/environment-variables#leadworker-model-configuration) is an alternative to plan mode. It allows you to configure a powerful lead model for initial planning and reasoning before automatically switching to a faster and/or cheaper worker model for execution. Both modes help you achieve optimal results by balancing model capabilities with cost and speed.
+:::
+
 ### Set Goose planner environment variables
 You might add these lines to your bash shell config file (.bashrc) to add the planner environment variables:
 ```bash

documentation/docs/guides/environment-variables.md

@@ -50,15 +50,23 @@ export GOOSE_PROVIDER__API_KEY="your-api-key-here"
 
 ### Lead/Worker Model Configuration
 
-Configure a lead/worker model pattern where a powerful model handles initial planning and complex reasoning, then switches to a faster/cheaper model for execution.
+These variables configure a lead/worker model pattern where a powerful lead model handles initial planning and complex reasoning, then switches to a faster/cheaper worker model for execution. The switch happens automatically based on your settings.
 
 | Variable | Purpose | Values | Default |
 |----------|---------|---------|---------|
-| `GOOSE_LEAD_MODEL` | **Required to enable lead mode.** Specifies the lead model name | Model name (e.g., "gpt-4o", "claude-3.5-sonnet") | None |
-| `GOOSE_LEAD_PROVIDER` | Provider for the lead model | [See available providers](/docs/getting-started/providers#available-providers) | Falls back to GOOSE_PROVIDER |
-| `GOOSE_LEAD_TURNS` | Number of initial turns using the lead model | Integer | 3 |
-| `GOOSE_LEAD_FAILURE_THRESHOLD` | Consecutive failures before fallback to lead model | Integer | 2 |
-| `GOOSE_LEAD_FALLBACK_TURNS` | Number of turns to use lead model in fallback mode | Integer | 2 |
+| `GOOSE_LEAD_MODEL` | **Required to enable lead mode.** Name of the lead model | Model name (e.g., "gpt-4o", "claude-3.5-sonnet") | None |
+| `GOOSE_LEAD_PROVIDER` | Provider for the lead model | [See available providers](/docs/getting-started/providers#available-providers) | Falls back to `GOOSE_PROVIDER` |
+| `GOOSE_LEAD_TURNS` | Number of initial turns using the lead model before switching to the worker model | Integer | 3 |
+| `GOOSE_LEAD_FAILURE_THRESHOLD` | Consecutive failures before fallback to the lead model | Integer | 2 |
+| `GOOSE_LEAD_FALLBACK_TURNS` | Number of turns to use the lead model in fallback mode | Integer | 2 |
+
+A _turn_ is one complete prompt-response interaction. Here's how it works with the default settings:
+- Use the lead model for the first 3 turns
+- Use the worker model starting on the 4th turns
+- Fallback to the lead model if the worker model struggles for 2 consecutive turns
+- Use the lead model for 2 turns and then switch back to the worker model
+
+The lead model and worker model names are displayed at the start of the Goose CLI session. If you don't export a `GOOSE_MODEL` for your session, the worker model defaults to the `GOOSE_MODEL` in your [configuration file](/docs/guides/config-file).
 
 **Examples**