From 00898d46c0ca556c6c71c205d5c72b4b4d346a80 Mon Sep 17 00:00:00 2001
From: Marshall Bowers <git@maxdeviant.com>
Date: Fri, 7 Nov 2025 13:38:20 -0500
Subject: [PATCH] docs: Add docs on extension capabilities (#42223)

This PR adds some initial docs on extension capabilities.

Release Notes:

- N/A
---
 docs/src/SUMMARY.md                 |  1 +
 docs/src/extensions.md              |  1 +
 docs/src/extensions/capabilities.md | 96 +++++++++++++++++++++++++++++
 3 files changed, 98 insertions(+)
 create mode 100644 docs/src/extensions/capabilities.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 789d9025a32f7b6b6fcc473558007e37b81e42bb..c57802afa61cde6bc0ae6998c95c7980e7c60d64 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -75,6 +75,7 @@
 - [Overview](./extensions.md)
 - [Installing Extensions](./extensions/installing-extensions.md)
 - [Developing Extensions](./extensions/developing-extensions.md)
+- [Extension Capabilities](./extensions/capabilities.md)
 - [Language Extensions](./extensions/languages.md)
 - [Debugger Extensions](./extensions/debugger-extensions.md)
 - [Theme Extensions](./extensions/themes.md)
diff --git a/docs/src/extensions.md b/docs/src/extensions.md
index 029cae1245dfef0bb9f1119ad03e7a332a0e89d3..627fe8f4c06a752ef953eef4950ae5a281abf727 100644
--- a/docs/src/extensions.md
+++ b/docs/src/extensions.md
@@ -3,6 +3,7 @@
 Zed lets you add new functionality using user-defined extensions.
 
 - [Installing Extensions](./extensions/installing-extensions.md)
+- [Extension Capabilities](./extensions/capabilities.md)
 - [Developing Extensions](./extensions/developing-extensions.md)
   - [Developing Language Extensions](./extensions/languages.md)
   - [Developing Debugger Extensions](./extensions/debugger-extensions.md)
diff --git a/docs/src/extensions/capabilities.md b/docs/src/extensions/capabilities.md
new file mode 100644
index 0000000000000000000000000000000000000000..4d935a0725a1285065070eccb5112dc636e26a27
--- /dev/null
+++ b/docs/src/extensions/capabilities.md
@@ -0,0 +1,96 @@
+# Extension Capabilities
+
+The operations that Zed extensions are able to perform are governed by a capability system.
+
+## Restricting capabilities
+
+As a user, you have the option of restricting the capabilities that are granted to extensions.
+
+This is controlled via the `granted_extension_capabilities` setting.
+
+Restricting or removing a capability will cause an error to be returned when an extension attempts to call the corresponding extension API without sufficient capabilities.
+
+For instance, if you wanted to restrict downloads to just files from GitHub, you could modify `host` for the `download_file` capability:
+
+```diff
+{
+  "granted_extension_capabilities": [
+    { "kind": "process:exec", "command": "*", "args": ["**"] },
+-   { "kind": "download_file", "host": "*", "path": ["**"] },
++   { "kind": "download_file", "host": "github.com", "path": ["**"] },
+    { "kind": "npm:install", "package": "*" }
+  ]
+}
+```
+
+If you don't want extensions to be able to perform _any_ capabilities, you can remove all granted capabilities:
+
+```json
+{
+  "granted_extension_capabilities": []
+}
+```
+
+> Note that this will likely make many extensions non-functional, at least in their default configuration.
+
+## Capabilities
+
+### `process:exec`
+
+The `process:exec` capability grants extensions the ability to invoke commands using [`zed_extension_api::process::Command`](https://docs.rs/zed_extension_api/latest/zed_extension_api/process/struct.Command.html).
+
+#### Examples
+
+To allow any command to be executed with any arguments:
+
+```toml
+{ kind = "process:exec", command = "*", args = ["**"] }
+```
+
+To allow a specific command (e.g., `gem`) to be executed with any arguments:
+
+```toml
+{ kind = "process:exec", command = "gem", args = ["**"] }
+```
+
+### `download_file`
+
+The `download_file` capability grants extensions the ability to download files using [`zed_extension_api::download_file`](https://docs.rs/zed_extension_api/latest/zed_extension_api/fn.download_file.html).
+
+#### Examples
+
+To allow any file to be downloaded:
+
+```toml
+{ kind = "download_file", host = "github.com", path = ["**"] }
+```
+
+To allow any file to be downloaded from `github.com`:
+
+```toml
+{ kind = "download_file", host = "github.com", path = ["**"] }
+```
+
+To allow any file to be downloaded from a specific GitHub repository:
+
+```toml
+{ kind = "download_file", host = "github.com", path = ["zed-industries", "zed", "**"] }
+```
+
+### `npm:install`
+
+The `npm:install` capability grants extensions the ability to install npm packages using [`zed_extension_api::npm_install_package`](https://docs.rs/zed_extension_api/latest/zed_extension_api/fn.npm_install_package.html).
+
+#### Examples
+
+To allow any npm package to be installed:
+
+```toml
+{ kind = "npm:install", package = "*" }
+```
+
+To allow a specific npm package (e.g., `typescript`) to be installed:
+
+```toml
+{ kind = "npm:install", package = "typescript" }
+```