Docs miss mentioning XDG base directories for global configuration while already supporting them

[pwuersch]

Description

In the configuration documentation, it is only stated that the global configuration file is located at ~/.config/opencode/opencode.json. However, in cases where the XDG_CONFIG_HOME environment variable is set, OpenCode will look up the global configuration file in XDG_CONFIG_HOME/opencode/opencode.json. This also applies for all other global configurations and files.

It is amazing that opencode supports the XDG spec. I just came across this misinformation in the docs because I couldn't get my global configuration file to work (I have a different folder set as my XDG config home). IMHO, this should be aligned better in the docs, although I understand that many users won't know of XDG base directory variables.

OpenCode version

v1.0.223

Steps to reproduce

1. Place a file with custom configuration in ~/.config/opencode/opencode.json
2. Run opencode with a custom XDG_CONFIG_HOME environment variable set (e.g., export XDG_CONFIG_HOME="$HOME/.imaginary-folder"
3. Observe how the global configuration in ~/.config/opencode/opencode.json does not have any effect anymore and $HOME/.imaginary-folder/opencode has been created.

Screenshot and/or share link

Current documentation content: https://github.com/sst/opencode/blob/70881b2937fab1e425416659445875952730934a/packages/web/src/content/docs/config.mdx?plain=1#L41-L43

Relevant implementation specs:

• Defining XDG_CONFIG_HOME/opencode as the global config dir: https://github.com/sst/opencode/blob/70881b2937fab1e425416659445875952730934a/packages/opencode/src/global/index.ts#L10
• Relevant source code of xdg-basedir: https://github.com/sindresorhus/xdg-basedir/blob/8cceade858e4da18cb971bf1844f086e9e213563/index.js#L10-L11
• Adding the global config dir to the locations that are searched for global opencode.json files: https://github.com/sst/opencode/blob/47ebb2973f8bad2c98f4834de7f443b03b097ccd/packages/opencode/src/config/config.ts#L71

Operating System

macOS Tahoe 26.2 (25C56)

Terminal

Ghostty v1.2.3 (build 12214)