diff --git a/packages/web/src/content/docs/rules.mdx b/packages/web/src/content/docs/rules.mdx
index 6db5d45b1d3a..e06a33f6b1f1 100644
--- a/packages/web/src/content/docs/rules.mdx
+++ b/packages/web/src/content/docs/rules.mdx
@@ -94,13 +94,13 @@ export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills
 
 ## Precedence
 
-When opencode starts, it looks for rule files in this order:
+OpenCode loads and concatenates rule files from multiple layers. All three layers below are loaded in order, with later layers appended after earlier ones:
 
 1. **Local files** by traversing up from the current directory (`AGENTS.md`, `CLAUDE.md`)
 2. **Global file** at `~/.config/opencode/AGENTS.md`
 3. **Claude Code file** at `~/.claude/CLAUDE.md` (unless disabled)
 
-The first matching file wins in each category. For example, if you have both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is used. Similarly, `~/.config/opencode/AGENTS.md` takes precedence over `~/.claude/CLAUDE.md`.
+Within each layer, the first matching file wins. For example, if your project root has both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` from that layer is used — `CLAUDE.md` is skipped. Similarly, a global `~/.config/opencode/AGENTS.md` takes precedence over `~/.claude/CLAUDE.md`, but both layers are still included after the local layer.
 
 ---