From f03418afde4cf05948720927c195edc1dd8ff915 Mon Sep 17 00:00:00 2001
From: Dax Raad <d@ironbay.co>
Date: Mon, 24 Aug 2026 22:50:50 -0400
Subject: [PATCH] docs: improve build and SDK customization guides

---
 packages/www/src/docs/content/build/index.mdx |  4 ++++
 .../www/src/docs/content/build/sdk/index.mdx  | 24 ++++++++++++-------
 2 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/packages/www/src/docs/content/build/index.mdx b/packages/www/src/docs/content/build/index.mdx
index 4dc9b818db7..8e1221ef756 100644
--- a/packages/www/src/docs/content/build/index.mdx
+++ b/packages/www/src/docs/content/build/index.mdx
@@ -2,6 +2,10 @@
 title: "Intro"
 ---
 
+OpenCode is used by millions every day. Build on top of it to create your own
+applications, integrations, and agent experiences without starting from
+scratch.
+
 <CardGroup cols={1}>
   <Card title="Extend OpenCode" href="/build/plugins">
     Build plugins that add tools, integrations, commands, agents, and custom behavior while keeping the rest of OpenCode
diff --git a/packages/www/src/docs/content/build/sdk/index.mdx b/packages/www/src/docs/content/build/sdk/index.mdx
index d27e72b28ea..13b2d6beb82 100644
--- a/packages/www/src/docs/content/build/sdk/index.mdx
+++ b/packages/www/src/docs/content/build/sdk/index.mdx
@@ -50,25 +50,31 @@ for await (const event of opencode.events.subscribe()) {
 Pass an `AbortSignal` through the generated request options, or leave an
 iteration to cancel its response body.
 
-## Register plugins
+## Customize
 
-Pass initial Promise plugins to `OpenCode.create()`. Embedded plugins use the
-same discovery and Location-scoped activation path as configured plugins.
+Customize your OpenCode instance by registering plugins. Pass plugins to
+`OpenCode.create()` to customize agents, models, tools, and other behavior when
+the embedded host starts:
 
 ```ts
-const plugin = {
-  id: "example",
+import { Plugin } from "@opencode-ai/plugin"
+import { OpenCode } from "@opencode-ai/sdk"
+
+const plugin = Plugin.define({
+  id: "customize-agent",
   async setup(ctx) {
     await ctx.agent.transform((agents) => {
-      // Modify the Location's agent catalog.
+      agents.update("build", (agent) => {
+        agent.description = "Builds features and fixes bugs for our team"
+      })
     })
   },
-}
+})
 
 await using opencode = await OpenCode.create({ plugins: [plugin] })
 ```
 
 Call `await opencode.plugin(plugin)` to register another plugin after startup.
 
-See the [Plugins guide](/build/plugins) for the plugin context and available
-hooks.
+See the [full plugins documentation](/build/plugins) for plugin hooks,
+transforms, tools, and the complete plugin context.