effect 4.0.0-beta.73 → 4.0.0-beta.75

package/dist/Effect.d.ts

@@ -482,10 +482,8 @@ export declare const all: <const Arg extends Iterable<Effect<any, any, any>> | R
  *
  * **Details**
  *
- * The returned tuple is `[excluded, satisfying]`, where:
- *
- * - `excluded` contains all failures.
- * - `satisfying` contains all successes.
+ * The returned tuple is `[excluded, satisfying]`, where `excluded` contains
+ * all failures and `satisfying` contains all successes.
  *
  * This function runs every effect and never fails. Use `concurrency` to control
  * parallelism.
@@ -513,10 +511,8 @@ export declare const partition: {
      *
      * **Details**
      *
-     * The returned tuple is `[excluded, satisfying]`, where:
-     *
-     * - `excluded` contains all failures.
-     * - `satisfying` contains all successes.
+     * The returned tuple is `[excluded, satisfying]`, where `excluded` contains
+     * all failures and `satisfying` contains all successes.
      *
      * This function runs every effect and never fails. Use `concurrency` to control
      * parallelism.
@@ -546,10 +542,8 @@ export declare const partition: {
      *
      * **Details**
      *
-     * The returned tuple is `[excluded, satisfying]`, where:
-     *
-     * - `excluded` contains all failures.
-     * - `satisfying` contains all successes.
+     * The returned tuple is `[excluded, satisfying]`, where `excluded` contains
+     * all failures and `satisfying` contains all successes.
      *
      * This function runs every effect and never fails. Use `concurrency` to control
      * parallelism.
@@ -1218,7 +1212,7 @@ export declare const whileLoop: <A, E, R>(options: {
  * ```
  *
  * @see {@link tryPromise} for a version that can handle failures.
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const promise: <A>(evaluate: (signal: AbortSignal) => PromiseLike<A>) => Effect<A>;
@@ -1284,7 +1278,7 @@ export declare const promise: <A>(evaluate: (signal: AbortSignal) => PromiseLike
  * ```
  *
  * @see {@link promise} if the effectful computation is asynchronous and does not throw errors.
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const tryPromise: <A, E = Cause.UnknownError>(options: {
@@ -1296,8 +1290,8 @@ export declare const tryPromise: <A, E = Cause.UnknownError>(options: {
  *
  * **When to use**
  *
- * Use when you use this function when you need an effect that completes successfully with a
- * specific value without any errors or external dependencies.
+ * Use when an effect should complete successfully with a specific value without any errors
+ * or external dependencies.
  *
  * **Example** (Creating a successful effect)
  *
@@ -1312,7 +1306,7 @@ export declare const tryPromise: <A, E = Cause.UnknownError>(options: {
  * ```
  *
  * @see {@link fail} to create an effect that represents a failure.
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const succeed: <A>(value: A) => Effect<A>;
@@ -1330,7 +1324,7 @@ export declare const succeed: <A>(value: A) => Effect<A>;
  * // Output: { _id: 'Option', _tag: 'None' }
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const succeedNone: Effect<Option<never>>;
@@ -1348,7 +1342,7 @@ export declare const succeedNone: Effect<Option<never>>;
  * // Output: { _id: 'Option', _tag: 'Some', value: 42 }
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const succeedSome: <A>(value: A) => Effect<Option<A>>;
@@ -1357,14 +1351,16 @@ export declare const succeedSome: <A>(value: A) => Effect<Option<A>>;
  *
  * **When to use**
  *
- * Use when you need to defer the evaluation of an effect until it is required. This is particularly useful for optimizing expensive computations, managing circular dependencies, or resolving type inference issues.
+ * Use when you need to defer the evaluation of an effect until it is required.
  *
  * **Details**
  *
- * `suspend` takes a thunk that represents the effect and wraps it in a suspended effect. This means the effect will not be created until it is explicitly needed, which is helpful in various scenarios:
- * - **Lazy Evaluation**: Helps optimize performance by deferring computations, especially when the effect might not be needed, or when its computation is expensive. This also ensures that any side effects or scoped captures are re-executed on each invocation.
- * - **Handling Circular Dependencies**: Useful in managing circular dependencies, such as recursive functions that need to avoid eager evaluation to prevent stack overflow.
- * - **Unifying Return Types**: Can help TypeScript unify return types in situations where multiple branches of logic return different effects, simplifying type inference.
+ * `suspend` takes a thunk that represents an effect and delays creating it
+ * until the suspended effect is evaluated. This is useful for optimizing
+ * expensive computations, managing circular dependencies such as recursive
+ * functions, and helping TypeScript unify return types when branches construct
+ * different effects. Any side effects or scoped captures inside the thunk are
+ * re-executed on each invocation.
  *
  * **Example** (Lazily evaluating side effects)
  *
@@ -1435,7 +1431,7 @@ export declare const succeedSome: <A>(value: A) => Effect<Option<A>>;
  *   )
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const suspend: <A, E, R>(effect: LazyArg<Effect<A, E, R>>) => Effect<A, E, R>;
@@ -1444,7 +1440,8 @@ export declare const suspend: <A, E, R>(effect: LazyArg<Effect<A, E, R>>) => Eff
  *
  * **When to use**
  *
- * Use when you are sure the operation will not fail.
+ * Use when you need to wrap a synchronous side-effectful operation that is not
+ * expected to throw.
  *
  * **Details**
  *
@@ -1471,7 +1468,7 @@ export declare const suspend: <A, E, R>(effect: LazyArg<Effect<A, E, R>>) => Eff
  * ```
  *
  * @see {@link try_ | try} for a version that can handle failures.
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const sync: <A>(thunk: LazyArg<A>) => Effect<A>;
@@ -1480,7 +1477,7 @@ export {
 /**
  * Returns an effect that succeeds with `void`.
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 void_ as void };
@@ -1489,7 +1486,7 @@ export {
 /**
  * Returns an effect that succeeds with `undefined`.
  *
- * @category creating effects
+ * @category constructors
  * @since 4.0.0
  */
 undefined_ as undefined };
@@ -1498,8 +1495,8 @@ undefined_ as undefined };
  *
  * **When to use**
  *
- * Use when integrating APIs that complete through callbacks
- * instead of returning a `Promise`.
+ * Use when you need to integrate APIs that complete through callbacks instead
+ * of returning a `Promise`.
  *
  * **Details**
  *
@@ -1525,7 +1522,7 @@ undefined_ as undefined };
  * const program = delay(1000)
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 4.0.0
  */
 export declare const callback: <A, E = never, R = never>(register: (this: Scheduler, resume: (effect: Effect<A, E, R>) => void, signal: AbortSignal) => void | Effect<void, never, R>) => Effect<A, E, R>;
@@ -1548,7 +1545,7 @@ export declare const callback: <A, E = never, R = never>(register: (this: Schedu
  * const timedProgram = Effect.timeout(program, "1 second")
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const never: Effect<never>;
@@ -1745,14 +1742,13 @@ export declare const bind: {
  *
  * **When to use**
  *
- * Use when `gen` allows you to write code that looks and behaves like synchronous
- * code, but it can handle asynchronous tasks, errors, and complex control flow
- * (like loops and conditions). It helps make asynchronous code more readable
- * and easier to manage.
+ * Use when you want to write effectful code that looks and behaves like
+ * synchronous code, while still handling asynchronous tasks, errors, and complex
+ * control flow such as loops and conditions.
  *
- * The generator functions work similarly to `async/await` but with more
- * explicit control over the execution of effects. You can `yield*` values from
- * effects and return the final result at the end.
+ * Generator functions work similarly to `async/await` but keep errors,
+ * requirements, and interruption in the Effect type. You can `yield*` values
+ * from effects and return the final result at the end.
  *
  * **Example** (Sequencing effects with generators)
  *
@@ -1787,7 +1783,7 @@ export declare const bind: {
  * })
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const gen: {
@@ -1797,14 +1793,13 @@ export declare const gen: {
      *
      * **When to use**
      *
-     * Use when `gen` allows you to write code that looks and behaves like synchronous
-     * code, but it can handle asynchronous tasks, errors, and complex control flow
-     * (like loops and conditions). It helps make asynchronous code more readable
-     * and easier to manage.
+     * Use when you want to write effectful code that looks and behaves like
+     * synchronous code, while still handling asynchronous tasks, errors, and complex
+     * control flow such as loops and conditions.
      *
-     * The generator functions work similarly to `async/await` but with more
-     * explicit control over the execution of effects. You can `yield*` values from
-     * effects and return the final result at the end.
+     * Generator functions work similarly to `async/await` but keep errors,
+     * requirements, and interruption in the Effect type. You can `yield*` values
+     * from effects and return the final result at the end.
      *
      * **Example** (Sequencing effects with generators)
      *
@@ -1839,7 +1834,7 @@ export declare const gen: {
      * })
      * ```
      *
-     * @category creating effects
+     * @category constructors
      * @since 2.0.0
      */
     <Eff extends Effect<any, any, any>, AEff>(f: () => Generator<Eff, AEff, never>): Effect<AEff, [
@@ -1853,14 +1848,13 @@ export declare const gen: {
      *
      * **When to use**
      *
-     * Use when `gen` allows you to write code that looks and behaves like synchronous
-     * code, but it can handle asynchronous tasks, errors, and complex control flow
-     * (like loops and conditions). It helps make asynchronous code more readable
-     * and easier to manage.
+     * Use when you want to write effectful code that looks and behaves like
+     * synchronous code, while still handling asynchronous tasks, errors, and complex
+     * control flow such as loops and conditions.
      *
-     * The generator functions work similarly to `async/await` but with more
-     * explicit control over the execution of effects. You can `yield*` values from
-     * effects and return the final result at the end.
+     * Generator functions work similarly to `async/await` but keep errors,
+     * requirements, and interruption in the Effect type. You can `yield*` values
+     * from effects and return the final result at the end.
      *
      * **Example** (Sequencing effects with generators)
      *
@@ -1895,7 +1889,7 @@ export declare const gen: {
      * })
      * ```
      *
-     * @category creating effects
+     * @category constructors
      * @since 2.0.0
      */
     <Self, Eff extends Effect<any, any, any>, AEff>(options: {
@@ -1915,7 +1909,7 @@ export declare namespace gen {
     /**
      * Generator return type accepted by `Effect.gen`.
      *
-     * @category creating effects
+     * @category constructors
      * @since 4.0.0
      */
     type Return<A, E = never, R = never> = Generator<Effect<any, E, R>, A, any>;
@@ -1925,9 +1919,12 @@ export declare namespace gen {
  *
  * **When to use**
  *
- * Use to explicitly signal an error in an `Effect`. The error
- * will keep propagating unless it is handled. You can handle the error with
- * functions like {@link catchTag} or {@link catchTags}.
+ * Use to explicitly signal a recoverable error in an `Effect`.
+ *
+ * **Details**
+ *
+ * The error keeps propagating unless it is handled. You can handle tagged
+ * errors with functions like {@link catchTag} or {@link catchTags}.
  *
  * **Example** (Creating a failed effect)
  *
@@ -1944,7 +1941,7 @@ export declare namespace gen {
  * ```
  *
  * @see {@link succeed} to create an effect that represents a successful value.
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const fail: <E>(error: E) => Effect<never, E>;
@@ -1972,13 +1969,19 @@ export declare const fail: <E>(error: E) => Effect<never, E>;
  * // Output: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const failSync: <E>(evaluate: LazyArg<E>) => Effect<never, E>;
 /**
  * Creates an `Effect` that represents a failure with a specific `Cause`.
  *
+ * **When to use**
+ *
+ * Use when you already have a full `Cause` and need to preserve defects,
+ * interruptions, annotations, or combined failures in the effect's failure
+ * channel.
+ *
  * **Details**
  *
  * This function allows you to create effects that fail with complex error
@@ -1997,7 +2000,7 @@ export declare const failSync: <E>(evaluate: LazyArg<E>) => Effect<never, E>;
  * // Output: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const failCause: <E>(cause: Cause.Cause<E>) => Effect<never, E>;
@@ -2025,7 +2028,7 @@ export declare const failCause: <E>(cause: Cause.Cause<E>) => Effect<never, E>;
  * // Output: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => Effect<never, E>;
@@ -2034,8 +2037,8 @@ export declare const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => Ef
  *
  * **When to use**
  *
- * Use when encountering unexpected conditions in your code that should
- * not be handled as regular errors but instead represent unrecoverable defects.
+ * Use when you need an `Effect` to report an unrecoverable defect instead of a
+ * typed error.
  *
  * **Details**
  *
@@ -2066,7 +2069,7 @@ export declare const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => Ef
  * //   ...stack trace...
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const die: (defect: unknown) => Effect<never>;
@@ -2081,10 +2084,8 @@ export {
  *
  * **When to use**
  *
- * Use when in situations where you need to perform synchronous operations that might
- * fail, such as parsing JSON, you can use the `try` constructor. This
- * constructor is designed to handle operations that could throw exceptions by
- * capturing those exceptions and transforming them into manageable errors.
+ * Use when you need to perform synchronous operations that might throw, such
+ * as parsing JSON, and convert thrown exceptions into typed Effect failures.
  *
  * **Details**
  *
@@ -2136,7 +2137,7 @@ export {
  *
  * @see {@link sync} if the effectful computation is synchronous and does not
  * throw errors.
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 try_ as try };
@@ -2157,7 +2158,7 @@ try_ as try };
  * Effect.runPromise(program)
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export declare const yieldNow: Effect<void>;
@@ -2178,7 +2179,7 @@ export declare const yieldNow: Effect<void>;
  * Effect.runPromise(program)
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 4.0.0
  */
 export declare const yieldNowWith: (priority?: number) => Effect<void>;
@@ -2198,7 +2199,7 @@ export declare const yieldNowWith: (priority?: number) => Effect<void>;
  * // Output: Fiber ID: 1
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 4.0.0
  */
 export declare const withFiber: <A, E = never, R = never>(evaluate: (fiber: Fiber<unknown, unknown>) => Effect<A, E, R>) => Effect<A, E, R>;
@@ -2228,6 +2229,11 @@ export declare const fromResult: <A, E>(result: Result.Result<A, E>) => Effect<A
 /**
  * Converts an `Option` into an `Effect`.
  *
+ * **When to use**
+ *
+ * Use when absence should become a typed `NoSuchElementError` in the effect error
+ * channel.
+ *
  * **Details**
  *
  * `Option.some` becomes a successful effect with the contained value, while
@@ -2508,8 +2514,8 @@ export declare const flatten: <A, E, R, E2, R2>(self: Effect<Effect<A, E, R>, E2
  *
  * **When to use**
  *
- * Use when one effect must run after another and the second effect
- * may depend on the first effect's success value.
+ * Use when you need one effect to run after another and the second effect may
+ * depend on the first effect's success value.
  *
  * **Details**
  *
@@ -2584,8 +2590,8 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * Use when one effect must run after another and the second effect
-     * may depend on the first effect's success value.
+     * Use when you need one effect to run after another and the second effect may
+     * depend on the first effect's success value.
      *
      * **Details**
      *
@@ -2660,8 +2666,8 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * Use when one effect must run after another and the second effect
-     * may depend on the first effect's success value.
+     * Use when you need one effect to run after another and the second effect may
+     * depend on the first effect's success value.
      *
      * **Details**
      *
@@ -2736,8 +2742,8 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * Use when one effect must run after another and the second effect
-     * may depend on the first effect's success value.
+     * Use when you need one effect to run after another and the second effect may
+     * depend on the first effect's success value.
      *
      * **Details**
      *
@@ -2812,8 +2818,8 @@ export declare const andThen: {
      *
      * **When to use**
      *
-     * Use when one effect must run after another and the second effect
-     * may depend on the first effect's success value.
+     * Use when you need one effect to run after another and the second effect may
+     * depend on the first effect's success value.
      *
      * **Details**
      *
@@ -2889,9 +2895,8 @@ export declare const andThen: {
  *
  * **When to use**
  *
- * Use when you want to perform a side effect, like logging or tracking,
- * without modifying the main value. This is useful when you need to observe or
- * record an action but want the original value to be passed to the next step.
+ * Use when you need to run an effectful observation, such as logging or
+ * tracking, while passing the original success value to the next step.
  *
  * **Details**
  *
@@ -2943,9 +2948,8 @@ export declare const tap: {
      *
      * **When to use**
      *
-     * Use when you want to perform a side effect, like logging or tracking,
-     * without modifying the main value. This is useful when you need to observe or
-     * record an action but want the original value to be passed to the next step.
+     * Use when you need to run an effectful observation, such as logging or
+     * tracking, while passing the original success value to the next step.
      *
      * **Details**
      *
@@ -2997,9 +3001,8 @@ export declare const tap: {
      *
      * **When to use**
      *
-     * Use when you want to perform a side effect, like logging or tracking,
-     * without modifying the main value. This is useful when you need to observe or
-     * record an action but want the original value to be passed to the next step.
+     * Use when you need to run an effectful observation, such as logging or
+     * tracking, while passing the original success value to the next step.
      *
      * **Details**
      *
@@ -3051,9 +3054,8 @@ export declare const tap: {
      *
      * **When to use**
      *
-     * Use when you want to perform a side effect, like logging or tracking,
-     * without modifying the main value. This is useful when you need to observe or
-     * record an action but want the original value to be passed to the next step.
+     * Use when you need to run an effectful observation, such as logging or
+     * tracking, while passing the original success value to the next step.
      *
      * **Details**
      *
@@ -3105,9 +3107,8 @@ export declare const tap: {
      *
      * **When to use**
      *
-     * Use when you want to perform a side effect, like logging or tracking,
-     * without modifying the main value. This is useful when you need to observe or
-     * record an action but want the original value to be passed to the next step.
+     * Use when you need to run an effectful observation, such as logging or
+     * tracking, while passing the original success value to the next step.
      *
      * **Details**
      *
@@ -3159,16 +3160,15 @@ export declare const tap: {
  *
  * **When to use**
  *
- * Use when you want to handle typed failures as data while preserving
- * the original error value. Use `option` when you only care whether the effect
- * succeeded, and `exit` when you need the full failure cause.
+ * Use when you want an `Effect`'s typed failures to be handled as `Result`
+ * data while preserving the original error value.
  *
  * **Details**
  *
  * This function converts an effect that may fail into an effect that always
  * succeeds, wrapping the outcome in a `Result` type. The result will be
- * `Result.Err` if the effect fails, containing the recoverable error, or
- * `Result.Ok` if it succeeds, containing the result.
+ * `Result.Failure` if the effect fails, containing the recoverable error, or
+ * `Result.Success` if it succeeds, containing the result.
  *
  * Using this function, you can handle recoverable errors explicitly without
  * causing the effect to fail. This is particularly useful in scenarios where
@@ -3214,9 +3214,8 @@ export declare const result: <A, E, R>(self: Effect<A, E, R>) => Effect<Result.R
  *
  * **When to use**
  *
- * Use when the failure value is not important and absence is enough.
- * Use `result` when you need the original typed failure, and `exit` when you
- * need the full failure cause.
+ * Use when you only care whether an effect succeeds and want recoverable
+ * failures represented as `Option.none`.
  *
  * **Details**
  *
@@ -3263,9 +3262,8 @@ export declare const option: <A, E, R>(self: Effect<A, E, R>) => Effect<Option<A
  *
  * **When to use**
  *
- * Use when you need to inspect the full outcome, including typed
- * failures, defects, and interruptions. Use `result` or `option` when you only
- * need to handle typed failures.
+ * Use when you need to inspect the full outcome, including typed failures, defects,
+ * and interruptions.
  *
  * **Details**
  *
@@ -3608,8 +3606,7 @@ export declare const asVoid: <A, E, R>(self: Effect<A, E, R>) => Effect<void, E,
  *
  * **When to use**
  *
- * Use to handle the failure value as a success, or to move the success value
- * into the failure channel.
+ * Use to swap an `Effect`'s success and failure channels.
  *
  * **Details**
  *
@@ -4020,6 +4017,11 @@ export {
 /**
  * Handles all errors in an effect by providing a fallback effect.
  *
+ * **When to use**
+ *
+ * Use when every recoverable error from an effect should be handled by the same
+ * fallback function while unrecoverable defects remain defects.
+ *
  * **Details**
  *
  * The `catch` function catches any errors that may occur during the
@@ -4027,8 +4029,10 @@ export {
  * effect. This ensures that the program continues without failing by recovering
  * from errors using the provided fallback logic.
  *
- * **Note**: `catch` only handles recoverable errors. It will not recover
- * from unrecoverable defects.
+ * **Gotchas**
+ *
+ * `catch` only handles recoverable errors. It will not recover from
+ * unrecoverable defects.
  *
  * @see {@link catchCause} for a version that can recover from both recoverable and unrecoverable errors.
  *
@@ -4042,8 +4046,8 @@ catch_ as catch };
  *
  * **When to use**
  *
- * Use when recovering from one specific tagged error in an effect error
- * channel.
+ * Use when you need to recover from one specific tagged error in an effect
+ * error channel.
  *
  * **Details**
  *
@@ -4087,8 +4091,8 @@ export declare const catchTag: {
      *
      * **When to use**
      *
-     * Use when recovering from one specific tagged error in an effect error
-     * channel.
+     * Use when you need to recover from one specific tagged error in an effect
+     * error channel.
      *
      * **Details**
      *
@@ -4132,8 +4136,8 @@ export declare const catchTag: {
      *
      * **When to use**
      *
-     * Use when recovering from one specific tagged error in an effect error
-     * channel.
+     * Use when you need to recover from one specific tagged error in an effect
+     * error channel.
      *
      * **Details**
      *
@@ -4178,10 +4182,14 @@ export declare const catchTag: {
  * **When to use**
  *
  * Use when one recovery step should handle several tagged error types by
- * matching their readonly `_tag` fields. Pass a handler table whose keys are
- * tags, plus an optional fallback for unmatched errors.
+ * matching their readonly `_tag` fields.
  *
- * The error type must have a readonly `_tag` field to use `catchTag`. This
+ * **Details**
+ *
+ * Pass a handler table whose keys are tags, plus an optional fallback for
+ * unmatched errors.
+ *
+ * The error type must have a readonly `_tag` field to use `catchTags`. This
  * field is used to identify and match errors.
  *
  * **Example** (Handling multiple tagged errors)
@@ -4219,10 +4227,14 @@ export declare const catchTags: {
      * **When to use**
      *
      * Use when one recovery step should handle several tagged error types by
-     * matching their readonly `_tag` fields. Pass a handler table whose keys are
-     * tags, plus an optional fallback for unmatched errors.
+     * matching their readonly `_tag` fields.
+     *
+     * **Details**
      *
-     * The error type must have a readonly `_tag` field to use `catchTag`. This
+     * Pass a handler table whose keys are tags, plus an optional fallback for
+     * unmatched errors.
+     *
+     * The error type must have a readonly `_tag` field to use `catchTags`. This
      * field is used to identify and match errors.
      *
      * **Example** (Handling multiple tagged errors)
@@ -4280,10 +4292,14 @@ export declare const catchTags: {
      * **When to use**
      *
      * Use when one recovery step should handle several tagged error types by
-     * matching their readonly `_tag` fields. Pass a handler table whose keys are
-     * tags, plus an optional fallback for unmatched errors.
+     * matching their readonly `_tag` fields.
+     *
+     * **Details**
      *
-     * The error type must have a readonly `_tag` field to use `catchTag`. This
+     * Pass a handler table whose keys are tags, plus an optional fallback for
+     * unmatched errors.
+     *
+     * The error type must have a readonly `_tag` field to use `catchTags`. This
      * field is used to identify and match errors.
      *
      * **Example** (Handling multiple tagged errors)
@@ -4341,8 +4357,8 @@ export declare const catchTags: {
  *
  * **When to use**
  *
- * Use to handle one nested reason inside a tagged error while preserving the
- * parent error shape for unmatched reasons.
+ * Use to handle one nested reason inside an `Effect`'s tagged error while
+ * preserving the parent error shape for unmatched reasons.
  *
  * **Details**
  *
@@ -4387,8 +4403,8 @@ export declare const catchReason: {
      *
      * **When to use**
      *
-     * Use to handle one nested reason inside a tagged error while preserving the
-     * parent error shape for unmatched reasons.
+     * Use to handle one nested reason inside an `Effect`'s tagged error while
+     * preserving the parent error shape for unmatched reasons.
      *
      * **Details**
      *
@@ -4433,8 +4449,8 @@ export declare const catchReason: {
      *
      * **When to use**
      *
-     * Use to handle one nested reason inside a tagged error while preserving the
-     * parent error shape for unmatched reasons.
+     * Use to handle one nested reason inside an `Effect`'s tagged error while
+     * preserving the parent error shape for unmatched reasons.
      *
      * **Details**
      *
@@ -4726,8 +4742,9 @@ export declare const unwrapReason: {
  *
  * **When to use**
  *
- * Use when recovery needs the full `Cause`, including recoverable failures,
- * defects, and interruptions, instead of only the typed error value.
+ * Use when you need to recover from an `Effect` by inspecting the full `Cause`,
+ * including recoverable failures, defects, and interruptions, instead of only
+ * the typed error value.
  *
  * **Details**
  *
@@ -4766,8 +4783,9 @@ export declare const catchCause: {
      *
      * **When to use**
      *
-     * Use when recovery needs the full `Cause`, including recoverable failures,
-     * defects, and interruptions, instead of only the typed error value.
+     * Use when you need to recover from an `Effect` by inspecting the full `Cause`,
+     * including recoverable failures, defects, and interruptions, instead of only
+     * the typed error value.
      *
      * **Details**
      *
@@ -4806,8 +4824,9 @@ export declare const catchCause: {
      *
      * **When to use**
      *
-     * Use when recovery needs the full `Cause`, including recoverable failures,
-     * defects, and interruptions, instead of only the typed error value.
+     * Use when you need to recover from an `Effect` by inspecting the full `Cause`,
+     * including recoverable failures, defects, and interruptions, instead of only
+     * the typed error value.
      *
      * **Details**
      *
@@ -4846,8 +4865,7 @@ export declare const catchCause: {
  *
  * **When to use**
  *
- * Use when you use this sparingly, usually at integration boundaries where defects must be
- * reported or translated for an external system.
+ * Use when you need to report or translate defects at integration boundaries.
  *
  * **Details**
  *
@@ -4887,8 +4905,7 @@ export declare const catchDefect: {
      *
      * **When to use**
      *
-     * Use when you use this sparingly, usually at integration boundaries where defects must be
-     * reported or translated for an external system.
+     * Use when you need to report or translate defects at integration boundaries.
      *
      * **Details**
      *
@@ -4928,8 +4945,7 @@ export declare const catchDefect: {
      *
      * **When to use**
      *
-     * Use when you use this sparingly, usually at integration boundaries where defects must be
-     * reported or translated for an external system.
+     * Use when you need to report or translate defects at integration boundaries.
      *
      * **Details**
      *
@@ -4970,8 +4986,11 @@ export declare const catchDefect: {
  *
  * **When to use**
  *
- * Use when you need to recover from errors that match a condition. Use a
- * `Refinement` for type narrowing or a `Predicate` for simple boolean
+ * Use when you need to recover from errors that match a condition.
+ *
+ * **Details**
+ *
+ * Use a `Refinement` for type narrowing or a `Predicate` for simple boolean
  * matching. Non-matching errors re-fail with the original cause. Defects and
  * interrupts are not caught.
  *
@@ -5010,8 +5029,11 @@ export declare const catchIf: {
      *
      * **When to use**
      *
-     * Use when you need to recover from errors that match a condition. Use a
-     * `Refinement` for type narrowing or a `Predicate` for simple boolean
+     * Use when you need to recover from errors that match a condition.
+     *
+     * **Details**
+     *
+     * Use a `Refinement` for type narrowing or a `Predicate` for simple boolean
      * matching. Non-matching errors re-fail with the original cause. Defects and
      * interrupts are not caught.
      *
@@ -5050,8 +5072,11 @@ export declare const catchIf: {
      *
      * **When to use**
      *
-     * Use when you need to recover from errors that match a condition. Use a
-     * `Refinement` for type narrowing or a `Predicate` for simple boolean
+     * Use when you need to recover from errors that match a condition.
+     *
+     * **Details**
+     *
+     * Use a `Refinement` for type narrowing or a `Predicate` for simple boolean
      * matching. Non-matching errors re-fail with the original cause. Defects and
      * interrupts are not caught.
      *
@@ -5090,8 +5115,11 @@ export declare const catchIf: {
      *
      * **When to use**
      *
-     * Use when you need to recover from errors that match a condition. Use a
-     * `Refinement` for type narrowing or a `Predicate` for simple boolean
+     * Use when you need to recover from errors that match a condition.
+     *
+     * **Details**
+     *
+     * Use a `Refinement` for type narrowing or a `Predicate` for simple boolean
      * matching. Non-matching errors re-fail with the original cause. Defects and
      * interrupts are not caught.
      *
@@ -5130,8 +5158,11 @@ export declare const catchIf: {
      *
      * **When to use**
      *
-     * Use when you need to recover from errors that match a condition. Use a
-     * `Refinement` for type narrowing or a `Predicate` for simple boolean
+     * Use when you need to recover from errors that match a condition.
+     *
+     * **Details**
+     *
+     * Use a `Refinement` for type narrowing or a `Predicate` for simple boolean
      * matching. Non-matching errors re-fail with the original cause. Defects and
      * interrupts are not caught.
      *
@@ -5247,7 +5278,8 @@ export declare const catchFilter: {
  *
  * **When to use**
  *
- * Use to convert `NoSuchElementError` failures into `Option.none`.
+ * Use when you expect missing-value failures and want them to become an
+ * optional success while all other failures keep failing.
  *
  * **Details**
  *
@@ -5279,7 +5311,7 @@ export declare const catchNoSuchElement: <A, E, R>(self: Effect<A, E, R>) => Eff
  *
  * **When to use**
  *
- * Use to recover from full causes selected by a predicate.
+ * Use to recover an `Effect` from full causes selected by a predicate.
  *
  * **Details**
  *
@@ -5323,7 +5355,7 @@ export declare const catchCauseIf: {
      *
      * **When to use**
      *
-     * Use to recover from full causes selected by a predicate.
+     * Use to recover an `Effect` from full causes selected by a predicate.
      *
      * **Details**
      *
@@ -5367,7 +5399,7 @@ export declare const catchCauseIf: {
      *
      * **When to use**
      *
-     * Use to recover from full causes selected by a predicate.
+     * Use to recover an `Effect` from full causes selected by a predicate.
      *
      * **Details**
      *
@@ -5412,8 +5444,9 @@ export declare const catchCauseIf: {
  *
  * **When to use**
  *
- * Use when you need to recover only from causes selected by a `Filter`, and the
- * recovery needs both the selected value and the original `Cause`.
+ * Use when you need to recover an `Effect` only from causes selected by a
+ * `Filter`, while giving the recovery both the selected value and the original
+ * `Cause`.
  *
  * **Details**
  *
@@ -5434,8 +5467,9 @@ export declare const catchCauseFilter: {
      *
      * **When to use**
      *
-     * Use when you need to recover only from causes selected by a `Filter`, and the
-     * recovery needs both the selected value and the original `Cause`.
+     * Use when you need to recover an `Effect` only from causes selected by a
+     * `Filter`, while giving the recovery both the selected value and the original
+     * `Cause`.
      *
      * **Details**
      *
@@ -5456,8 +5490,9 @@ export declare const catchCauseFilter: {
      *
      * **When to use**
      *
-     * Use when you need to recover only from causes selected by a `Filter`, and the
-     * recovery needs both the selected value and the original `Cause`.
+     * Use when you need to recover an `Effect` only from causes selected by a
+     * `Filter`, while giving the recovery both the selected value and the original
+     * `Cause`.
      *
      * **Details**
      *
@@ -5479,7 +5514,8 @@ export declare const catchCauseFilter: {
  *
  * **When to use**
  *
- * Use to translate typed failures while leaving successful values unchanged.
+ * Use to translate an `Effect`'s typed failures while leaving successful values
+ * unchanged.
  *
  * **Details**
  *
@@ -5517,7 +5553,8 @@ export declare const mapError: {
      *
      * **When to use**
      *
-     * Use to translate typed failures while leaving successful values unchanged.
+     * Use to translate an `Effect`'s typed failures while leaving successful values
+     * unchanged.
      *
      * **Details**
      *
@@ -5555,7 +5592,8 @@ export declare const mapError: {
      *
      * **When to use**
      *
-     * Use to translate typed failures while leaving successful values unchanged.
+     * Use to translate an `Effect`'s typed failures while leaving successful values
+     * unchanged.
      *
      * **Details**
      *
@@ -5594,8 +5632,8 @@ export declare const mapError: {
  *
  * **When to use**
  *
- * Use to transform both success and failure values without changing whether the
- * effect succeeds or fails.
+ * Use to transform both success and failure channels of an `Effect` without
+ * changing whether it succeeds or fails.
  *
  * **Details**
  *
@@ -5635,8 +5673,8 @@ export declare const mapBoth: {
      *
      * **When to use**
      *
-     * Use to transform both success and failure values without changing whether the
-     * effect succeeds or fails.
+     * Use to transform both success and failure channels of an `Effect` without
+     * changing whether it succeeds or fails.
      *
      * **Details**
      *
@@ -5679,8 +5717,8 @@ export declare const mapBoth: {
      *
      * **When to use**
      *
-     * Use to transform both success and failure values without changing whether the
-     * effect succeeds or fails.
+     * Use to transform both success and failure channels of an `Effect` without
+     * changing whether it succeeds or fails.
      *
      * **Details**
      *
@@ -5725,8 +5763,8 @@ export declare const mapBoth: {
  *
  * **When to use**
  *
- * Use when a typed failure represents an unrecoverable bug or invalid
- * state and should not be handled as a recoverable error.
+ * Use when you need to turn an `Effect` typed failure that represents an
+ * unrecoverable bug or invalid state into a defect.
  *
  * **Example** (Converting typed failures into defects)
  *
@@ -5973,6 +6011,11 @@ export declare const tapErrorTag: {
  * Runs an effectful operation with the full `Cause` when the source effect
  * fails.
  *
+ * **When to use**
+ *
+ * Use when failure observation needs typed failures, defects, and interruptions
+ * rather than only the typed error value.
+ *
  * **Details**
  *
  * Use this to log or inspect typed failures, defects, and interruptions. When
@@ -6004,6 +6047,11 @@ export declare const tapCause: {
      * Runs an effectful operation with the full `Cause` when the source effect
      * fails.
      *
+     * **When to use**
+     *
+     * Use when failure observation needs typed failures, defects, and interruptions
+     * rather than only the typed error value.
+     *
      * **Details**
      *
      * Use this to log or inspect typed failures, defects, and interruptions. When
@@ -6035,6 +6083,11 @@ export declare const tapCause: {
      * Runs an effectful operation with the full `Cause` when the source effect
      * fails.
      *
+     * **When to use**
+     *
+     * Use when failure observation needs typed failures, defects, and interruptions
+     * rather than only the typed error value.
+     *
      * **Details**
      *
      * Use this to log or inspect typed failures, defects, and interruptions. When
@@ -6165,8 +6218,9 @@ export declare const tapCauseIf: {
  *
  * **When to use**
  *
- * Use when you need to observe only failure causes selected by a `Filter`, and
- * the side effect needs both the selected value and the original `Cause`.
+ * Use when you need to observe only failure causes selected by a `Filter`,
+ * while giving the side effect both the selected value and the original
+ * `Cause`.
  *
  * **Details**
  *
@@ -6187,8 +6241,9 @@ export declare const tapCauseFilter: {
      *
      * **When to use**
      *
-     * Use when you need to observe only failure causes selected by a `Filter`, and
-     * the side effect needs both the selected value and the original `Cause`.
+     * Use when you need to observe only failure causes selected by a `Filter`,
+     * while giving the side effect both the selected value and the original
+     * `Cause`.
      *
      * **Details**
      *
@@ -6209,8 +6264,9 @@ export declare const tapCauseFilter: {
      *
      * **When to use**
      *
-     * Use when you need to observe only failure causes selected by a `Filter`, and
-     * the side effect needs both the selected value and the original `Cause`.
+     * Use when you need to observe only failure causes selected by a `Filter`,
+     * while giving the side effect both the selected value and the original
+     * `Cause`.
      *
      * **Details**
      *
@@ -6405,7 +6461,7 @@ export declare const tapDefect: {
  * // Ready
  * ```
  *
- * @category repetition / recursion
+ * @category repetition
  * @since 2.0.0
  */
 export declare const eventually: <A, E, R>(self: Effect<A, E, R>) => Effect<A, never, R>;
@@ -6460,8 +6516,8 @@ export declare namespace Retry {
  *
  * **When to use**
  *
- * Use when typed failures may be transient, such as network issues or
- * temporary resource unavailability.
+ * Use when you need to rerun an effect after transient typed failures, such as
+ * network issues or temporary resource unavailability.
  *
  * **Details**
  *
@@ -6513,8 +6569,8 @@ export declare const retry: {
      *
      * **When to use**
      *
-     * Use when typed failures may be transient, such as network issues or
-     * temporary resource unavailability.
+     * Use when you need to rerun an effect after transient typed failures, such as
+     * network issues or temporary resource unavailability.
      *
      * **Details**
      *
@@ -6566,8 +6622,8 @@ export declare const retry: {
      *
      * **When to use**
      *
-     * Use when typed failures may be transient, such as network issues or
-     * temporary resource unavailability.
+     * Use when you need to rerun an effect after transient typed failures, such as
+     * network issues or temporary resource unavailability.
      *
      * **Details**
      *
@@ -6619,8 +6675,8 @@ export declare const retry: {
      *
      * **When to use**
      *
-     * Use when typed failures may be transient, such as network issues or
-     * temporary resource unavailability.
+     * Use when you need to rerun an effect after transient typed failures, such as
+     * network issues or temporary resource unavailability.
      *
      * **Details**
      *
@@ -6672,8 +6728,8 @@ export declare const retry: {
      *
      * **When to use**
      *
-     * Use when typed failures may be transient, such as network issues or
-     * temporary resource unavailability.
+     * Use when you need to rerun an effect after transient typed failures, such as
+     * network issues or temporary resource unavailability.
      *
      * **Details**
      *
@@ -6725,8 +6781,8 @@ export declare const retry: {
      *
      * **When to use**
      *
-     * Use when typed failures may be transient, such as network issues or
-     * temporary resource unavailability.
+     * Use when you need to rerun an effect after transient typed failures, such as
+     * network issues or temporary resource unavailability.
      *
      * **Details**
      *
@@ -6778,8 +6834,8 @@ export declare const retry: {
      *
      * **When to use**
      *
-     * Use when typed failures may be transient, such as network issues or
-     * temporary resource unavailability.
+     * Use when you need to rerun an effect after transient typed failures, such as
+     * network issues or temporary resource unavailability.
      *
      * **Details**
      *
@@ -7037,6 +7093,8 @@ export declare const sandbox: <A, E, R>(self: Effect<A, E, R>) => Effect<A, Caus
  * Use when an effect should run for its side effects while both success and
  * failure values are discarded.
  *
+ * **Details**
+ *
  * Use the `log` option to emit the full {@link Cause} when the effect fails,
  * and `message` to prepend a custom log message.
  *
@@ -7081,6 +7139,11 @@ export declare const ignore: <Arg extends Effect<any, any, any> | {
 /**
  * Ignores the effect's failure cause, including defects and interruptions.
  *
+ * **When to use**
+ *
+ * Use when a best-effort effect should never fail, even from defects or
+ * interruption, and optional cause logging is enough.
+ *
  * **Details**
  *
  * Use the `log` option to emit the full {@link Cause} when the effect fails,
@@ -7368,9 +7431,9 @@ export declare const orElseSucceed: {
  *
  * **When to use**
  *
- * Use when you have prioritized fallback strategies, such as
- * attempting multiple APIs, reading configuration from several sources, or
- * trying alternative resource locations in order.
+ * Use when you have prioritized fallback `Effect`s, such as attempting
+ * multiple APIs, reading configuration from several sources, or trying
+ * alternative resource locations in order.
  *
  * **Details**
  *
@@ -7413,9 +7476,8 @@ export declare const firstSuccessOf: <Eff extends Effect<any, any, any>>(effects
  *
  * **When to use**
  *
- * Use when exceeding the time limit should be represented as a typed
- * failure. Use `timeoutOption` when a timeout should become `Option.none`, and
- * `timeoutOrElse` when you want to run a fallback effect.
+ * Use when you need a timeout of an `Effect` to be represented as a typed
+ * failure.
  *
  * **Details**
  *
@@ -7472,9 +7534,8 @@ export declare const timeout: {
      *
      * **When to use**
      *
-     * Use when exceeding the time limit should be represented as a typed
-     * failure. Use `timeoutOption` when a timeout should become `Option.none`, and
-     * `timeoutOrElse` when you want to run a fallback effect.
+     * Use when you need a timeout of an `Effect` to be represented as a typed
+     * failure.
      *
      * **Details**
      *
@@ -7531,9 +7592,8 @@ export declare const timeout: {
      *
      * **When to use**
      *
-     * Use when exceeding the time limit should be represented as a typed
-     * failure. Use `timeoutOption` when a timeout should become `Option.none`, and
-     * `timeoutOrElse` when you want to run a fallback effect.
+     * Use when you need a timeout of an `Effect` to be represented as a typed
+     * failure.
      *
      * **Details**
      *
@@ -7591,9 +7651,7 @@ export declare const timeout: {
  *
  * **When to use**
  *
- * Use when a timeout should be handled as absence. Use
- * `timeout` when a timeout should fail the effect, and `timeoutOrElse` when
- * you want to run a fallback effect.
+ * Use when a timeout of an `Effect` should be handled as `Option.none`.
  *
  * **Details**
  *
@@ -7643,9 +7701,7 @@ export declare const timeoutOption: {
      *
      * **When to use**
      *
-     * Use when a timeout should be handled as absence. Use
-     * `timeout` when a timeout should fail the effect, and `timeoutOrElse` when
-     * you want to run a fallback effect.
+     * Use when a timeout of an `Effect` should be handled as `Option.none`.
      *
      * **Details**
      *
@@ -7695,9 +7751,7 @@ export declare const timeoutOption: {
      *
      * **When to use**
      *
-     * Use when a timeout should be handled as absence. Use
-     * `timeout` when a timeout should fail the effect, and `timeoutOrElse` when
-     * you want to run a fallback effect.
+     * Use when a timeout of an `Effect` should be handled as `Option.none`.
      *
      * **Details**
      *
@@ -7747,9 +7801,7 @@ export declare const timeoutOption: {
  *
  * **When to use**
  *
- * Use when a timeout should switch to a fallback effect. Use
- * `timeout` when a timeout should fail the effect, and `timeoutOption` when a
- * timeout should become `Option.none`.
+ * Use when a timeout of an `Effect` should switch to a fallback effect.
  *
  * **Details**
  *
@@ -7801,9 +7853,7 @@ export declare const timeoutOrElse: {
      *
      * **When to use**
      *
-     * Use when a timeout should switch to a fallback effect. Use
-     * `timeout` when a timeout should fail the effect, and `timeoutOption` when a
-     * timeout should become `Option.none`.
+     * Use when a timeout of an `Effect` should switch to a fallback effect.
      *
      * **Details**
      *
@@ -7858,9 +7908,7 @@ export declare const timeoutOrElse: {
      *
      * **When to use**
      *
-     * Use when a timeout should switch to a fallback effect. Use
-     * `timeout` when a timeout should fail the effect, and `timeoutOption` when a
-     * timeout should become `Option.none`.
+     * Use when a timeout of an `Effect` should switch to a fallback effect.
      *
      * **Details**
      *
@@ -8207,6 +8255,11 @@ export declare const race: {
  * Races two effects and returns the result of the first one to complete, whether
  * it succeeds or fails.
  *
+ * **When to use**
+ *
+ * Use when any completion, including failure, should decide the race and
+ * interrupt the losing effect.
+ *
  * **Details**
  *
  * The losing effect is interrupted, and `onWinner` can observe the winning fiber.
@@ -8239,6 +8292,11 @@ export declare const raceFirst: {
      * Races two effects and returns the result of the first one to complete, whether
      * it succeeds or fails.
      *
+     * **When to use**
+     *
+     * Use when any completion, including failure, should decide the race and
+     * interrupt the losing effect.
+     *
      * **Details**
      *
      * The losing effect is interrupted, and `onWinner` can observe the winning fiber.
@@ -8277,6 +8335,11 @@ export declare const raceFirst: {
      * Races two effects and returns the result of the first one to complete, whether
      * it succeeds or fails.
      *
+     * **When to use**
+     *
+     * Use when any completion, including failure, should decide the race and
+     * interrupt the losing effect.
+     *
      * **Details**
      *
      * The losing effect is interrupted, and `onWinner` can observe the winning fiber.
@@ -8476,8 +8539,8 @@ export declare const filter: {
  *
  * **When to use**
  *
- * Use to keep only iterable elements accepted by a `Filter` and collect each
- * filter success value.
+ * Use when you need to filter an iterable with a `Filter` inside an `Effect`,
+ * collecting each filter success value.
  *
  * **Details**
  *
@@ -8496,8 +8559,8 @@ export declare const filterMap: {
      *
      * **When to use**
      *
-     * Use to keep only iterable elements accepted by a `Filter` and collect each
-     * filter success value.
+     * Use when you need to filter an iterable with a `Filter` inside an `Effect`,
+     * collecting each filter success value.
      *
      * **Details**
      *
@@ -8516,8 +8579,8 @@ export declare const filterMap: {
      *
      * **When to use**
      *
-     * Use to keep only iterable elements accepted by a `Filter` and collect each
-     * filter success value.
+     * Use when you need to filter an iterable with a `Filter` inside an `Effect`,
+     * collecting each filter success value.
      *
      * **Details**
      *
@@ -8537,8 +8600,8 @@ export declare const filterMap: {
  *
  * **When to use**
  *
- * Use when filtering each iterable element requires effects and accepted
- * elements should be transformed into successful output values.
+ * Use when you need to filter each iterable element effectfully and transform
+ * accepted elements into successful output values.
  *
  * **Details**
  *
@@ -8562,8 +8625,8 @@ export declare const filterMapEffect: {
      *
      * **When to use**
      *
-     * Use when filtering each iterable element requires effects and accepted
-     * elements should be transformed into successful output values.
+     * Use when you need to filter each iterable element effectfully and transform
+     * accepted elements into successful output values.
      *
      * **Details**
      *
@@ -8589,8 +8652,8 @@ export declare const filterMapEffect: {
      *
      * **When to use**
      *
-     * Use when filtering each iterable element requires effects and accepted
-     * elements should be transformed into successful output values.
+     * Use when you need to filter each iterable element effectfully and transform
+     * accepted elements into successful output values.
      *
      * **Details**
      *
@@ -8615,6 +8678,11 @@ export declare const filterMapEffect: {
 /**
  * Filters an effect, providing an alternative effect if the predicate fails.
  *
+ * **When to use**
+ *
+ * Use when a successful value that fails a predicate should continue with an
+ * effectful fallback instead of failing the effect.
+ *
  * **Details**
  *
  * This function applies a predicate to the result of an effect. If the
@@ -8647,6 +8715,11 @@ export declare const filterOrElse: {
     /**
      * Filters an effect, providing an alternative effect if the predicate fails.
      *
+     * **When to use**
+     *
+     * Use when a successful value that fails a predicate should continue with an
+     * effectful fallback instead of failing the effect.
+     *
      * **Details**
      *
      * This function applies a predicate to the result of an effect. If the
@@ -8679,6 +8752,11 @@ export declare const filterOrElse: {
     /**
      * Filters an effect, providing an alternative effect if the predicate fails.
      *
+     * **When to use**
+     *
+     * Use when a successful value that fails a predicate should continue with an
+     * effectful fallback instead of failing the effect.
+     *
      * **Details**
      *
      * This function applies a predicate to the result of an effect. If the
@@ -8711,6 +8789,11 @@ export declare const filterOrElse: {
     /**
      * Filters an effect, providing an alternative effect if the predicate fails.
      *
+     * **When to use**
+     *
+     * Use when a successful value that fails a predicate should continue with an
+     * effectful fallback instead of failing the effect.
+     *
      * **Details**
      *
      * This function applies a predicate to the result of an effect. If the
@@ -8743,6 +8826,11 @@ export declare const filterOrElse: {
     /**
      * Filters an effect, providing an alternative effect if the predicate fails.
      *
+     * **When to use**
+     *
+     * Use when a successful value that fails a predicate should continue with an
+     * effectful fallback instead of failing the effect.
+     *
      * **Details**
      *
      * This function applies a predicate to the result of an effect. If the
@@ -9229,8 +9317,8 @@ export declare const filterMapOrFail: {
  *
  * **When to use**
  *
- * Use when an effectful check decides whether to run another effect while
- * representing the skipped case explicitly.
+ * Use when you need an effectful check to decide whether another effect should
+ * run while representing the skipped case explicitly.
  *
  * **Details**
  *
@@ -9266,8 +9354,8 @@ export declare const when: {
      *
      * **When to use**
      *
-     * Use when an effectful check decides whether to run another effect while
-     * representing the skipped case explicitly.
+     * Use when you need an effectful check to decide whether another effect should
+     * run while representing the skipped case explicitly.
      *
      * **Details**
      *
@@ -9303,8 +9391,8 @@ export declare const when: {
      *
      * **When to use**
      *
-     * Use when an effectful check decides whether to run another effect while
-     * representing the skipped case explicitly.
+     * Use when you need an effectful check to decide whether another effect should
+     * run while representing the skipped case explicitly.
      *
      * **Details**
      *
@@ -9341,8 +9429,8 @@ export declare const when: {
  *
  * **When to use**
  *
- * Use when this is useful for structuring your code to respond differently to success or
- * failure without triggering side effects.
+ * Use when you need to fold an `Effect` into a value by handling success and
+ * failure differently without triggering side effects.
  *
  * **Details**
  *
@@ -9394,8 +9482,8 @@ export declare const match: {
      *
      * **When to use**
      *
-     * Use when this is useful for structuring your code to respond differently to success or
-     * failure without triggering side effects.
+     * Use when you need to fold an `Effect` into a value by handling success and
+     * failure differently without triggering side effects.
      *
      * **Details**
      *
@@ -9450,8 +9538,8 @@ export declare const match: {
      *
      * **When to use**
      *
-     * Use when this is useful for structuring your code to respond differently to success or
-     * failure without triggering side effects.
+     * Use when you need to fold an `Effect` into a value by handling success and
+     * failure differently without triggering side effects.
      *
      * **Details**
      *
@@ -9507,9 +9595,8 @@ export declare const match: {
  *
  * **When to use**
  *
- * Use when you need to handle both success and failure cases and want
- * optimal performance for resolved effects. This is particularly useful in
- * scenarios where you frequently work with already computed values.
+ * Use when you need to handle both success and failure cases of an
+ * already-resolved `Effect` with optimized handling.
  *
  * **Details**
  *
@@ -9544,9 +9631,8 @@ export declare const matchEager: {
      *
      * **When to use**
      *
-     * Use when you need to handle both success and failure cases and want
-     * optimal performance for resolved effects. This is particularly useful in
-     * scenarios where you frequently work with already computed values.
+     * Use when you need to handle both success and failure cases of an
+     * already-resolved `Effect` with optimized handling.
      *
      * **Details**
      *
@@ -9584,9 +9670,8 @@ export declare const matchEager: {
      *
      * **When to use**
      *
-     * Use when you need to handle both success and failure cases and want
-     * optimal performance for resolved effects. This is particularly useful in
-     * scenarios where you frequently work with already computed values.
+     * Use when you need to handle both success and failure cases of an
+     * already-resolved `Effect` with optimized handling.
      *
      * **Details**
      *
@@ -9624,9 +9709,8 @@ export declare const matchEager: {
  *
  * **When to use**
  *
- * Use when this is useful for differentiating between different types of errors, such as
- * regular failures, defects, or interruptions. You can provide specific
- * handling logic for each failure type based on the cause.
+ * Use when you need to fold an `Effect` while the failure handler inspects the
+ * full `Cause`.
  *
  * **Details**
  *
@@ -9661,9 +9745,8 @@ export declare const matchCause: {
      *
      * **When to use**
      *
-     * Use when this is useful for differentiating between different types of errors, such as
-     * regular failures, defects, or interruptions. You can provide specific
-     * handling logic for each failure type based on the cause.
+     * Use when you need to fold an `Effect` while the failure handler inspects the
+     * full `Cause`.
      *
      * **Details**
      *
@@ -9701,9 +9784,8 @@ export declare const matchCause: {
      *
      * **When to use**
      *
-     * Use when this is useful for differentiating between different types of errors, such as
-     * regular failures, defects, or interruptions. You can provide specific
-     * handling logic for each failure type based on the cause.
+     * Use when you need to fold an `Effect` while the failure handler inspects the
+     * full `Cause`.
      *
      * **Details**
      *
@@ -9742,9 +9824,8 @@ export declare const matchCause: {
  *
  * **When to use**
  *
- * Use when this is useful when you have effects that are likely to be already resolved
- * and you want to avoid the overhead of the effect pipeline. For pending effects,
- * it automatically falls back to the regular `matchCause` behavior.
+ * Use when you expect an `Effect` to already be resolved and want to match the
+ * `Cause` without regular effect pipeline overhead.
  *
  * **Details**
  *
@@ -9772,9 +9853,8 @@ export declare const matchCauseEager: {
      *
      * **When to use**
      *
-     * Use when this is useful when you have effects that are likely to be already resolved
-     * and you want to avoid the overhead of the effect pipeline. For pending effects,
-     * it automatically falls back to the regular `matchCause` behavior.
+     * Use when you expect an `Effect` to already be resolved and want to match the
+     * `Cause` without regular effect pipeline overhead.
      *
      * **Details**
      *
@@ -9805,9 +9885,8 @@ export declare const matchCauseEager: {
      *
      * **When to use**
      *
-     * Use when this is useful when you have effects that are likely to be already resolved
-     * and you want to avoid the overhead of the effect pipeline. For pending effects,
-     * it automatically falls back to the regular `matchCause` behavior.
+     * Use when you expect an `Effect` to already be resolved and want to match the
+     * `Cause` without regular effect pipeline overhead.
      *
      * **Details**
      *
@@ -9839,9 +9918,8 @@ export declare const matchCauseEager: {
  *
  * **When to use**
  *
- * Use when success and cause-aware failure handlers return effects and the
- * input may already be resolved, so the selected handler can run immediately
- * while unresolved inputs keep normal effectful matching behavior.
+ * Use when you need effectful success and cause-aware failure handlers for
+ * `Effect` inputs that may already be resolved.
  *
  * **Details**
  *
@@ -9861,9 +9939,8 @@ export declare const matchCauseEffectEager: {
      *
      * **When to use**
      *
-     * Use when success and cause-aware failure handlers return effects and the
-     * input may already be resolved, so the selected handler can run immediately
-     * while unresolved inputs keep normal effectful matching behavior.
+     * Use when you need effectful success and cause-aware failure handlers for
+     * `Effect` inputs that may already be resolved.
      *
      * **Details**
      *
@@ -9886,9 +9963,8 @@ export declare const matchCauseEffectEager: {
      *
      * **When to use**
      *
-     * Use when success and cause-aware failure handlers return effects and the
-     * input may already be resolved, so the selected handler can run immediately
-     * while unresolved inputs keep normal effectful matching behavior.
+     * Use when you need effectful success and cause-aware failure handlers for
+     * `Effect` inputs that may already be resolved.
      *
      * **Details**
      *
@@ -9912,8 +9988,8 @@ export declare const matchCauseEffectEager: {
  *
  * **When to use**
  *
- * Use when both success and failure handling must return effects and the
- * failure branch needs the full `Cause`.
+ * Use when you need to fold an `Effect` with effectful success handlers and
+ * `Cause`-aware failure handlers.
  *
  * **Details**
  *
@@ -9972,8 +10048,8 @@ export declare const matchCauseEffect: {
      *
      * **When to use**
      *
-     * Use when both success and failure handling must return effects and the
-     * failure branch needs the full `Cause`.
+     * Use when you need to fold an `Effect` with effectful success handlers and
+     * `Cause`-aware failure handlers.
      *
      * **Details**
      *
@@ -10035,8 +10111,8 @@ export declare const matchCauseEffect: {
      *
      * **When to use**
      *
-     * Use when both success and failure handling must return effects and the
-     * failure branch needs the full `Cause`.
+     * Use when you need to fold an `Effect` with effectful success handlers and
+     * `Cause`-aware failure handlers.
      *
      * **Details**
      *
@@ -10099,7 +10175,8 @@ export declare const matchCauseEffect: {
  *
  * **When to use**
  *
- * Use when the failure or success branch must run additional effects.
+ * Use when you need to handle an `Effect`'s failure or success with handlers
+ * that return effects.
  *
  * **Details**
  *
@@ -10159,7 +10236,8 @@ export declare const matchEffect: {
      *
      * **When to use**
      *
-     * Use when the failure or success branch must run additional effects.
+     * Use when you need to handle an `Effect`'s failure or success with handlers
+     * that return effects.
      *
      * **Details**
      *
@@ -10222,7 +10300,8 @@ export declare const matchEffect: {
      *
      * **When to use**
      *
-     * Use when the failure or success branch must run additional effects.
+     * Use when you need to handle an `Effect`'s failure or success with handlers
+     * that return effects.
      *
      * **Details**
      *
@@ -11424,6 +11503,11 @@ export declare const provideService: {
 /**
  * Provides one service to an effect using an effectful acquisition.
  *
+ * **When to use**
+ *
+ * Use when the service implementation must be created by an effect and its
+ * acquisition failure should remain in the returned effect.
+ *
  * **Details**
  *
  * `provideServiceEffect` runs the acquisition effect to produce the service
@@ -11478,6 +11562,11 @@ export declare const provideServiceEffect: {
     /**
      * Provides one service to an effect using an effectful acquisition.
      *
+     * **When to use**
+     *
+     * Use when the service implementation must be created by an effect and its
+     * acquisition failure should remain in the returned effect.
+     *
      * **Details**
      *
      * `provideServiceEffect` runs the acquisition effect to produce the service
@@ -11532,6 +11621,11 @@ export declare const provideServiceEffect: {
     /**
      * Provides one service to an effect using an effectful acquisition.
      *
+     * **When to use**
+     *
+     * Use when the service implementation must be created by an effect and its
+     * acquisition failure should remain in the returned effect.
+     *
      * **Details**
      *
      * `provideServiceEffect` runs the acquisition effect to produce the service
@@ -11760,6 +11854,11 @@ export declare const scoped: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Ex
 /**
  * Creates a scoped effect by providing access to the scope.
  *
+ * **When to use**
+ *
+ * Use when resource acquisition needs direct access to the scope being created,
+ * for example to register finalizers manually.
+ *
  * **Example** (Working with an explicit scope)
  *
  * ```ts
@@ -11866,8 +11965,8 @@ export declare const acquireRelease: <A, E, R, R2>(acquire: Effect<A, E, R>, rel
  *
  * **When to use**
  *
- * Use with JavaScript `Disposable` or `AsyncDisposable` resources that should
- * be closed with the surrounding scope.
+ * Use when you work with JavaScript `Disposable` or `AsyncDisposable` resources
+ * that should be closed with the surrounding scope.
  *
  * **Details**
  *
@@ -12626,10 +12725,8 @@ export declare const onExitFilter: {
  *
  * **When to use**
  *
- * Use when you use this function when you have an expensive or time-consuming operation that
- * you want to avoid repeating. The first evaluation will compute the result,
- * and all following evaluations will immediately return the cached value,
- * improving performance and reducing unnecessary work.
+ * Use when you need an expensive or time-consuming operation to be evaluated
+ * once and reused by later callers.
  *
  * **Details**
  *
@@ -12690,14 +12787,8 @@ export declare const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A
  *
  * **When to use**
  *
- * Use when you use this function when you have an effect that involves costly operations or
- * computations, and you want to avoid repeating them within a short time frame.
- *
- * It's ideal for scenarios where the result of an effect doesn't change
- * frequently and can be reused for a specified duration.
- *
- * By caching the result, you can improve efficiency and reduce unnecessary
- * computations, especially in performance-critical applications.
+ * Use when you need a costly effect result to be reused for a bounded duration
+ * before being recomputed.
  *
  * **Details**
  *
@@ -12757,14 +12848,8 @@ export declare const cachedWithTTL: {
      *
      * **When to use**
      *
-     * Use when you use this function when you have an effect that involves costly operations or
-     * computations, and you want to avoid repeating them within a short time frame.
-     *
-     * It's ideal for scenarios where the result of an effect doesn't change
-     * frequently and can be reused for a specified duration.
-     *
-     * By caching the result, you can improve efficiency and reduce unnecessary
-     * computations, especially in performance-critical applications.
+     * Use when you need a costly effect result to be reused for a bounded duration
+     * before being recomputed.
      *
      * **Details**
      *
@@ -12824,14 +12909,8 @@ export declare const cachedWithTTL: {
      *
      * **When to use**
      *
-     * Use when you use this function when you have an effect that involves costly operations or
-     * computations, and you want to avoid repeating them within a short time frame.
-     *
-     * It's ideal for scenarios where the result of an effect doesn't change
-     * frequently and can be reused for a specified duration.
-     *
-     * By caching the result, you can improve efficiency and reduce unnecessary
-     * computations, especially in performance-critical applications.
+     * Use when you need a costly effect result to be reused for a bounded duration
+     * before being recomputed.
      *
      * **Details**
      *
@@ -13324,7 +13403,7 @@ export declare namespace Repeat {
     /**
      * Computes the result type of `Effect.repeat` from the original effect and repeat options.
      *
-     * @category repetition / recursion
+     * @category repetition
      * @since 2.0.0
      */
     type Return<R, E, A, O extends Options<A>> = Effect<O extends {
@@ -13347,7 +13426,7 @@ export declare namespace Repeat {
     /**
      * Options that control whether and how an effect is repeated.
      *
-     * @category repetition / recursion
+     * @category repetition
      * @since 2.0.0
      */
     interface Options<A> {
@@ -13384,7 +13463,7 @@ export declare namespace Repeat {
  * })
  * ```
  *
- * @category repetition / recursion
+ * @category repetition
  * @since 2.0.0
  */
 export declare const forever: <Arg extends Effect<any, any, any> | {
@@ -13467,7 +13546,7 @@ export declare const forever: <Arg extends Effect<any, any, any> | {
  * @see {@link retry} for failure-based repetition
  * @see {@link repeatOrElse} for fallback handling when repetition fails
  *
- * @category repetition / recursion
+ * @category repetition
  * @since 2.0.0
  */
 export declare const repeat: {
@@ -13544,7 +13623,7 @@ export declare const repeat: {
      * @see {@link retry} for failure-based repetition
      * @see {@link repeatOrElse} for fallback handling when repetition fails
      *
-     * @category repetition / recursion
+     * @category repetition
      * @since 2.0.0
      */
     <O extends Repeat.Options<A>, A>(options: O): <E, R>(self: Effect<A, E, R>) => Repeat.Return<R, E, A, O>;
@@ -13621,7 +13700,7 @@ export declare const repeat: {
      * @see {@link retry} for failure-based repetition
      * @see {@link repeatOrElse} for fallback handling when repetition fails
      *
-     * @category repetition / recursion
+     * @category repetition
      * @since 2.0.0
      */
     <Output, Input, Error, Env>(schedule: Schedule<Output, NoInfer<Input>, Error, Env>): <E, R>(self: Effect<Input, E, R>) => Effect<Output, E | Error, R | Env>;
@@ -13698,7 +13777,7 @@ export declare const repeat: {
      * @see {@link retry} for failure-based repetition
      * @see {@link repeatOrElse} for fallback handling when repetition fails
      *
-     * @category repetition / recursion
+     * @category repetition
      * @since 2.0.0
      */
     <Output, Input, Error, Env>(builder: ($: <O, E, R>(_: Schedule<O, NoInfer<Input>, E, R>) => Schedule<O, Input, E, R>) => Schedule<Output, NoInfer<Input>, Error, Env>): <E, R>(self: Effect<Input, E, R>) => Effect<Output, E | Error, R | Env>;
@@ -13775,7 +13854,7 @@ export declare const repeat: {
      * @see {@link retry} for failure-based repetition
      * @see {@link repeatOrElse} for fallback handling when repetition fails
      *
-     * @category repetition / recursion
+     * @category repetition
      * @since 2.0.0
      */
     <A, E, R, O extends Repeat.Options<A>>(self: Effect<A, E, R>, options: O): Repeat.Return<R, E, A, O>;
@@ -13852,7 +13931,7 @@ export declare const repeat: {
      * @see {@link retry} for failure-based repetition
      * @see {@link repeatOrElse} for fallback handling when repetition fails
      *
-     * @category repetition / recursion
+     * @category repetition
      * @since 2.0.0
      */
     <Input, E, R, Output, Error, Env>(self: Effect<Input, E, R>, schedule: Schedule<Output, NoInfer<Input>, Error, Env>): Effect<Output, E | Error, R | Env>;
@@ -13929,7 +14008,7 @@ export declare const repeat: {
      * @see {@link retry} for failure-based repetition
      * @see {@link repeatOrElse} for fallback handling when repetition fails
      *
-     * @category repetition / recursion
+     * @category repetition
      * @since 2.0.0
      */
     <Input, E, R, Output, Error, Env>(self: Effect<Input, E, R>, builder: ($: <O, E, R>(_: Schedule<O, NoInfer<Input>, E, R>) => Schedule<O, Input, E, R>) => Schedule<Output, NoInfer<Input>, Error, Env>): Effect<Output, E | Error, R | Env>;
@@ -13938,6 +14017,11 @@ export declare const repeat: {
  * Repeats an effect according to a schedule and runs a fallback effect if
  * repetition fails before the schedule completes.
  *
+ * **When to use**
+ *
+ * Use when successful repetitions should follow a schedule, but failures from
+ * the repeated effect or schedule need an effectful fallback.
+ *
  * **Details**
  *
  * If the repeated effect or schedule step fails, `orElse` receives the failure
@@ -13973,7 +14057,7 @@ export declare const repeat: {
  * )
  * ```
  *
- * @category repetition / recursion
+ * @category repetition
  * @since 2.0.0
  */
 export declare const repeatOrElse: {
@@ -13981,6 +14065,11 @@ export declare const repeatOrElse: {
      * Repeats an effect according to a schedule and runs a fallback effect if
      * repetition fails before the schedule completes.
      *
+     * **When to use**
+     *
+     * Use when successful repetitions should follow a schedule, but failures from
+     * the repeated effect or schedule need an effectful fallback.
+     *
      * **Details**
      *
      * If the repeated effect or schedule step fails, `orElse` receives the failure
@@ -14016,7 +14105,7 @@ export declare const repeatOrElse: {
      * )
      * ```
      *
-     * @category repetition / recursion
+     * @category repetition
      * @since 2.0.0
      */
     <R2, A, B, E, E2, E3, R3>(schedule: Schedule<B, A, E2, R2>, orElse: (error: E | E2, option: Option<B>) => Effect<B, E3, R3>): <R>(self: Effect<A, E, R>) => Effect<B, E3, R | R2 | R3>;
@@ -14024,6 +14113,11 @@ export declare const repeatOrElse: {
      * Repeats an effect according to a schedule and runs a fallback effect if
      * repetition fails before the schedule completes.
      *
+     * **When to use**
+     *
+     * Use when successful repetitions should follow a schedule, but failures from
+     * the repeated effect or schedule need an effectful fallback.
+     *
      * **Details**
      *
      * If the repeated effect or schedule step fails, `orElse` receives the failure
@@ -14059,7 +14153,7 @@ export declare const repeatOrElse: {
      * )
      * ```
      *
-     * @category repetition / recursion
+     * @category repetition
      * @since 2.0.0
      */
     <A, E, R, R2, B, E2, E3, R3>(self: Effect<A, E, R>, schedule: Schedule<B, A, E2, R2>, orElse: (error: E | E2, option: Option<B>) => Effect<B, E3, R3>): Effect<B, E3, R | R2 | R3>;
@@ -14069,9 +14163,8 @@ export declare const repeatOrElse: {
  *
  * **When to use**
  *
- * Use to create an array containing the same effect multiple times when you
- * want to pass those effects to another collector or control execution
- * separately.
+ * Use when you need an array of identical effect values without running them
+ * yet.
  *
  * **Details**
  *
@@ -14089,9 +14182,8 @@ export declare const replicate: {
      *
      * **When to use**
      *
-     * Use to create an array containing the same effect multiple times when you
-     * want to pass those effects to another collector or control execution
-     * separately.
+     * Use when you need an array of identical effect values without running them
+     * yet.
      *
      * **Details**
      *
@@ -14109,9 +14201,8 @@ export declare const replicate: {
      *
      * **When to use**
      *
-     * Use to create an array containing the same effect multiple times when you
-     * want to pass those effects to another collector or control execution
-     * separately.
+     * Use when you need an array of identical effect values without running them
+     * yet.
      *
      * **Details**
      *
@@ -14128,6 +14219,11 @@ export declare const replicate: {
 /**
  * Performs this effect `n` times and collects results with `Effect.all` semantics.
  *
+ * **When to use**
+ *
+ * Use when you want to run the repeated effects immediately, with optional
+ * concurrency control or result discarding.
+ *
  * **Details**
  *
  * Use `concurrency` to control parallelism and `discard: true` to ignore results.
@@ -14150,6 +14246,11 @@ export declare const replicateEffect: {
     /**
      * Performs this effect `n` times and collects results with `Effect.all` semantics.
      *
+     * **When to use**
+     *
+     * Use when you want to run the repeated effects immediately, with optional
+     * concurrency control or result discarding.
+     *
      * **Details**
      *
      * Use `concurrency` to control parallelism and `discard: true` to ignore results.
@@ -14175,6 +14276,11 @@ export declare const replicateEffect: {
     /**
      * Performs this effect `n` times and collects results with `Effect.all` semantics.
      *
+     * **When to use**
+     *
+     * Use when you want to run the repeated effects immediately, with optional
+     * concurrency control or result discarding.
+     *
      * **Details**
      *
      * Use `concurrency` to control parallelism and `discard: true` to ignore results.
@@ -14200,6 +14306,11 @@ export declare const replicateEffect: {
     /**
      * Performs this effect `n` times and collects results with `Effect.all` semantics.
      *
+     * **When to use**
+     *
+     * Use when you want to run the repeated effects immediately, with optional
+     * concurrency control or result discarding.
+     *
      * **Details**
      *
      * Use `concurrency` to control parallelism and `discard: true` to ignore results.
@@ -14225,6 +14336,11 @@ export declare const replicateEffect: {
     /**
      * Performs this effect `n` times and collects results with `Effect.all` semantics.
      *
+     * **When to use**
+     *
+     * Use when you want to run the repeated effects immediately, with optional
+     * concurrency control or result discarding.
+     *
      * **Details**
      *
      * Use `concurrency` to control parallelism and `discard: true` to ignore results.
@@ -14292,7 +14408,7 @@ export declare const replicateEffect: {
  * @see {@link scheduleFrom} for a variant that allows the schedule's decision
  * to depend on the result of this effect.
  *
- * @category repetition / recursion
+ * @category repetition
  * @since 2.0.0
  */
 export declare const schedule: {
@@ -14340,7 +14456,7 @@ export declare const schedule: {
      * @see {@link scheduleFrom} for a variant that allows the schedule's decision
      * to depend on the result of this effect.
      *
-     * @category repetition / recursion
+     * @category repetition
      * @since 2.0.0
      */
     <Output, Error, Env>(schedule: Schedule<Output, unknown, Error, Env>): <A, E, R>(self: Effect<A, E, R>) => Effect<Output, E, R | Env>;
@@ -14388,7 +14504,7 @@ export declare const schedule: {
      * @see {@link scheduleFrom} for a variant that allows the schedule's decision
      * to depend on the result of this effect.
      *
-     * @category repetition / recursion
+     * @category repetition
      * @since 2.0.0
      */
     <A, E, R, Output, Error, Env>(self: Effect<A, E, R>, schedule: Schedule<Output, unknown, Error, Env>): Effect<Output, E, R | Env>;
@@ -14427,7 +14543,7 @@ export declare const schedule: {
  * // Returns the schedule count
  * ```
  *
- * @category repetition / recursion
+ * @category repetition
  * @since 2.0.0
  */
 export declare const scheduleFrom: {
@@ -14465,7 +14581,7 @@ export declare const scheduleFrom: {
      * // Returns the schedule count
      * ```
      *
-     * @category repetition / recursion
+     * @category repetition
      * @since 2.0.0
      */
     <Input, Output, Error, Env>(initial: Input, schedule: Schedule<Output, Input, Error, Env>): <E, R>(self: Effect<Input, E, R>) => Effect<Output, E, R | Env>;
@@ -14503,7 +14619,7 @@ export declare const scheduleFrom: {
      * // Returns the schedule count
      * ```
      *
-     * @category repetition / recursion
+     * @category repetition
      * @since 2.0.0
      */
     <Input, E, R, Output, Error, Env>(self: Effect<Input, E, R>, initial: Input, schedule: Schedule<Output, Input, Error, Env>): Effect<Output, E, R | Env>;
@@ -15568,9 +15684,7 @@ export declare const withParentSpan: {
  *
  * **When to use**
  *
- * Use to execute a typed `Request` through a `RequestResolver` when you want
- * concurrent requests made with the same resolver to be collected and completed
- * by resolver logic.
+ * Use when you need resolver-driven batching for a typed `Request`.
  *
  * **Example** (Executing a request through a resolver)
  *
@@ -15608,9 +15722,7 @@ export declare const request: {
      *
      * **When to use**
      *
-     * Use to execute a typed `Request` through a `RequestResolver` when you want
-     * concurrent requests made with the same resolver to be collected and completed
-     * by resolver logic.
+     * Use when you need resolver-driven batching for a typed `Request`.
      *
      * **Example** (Executing a request through a resolver)
      *
@@ -15648,9 +15760,7 @@ export declare const request: {
      *
      * **When to use**
      *
-     * Use to execute a typed `Request` through a `RequestResolver` when you want
-     * concurrent requests made with the same resolver to be collected and completed
-     * by resolver logic.
+     * Use when you need resolver-driven batching for a typed `Request`.
      *
      * **Example** (Executing a request through a resolver)
      *
@@ -16029,7 +16139,7 @@ export declare const fiberId: Effect<number>;
  * @see {@link runPromise} for promise-based running with these options
  * @see {@link runPromiseExit} for promise-based running that returns an `Exit`
  *
- * @category running effects
+ * @category running
  * @since 4.0.0
  */
 export interface RunOptions {
@@ -16044,9 +16154,7 @@ export interface RunOptions {
  *
  * **When to use**
  *
- * Use when an effect should start in the background and return a fiber that can
- * be observed or interrupted. Prefer this when you do not need a `Promise` or
- * synchronous result.
+ * Use when you need to start an effect in the background and receive a fiber.
  *
  * **Example** (Running an effect in the background)
  *
@@ -16069,13 +16177,18 @@ export interface RunOptions {
  * }, 500)
  * ```
  *
- * @category running effects
+ * @category running
  * @since 2.0.0
  */
 export declare const runFork: <A, E>(effect: Effect<A, E, never>, options?: RunOptions | undefined) => Fiber<A, E>;
 /**
  * Runs an effect in the background with the provided services.
  *
+ * **When to use**
+ *
+ * Use when an effect still requires services, you already have a `Context`, and
+ * you want a background fiber.
+ *
  * **Example** (Running with services in the background)
  *
  * ```ts
@@ -16100,13 +16213,18 @@ export declare const runFork: <A, E>(effect: Effect<A, E, never>, options?: RunO
  * const fiber = Effect.runForkWith(services)(program)
  * ```
  *
- * @category running effects
+ * @category running
  * @since 4.0.0
  */
 export declare const runForkWith: <R>(context: Context.Context<R>) => <A, E>(effect: Effect<A, E, R>, options?: RunOptions | undefined) => Fiber<A, E>;
 /**
  * Forks an effect with the provided services, registers `onExit` as a fiber observer, and returns an interruptor.
  *
+ * **When to use**
+ *
+ * Use when embedding an effect into callback-style code with explicit services
+ * and a synchronous interruptor.
+ *
  * **Details**
  *
  * The returned interruptor calls `fiber.interruptUnsafe`, optionally with an interruptor id.
@@ -16144,7 +16262,7 @@ export declare const runForkWith: <R>(context: Context.Context<R>) => <A, E>(eff
  * interrupt()
  * ```
  *
- * @category running effects
+ * @category running
  * @since 4.0.0
  */
 export declare const runCallbackWith: <R>(context: Context.Context<R>) => <A, E>(effect: Effect<A, E, R>, options?: (RunOptions & {
@@ -16187,7 +16305,7 @@ export declare const runCallbackWith: <R>(context: Context.Context<R>) => <A, E>
  * // interrupt() to cancel the fiber if needed
  * ```
  *
- * @category running effects
+ * @category running
  * @since 2.0.0
  */
 export declare const runCallback: <A, E>(effect: Effect<A, E, never>, options?: (RunOptions & {
@@ -16226,13 +16344,18 @@ export declare const runCallback: <A, E>(effect: Effect<A, E, never>, options?:
  * ```
  *
  * @see {@link runPromiseExit} for a version that returns an `Exit` type instead of rejecting.
- * @category running effects
+ * @category running
  * @since 2.0.0
  */
 export declare const runPromise: <A, E>(effect: Effect<A, E>, options?: RunOptions | undefined) => Promise<A>;
 /**
  * Executes an effect as a Promise with the provided services.
  *
+ * **When to use**
+ *
+ * Use when you already have a `Context` and need Promise interop that rejects on
+ * effect failure.
+ *
  * **Example** (Running with services as a promise)
  *
  * ```ts
@@ -16256,7 +16379,7 @@ export declare const runPromise: <A, E>(effect: Effect<A, E>, options?: RunOptio
  * Effect.runPromiseWith(context)(program).then(console.log)
  * ```
  *
- * @category running effects
+ * @category running
  * @since 4.0.0
  */
 export declare const runPromiseWith: <R>(context: Context.Context<R>) => <A, E>(effect: Effect<A, E, R>, options?: RunOptions | undefined) => Promise<A>;
@@ -16271,10 +16394,9 @@ export declare const runPromiseWith: <R>(context: Context.Context<R>) => <A, E>(
  *
  * **Details**
  *
- * The `Exit` type represents the result of the effect:
- * - If the effect succeeds, the result is wrapped in a `Success`.
- * - If it fails, the failure information is provided as a `Failure` containing
- *   a `Cause` type.
+ * The `Exit` type represents the result of the effect. Successful effects are
+ * wrapped in `Success`, and failed effects are wrapped in `Failure` with a
+ * `Cause`.
  *
  * **Example** (Observing promise results as Exit)
  *
@@ -16306,13 +16428,18 @@ export declare const runPromiseWith: <R>(context: Context.Context<R>) => <A, E>(
  *
  * @see {@link runPromise} for a version that rejects on failure.
  *
- * @category running effects
+ * @category running
  * @since 2.0.0
  */
 export declare const runPromiseExit: <A, E>(effect: Effect<A, E>, options?: RunOptions | undefined) => Promise<Exit.Exit<A, E>>;
 /**
  * Runs an effect and returns a Promise of Exit with provided services.
  *
+ * **When to use**
+ *
+ * Use when you already have a `Context` and need Promise interop that preserves
+ * success and failure as an `Exit`.
+ *
  * **Example** (Running with services as an Exit promise)
  *
  * ```ts
@@ -16340,7 +16467,7 @@ export declare const runPromiseExit: <A, E>(effect: Effect<A, E>, options?: RunO
  * })
  * ```
  *
- * @category running effects
+ * @category running
  * @since 4.0.0
  */
 export declare const runPromiseExitWith: <R>(context: Context.Context<R>) => <A, E>(effect: Effect<A, E, R>, options?: RunOptions | undefined) => Promise<Exit.Exit<A, E>>;
@@ -16401,13 +16528,18 @@ export declare const runPromiseExitWith: <R>(context: Context.Context<R>) => <A,
  *
  * @see {@link runSyncExit} for a version that returns an `Exit` type instead of
  * throwing an error.
- * @category running effects
+ * @category running
  * @since 2.0.0
  */
 export declare const runSync: <A, E>(effect: Effect<A, E>) => A;
 /**
  * Executes an effect synchronously with provided services.
  *
+ * **When to use**
+ *
+ * Use when you already have a `Context`, the effect is known to complete
+ * synchronously, and failures should throw.
+ *
  * **Example** (Running synchronously with services)
  *
  * ```ts
@@ -16432,7 +16564,7 @@ export declare const runSync: <A, E>(effect: Effect<A, E>) => A;
  * console.log(result) // 5
  * ```
  *
- * @category running effects
+ * @category running
  * @since 4.0.0
  */
 export declare const runSyncWith: <R>(context: Context.Context<R>) => <A, E>(effect: Effect<A, E, R>) => A;
@@ -16447,10 +16579,9 @@ export declare const runSyncWith: <R>(context: Context.Context<R>) => <A, E>(eff
  *
  * **Details**
  *
- * The `Exit` type represents the result of the effect:
- * - If the effect succeeds, the result is wrapped in a `Success`.
- * - If it fails, the failure information is provided as a `Failure` containing
- *   a `Cause` type.
+ * The `Exit` type represents the result of the effect. Successful effects are
+ * wrapped in `Success`, and failed effects are wrapped in `Failure` with a
+ * `Cause`.
  *
  * If the effect contains asynchronous operations, `runSyncExit` will
  * return an `Failure` with a `Die` cause, indicating that the effect cannot be
@@ -16506,13 +16637,18 @@ export declare const runSyncWith: <R>(context: Context.Context<R>) => <A, E>(eff
  *
  * @see {@link runSync} for a version that throws on failure.
  *
- * @category running effects
+ * @category running
  * @since 2.0.0
  */
 export declare const runSyncExit: <A, E>(effect: Effect<A, E>) => Exit.Exit<A, E>;
 /**
  * Runs an effect synchronously with provided services, returning an Exit result safely.
  *
+ * **When to use**
+ *
+ * Use when you already have a `Context` and need a synchronous `Exit` instead of
+ * throwing on failure.
+ *
  * **Example** (Running synchronously with services as Exit)
  *
  * ```ts
@@ -16546,7 +16682,7 @@ export declare const runSyncExit: <A, E>(effect: Effect<A, E>) => Exit.Exit<A, E
  * // Success: 42
  * ```
  *
- * @category running effects
+ * @category running
  * @since 4.0.0
  */
 export declare const runSyncExitWith: <R>(context: Context.Context<R>) => <A, E>(effect: Effect<A, E, R>) => Exit.Exit<A, E>;
@@ -19002,13 +19138,10 @@ export declare class Transaction extends Transaction_base {
  * If called inside an active transaction, `tx` composes with the current transaction and reuses
  * its journal and retry state instead of creating a nested boundary.
  *
- * In Effect transactions are optimistic with retry, that means transactions are retried when:
- *
- * - the body of the transaction explicitely calls to `Effect.txRetry` and any of the
- *   accessed transactional values changes.
- *
- * - any of the accessed transactional values change during the execution of the transaction
- *   due to a different transaction committing before the current.
+ * Effect transactions are optimistic with retry. A transaction is retried when
+ * its body explicitly calls `Effect.txRetry` and any accessed transactional
+ * value changes, or when any accessed transactional value changes because a
+ * different transaction commits before the current one.
  *
  * The outermost `tx` call creates the transaction boundary and commits or rolls back the full
  * composed transaction.
@@ -19230,7 +19363,7 @@ export declare namespace Effectify {
     /**
      * Extracts the callback error type from a callback-based function type.
      *
-     * @category utils
+     * @category effectify
      * @since 4.0.0
      */
     type EffectifyError<T> = T extends {
@@ -19596,11 +19729,8 @@ export declare const satisfiesServicesType: <R>() => <A, E, R2 extends R>(effect
  *
  * **Details**
  *
- * Behavior:
- *
- * - For **Success effects**: Applies the mapping function immediately to the value
- * - For **Failure effects**: Returns the failure as-is without applying the mapping
- * - For **Pending effects**: Falls back to the regular `map` behavior
+ * Success effects apply the mapping function immediately. Failure effects pass
+ * through unchanged, and pending effects fall back to regular `map` behavior.
  *
  * **Example** (Mapping already completed effects)
  *
@@ -19630,11 +19760,8 @@ export declare const mapEager: {
      *
      * **Details**
      *
-     * Behavior:
-     *
-     * - For **Success effects**: Applies the mapping function immediately to the value
-     * - For **Failure effects**: Returns the failure as-is without applying the mapping
-     * - For **Pending effects**: Falls back to the regular `map` behavior
+     * Success effects apply the mapping function immediately. Failure effects pass
+     * through unchanged, and pending effects fall back to regular `map` behavior.
      *
      * **Example** (Mapping already completed effects)
      *
@@ -19664,11 +19791,8 @@ export declare const mapEager: {
      *
      * **Details**
      *
-     * Behavior:
-     *
-     * - For **Success effects**: Applies the mapping function immediately to the value
-     * - For **Failure effects**: Returns the failure as-is without applying the mapping
-     * - For **Pending effects**: Falls back to the regular `map` behavior
+     * Success effects apply the mapping function immediately. Failure effects pass
+     * through unchanged, and pending effects fall back to regular `map` behavior.
      *
      * **Example** (Mapping already completed effects)
      *
@@ -19700,11 +19824,9 @@ export declare const mapEager: {
  *
  * **Details**
  *
- * Behavior:
- *
- * - For **Success effects**: Returns the success as-is (no error to transform)
- * - For **Failure effects**: Applies the mapping function immediately to the error
- * - For **Pending effects**: Falls back to the regular `mapError` behavior
+ * Success effects pass through unchanged because there is no error to
+ * transform. Failure effects apply the mapping function immediately, and
+ * pending effects fall back to regular `mapError` behavior.
  *
  * **Example** (Mapping errors eagerly when possible)
  *
@@ -19738,11 +19860,9 @@ export declare const mapErrorEager: {
      *
      * **Details**
      *
-     * Behavior:
-     *
-     * - For **Success effects**: Returns the success as-is (no error to transform)
-     * - For **Failure effects**: Applies the mapping function immediately to the error
-     * - For **Pending effects**: Falls back to the regular `mapError` behavior
+     * Success effects pass through unchanged because there is no error to
+     * transform. Failure effects apply the mapping function immediately, and
+     * pending effects fall back to regular `mapError` behavior.
      *
      * **Example** (Mapping errors eagerly when possible)
      *
@@ -19776,11 +19896,9 @@ export declare const mapErrorEager: {
      *
      * **Details**
      *
-     * Behavior:
-     *
-     * - For **Success effects**: Returns the success as-is (no error to transform)
-     * - For **Failure effects**: Applies the mapping function immediately to the error
-     * - For **Pending effects**: Falls back to the regular `mapError` behavior
+     * Success effects pass through unchanged because there is no error to
+     * transform. Failure effects apply the mapping function immediately, and
+     * pending effects fall back to regular `mapError` behavior.
      *
      * **Example** (Mapping errors eagerly when possible)
      *
@@ -19814,11 +19932,9 @@ export declare const mapErrorEager: {
  *
  * **Details**
  *
- * Behavior:
- *
- * - For **Success effects**: Applies the `onSuccess` function immediately to the value
- * - For **Failure effects**: Applies the `onFailure` function immediately to the error
- * - For **Pending effects**: Falls back to the regular `mapBoth` behavior
+ * Success effects apply `onSuccess` immediately, and failure effects apply
+ * `onFailure` immediately. Pending effects fall back to regular `mapBoth`
+ * behavior.
  *
  * **Example** (Mapping both channels eagerly when possible)
  *
@@ -19853,11 +19969,9 @@ export declare const mapBothEager: {
      *
      * **Details**
      *
-     * Behavior:
-     *
-     * - For **Success effects**: Applies the `onSuccess` function immediately to the value
-     * - For **Failure effects**: Applies the `onFailure` function immediately to the error
-     * - For **Pending effects**: Falls back to the regular `mapBoth` behavior
+     * Success effects apply `onSuccess` immediately, and failure effects apply
+     * `onFailure` immediately. Pending effects fall back to regular `mapBoth`
+     * behavior.
      *
      * **Example** (Mapping both channels eagerly when possible)
      *
@@ -19895,11 +20009,9 @@ export declare const mapBothEager: {
      *
      * **Details**
      *
-     * Behavior:
-     *
-     * - For **Success effects**: Applies the `onSuccess` function immediately to the value
-     * - For **Failure effects**: Applies the `onFailure` function immediately to the error
-     * - For **Pending effects**: Falls back to the regular `mapBoth` behavior
+     * Success effects apply `onSuccess` immediately, and failure effects apply
+     * `onFailure` immediately. Pending effects fall back to regular `mapBoth`
+     * behavior.
      *
      * **Example** (Mapping both channels eagerly when possible)
      *
@@ -19938,11 +20050,9 @@ export declare const mapBothEager: {
  *
  * **Details**
  *
- * Behavior:
- *
- * - For **Success effects**: Applies the flatMap function immediately to the value
- * - For **Failure effects**: Returns the failure as-is without applying the flatMap
- * - For **Pending effects**: Falls back to the regular `flatMap` behavior
+ * Success effects apply the flatMap function immediately. Failure effects pass
+ * through unchanged, and pending effects fall back to regular `flatMap`
+ * behavior.
  *
  * **Example** (Flat mapping eagerly when possible)
  *
@@ -19975,11 +20085,9 @@ export declare const flatMapEager: {
      *
      * **Details**
      *
-     * Behavior:
-     *
-     * - For **Success effects**: Applies the flatMap function immediately to the value
-     * - For **Failure effects**: Returns the failure as-is without applying the flatMap
-     * - For **Pending effects**: Falls back to the regular `flatMap` behavior
+     * Success effects apply the flatMap function immediately. Failure effects pass
+     * through unchanged, and pending effects fall back to regular `flatMap`
+     * behavior.
      *
      * **Example** (Flat mapping eagerly when possible)
      *
@@ -20012,11 +20120,9 @@ export declare const flatMapEager: {
      *
      * **Details**
      *
-     * Behavior:
-     *
-     * - For **Success effects**: Applies the flatMap function immediately to the value
-     * - For **Failure effects**: Returns the failure as-is without applying the flatMap
-     * - For **Pending effects**: Falls back to the regular `flatMap` behavior
+     * Success effects apply the flatMap function immediately. Failure effects pass
+     * through unchanged, and pending effects fall back to regular `flatMap`
+     * behavior.
      *
      * **Example** (Flat mapping eagerly when possible)
      *
@@ -20050,11 +20156,9 @@ export declare const flatMapEager: {
  *
  * **Details**
  *
- * Behavior:
- *
- * - For **Success effects**: Returns the success as-is (no error to catch)
- * - For **Failure effects**: Applies the catch function immediately to the error
- * - For **Pending effects**: Falls back to the regular `catch` behavior
+ * Success effects pass through unchanged because there is no error to catch.
+ * Failure effects apply the catch function immediately, and pending effects
+ * fall back to regular `catch` behavior.
  *
  * **Example** (Catching failures eagerly when possible)
  *
@@ -20097,11 +20201,9 @@ export declare const catchEager: {
      *
      * **Details**
      *
-     * Behavior:
-     *
-     * - For **Success effects**: Returns the success as-is (no error to catch)
-     * - For **Failure effects**: Applies the catch function immediately to the error
-     * - For **Pending effects**: Falls back to the regular `catch` behavior
+     * Success effects pass through unchanged because there is no error to catch.
+     * Failure effects apply the catch function immediately, and pending effects
+     * fall back to regular `catch` behavior.
      *
      * **Example** (Catching failures eagerly when possible)
      *
@@ -20144,11 +20246,9 @@ export declare const catchEager: {
      *
      * **Details**
      *
-     * Behavior:
-     *
-     * - For **Success effects**: Returns the success as-is (no error to catch)
-     * - For **Failure effects**: Applies the catch function immediately to the error
-     * - For **Pending effects**: Falls back to the regular `catch` behavior
+     * Success effects pass through unchanged because there is no error to catch.
+     * Failure effects apply the catch function immediately, and pending effects
+     * fall back to regular `catch` behavior.
      *
      * **Example** (Catching failures eagerly when possible)
      *