From 0c19b71f428be388ad9591097b8b234e82192ad9 Mon Sep 17 00:00:00 2001
From: Matt Silverlock <matt@eatsleeprepeat.net>
Date: Sun, 28 Dec 2025 14:13:11 -0500
Subject: docs: add plugin configuration documentation (#6301)

Co-authored-by: OpenCode <opencode@example.com>
---
 packages/web/src/content/docs/plugins.mdx | 64 +++++++++++++++++++++++++++----
 1 file changed, 57 insertions(+), 7 deletions(-)

(limited to 'packages/web/src/content/docs/plugins.mdx')

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.
 
 ---
 
-- 
cgit v1.2.3

