diff --git a/DIVERGENCES.md b/DIVERGENCES.md
index f92c9763f0..09cab61bf2 100644
--- a/DIVERGENCES.md
+++ b/DIVERGENCES.md
@@ -30,6 +30,15 @@ git checkout -b sync-upstream main
 # FROM = current version in packages/opencode/package.json; TO = target release
 FROM=v1.17.15 TO=v1.17.16
 
+# Drop the fork's revision suffix first. Upstream's manifests carry the plain
+# version at FROM, so while ours read 1.17.15-2 every one of their version hunks
+# conflicts (~29 manifests); matching FROM lets them apply clean and land on TO
+# by themselves. Skip if the fork is already on the plain value — `bump` refuses
+# a no-op. `git add` is required: `git apply --index` rejects unstaged changes
+# with "does not match index", and staging folds this into the sync commit.
+bun bump ${FROM#v}
+git add -A
+
 # `git apply` is atomic: hunks against files the fork deleted (locales, docs
 # translations — see the table below) hard-error and roll back the entire patch,
 # so filter them out first. A path is skipped only if it existed in FROM and is
diff --git a/README.md b/README.md
index f761657d5c..1b1573be5c 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ CoDev Code is a fork of [OpenCode](https://github.com/anomalyco/opencode) that t
 
 All workspace packages share one version — the one releases publish — kept in lockstep (`packages/codev-gateway` is fork-only and versions independently). There are only two ways it changes:
 
-- **Upstream sync** — the version comes from upstream; do not bump manually. The sync restores the plain upstream value (e.g. `1.17.18-2` → `1.17.19`).
+- **Upstream sync** — the version comes from upstream; never pick one yourself. The sync restores the plain upstream value (e.g. `1.17.18-2` → `1.17.19`). Its [procedure](DIVERGENCES.md#syncing-with-upstream) drops the fork's suffix with the same script on the way, so upstream's version applies cleanly.
 - **Fork-only re-release between syncs** — append or increment a numeric revision suffix: `1.17.18` → `1.17.18-1` → `1.17.18-2` (the Nth fork build of that upstream release). Semver sorts the suffixed form below the bare `1.17.18`, but installs follow the `latest` dist-tag, so that quirk is harmless.
 
 For a fork-only bump, run the script — it rewrites every manifest in lockstep, regenerates `bun.lock`, and verifies nothing was missed: