diff --git a/docs/adr/25830-opencode-engine-integration.md b/docs/adr/25830-opencode-engine-integration.md
index b5bd66cd6b0..a91df8a0471 100644
--- a/docs/adr/25830-opencode-engine-integration.md
+++ b/docs/adr/25830-opencode-engine-integration.md
@@ -1,7 +1,7 @@
 # ADR-25830: Add OpenCode as a Provider-Agnostic BYOK Agentic Engine
 
 **Date**: 2026-04-11
-**Status**: Draft
+**Status**: Superseded by [PR #26819](https://github.com/github/gh-aw/pull/26819) — OpenCode was archived; the engine was replaced by Crush (`engine: id: crush`) on 2026-04-17.
 **Deciders**: pelikhan, Copilot
 
 ---
diff --git a/docs/src/content/docs/guides/upgrading.md b/docs/src/content/docs/guides/upgrading.md
index 2c0e8e3ca56..4bc954514ce 100644
--- a/docs/src/content/docs/guides/upgrading.md
+++ b/docs/src/content/docs/guides/upgrading.md
@@ -77,6 +77,14 @@ The upgrade automatically applies codemods to fix deprecated fields in all workf
 | **delete-schema-file** | Deletes deprecated schema file | Removes `.github/aw/schemas/agentic-workflow.json` |
 | **delete-old-agents** | Deletes old `.agent.md` files moved to `.github/aw/` | Removes outdated agent files |
 
+### 3.2.1 Manual Migrations (No Codemod)
+
+Some breaking changes require manual edits because no automatic codemod was shipped:
+
+| Change | What to do |
+|--------|------------|
+| `engine: id: opencode` removed (April 2026) | Change to `engine: id: crush`. The OpenCode engine was archived; Crush is its successor. Also update any `GH_AW_MODEL_AGENT_OPENCODE` org/repo variables to `GH_AW_MODEL_AGENT_CRUSH`. |
+
 ### 3.3 Compiles All Workflows
 
 The upgrade automatically compiles all workflows to generate or update `.lock.yml` files, ensuring they're ready to run in GitHub Actions.