diff --git a/packages/core/src/plugin/skill/opencode.md b/packages/core/src/plugin/skill/opencode.md
index 6d23feb5f01..1ed6bb2ffc2 100644
--- a/packages/core/src/plugin/skill/opencode.md
+++ b/packages/core/src/plugin/skill/opencode.md
@@ -76,11 +76,13 @@ to every project for that user. Project configuration can live in any directory
 as `opencode.json(c)` or `.opencode/opencode.json(c)`, including nested packages
 in a monorepo.
 
-When OpenCode starts, it searches from the current directory up to the project
-root. It merges direct `opencode.json(c)` files from root to current directory,
+During ordinary project discovery, OpenCode searches the current Location
+directory and every ancestor through the filesystem root, including directories
+above the detected project or repository root. It merges direct
+`opencode.json(c)` files from the farthest ancestor to the current directory,
 then does the same for `.opencode/opencode.json(c)` files. This means every
-`.opencode` config overrides every direct config. Global configuration has the
-lowest precedence.
+discovered `.opencode` config overrides every discovered direct config. Global
+filesystem configuration has lower precedence than these discovered documents.
 
 Common configuration fields include `model`, `default_agent`, `permissions`,
 `agents`, `commands`, `plugins`, `providers`, `mcp`, `skills`, `instructions`,
diff --git a/packages/www/src/docs/content/config.mdx b/packages/www/src/docs/content/config.mdx
index 94485302577..f2d10ca4089 100644
--- a/packages/www/src/docs/content/config.mdx
+++ b/packages/www/src/docs/content/config.mdx
@@ -40,13 +40,15 @@ Project-specific configuration can use either form:
 /home/user/projects/my-app/.opencode/opencode.json(c)
 ```
 
-When OpenCode starts, it searches for configuration files from the current
-directory upward to the project root. It merges direct `opencode.json(c)` files
-from the project root toward the current directory, then does the same for
-files inside `.opencode` directories. A `.opencode` config therefore overrides
-every direct config, even when the direct config is closer to the current
-directory. Avoid mixing the two forms across one project hierarchy unless this
-precedence is intentional.
+During ordinary project discovery, OpenCode searches for configuration files
+from the current Location directory through every ancestor to the filesystem
+root, including directories above the detected project or repository root. It
+merges direct `opencode.json(c)` files from the farthest ancestor toward the
+current directory, then does the same for files inside `.opencode` directories.
+A discovered `.opencode` config therefore overrides every discovered direct
+config, even when the direct config is closer to the current directory. Avoid
+mixing the two forms across one directory hierarchy unless this precedence is
+intentional.
 
 For example, consider a monorepo with OpenCode started from
 `/home/user/projects/acme/packages/web`: