diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md
index b4da4f59..94d12597 100644
--- a/packages/coding-agent/README.md
+++ b/packages/coding-agent/README.md
@@ -1025,6 +1025,7 @@ Use `-l` to install into project settings (`.pi/settings.json`).
 - Paths are relative to package root
 - Use `!pattern` to exclude (e.g., `"!deprecated/*"`)
 - Glob patterns supported via minimatch (e.g., `"*.ts"`, `"**/*.json"`)
+- **Pattern precedence:** Exclusions always win. If a path matches both an include and exclude pattern, it is excluded. Order in the array does not matter.
 
 **Dependencies:** Extensions can have their own dependencies. Place a `package.json` next to the extension (or in a parent directory), run `npm install`, and imports are resolved via [jiti](https://github.com/unjs/jiti). See [examples/extensions/with-deps/](examples/extensions/with-deps/).
 
diff --git a/packages/coding-agent/docs/extensions.md b/packages/coding-agent/docs/extensions.md
index 15e08f0b..57ea11ce 100644
--- a/packages/coding-agent/docs/extensions.md
+++ b/packages/coding-agent/docs/extensions.md
@@ -159,6 +159,7 @@ pi update  # update all non-pinned packages
 - Paths are relative to package root
 - Use `!pattern` to exclude (e.g., `"themes": ["!funky.json"]`)
 - Glob patterns supported via minimatch (e.g., `"extensions": ["**/*.ts", "!**/deprecated/*"]`)
+- **Pattern precedence:** Exclusions always win. If a path matches both an include and exclude pattern, it is excluded. Order in the array does not matter.
 
 **Discovery rules:**