docs(react-native): Add warning about AGP autoInstallation on Android

Add alerts to manual setup and v7-to-v8 migration guides warning that
the Sentry Android Gradle Plugin autoInstallation must be disabled for
React Native. Add a troubleshooting section for the
IllegalStateException mix of versions crash caused by this
misconfiguration.

Refs getsentry/sentry-react-native#5682
Co-Authored-By: Claude <noreply@anthropic.com>

Author: antonis

docs/platforms/react-native/manual-setup/manual-setup.mdx

@@ -185,6 +185,12 @@ buildscript {
 
 You can configure the plugin options in `android/app/build.gradle`, as shown below:
 
+<Alert level="warning" title="Auto-Installation Must Be Disabled">
+
+The `autoInstallation` option **must** be set to `false` when using the Sentry Android Gradle Plugin with React Native. The `@sentry/react-native` SDK manages its own `sentry-android` dependency. If auto-installation is enabled, the plugin may pull in a different `sentry-android` version, causing an `IllegalStateException: Sentry SDK has detected a mix of versions` crash at app startup.
+
+</Alert>
+
 ```groovy {filename:android/app/build.gradle}
 apply plugin: "io.sentry.android.gradle"
 
@@ -207,6 +213,7 @@ sentry {
     // which might be incompatible with the React Native SDK
     // Enable auto-installation of Sentry components (sentry-android SDK and okhttp, timber and fragment integrations).
     // Default is enabled.
+    // IMPORTANT: Must be false for React Native.
     autoInstallation {
       enabled = false
     }

docs/platforms/react-native/migration/v7-to-v8.mdx

@@ -61,6 +61,12 @@ buildscript {
 }
 ```
 
+<Alert level="warning" title="Sentry Android Gradle Plugin Auto-Installation">
+
+If you use the Sentry Android Gradle Plugin (AGP), make sure `autoInstallation` is **disabled** in your `android/app/build.gradle`. The `@sentry/react-native` SDK ships with its own compatible `sentry-android` dependency. If `autoInstallation` is enabled, the plugin may pull in a different `sentry-android` version, causing an `IllegalStateException: Sentry SDK has detected a mix of versions` crash at app startup. See the [manual setup guide](/platforms/react-native/manual-setup/manual-setup/#enable-sentry-agp) for the correct configuration.
+
+</Alert>
+
 #### Sentry Self-Hosted
 
 Sentry CLI v3 requires self-hosted Sentry instances version **25.11.1+** (previously 25.2.0).

docs/platforms/react-native/troubleshooting/index.mdx

@@ -359,6 +359,32 @@ You can also use [Advanced Data Scrubbing](/security-legal-pii/scrubbing/advance
 [Replace] [Anything] from [contexts.trace.data.previousRoute.params]
 ```
 
+## Android: IllegalStateException Mix of Versions
+
+If your Android app crashes on startup with:
+
+```
+IllegalStateException: Sentry SDK has detected a mix of versions
+```
+
+This is caused by the Sentry Android Gradle Plugin (AGP) auto-installing a `sentry-android` version that conflicts with the one shipped by `@sentry/react-native`.
+
+### Solution
+
+Set `autoInstallation.enabled = false` in your `android/app/build.gradle`:
+
+```groovy {filename:android/app/build.gradle}
+sentry {
+    autoInstallation {
+      enabled = false
+    }
+}
+```
+
+The React Native SDK manages its own compatible `sentry-android` dependency, so the Gradle plugin should not auto-install one. See the [manual setup guide](/platforms/react-native/manual-setup/manual-setup/#enable-sentry-agp) for the full configuration.
+
+For more information, see [GitHub issue #5682](https://github.com/getsentry/sentry-react-native/issues/5682).
+
 ## Sentry Android Gradle Plugin Circular Dependency
 
 If you encounter a circular dependency error when building your Android app with the Sentry Android Gradle Plugin, this is typically caused by using an older version of the Android Gradle Plugin (AGP).