docs(opencode): fix build/install paths and add agent responsibilities (#396)

.fork-features/manifest.json

@@ -86,7 +86,7 @@
     },
     "agents-config": {
       "status": "active",
-      "description": "Fork-specific AGENTS.md with build instructions, codesign steps, quality gates, context7 protocol, and fork governance rules. Upstream's AGENTS.md only has a style guide — ours is comprehensive. Must be manually re-applied after each upstream sync.",
+      "description": "Fork-specific AGENTS.md with build instructions, codesign steps, quality gates, context7 protocol, and fork governance rules. Includes explicit agent responsibilities for build/install workflow and candidate binary promotion pattern. Upstream's AGENTS.md only has a style guide — ours is comprehensive. Must be manually re-applied after each upstream sync.",
       "issue": "https://github.com/randomm/opencode/issues/158",
       "newFiles": [],
       "deletedFiles": [],
@@ -100,7 +100,11 @@
         "Pre-Push Verification",
         "Minimalist Engineering",
         "Auto-Merge Policy",
-        "Worktree and PR Policy"
+        "Worktree and PR Policy",
+        "./script/install.sh",
+        "~/bin/opencode-new",
+        "Agent responsibilities",
+        "Promote candidate"
       ],
       "tests": [],
       "upstreamTracking": {

AGENTS.md

@@ -326,43 +326,80 @@ taskctl override <taskId> --commit-as-is   # Commit despite issues (PM responsib
 
 ### Main opencode TUI
 
-**Recommended: Use comprehensive installation script**
+**Quick reference — all commands from repo root:**
 
 ```bash
+# 1. Build (from packages/opencode)
 cd packages/opencode && bun run build --single
-./script/install.sh
+
+# 2. Install (from repo root — NOT from packages/opencode)
+cd ../.. && ./script/install.sh
+
+# 3. Promote candidate binary to stable
+mv ~/bin/opencode-new ~/bin/opencode
+
+# 4. Verify
+~/bin/opencode --version
 ```
 
-The install script handles:
+**Agent responsibilities:**
+
+| Step | Agent | Commands |
+|------|-------|----------|
+| Build binary | @ops | `cd packages/opencode && bun run build --single` |
+| Run install script | @ops | `./script/install.sh` (from repo root) |
+| Promote candidate | User | `mv ~/bin/opencode-new ~/bin/opencode` |
+
+> **Note:** @ops handles build and install because it requires `cp`, `codesign`, and file system operations not available to @developer. The install script runs from the **repo root** (`./script/install.sh`), NOT from `packages/opencode/`.
+
+### How install.sh works
+
+The install script (`./script/install.sh` from repo root) automates:
 
-- Platform/architecture detection
-- Binary verification (size, executability)
-- Directory creation and permission checks
-- Atomic installation with rollback on failure
-- macOS codesigning with error detection
-- Comprehensive verification
+1. Platform/architecture detection (Darwin/Linux/Windows + arch)
+2. Binary verification (size > 10MB, executable flag, symlink resolution)
+3. Directory setup (creates `~/bin` if needed)
+4. Atomic installation via mktemp + mv (rollback on failure)
+5. macOS codesigning (with rollback to previous binary on failure)
+6. Verification (`--version` runs successfully)
 
-**Manual installation (advanced):**
+The script installs to `~/bin/opencode-new` (candidate binary), NOT `~/bin/opencode` (stable binary). This protects your working installation — you must promote manually:
 
 ```bash
-# Build for current platform only (dev builds)
+# Test the candidate
+~/bin/opencode-new --version
+
+# If satisfied, promote to stable
+mv ~/bin/opencode-new ~/bin/opencode
+```
+
+### Manual installation (advanced)
+
+Only if the install script is unavailable:
+
+```bash
+# Build for current platform only
 cd packages/opencode && bun run build --single
 
 # Copy to ~/bin
-cp packages/opencode/dist/opencode-darwin-arm64/bin/opencode ~/bin/opencode
+cp packages/opencode/dist/opencode-darwin-arm64/bin/opencode ~/bin/opencode-new
 
 # REQUIRED on macOS: ad-hoc codesign (build script does NOT auto-sign)
-codesign --force --deep --sign - ~/bin/opencode || exit 1
+codesign --force --deep --sign - ~/bin/opencode-new || exit 1
 
-# Verify
-~/bin/opencode --version
+# Verify candidate
+~/bin/opencode-new --version
+
+# Promote to stable
+mv ~/bin/opencode-new ~/bin/opencode
 ```
 
-**Critical Notes:**
+**Critical notes:**
 
-- The build script (`script/build.ts`) does NOT auto-codesign. Without codesign, macOS will refuse to run the binary.
-- Manual installation requires all 4 steps to succeed. Use `./script/install.sh` for automated error handling.
-- If codesigning fails on macOS, the binary becomes non-executable. The install script will detect this and rollback automatically.
+- The build script (`packages/opencode/script/build.ts`) does NOT auto-codesign. The install script handles codesigning.
+- The install script lives at **repo root** (`./script/install.sh`), NOT in `packages/opencode/script/`.
+- If codesigning fails on macOS, the binary will not execute. The install script detects this and rolls back automatically.
+- Always verify with `--version` before promoting the candidate binary.
 
 ### JavaScript SDK