docs: add plugin configuration documentation (#6301)

Co-authored-by: OpenCode <[email protected]>

2 files changed, 77 insertions, 7 deletions

diff --git a/packages/web/src/content/docs/config.mdx b/packages/web/src/content/docs/config.mdx
index d7f803178..c7f151338 100644
--- a/packages/web/src/content/docs/config.mdx
+++ b/packages/web/src/content/docs/config.mdx
@@ -378,6 +378,26 @@ You can configure MCP servers you want to use through the `mcp` option.
 
 ---
 
+### Plugins
+
+[Plugins](/docs/plugins) extend OpenCode with custom tools, hooks, and integrations.
+
+Place plugin files in `.opencode/plugin/` or `~/.config/opencode/plugin/`. You can also load plugins from npm through the `plugin` option.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "opencode-helicone-session",
+    "@my-org/custom-plugin"
+  ]
+}
+```
+
+[Learn more here](/docs/plugins).
+
+---
+
 ### Instructions
 
 You can configure the instructions for the model you're using through the `instructions` option.
diff --git a/packages/web/src/content/docs/plugins.mdx b/packages/web/src/content/docs/plugins.mdx
index 6be545482..eb941565d 100644
--- a/packages/web/src/content/docs/plugins.mdx
+++ b/packages/web/src/content/docs/plugins.mdx
@@ -9,19 +9,69 @@ For examples, check out the [plugins](/docs/ecosystem#plugins) created by the co
 
 ---
 
-## Create a plugin
+## Use a plugin
 
-A plugin is a **JavaScript/TypeScript module** that exports one or more plugin
-functions. Each function receives a context object and returns a hooks object.
+There are two ways to load plugins.
+
+---
+
+### From local files
+
+Place JavaScript or TypeScript files in the plugin directory.
+
+- `.opencode/plugin/` - Project-level plugins
+- `~/.config/opencode/plugin/` - Global plugins
+
+Files in these directories are automatically loaded at startup.
 
 ---
 
-### Location
+### From npm
+
+Specify npm packages in your config file.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "opencode-helicone-session",
+    "opencode-wakatime",
+    "@my-org/custom-plugin"
+  ]
+}
+```
+
+Both regular and scoped npm packages are supported.
 
-Plugins are loaded from:
+Browse available plugins in the [ecosystem](/docs/ecosystem#plugins).
+
+---
 
-1. `.opencode/plugin` directory either in your project
-2. Or, globally in `~/.config/opencode/plugin`
+### How plugins are installed
+
+**npm plugins** are installed automatically using Bun at startup. Packages and their dependencies are cached in `~/.cache/opencode/node_modules/`.
+
+**Local plugins** are loaded directly from the plugin directory. Dependencies are not installed automatically. If your local plugin requires external packages, publish it to npm instead and add it to your config.
+
+---
+
+### Load order
+
+Plugins are loaded from all sources and all hooks run in sequence. The load order is:
+
+1. Global config (`~/.config/opencode/opencode.json`)
+2. Project config (`opencode.json`)
+3. Global plugin directory (`~/.config/opencode/plugin/`)
+4. Project plugin directory (`.opencode/plugin/`)
+
+Duplicate npm packages with the same name and version are loaded once. However, a local plugin and an npm plugin with similar names are both loaded separately.
+
+---
+
+## Create a plugin
+
+A plugin is a **JavaScript/TypeScript module** that exports one or more plugin
+functions. Each function receives a context object and returns a hooks object.
 
 ---