diff --git a/docs/platforms/mac/release.md b/docs/platforms/mac/release.md
index ebe4b1c8d1b..800f0164a86 100644
--- a/docs/platforms/mac/release.md
+++ b/docs/platforms/mac/release.md
@@ -27,12 +27,15 @@ This app now ships Sparkle auto-updates. Release builds must be Developer ID–s
 Notes:
 
 - `APP_BUILD` maps to `CFBundleVersion`/`sparkle:version`; keep it numeric + monotonic (no `-beta`), or Sparkle compares it as equal.
+- If `APP_BUILD` is omitted, `scripts/package-mac-app.sh` derives a Sparkle-safe default from `APP_VERSION` (`YYYYMMDD0`) and uses the higher of that value and git commit count.
+- You can still override `APP_BUILD` explicitly when release engineering needs a specific monotonic value.
 - Defaults to the current architecture (`$(uname -m)`). For release/universal builds, set `BUILD_ARCHS="arm64 x86_64"` (or `BUILD_ARCHS=all`).
 - Use `scripts/package-mac-dist.sh` for release artifacts (zip + DMG + notarization). Use `scripts/package-mac-app.sh` for local/dev packaging.
 
 ```bash
 # From repo root; set release IDs so Sparkle feed is enabled.
 # APP_BUILD must be numeric + monotonic for Sparkle compare.
+# Default is auto-derived from APP_VERSION when omitted.
 BUNDLE_ID=ai.openclaw.mac \
 APP_VERSION=2026.2.27 \
 APP_BUILD="$(git rev-list --count HEAD)" \