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

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

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: