diff --git a/packages/opencode/README.md b/packages/opencode/README.md
index 6630e7d..0d4646c 100644
--- a/packages/opencode/README.md
+++ b/packages/opencode/README.md
@@ -459,6 +459,25 @@ bun run lint
 bun run format:check
 ```
 
+### Build modes
+
+Two build modes are available:
+
+```bash
+bun run build      # Deploy: bun build → bundled dist/ with all deps inlined (core + xxhash-wasm)
+bun run build:dev  # Dev: tsc → individual dist/*.js files (requires workspace node_modules)
+```
+
+The default `build` uses `bun build` to bundle `@cortexkit/anthropic-auth-core` and all transitive dependencies into self-contained output files. No `node_modules/` needed at runtime — the plugin works via `file://` path in OpenCode config:
+
+```json
+{
+  "plugin": ["file:///path/to/anthropic-auth/packages/opencode"]
+}
+```
+
+`@opencode-ai/plugin` remains external (peer dep provided by OpenCode).
+
 Inspect package contents:
 
 ```bash
diff --git a/packages/opencode/package.json b/packages/opencode/package.json
index 7c40708..f81a940 100644
--- a/packages/opencode/package.json
+++ b/packages/opencode/package.json
@@ -27,7 +27,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && bun build src/index.ts src/cli.ts --outdir dist --target node --format esm --splitting --external @opencode-ai/plugin --minify && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build:dev": "rm -rf dist && tsc -p tsconfig.build.json",
     "dev": "bun ../../scripts/dev.ts",
     "dev:clean": "bun ../../scripts/dev-clean.ts",
     "extract": "bun ../../scripts/extract-system-prompt.ts",