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

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

@@ -308,7 +308,7 @@ When you remove the environmental variable in front of your build command, your
 
 ## Expo Transactions Never Finish
 
-If you're using [expo-dev-client](https://docs.expo.dev/development/introduction/#what-is-an-expo-dev-client), you might notice that transactions never finish in your dev builds. This is due to logs that the dev client is continuously sending to the development server. To fix this, you can stop creating spans for the HTTP requests to the log endpoint in your dev builds by adding the following to your `Sentry.init()`:
+If you're using [expo-dev-client](https://docs.expo.dev/develop/development-builds/introduction/), you might notice that transactions never finish in your dev builds. This is due to logs that the dev client is continuously sending to the development server. To fix this, you can stop creating spans for the HTTP requests to the log endpoint in your dev builds by adding the following to your `Sentry.init()`:
 
 ```javascript
 import * as Sentry from "sentry-expo";
@@ -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).