docs: add fork development, build, and orw documentation

Author: rustybret

AGENTS.md

@@ -2,6 +2,36 @@
 - The default branch in this repo is `dev`.
 - Local `main` ref may not exist; use `dev` or `origin/dev` for diffs.
 
+## Fork Development
+
+This repo is a private fork of `anomalyco/opencode` using a **two-branch model**:
+
+- **`dev`** — clean mirror of `upstream/dev`. Never commit fork changes here. Updated via `git sync-upstream`.
+- **`fork/local`** — the customization layer. All local development happens here.
+
+### Syncing with upstream
+
+```bash
+git sync-upstream   # fetch upstream → FF dev → rebase fork/local → push both
+```
+
+The alias lives in `.git/config`. If `rebase` conflicts during the `fork/local` step the chain halts before pushing — resolve conflicts manually, then `git rebase --continue` and re-run the push.
+
+### Standalone build
+
+```bash
+./packages/opencode/script/build.ts --single
+# Output: packages/opencode/dist/opencode-<platform>/bin/opencode
+```
+
+Run `bun typecheck` from `packages/opencode` (never `tsc` directly) before building.
+
+### Release watcher (orw)
+
+`@cortexkit/orw` runs at `~/opencode-release-watch/` via launchd (30-min poll). On each new upstream release it AI-merges `fork/local` onto the release tag using `claude-opus-4-8`, builds a native CLI, and auto-installs to `~/.opencode/bin/opencode`. The Homebrew binary at `/opt/homebrew/bin/opencode` stays as a fallback.
+
+Operator runbook: `agent-harness/docs/runbooks/OpenCode-Release-Watcher.md`
+
 ## Commits and PR Titles
 
 Use conventional commit-style messages and PR titles: `type(scope): summary`.

CONTRIBUTING.md

@@ -175,6 +175,55 @@ Some debug methods that can be problematic:
 
 With that said, you may want to try these methods, as they might work for you.
 
+## Fork Development
+
+> **This section applies only to the private fork (`rustybret/opencode`), not to upstream contributors.**
+
+### Branch model
+
+| Branch | Purpose |
+|--------|---------|
+| `dev` | Clean mirror of `upstream/dev`. Never commit here. |
+| `fork/local` | Customization layer rebased on top of `dev`. All work goes here. |
+
+### Syncing with upstream
+
+```bash
+git sync-upstream
+```
+
+This repo-local alias (`.git/config`) fetches upstream, fast-forwards `dev` to `upstream/dev`, pushes `origin/dev`, rebases `fork/local` onto `dev`, syncs submodules, runs `bun install`, then pushes `fork/local`. If the rebase conflicts the chain stops before the push — resolve manually, then `git rebase --continue` and re-run the push.
+
+### Building a standalone binary
+
+```bash
+./packages/opencode/script/build.ts --single
+# Output: packages/opencode/dist/opencode-<platform>/bin/opencode
+```
+
+Always typecheck first:
+
+```bash
+bun typecheck   # from packages/opencode — never tsc directly
+```
+
+### Release watcher (orw)
+
+`@cortexkit/orw` runs at `~/opencode-release-watch/` via launchd (every 30 min). It AI-merges `fork/local` onto each new upstream release using `claude-opus-4-8` and auto-installs to `~/.opencode/bin/opencode`.
+
+```bash
+# Manual build + verify
+cd ~/opencode-release-watch && bunx @cortexkit/orw check --force
+
+# Status
+bunx @cortexkit/orw status
+
+# Rollback
+~/opencode-release-watch/rollback.sh
+```
+
+Operator runbook: `agent-harness/docs/runbooks/OpenCode-Release-Watcher.md`
+
 ## Pull Request Expectations
 
 ### Issue First Policy

README.md

@@ -43,6 +43,50 @@
 
 ---
 
+## Fork
+
+> This is a private fork of [`anomalyco/opencode`](https://github.com/anomalyco/opencode) maintained on the `fork/local` branch. The `dev` branch is a clean mirror of upstream — never carry fork commits there.
+
+### Branch model
+
+```
+upstream/dev  ─────────────────────────────────►
+                                                 ↓
+origin/dev    ──── (clean mirror, FF-only) ──────►
+                                                 ↓
+fork/local    ──── our patches on top ───────────►
+```
+
+### Syncing with upstream
+
+```bash
+git sync-upstream
+```
+
+### Building from this fork
+
+```bash
+# Standalone native binary (canonical fork build)
+./packages/opencode/script/build.ts --single
+
+# Output
+packages/opencode/dist/opencode-<platform>/bin/opencode
+```
+
+### Automated release tracking (orw)
+
+Uses [`@cortexkit/orw`](https://github.com/cortexkit/orw) to stay current with upstream releases. Polls every 30 min, AI-merges `fork/local` onto each new release tag, builds a native CLI, and installs automatically.
+
+```bash
+# Manual check/build
+cd ~/opencode-release-watch && bunx @cortexkit/orw check --force
+
+# Rollback
+~/opencode-release-watch/rollback.sh
+```
+
+---
+
 ### Installation
 
 ```bash