From 9a90b94921752c009c3cf42db015238d04f88fc2 Mon Sep 17 00:00:00 2001
From: Dax Raad <d@ironbay.co>
Date: Mon, 24 Aug 2026 22:52:24 -0400
Subject: [PATCH] docs(sdk): align Effect and Cloudflare customization guides

---
 .../src/docs/content/build/sdk/cloudflare.mdx | 44 +++++++++++--------
 .../www/src/docs/content/build/sdk/effect.mdx | 22 +++++-----
 2 files changed, 37 insertions(+), 29 deletions(-)

diff --git a/packages/www/src/docs/content/build/sdk/cloudflare.mdx b/packages/www/src/docs/content/build/sdk/cloudflare.mdx
index 61085ab9a9f..db8384cb83c 100644
--- a/packages/www/src/docs/content/build/sdk/cloudflare.mdx
+++ b/packages/www/src/docs/content/build/sdk/cloudflare.mdx
@@ -46,16 +46,6 @@ constructor(state: DurableObjectState) {
 }
 ```
 
-Configuration is a typed JavaScript object, and plugins are imported values bundled with the Worker.
-
-```ts
-await OpenCodeWorkerd.create({
-  storage: state.storage,
-  config: { default_agent: "build" },
-  plugins: [myPlugin],
-})
-```
-
 Wrangler selects OpenCode's Workerd-safe implementations through the `workerd` package condition. Cloudflare may evict
 a Durable Object without running cleanup, so correctness does not depend on `close()` being called.
 
@@ -65,17 +55,33 @@ a Durable Object without running cleanup, so correctness does not depend on `clo
 }
 ```
 
-## Effect
+## Customize
 
-Use the Effect-native entrypoint from `@opencode-ai/sdk/workerd/effect`.
+Customize your OpenCode instance by registering plugins bundled with your
+Worker. Pass plugins to `OpenCodeWorkerd.create()` to customize agents, models,
+tools, and other behavior:
 
 ```ts
-import { OpenCodeWorkerd } from "@opencode-ai/sdk/workerd/effect"
-import { Effect } from "effect"
+import { Plugin } from "@opencode-ai/plugin"
+import { OpenCodeWorkerd } from "@opencode-ai/sdk/workerd"
 
-const program = Effect.scoped(
-  Effect.gen(function* () {
-    return yield* OpenCodeWorkerd.create({ storage: state.storage })
-  }),
-)
+const plugin = Plugin.define({
+  id: "customize-agent",
+  async setup(ctx) {
+    await ctx.agent.transform((agents) => {
+      agents.update("build", (agent) => {
+        agent.description = "Builds features and fixes bugs for our team"
+      })
+    })
+  },
+})
+
+await OpenCodeWorkerd.create({
+  storage: state.storage,
+  config: { default_agent: "build" },
+  plugins: [plugin],
+})
 ```
+
+See the [full plugins documentation](/build/plugins) for plugin hooks,
+transforms, tools, and the complete plugin context.
diff --git a/packages/www/src/docs/content/build/sdk/effect.mdx b/packages/www/src/docs/content/build/sdk/effect.mdx
index 56377722ee0..9b0913c83ec 100644
--- a/packages/www/src/docs/content/build/sdk/effect.mdx
+++ b/packages/www/src/docs/content/build/sdk/effect.mdx
@@ -56,31 +56,33 @@ yield* opencode.events.subscribe().pipe(
 )
 ```
 
-## Register plugins
+## Customize
 
-Register Effect plugins through the embedded host. Their registrations remain scoped to the host.
+Customize your OpenCode instance by registering Effect plugins. Use the embedded
+host to customize agents, models, tools, and other behavior:
 
 ```ts
 import { Plugin } from "@opencode-ai/plugin/effect"
 import { Effect } from "effect"
 
 const plugin = Plugin.define({
-  id: "example",
+  id: "customize-agent",
   effect: (ctx) =>
     Effect.gen(function* () {
-      const storage = ctx.storage
-      yield* storage.set("embedded", true)
+      const agent = ctx.agent
+      yield* agent.transform((agents) => {
+        agents.update("build", (agent) => {
+          agent.description = "Builds features and fixes bugs for our team"
+        })
+      })
     }),
 })
 
 yield* opencode.plugin(plugin)
 ```
 
-See the [Effect plugins guide](/build/plugins/effect) for the complete plugin context.
-
-```ts
-yield* opencode.plugin.list()
-```
+See the [full Effect plugins documentation](/build/plugins/effect) for plugin
+hooks, transforms, tools, and the complete plugin context.
 
 ## Layer