`goose configure` Documentation incorrectly references config.yaml instead of config directory

[blackgirlbytes]

The documentation currently references config.yaml as if it's the only configuration file, but goose actually uses multiple configuration files within the ~/.config/goose/ directory. The documentation should be updated to accurately reflect this multi-file structure.

Current Problem

Documentation references like:

• "edit it directly at ~/.config/goose/config.yaml"
• "your config file at ~/.config/goose/config.yaml"
• Instructions to modify config.yaml for settings that are actually stored elsewhere

Expected Behavior

Documentation should:

1. Reference the config directory (~/.config/goose/) when discussing configuration generally
2. Specify which specific file is used for different types of configuration
3. Explain the purpose of each configuration file

Configuration Files Structure

~/.config/goose/
├── config.yaml              # Provider, model, extensions, general settings
├── permission.yaml          # Tool permission levels (user-configured)
├── secrets.yaml             # Secrets (when keyring is disabled)
└── permissions/             # Runtime permission decisions (auto-managed)
    └── tool_permissions.json

Files That Need Updates

The following 13 documentation files reference config.yaml and need to be reviewed and updated:

High Priority

1. documentation/docs/guides/config-file.md - Main config documentation
2. documentation/docs/getting-started/installation.md
3. documentation/docs/troubleshooting.md

Medium Priority

4. documentation/docs/getting-started/using-extensions.md
5. documentation/docs/guides/managing-tools/tool-router.md
6. documentation/docs/guides/subagents.mdx
7. documentation/docs/guides/recipes/session-recipes.md
8. documentation/docs/guides/multi-model/creating-plans.md
9. documentation/docs/guides/multi-model/autopilot.md
10. documentation/docs/guides/sessions/smart-context-management.md

Lower Priority

11. documentation/docs/tutorials/isolated-development-environments.md
12. documentation/docs/tutorials/cicd.md
13. documentation/blog/2025-06-19-isolated-development-environments/index.md

Suggested Changes

General References

Before:

You can edit your config file at `~/.config/goose/config.yaml`

After:

Configuration files are stored in `~/.config/goose/`. The main config file is `config.yaml`.

Specific Settings

When documenting specific settings, specify which file:

Example for provider settings:

Provider and model settings are stored in `~/.config/goose/config.yaml`

Example for permissions:

Tool permissions are stored in `~/.config/goose/permission.yaml`

Add Configuration Overview Section

The main config documentation (docs/guides/config-file.md) should include a section explaining all configuration files:

## Configuration Files

goose stores configuration in multiple files within `~/.config/goose/`:

- **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)

Related Issue

This is part of the fix for the bug reported in #4734, which identified that goose misdocuments its configuration structure. The CLI portion is being addressed in a separate issue.

Acceptance Criteria

• All 13 documentation files have been reviewed
• References to config.yaml are updated to either:
  • Reference the config directory generally, OR
  • Specify the correct file for the specific setting
• Main config documentation includes overview of all config files
• Documentation accurately reflects which settings go in which files
• No misleading references that suggest only config.yaml is used

Additional Context

Search command to find all references:

rg "config\.yaml" documentation/ -l

[anthonydmays]

I'll .take this

[github-actions]

Thanks for taking this issue! Let us know if you have any questions!

[Shreyanshsingh23]

I'll take this

[taniacryptid]

Hi @Shreyanshsingh23 - this is already in progress and being worked on!

[blackgirlbytes]

I was hoping the devs would merge the code PR for this..so that I could merge the related docs PR (which is the one)

[taniacryptid]

Reopening only because #5210 needs to be merged to close this