docs(android): Document manual Session Replay controls

docs/platforms/android/session-replay/configuration.mdx

@@ -33,6 +33,37 @@ and the following options provide further customization:
  | beforeErrorSampling | `—`                                                     | `BeforeErrorSamplingCallback`                                      | `null`                               | A callback invoked before the `onErrorSampleRate` is checked. Return `false` to skip replay capture for this error, or `true` to proceed with the normal sample rate check. If the callback throws, replay capture proceeds normally (fail-open). Only configurable in code. See [Ignore Certain Errors from Error Sampling](/platforms/android/session-replay/#ignore-certain-errors-from-error-sampling). |
 
 
+## Disable Automatic Replay Sampling
+
+If Session Replay should start only after user consent or an app-specific condition, set both sample rates to `0.0` during initialization. This disables automatic session and error recording while keeping the Session Replay integration available for manual control.
+
+```kotlin {tabTitle:Kotlin} {mdExpandTabs}
+SentryAndroid.init(context) { options ->
+  options.sessionReplay.sessionSampleRate = 0.0
+  options.sessionReplay.onErrorSampleRate = 0.0
+}
+```
+
+```java {tabTitle:Java}
+SentryAndroid.init(context, options -> {
+  options.getSessionReplay().setSessionSampleRate(0.0);
+  options.getSessionReplay().setOnErrorSampleRate(0.0);
+});
+```
+
+```xml {tabTitle:AndroidManifest.xml}
+<application>
+  <meta-data
+    android:name="io.sentry.session-replay.session-sample-rate"
+    android:value="0.0" />
+  <meta-data
+    android:name="io.sentry.session-replay.on-error-sample-rate"
+    android:value="0.0" />
+</application>
+```
+
+Explicit calls to `Sentry.replay().start()` and `Sentry.replay().startBuffering()` bypass these sample rates when starting recording. With `onErrorSampleRate` set to `0.0`, call `flush()` to send a manually started buffer. See [Manual Control](/platforms/android/session-replay/#manual-control) for the complete API behavior.
+
 ## Network Details
 
 By default, Replay will capture basic information about all outgoing http requests in your application. This includes the URL, request and response body sizes, method, and status code. The intention is to limit the chance of collecting private data.

docs/platforms/android/session-replay/index.mdx

@@ -152,6 +152,77 @@ SentryAndroid.init(context, options -> {
 });
 ```
 
+## Manual Control
+
+Use manual control when replay recording depends on user consent, authentication, or a specific workflow. To disable automatic recording, [set both replay sample rates to `0.0`](/platforms/android/session-replay/configuration/#disable-automatic-replay-sampling).
+
+You can call the manual control APIs from any thread. Calls return before the requested operation completes because the SDK queues it.
+
+### Start Recording
+
+Choose the recording mode that fits your use case:
+
+- `start()` starts a full-session replay.
+- `startBuffering()` keeps a rolling buffer of up to 30 seconds. The SDK sends the buffer when an error is sampled or you call `flush()`, then continues recording in session mode.
+
+Explicit calls to `start()` and `startBuffering()` bypass the configured replay sample rates when starting recording. `onErrorSampleRate` still controls whether an error sends a buffered replay. If a replay is already recording, both methods do nothing.
+
+```kotlin {tabTitle:Kotlin}
+// Start a full-session replay.
+Sentry.replay().start()
+
+// Or start a buffered replay instead.
+// Sentry.replay().startBuffering()
+```
+
+```java {tabTitle:Java}
+// Start a full-session replay.
+Sentry.replay().start();
+
+// Or start a buffered replay instead.
+// Sentry.replay().startBuffering();
+```
+
+### Pause Recording on Sensitive Screens
+
+Pause recording before showing sensitive content, such as a PIN entry screen, and resume it after the content is hidden. A manually paused replay stays paused across app background and foreground transitions until you call `resume()`. Calling `resume()` when replay is stopped does nothing.
+
+```kotlin {tabTitle:Kotlin}
+Sentry.replay().pause()
+
+// Resume the same replay after leaving the sensitive screen.
+Sentry.replay().resume()
+```
+
+```java {tabTitle:Java}
+Sentry.replay().pause();
+
+// Resume the same replay after leaving the sensitive screen.
+Sentry.replay().resume();
+```
+
+### Stop or Flush Recording
+
+Call `stop()` to end the current replay. A later call to `start()` or `startBuffering()` creates a new replay session.
+
+```kotlin {tabTitle:Kotlin}
+Sentry.replay().stop()
+```
+
+```java {tabTitle:Java}
+Sentry.replay().stop();
+```
+
+Call `flush()` to send the current replay data without stopping recording. In session mode, it sends the pending segment and continues recording. In buffer mode, it sends the buffer and switches to session mode. Calling `flush()` while recording is stopped starts a new full-session replay.
+
+```kotlin {tabTitle:Kotlin}
+Sentry.replay().flush()
+```
+
+```java {tabTitle:Java}
+Sentry.replay().flush();
+```
+
 ## Privacy
 
 The SDK is recording and aggressively masking all text, images, and webviews by default. If your app has any sensitive data, you should only turn the default masking off after explicitly masking out the sensitive data, using the APIs described below.