diff --git a/packages/opencode/src/cli/cmd/tui/component/tips.ts b/packages/opencode/src/cli/cmd/tui/component/tips.ts
index ed8ce147471..b0a7efe699f 100644
--- a/packages/opencode/src/cli/cmd/tui/component/tips.ts
+++ b/packages/opencode/src/cli/cmd/tui/component/tips.ts
@@ -31,7 +31,7 @@ export const TIPS = [
   "Use {highlight}@<agent-name>{/highlight} in prompts to invoke specialized subagents.",
   "Press {highlight}Ctrl+X Right/Left{/highlight} to cycle through parent and child sessions.",
   "Create {highlight}opencode.json{/highlight} in project root for project-specific settings.",
-  "Place settings in {highlight}~/.config/opencode/opencode.json{/highlight} for global config.",
+  "Place settings in {highlight}~/.config/opencode/opencode.json{/highlight} for global config (see docs for XDG support).",
   "Add {highlight}$schema{/highlight} to your config for autocomplete in your editor.",
   "Configure {highlight}model{/highlight} in config to set your default model.",
   "Override any keybind in config via the {highlight}keybinds{/highlight} section.",
diff --git a/packages/web/src/content/docs/config.mdx b/packages/web/src/content/docs/config.mdx
index a5931b6fcf5..dbba1b1a520 100644
--- a/packages/web/src/content/docs/config.mdx
+++ b/packages/web/src/content/docs/config.mdx
@@ -91,9 +91,9 @@ You can enable specific servers in your local config:
 
 ### Global
 
-Place your global OpenCode config in `~/.config/opencode/opencode.json`. Use global config for user-wide preferences like themes, providers, or keybinds.
+Place your global OpenCode config in `$XDG_CONFIG_HOME/opencode/opencode.json`. Use global config for user-wide preferences like themes, providers, or keybinds. Global config overrides remote organizational defaults.
 
-Global config overrides remote organizational defaults.
+If the `XDG_CONFIG_HOME` environment variable is not set, OpenCode uses the default location: `~/.config/opencode/opencode.json`.
 
 ---
 
diff --git a/packages/web/src/content/docs/plugins.mdx b/packages/web/src/content/docs/plugins.mdx
index bf26744f6c4..170b193e436 100644
--- a/packages/web/src/content/docs/plugins.mdx
+++ b/packages/web/src/content/docs/plugins.mdx
@@ -55,9 +55,9 @@ Browse available plugins in the [ecosystem](/docs/ecosystem#plugins).
 
 Plugins are loaded from all sources and all hooks run in sequence. The load order is:
 
-1. Global config (`~/.config/opencode/opencode.json`)
+1. Global config (see [config locations](/docs/config#locations))
 2. Project config (`opencode.json`)
-3. Global plugin directory (`~/.config/opencode/plugin/`)
+3. Global plugin directory
 4. Project plugin directory (`.opencode/plugin/`)
 
 Duplicate npm packages with the same name and version are loaded once. However, a local plugin and an npm plugin with similar names are both loaded separately.
diff --git a/packages/web/src/content/docs/rules.mdx b/packages/web/src/content/docs/rules.mdx
index aa5590bb5f4..d7b8cb1b81a 100644
--- a/packages/web/src/content/docs/rules.mdx
+++ b/packages/web/src/content/docs/rules.mdx
@@ -64,6 +64,10 @@ The ones we have seen above, where the `AGENTS.md` is placed in the project root
 
 You can also have global rules in a `~/.config/opencode/AGENTS.md` file. This gets applied across all opencode sessions.
 
+:::note
+Global files are placed in your OpenCode config directory. [Learn more about config locations](/docs/config#locations).
+:::
+
 Since this isn't committed to Git or shared with your team, we recommend using this to specify any personal rules that the LLM should follow.
 
 ---
@@ -73,7 +77,7 @@ Since this isn't committed to Git or shared with your team, we recommend using t
 So when opencode starts, it looks for:
 
 1. **Local files** by traversing up from the current directory
-2. **Global file** by checking `~/.config/opencode/AGENTS.md`
+2. **Global file** by checking your [config directory](/docs/config#locations) for AGENTS.md
 
 If you have both global and project-specific rules, opencode will combine them together.