diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/capture/BufferCaptureStrategy.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/capture/BufferCaptureStrategy.kt
index f6c6f3997ae..5a1bdbb2909 100644
--- a/sentry-android-replay/src/main/java/io/sentry/android/replay/capture/BufferCaptureStrategy.kt
+++ b/sentry-android-replay/src/main/java/io/sentry/android/replay/capture/BufferCaptureStrategy.kt
@@ -25,6 +25,18 @@ import java.io.File
 import java.util.Date
 import java.util.concurrent.ScheduledExecutorService
 
+/**
+ * Records a rolling `errorReplayDuration` window: segments are encoded but held in memory, and
+ * frames and segments older than the window are dropped on every screenshot. Used when the session
+ * is not sampled by `sessionSampleRate` but `onErrorSampleRate` is set.
+ *
+ * Nothing is sent until [captureReplay] flushes the buffer for an error — sampled per error against
+ * `onErrorSampleRate`, unlike session mode which samples once at start. After a successful flush
+ * [convert] hands over to a [SessionCaptureStrategy] so the rest of the session is recorded live.
+ *
+ * Since nothing is in flight, `ReplayIntegration` deliberately keeps this strategy recording while
+ * rate-limited, so the buffer stays warm for when the limit expires.
+ */
 @SuppressLint("UseRequiresApi")
 @TargetApi(26)
 internal class BufferCaptureStrategy(
diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/capture/SessionCaptureStrategy.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/capture/SessionCaptureStrategy.kt
index d62efb534cc..df6e09b5358 100644
--- a/sentry-android-replay/src/main/java/io/sentry/android/replay/capture/SessionCaptureStrategy.kt
+++ b/sentry-android-replay/src/main/java/io/sentry/android/replay/capture/SessionCaptureStrategy.kt
@@ -16,6 +16,17 @@ import io.sentry.util.FileUtils
 import java.util.Date
 import java.util.concurrent.ScheduledExecutorService
 
+/**
+ * Records a full session: segments are encoded and sent continuously, one per
+ * `sessionSegmentDuration`, until the 1h `sessionDuration` deadline. Used when the session is
+ * sampled by `sessionSampleRate`.
+ *
+ * [captureReplay] is a no-op here — there is no buffer to flush, the segment covering the error is
+ * sent like any other. Because envelopes are in flight the whole time, `ReplayIntegration` pauses
+ * this strategy while offline or rate-limited so the envelope cache doesn't overflow.
+ *
+ * See [BufferCaptureStrategy] for the on-error counterpart.
+ */
 internal class SessionCaptureStrategy(
   private val options: SentryOptions,
   private val scopes: IScopes?,