diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md
index 26f8469bf64..7980dd7c1a6 100644
--- a/docs/src/content/docs/reference/engines.md
+++ b/docs/src/content/docs/reference/engines.md
@@ -419,6 +419,20 @@ engine:
 
 Custom weights are embedded in the compiled workflow YAML and read by `gh aw logs` and `gh aw audit` when analyzing runs.
 
+### Pi Extensions (`extensions`)
+
+The Pi engine supports loading additional plugins via `engine.extensions`. Each entry is an npm package name installed with `pi install <extension>` before the agent runs. Only the Pi engine reads this field; other engines ignore it.
+
+```yaml wrap
+engine:
+  id: pi
+  extensions:
+    - "@pi/web-search"
+    - "@pi/file-browser"
+```
+
+Each listed extension produces one additional install step in the compiled workflow. If `engine.command` is set, the same executable is used to install the extensions.
+
 ## Timeout Configuration
 
 Repositories with long build or test cycles require careful timeout tuning at multiple levels. This section documents the timeout knobs available for each engine.