diff --git a/macos-spm-app-packaging/SKILL.md b/macos-spm-app-packaging/SKILL.md
index 5506dc6..ab5e4a6 100644
--- a/macos-spm-app-packaging/SKILL.md
+++ b/macos-spm-app-packaging/SKILL.md
@@ -36,4 +36,5 @@ Bootstrap a complete SwiftPM macOS app folder, then build, package, and run it w
 ## Notes
 - Keep entitlements and signing configuration explicit; edit the template scripts instead of reimplementing.
 - Remove Sparkle steps if you do not use Sparkle for updates.
+- Sparkle relies on the bundle build number (`CFBundleVersion`), so `BUILD_NUMBER` in `version.env` must increase for each update.
 - For menu bar apps, set `MENU_BAR_APP=1` when packaging to emit `LSUIElement` in Info.plist.
diff --git a/macos-spm-app-packaging/references/release.md b/macos-spm-app-packaging/references/release.md
index a95a097..5593086 100644
--- a/macos-spm-app-packaging/references/release.md
+++ b/macos-spm-app-packaging/references/release.md
@@ -12,6 +12,7 @@
 - Install Sparkle tools so `generate_appcast` is on PATH.
 - Provide `SPARKLE_PRIVATE_KEY_FILE` (ed25519 key).
 - The appcast script uses your zip artifact to create an updated `appcast.xml`.
+- Sparkle compares `sparkle:version` (derived from `CFBundleVersion`), so bump `BUILD_NUMBER` for every release.
 
 ## Tag and GitHub release (optional)
 Use a versioned git tag and publish a GitHub release with the notarized zip (and appcast if you host it on GitHub Releases).