docs: clarifies config file locations and purposes (#5210)

Signed-off-by: Anthony D. Mays <anthony@morganlatimer.com>

BUILDING_DOCKER.md

@@ -319,4 +319,4 @@ When contributing Docker-related changes:
 
 - [goose in Docker Tutorial](documentation/docs/tutorials/goose-in-docker.md) - Step-by-step tutorial
 - [Installation Guide](https://block.github.io/goose/docs/getting-started/installation) - All installation methods
-- [Configuration Guide](https://block.github.io/goose/docs/guides/config-file) - Detailed configuration options
+- [Configuration Guide](https://block.github.io/goose/docs/guides/config-files) - Detailed configuration options

documentation/docs/getting-started/installation.md

@@ -376,10 +376,10 @@ You can change your LLM provider and/or model or update your API key at any time
 
 ## Shared Configuration Settings
 
-The Goose CLI and Desktop UI share all core configurations, including LLM provider settings, model selection, and extension configurations. When you install or configure extensions in either interface, the settings are stored in a central location at `~/.config/goose/config.yaml`, making them available to both the Desktop application and CLI. This makes it convenient to switch between interfaces while maintaining consistent settings.
+The Goose CLI and Desktop UI share all core configurations, including LLM provider settings, model selection, and extension configurations. When you install or configure extensions in either interface, the settings are stored in a central location, making them available to both the Desktop application and CLI. This makes it convenient to switch between interfaces while maintaining consistent settings. For more information, visit the [Config Files][config-files] guide.
 
 :::info
-While core configurations are shared between interfaces, extensions have flexibility in how they store authentication credentials. Some extensions may use the shared config file while others implement their own storage methods.
+While core configurations are shared between interfaces, extensions have flexibility in how they store authentication credentials. Some extensions may use the shared config files while others implement their own storage methods.
 :::
 
 <Tabs groupId="interface">
@@ -404,3 +404,4 @@ You can also configure Extensions to extend Goose's functionality, including add
 [providers]: /docs/getting-started/providers
 [handling-rate-limits]: /docs/guides/handling-llm-rate-limits-with-goose
 [mcp]: https://www.anthropic.com/news/model-context-protocol
+[config-files]: /docs/guides/config-files.md

documentation/docs/getting-started/using-extensions.md

@@ -523,7 +523,7 @@ Goose relies on extension properties to determine how to handle an extension. Yo
 
   <TabItem value="cli" label="Config file">
   
-  1. Navigate to the Goose [configuration file](/docs/guides/config-file). For example, navigate to `~/.config/goose/config.yaml` on macOS.
+  1. Navigate to the Goose [configuration file](/docs/guides/config-files). For example, navigate to `~/.config/goose/config.yaml` on macOS.
   2. Edit the extension properties as needed and save your changes.
 
   </TabItem>

documentation/docs/guides/acp-clients.md

@@ -77,7 +77,7 @@ You should now be able to interact with Goose directly in Zed. Your ACP sessions
 
 ### Advanced Configuration
 
-By default, Goose will use the provider and model defined in your [configuration file](/docs/guides/config-file). You can override this for specific ACP configurations using the `GOOSE_PROVIDER` and `GOOSE_MODEL` environment variables.
+By default, Goose will use the provider and model defined in your [configuration file](/docs/guides/config-files). You can override this for specific ACP configurations using the `GOOSE_PROVIDER` and `GOOSE_MODEL` environment variables.
 
 The following Zed settings example configures two Goose agent instances. This is useful for:
 - Comparing model performance on the same task

documentation/docs/guides/config-files.md

@@ -1,17 +1,24 @@
 ---
 sidebar_position: 85
-title: Configuration File
-sidebar_label: Configuration File
+title: Configuration Files
+sidebar_label: Configuration Files
 ---
 
-# Configuration File
+# Configuration Overview
 
-goose uses a YAML configuration file to manage settings and extensions. This file is located at:
+goose uses YAML [configuration files](#configuration-files) to manage settings and extensions. The primary config file is located at:
 
 * 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](/docs/guides/environment-variables), the config file provides a persistent way to maintain your preferences.
+The configuration files allow you to set default behaviors, configure language models, set tool permissions, and manage extensions. While many settings can also be set using [environment variables](/docs/guides/environment-variables), the config files provide a persistent way to maintain your preferences.
+
+## Configuration Files
+
+- **config.yaml** - Provider, model, extensions, and general settings
+- **permission.yaml** - Tool permission levels configured via `goose configure`
+- **secrets.yaml** - API keys and secrets (only when keyring is disabled)
+- **permissions/tool_permissions.json** - Runtime permission decisions (auto-managed)
 
 ## Global Settings
 
@@ -139,7 +146,7 @@ Settings are applied in the following order of precedence:
 
 ## Updating Configuration
 
-Changes to the config file require restarting goose to take effect. You can verify your current configuration using:
+Changes to config files require restarting goose to take effect. You can verify your current configuration using:
 
 ```bash
 goose info -v

documentation/docs/guides/environment-variables.md

@@ -70,7 +70,7 @@ A _turn_ is one complete prompt-response interaction. Here's how it works with t
 - 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).
+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-files).
 
 **Examples**
 

documentation/docs/guides/goose-cli-commands.md

@@ -507,7 +507,7 @@ The `/t` command controls the syntax highlighting theme for markdown content in
 
 **Configuration:**
 - The default theme is `dark`
-- The theme setting is saved to the [configuration file](/docs/guides/config-file) as `GOOSE_CLI_THEME` and persists between sessions
+- The theme setting is saved to the [configuration file](/docs/guides/config-files) as `GOOSE_CLI_THEME` and persists between sessions
 - The saved configuration can be overridden for the session using the `GOOSE_CLI_THEME` [environment variable](/docs/guides/environment-variables#session-management)
 
 :::info

documentation/docs/guides/managing-tools/tool-router.md

@@ -147,7 +147,7 @@ When enabled, Goose uses LLM intelligence to analyze your query and select only
 
 ## Environment Variable Configuration
 
-You can also configure tool selection using environment variables or in your [configuration file](/docs/guides/config-file):
+You can also configure tool selection using environment variables or in your [configuration file](/docs/guides/config-files):
 
 ```bash
 # Enable LLM-based tool selection

documentation/docs/guides/multi-model/autopilot.md

@@ -33,7 +33,7 @@ You can use `goose session --debug` in goose CLI to see when AutoPilot switches
 
 ## Configuration
 
-Add the `x-advanced-models` section to your [`config.yaml`](/docs/guides/config-file) file and map your model preferences to [predefined](#predefined-roles) or custom roles. 
+Add the `x-advanced-models` section to your [`config.yaml`](/docs/guides/config-files) file and map your model preferences to [predefined](#predefined-roles) or custom roles. 
 
 The `provider`, `model` and `role` parameters are required.
 

documentation/docs/guides/recipes/session-recipes.md

@@ -265,7 +265,7 @@ You can turn your current goose session into a reusable recipe that includes the
 
    #### Configure Recipe Location
 
-  Recipes can be stored locally on your device or in a GitHub repository. Configure your recipe repository using either the `goose configure` command or [config file](/docs/guides/config-file#global-settings).
+  Recipes can be stored locally on your device or in a GitHub repository. Configure your recipe repository using either the `goose configure` command or [config file](/docs/guides/config-files#global-settings).
 
   :::tip Repository Structure
   - Each recipe should be in its own directory

documentation/docs/guides/security/prompt-injection-detection.md

@@ -64,7 +64,7 @@ When in doubt, deny.
   </TabItem>
   <TabItem value="config" label="goose config file">
 
-    Add these settings to your [`config.yaml`](/docs/guides/config-file):
+    Add these settings to your [`config.yaml`](/docs/guides/config-files):
 
     ```yaml
     security_prompt_enabled: true

documentation/docs/guides/sessions/smart-context-management.md

@@ -159,7 +159,7 @@ This feature gives you control over agent autonomy and prevents infinite loops a
 - Enabling human supervision or interaction during autonomous operations
 - Controlling loops while testing and debugging agent behavior
 
-This setting is stored as the `GOOSE_MAX_TURNS` environment variable in your [config.yaml file](/docs/guides/config-file). You can configure it using the Desktop app or CLI.
+This setting is stored as the `GOOSE_MAX_TURNS` environment variable in your [config.yaml file](/docs/guides/config-files). You can configure it using the Desktop app or CLI.
 
 <Tabs groupId="interface">
     <TabItem value="ui" label="goose Desktop" default>
@@ -375,7 +375,7 @@ Pricing data is regularly fetched from the OpenRouter API and cached locally. Th
 These costs are estimates only, and not connected to your actual provider bill. The cost shown is an approximation based on token counts and public pricing data.
 </TabItem>
     <TabItem value="cli" label="goose CLI">
-    Show estimated cost in the Goose CLI by setting the `GOOSE_CLI_SHOW_COST` [environment variable](/docs/guides/environment-variables.md#session-management) or including it in the [configuration file](/docs/guides/config-file.md).
+    Show estimated cost in the Goose CLI by setting the `GOOSE_CLI_SHOW_COST` [environment variable](/docs/guides/environment-variables.md#session-management) or including it in the [configuration file](/docs/guides/config-files.md).
 
   ```
   # Set environment variable

documentation/docs/guides/subagents.mdx

@@ -150,7 +150,7 @@ I'll use your code-reviewer recipe to create a specialized subagent for this ana
 
 External subagents let you bring in AI agents from other providers and platforms, enabling Goose to coordinate and integrate your workflow with the broader ecosystem. In the below example, we use Codex as a subagent by running it as an MCP server:
 
-**[Goose Configuration File](/docs/guides/config-file)** (`.~/.config/goose/config.yaml `):
+**[Goose Configuration File](/docs/guides/config-files)** (`.~/.config/goose/config.yaml `):
 ```yaml
 subagent:
   args:

documentation/docs/troubleshooting.md

@@ -125,7 +125,7 @@ Failed to authenticate: Execution error: OAuth configuration not supported by th
 ``` 
 
 To resolve:
-1. Temporarily comment out or remove lead/worker model variables from your config file (`~/.config/goose/config.yaml`):
+1. Temporarily comment out or remove lead/worker model variables from the main config file (`~/.config/goose/config.yaml`):
    ```yaml
    # GOOSE_LEAD_MODEL: your-model
    # GOOSE_WORKER_MODEL: your-model

documentation/docusaurus.config.ts

@@ -162,6 +162,10 @@ const config: Config = {
             from: '/docs/guides/creating-plans',
             to: '/docs/guides/multi-model/creating-plans'
           },
+          {
+            from: '/docs/guides/config-file',
+            to: '/docs/guides/config-files',
+          },
           // MCP tutorial redirects - moved from /docs/tutorials/ to /docs/mcp/
           {
             from: '/docs/tutorials/agentql-mcp',