From 13c70cff121865fcc22cd26e2e13fb623273bce8 Mon Sep 17 00:00:00 2001
From: Matan Kushner <hello@matchai.dev>
Date: Mon, 4 May 2026 19:41:12 +0900
Subject: [PATCH] docs(config): document hierarchical config discovery

Update the README quick-overview bullet and the dedicated File Locations
section in docs/reference/configuration.md to describe the walk-up
behaviour added in #417: configs under `.opencode/` are discovered by
walking from the working directory up to $HOME, with closer configs
winning.

Includes a hierarchical example (`~/.config/opencode/` global,
`~/work/.opencode/` work overrides, repo-specific overrides under that)
and a security note explaining why `mcp_env_allowlist` remains
extensible only from the canonical user config.
---
 README.md                       | 2 +-
 docs/reference/configuration.md | 6 ++++--
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index ce12f818b..c3fbc3441 100644
--- a/README.md
+++ b/README.md
@@ -336,7 +336,7 @@ Opinionated defaults, adjustable if you insist.
 See [Configuration Documentation](docs/reference/configuration.md).
 
 **Quick Overview:**
-- **Config Locations**: The compatibility layer recognizes both `oh-my-openagent.json[c]` and legacy `oh-my-opencode.json[c]` plugin config files. Existing installs still commonly use the legacy basename.
+- **Config Locations**: User config plus walked `.opencode/oh-my-openagent.json[c]` configs up to `$HOME`; closest wins. Legacy `oh-my-opencode.json[c]` still works.
 - **JSONC Support**: Comments and trailing commas supported
 - **Agents**: Override models, temperatures, prompts, and permissions for any agent
 - **Built-in Skills**: `playwright` (browser automation), `git-master` (atomic commits)
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index cfd5e1b18..7a6004a49 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -43,9 +43,9 @@ Complete reference for Oh My OpenCode plugin configuration. During the rename tr
 
 ### File Locations
 
-User config is loaded first, then project config overrides it. In each directory, the compatibility layer recognizes both the renamed and legacy basenames.
+User config loads first. Project configs are discovered by walking from the working directory up to `$HOME`; closer configs win. If the working directory is outside `$HOME`, only that directory is checked.
 
-1. Project config: `.opencode/oh-my-openagent.json[c]` or `.opencode/oh-my-opencode.json[c]`
+1. Walked configs: `.opencode/oh-my-openagent.json[c]` or legacy `.opencode/oh-my-opencode.json[c]`
 2. User config (`.jsonc` preferred over `.json`):
 
 | Platform    | Path candidates |
@@ -53,6 +53,8 @@ User config is loaded first, then project config overrides it. In each directory
 | macOS/Linux | `~/.config/opencode/oh-my-openagent.json[c]`, `~/.config/opencode/oh-my-opencode.json[c]` |
 | Windows     | `%APPDATA%\opencode\oh-my-openagent.json[c]`, `%APPDATA%\opencode\oh-my-opencode.json[c]` |
 
+**Security note:** `mcp_env_allowlist` is user-only. Walked configs cannot extend it.
+
 **Rename compatibility:** The published package and CLI binary remain `oh-my-opencode`. OpenCode plugin registration prefers `oh-my-openagent`, while legacy `oh-my-opencode` entries and config basenames still load during the transition. Config detection checks `oh-my-opencode` before `oh-my-openagent`, so if both plugin config basenames exist in the same directory, the legacy `oh-my-opencode.*` file currently wins.
 JSONC supports `// line comments`, `/* block comments */`, and trailing commas.