diff --git a/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx b/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx
index 4737d37812f1f..8caae190e5844 100644
--- a/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx
+++ b/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx
@@ -38,13 +38,13 @@ Create a `sentry.options.json` file in your React Native project root with the s
 
 When `Sentry.init()` runs in JavaScript, the native SDK is re-initialized with the JS options merged on top of the file options. This means JavaScript options take precedence for events captured **after** JS loads.
 
-However, crashes and errors that occur **before** JavaScript loads (which is the purpose of this feature) are captured using only the values from `sentry.options.json` and native auto-detection. If you set a custom `release` or `dist` in `Sentry.init()`, make sure the same values are also in `sentry.options.json`. Otherwise, pre-JS crashes will be attributed to a different release than post-JS events.
+However, crashes and errors that occur **before** JavaScript loads (which is the purpose of this feature) are captured using only the values from `sentry.options.json` and native auto-detection. If you set a custom `environment`, `release`, or `dist` in `Sentry.init()`, make sure the same values are also in `sentry.options.json`. Otherwise, pre-JS crashes will be attributed to a different release or environment than post-JS events.
 
 </Alert>
 
 ### Setting the Environment
 
-If you need different `environment` values for build (e.g., production vs staging), set the `SENTRY_ENVIRONMENT` environment variable at build time. The SDK build scripts will use this to override the `environment` in your `sentry.options.json` without modifying the source file.
+If you need different `environment` values for build (e.g., production vs staging), set the `SENTRY_ENVIRONMENT` environment variable at build time. The SDK build scripts will use this to override the `environment` in both the native copy of your `sentry.options.json` and the options bundled into JavaScript, without modifying the source file.
 
 ```bash
 SENTRY_ENVIRONMENT=staging npx react-native run-android
@@ -52,6 +52,12 @@ SENTRY_ENVIRONMENT=staging npx react-native run-android
 
 This works in any CI/CD system by setting the environment variable in your build configuration.
 
+<Alert level="info" title="JavaScript Alignment Requires SDK 8.16.0">
+
+Applying `SENTRY_ENVIRONMENT` (and `SENTRY_RELEASE`/`SENTRY_DIST`) to the JavaScript-bundled options requires Sentry React Native SDK version 8.16.0 or higher. On earlier versions these build variables override only the native side, so also set matching values in `Sentry.init()`.
+
+</Alert>
+
 ### Setting Release and Distribution
 
 If you use a custom `release` or `dist` in `Sentry.init()`, you should set matching values in `sentry.options.json` so that pre-JavaScript crashes are attributed to the correct release:
@@ -64,7 +70,7 @@ If you use a custom `release` or `dist` in `Sentry.init()`, you should set match
 }
 ```
 
-For dynamic values that change per build, set the `SENTRY_RELEASE` and `SENTRY_DIST` environment variables at build time. The SDK build scripts will use these to override the values in your `sentry.options.json`, similar to how `SENTRY_ENVIRONMENT` works.
+For dynamic values that change per build, set the `SENTRY_RELEASE` and `SENTRY_DIST` environment variables at build time. The SDK build scripts will use these to override the values in both the native copy of your `sentry.options.json` and the options bundled into JavaScript, similar to how `SENTRY_ENVIRONMENT` works.
 
 ```bash
 SENTRY_RELEASE="my-app@1.0.0+42" SENTRY_DIST="42" npx react-native run-ios
@@ -72,7 +78,7 @@ SENTRY_RELEASE="my-app@1.0.0+42" SENTRY_DIST="42" npx react-native run-ios
 
 <Alert level="warning" title="Release Alignment">
 
-If the `release` or `dist` in `sentry.options.json` doesn't match what you pass to `Sentry.init()`, you'll see two separate releases in Sentry — one for native crashes captured before JS loads and another for events captured after. Make sure both sources use the same values.
+If the `environment`, `release`, or `dist` in `sentry.options.json` doesn't match what you pass to `Sentry.init()`, you'll see two separate releases or environments in Sentry — one for native crashes and sessions captured before JS loads and another for events captured after. This splits release health, so the **Releases** page shows **Failure Rate** instead of **Crash Free Session Rate**. Make sure both sources use the same values.
 
 </Alert>
 
@@ -210,3 +216,5 @@ For per-environment builds with EAS Build, set `SENTRY_ENVIRONMENT` in your buil
   }
 }
 ```
+
+Applying `SENTRY_RELEASE` and `SENTRY_DIST` from EAS to the JavaScript-bundled options requires Sentry React Native SDK version 8.16.0 or higher (see [Setting the Environment](#setting-the-environment) above). On earlier versions, also set matching values in `Sentry.init()`.