docs(react-native): Document SENTRY_RELEASE and SENTRY_DIST env var support

docs/platforms/react-native/manual-setup/app-start-error-capture.mdx

@@ -36,7 +36,9 @@ Create a `sentry.options.json` file in your React Native project root with the s
 
 <Alert level="info" title="Options Merging">
 
-Options from `sentry.options.json` are merged with options from `Sentry.init()` in JavaScript. Options specified in JavaScript take precedence over the configuration file, allowing you to override settings at runtime.
+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.
 
 </Alert>
 
@@ -50,6 +52,30 @@ SENTRY_ENVIRONMENT=staging npx react-native run-android
 
 This works in any CI/CD system by setting the environment variable in your build configuration.
 
+### 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:
+
+```json {filename:sentry.options.json}
+{
+  "dsn": "https://key@example.io/value",
+  "release": "my-app@1.0.0+42",
+  "dist": "42"
+}
+```
+
+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.
+
+```bash
+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.
+
+</Alert>
+
 ## Android Setup
 
 Initialize Sentry in your `MainApplication` class:
@@ -164,16 +190,22 @@ When `useNativeInit` is set to `true`, the Expo plugin automatically:
 
 You can set the `environment` using the plugin `options` property as shown above, or using the `SENTRY_ENVIRONMENT` environment variable. The environment variable takes precedence over the plugin option.
 
-For per-environment builds with EAS Build, set `SENTRY_ENVIRONMENT` in your build profiles:
+For per-environment builds with EAS Build, set `SENTRY_ENVIRONMENT` in your build profiles. You can also set `SENTRY_RELEASE` and `SENTRY_DIST` if you use custom release names:
 
 ```json {filename:eas.json}
 {
   "build": {
     "production": {
-      "env": { "SENTRY_ENVIRONMENT": "production" }
+      "env": {
+        "SENTRY_ENVIRONMENT": "production",
+        "SENTRY_RELEASE": "my-app@1.0.0+42",
+        "SENTRY_DIST": "42"
+      }
     },
     "staging": {
-      "env": { "SENTRY_ENVIRONMENT": "staging" }
+      "env": {
+        "SENTRY_ENVIRONMENT": "staging"
+      }
     }
   }
 }