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)

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Inconsistency in docs for where to install skills #6171: Inconsistency in docs for where to install skills - Also relates to documentation inconsistency about XDG paths vs standard paths
• Reorganize and document dirs for config, agents, auth credentials, sessions #4170: Reorganize and document dirs for config, agents, auth credentials, sessions - Discusses the broader issue of scattered config locations and lack of documentation
• Install script should use XDG_DATA_HOME for binary location #5176: Install script should use XDG_DATA_HOME for binary location - Related to XDG spec support inconsistency

Feel free to ignore if none of these address your specific case.

[pwuersch]

I apologize for missing the discussion in #4170 which seems to partially relate to my concerns. However, I am not convinced that that big of a change is necessary, as stated in the issue description above. Hence, I wouldn't call this a duplicate.

I created a draft PR with a proposal on how to mention both the XDG base directory spec as well as the used default of ~/.config/opencode here: #6670

As a side note, bug might not be the appropriate label for this issue; it should rather only be docs.