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

package/src/Effect.ts

@@ -598,10 +598,8 @@ export const all: <
  *
  * **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.
@@ -629,10 +627,8 @@ export 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.
@@ -663,10 +659,8 @@ export 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.
@@ -1370,7 +1364,7 @@ export 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 const promise: <A>(
@@ -1439,7 +1433,7 @@ export const promise: <A>(
  * ```
  *
  * @see {@link promise} if the effectful computation is asynchronous and does not throw errors.
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export const tryPromise: <A, E = Cause.UnknownError>(
@@ -1453,8 +1447,8 @@ export const tryPromise: <A, E = Cause.UnknownError>(
  *
  * **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)
  *
@@ -1469,7 +1463,7 @@ export const tryPromise: <A, E = Cause.UnknownError>(
  * ```
  *
  * @see {@link fail} to create an effect that represents a failure.
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export const succeed: <A>(value: A) => Effect<A> = internal.succeed
@@ -1488,7 +1482,7 @@ export const succeed: <A>(value: A) => Effect<A> = internal.succeed
  * // Output: { _id: 'Option', _tag: 'None' }
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export const succeedNone: Effect<Option<never>> = internal.succeedNone
@@ -1507,7 +1501,7 @@ export const succeedNone: Effect<Option<never>> = internal.succeedNone
  * // Output: { _id: 'Option', _tag: 'Some', value: 42 }
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export const succeedSome: <A>(value: A) => Effect<Option<A>> = internal.succeedSome
@@ -1517,14 +1511,16 @@ export const succeedSome: <A>(value: A) => Effect<Option<A>> = internal.succeedS
  *
  * **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)
  *
@@ -1595,7 +1591,7 @@ export const succeedSome: <A>(value: A) => Effect<Option<A>> = internal.succeedS
  *   )
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export const suspend: <A, E, R>(
@@ -1607,7 +1603,8 @@ export const suspend: <A, E, R>(
  *
  * **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**
  *
@@ -1634,7 +1631,7 @@ export const suspend: <A, E, R>(
  * ```
  *
  * @see {@link try_ | try} for a version that can handle failures.
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export const sync: <A>(thunk: LazyArg<A>) => Effect<A> = internal.sync
@@ -1644,7 +1641,7 @@ export {
   /**
    * Returns an effect that succeeds with `void`.
    *
-   * @category creating effects
+   * @category constructors
    * @since 2.0.0
    */
   void_ as void
@@ -1655,7 +1652,7 @@ export {
   /**
    * Returns an effect that succeeds with `undefined`.
    *
-   * @category creating effects
+   * @category constructors
    * @since 4.0.0
    */
   undefined_ as undefined
@@ -1666,8 +1663,8 @@ export {
  *
  * **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**
  *
@@ -1693,7 +1690,7 @@ export {
  * const program = delay(1000)
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 4.0.0
  */
 export const callback: <A, E = never, R = never>(
@@ -1723,7 +1720,7 @@ export const callback: <A, E = never, R = never>(
  * const timedProgram = Effect.timeout(program, "1 second")
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export const never: Effect<never> = internal.never
@@ -1934,14 +1931,13 @@ export 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)
  *
@@ -1976,7 +1972,7 @@ export const bind: {
  * })
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export const gen: {
@@ -1986,14 +1982,13 @@ export 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)
    *
@@ -2028,7 +2023,7 @@ export const gen: {
    * })
    * ```
    *
-   * @category creating effects
+   * @category constructors
    * @since 2.0.0
    */
   <Eff extends Effect<any, any, any>, AEff>(f: () => Generator<Eff, AEff, never>): Effect<
@@ -2046,14 +2041,13 @@ export 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)
    *
@@ -2088,7 +2082,7 @@ export const gen: {
    * })
    * ```
    *
-   * @category creating effects
+   * @category constructors
    * @since 2.0.0
    */
   <Self, Eff extends Effect<any, any, any>, AEff>(
@@ -2116,7 +2110,7 @@ export declare namespace gen {
   /**
    * Generator return type accepted by `Effect.gen`.
    *
-   * @category creating effects
+   * @category constructors
    * @since 4.0.0
    */
   export type Return<A, E = never, R = never> = Generator<Effect<any, E, R>, A, any>
@@ -2127,9 +2121,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)
  *
@@ -2146,7 +2143,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 const fail: <E>(error: E) => Effect<never, E> = internal.fail
@@ -2175,7 +2172,7 @@ export const fail: <E>(error: E) => Effect<never, E> = internal.fail
  * // Output: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export const failSync: <E>(evaluate: LazyArg<E>) => Effect<never, E> = internal.failSync
@@ -2183,6 +2180,12 @@ export const failSync: <E>(evaluate: LazyArg<E>) => Effect<never, E> = internal.
 /**
  * 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
@@ -2201,7 +2204,7 @@ export const failSync: <E>(evaluate: LazyArg<E>) => Effect<never, E> = internal.
  * // Output: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export const failCause: <E>(cause: Cause.Cause<E>) => Effect<never, E> = internal.failCause
@@ -2230,7 +2233,7 @@ export const failCause: <E>(cause: Cause.Cause<E>) => Effect<never, E> = interna
  * // Output: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export const failCauseSync: <E>(
@@ -2242,8 +2245,8 @@ export const failCauseSync: <E>(
  *
  * **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**
  *
@@ -2274,7 +2277,7 @@ export const failCauseSync: <E>(
  * //   ...stack trace...
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export const die: (defect: unknown) => Effect<never> = internal.die
@@ -2291,10 +2294,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**
    *
@@ -2346,7 +2347,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
@@ -2369,7 +2370,7 @@ export {
  * Effect.runPromise(program)
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 2.0.0
  */
 export const yieldNow: Effect<void> = internal.yieldNow
@@ -2391,7 +2392,7 @@ export const yieldNow: Effect<void> = internal.yieldNow
  * Effect.runPromise(program)
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 4.0.0
  */
 export const yieldNowWith: (priority?: number) => Effect<void> = internal.yieldNowWith
@@ -2412,7 +2413,7 @@ export const yieldNowWith: (priority?: number) => Effect<void> = internal.yieldN
  * // Output: Fiber ID: 1
  * ```
  *
- * @category creating effects
+ * @category constructors
  * @since 4.0.0
  */
 export const withFiber: <A, E = never, R = never>(
@@ -2450,6 +2451,11 @@ export const fromResult: <A, E>(result: Result.Result<A, E>) => Effect<A, E> = i
 /**
  * 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
@@ -2749,8 +2755,8 @@ export const flatten: <A, E, R, E2, R2>(self: Effect<Effect<A, E, R>, E2, R2>) =
  *
  * **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**
  *
@@ -2825,8 +2831,8 @@ export 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**
    *
@@ -2901,8 +2907,8 @@ export 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**
    *
@@ -2977,8 +2983,8 @@ export 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**
    *
@@ -3053,8 +3059,8 @@ export 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**
    *
@@ -3131,9 +3137,8 @@ export 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**
  *
@@ -3185,9 +3190,8 @@ export 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**
    *
@@ -3239,9 +3243,8 @@ export 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**
    *
@@ -3293,9 +3296,8 @@ export 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**
    *
@@ -3347,9 +3349,8 @@ export 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**
    *
@@ -3402,16 +3403,15 @@ export 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
@@ -3458,9 +3458,8 @@ export const result: <A, E, R>(self: Effect<A, E, R>) => Effect<Result.Result<A,
  *
  * **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**
  *
@@ -3508,9 +3507,8 @@ export const option: <A, E, R>(self: Effect<A, E, R>) => Effect<Option<A>, never
  *
  * **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**
  *
@@ -3860,8 +3858,7 @@ export const asVoid: <A, E, R>(self: Effect<A, E, R>) => Effect<void, E, R> = in
  *
  * **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**
  *
@@ -4305,6 +4302,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
@@ -4312,8 +4314,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.
    *
@@ -4329,8 +4333,8 @@ export {
  *
  * **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**
  *
@@ -4374,8 +4378,8 @@ export 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**
    *
@@ -4442,8 +4446,8 @@ export 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**
    *
@@ -4513,10 +4517,14 @@ export 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)
@@ -4554,10 +4562,14 @@ export 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)
@@ -4624,10 +4636,14 @@ export 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)
@@ -4696,8 +4712,8 @@ export 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**
  *
@@ -4742,8 +4758,8 @@ export 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**
    *
@@ -4817,8 +4833,8 @@ export 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**
    *
@@ -5211,8 +5227,9 @@ export 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**
  *
@@ -5251,8 +5268,9 @@ export 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**
    *
@@ -5291,8 +5309,9 @@ export 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**
    *
@@ -5332,8 +5351,7 @@ export 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**
  *
@@ -5373,8 +5391,7 @@ export 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**
    *
@@ -5414,8 +5431,7 @@ export 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**
    *
@@ -5457,8 +5473,11 @@ export 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.
  *
@@ -5497,8 +5516,11 @@ export 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.
    *
@@ -5543,8 +5565,11 @@ export 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.
    *
@@ -5589,8 +5614,11 @@ export 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.
    *
@@ -5634,8 +5662,11 @@ export 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.
    *
@@ -5769,7 +5800,8 @@ export 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**
  *
@@ -5804,7 +5836,7 @@ export const catchNoSuchElement: <A, E, R>(
  *
  * **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**
  *
@@ -5848,7 +5880,7 @@ export 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**
    *
@@ -5895,7 +5927,7 @@ export 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**
    *
@@ -5945,8 +5977,9 @@ export 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**
  *
@@ -5967,8 +6000,9 @@ export 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**
    *
@@ -5992,8 +6026,9 @@ export 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**
    *
@@ -6020,7 +6055,8 @@ export 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**
  *
@@ -6058,7 +6094,8 @@ export 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**
    *
@@ -6096,7 +6133,8 @@ export 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**
    *
@@ -6136,8 +6174,8 @@ export 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**
  *
@@ -6177,8 +6215,8 @@ export 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**
    *
@@ -6220,8 +6258,8 @@ export 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**
    *
@@ -6267,8 +6305,8 @@ export 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)
  *
@@ -6533,6 +6571,11 @@ export 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
@@ -6564,6 +6607,11 @@ export 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
@@ -6595,6 +6643,11 @@ export 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
@@ -6734,8 +6787,9 @@ export 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**
  *
@@ -6756,8 +6810,9 @@ export 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**
    *
@@ -6781,8 +6836,9 @@ export 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**
    *
@@ -6983,7 +7039,7 @@ export const tapDefect: {
  * // Ready
  * ```
  *
- * @category repetition / recursion
+ * @category repetition
  * @since 2.0.0
  */
 export const eventually: <A, E, R>(self: Effect<A, E, R>) => Effect<A, never, R> = internal.eventually
@@ -7046,8 +7102,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**
  *
@@ -7099,8 +7155,8 @@ export 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**
    *
@@ -7152,8 +7208,8 @@ export 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**
    *
@@ -7205,8 +7261,8 @@ export 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**
    *
@@ -7262,8 +7318,8 @@ export 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**
    *
@@ -7315,8 +7371,8 @@ export 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**
    *
@@ -7368,8 +7424,8 @@ export 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**
    *
@@ -7644,6 +7700,8 @@ export const sandbox: <A, E, R>(
  * 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.
  *
@@ -7695,6 +7753,11 @@ export const ignore: <
 /**
  * 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,
@@ -8003,9 +8066,9 @@ export 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**
  *
@@ -8055,9 +8118,8 @@ export const firstSuccessOf: <Eff extends Effect<any, any, any>>(
  *
  * **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**
  *
@@ -8118,9 +8180,8 @@ export 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**
    *
@@ -8181,9 +8242,8 @@ export 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**
    *
@@ -8242,9 +8302,7 @@ export 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**
  *
@@ -8294,9 +8352,7 @@ export 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**
    *
@@ -8346,9 +8402,7 @@ export 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**
    *
@@ -8399,9 +8453,7 @@ export 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**
  *
@@ -8453,9 +8505,7 @@ export 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**
    *
@@ -8512,9 +8562,7 @@ export 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**
    *
@@ -8885,6 +8933,11 @@ export 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.
@@ -8917,6 +8970,11 @@ export 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.
@@ -8956,6 +9014,11 @@ export 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.
@@ -9190,8 +9253,8 @@ export 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**
  *
@@ -9210,8 +9273,8 @@ export 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**
    *
@@ -9230,8 +9293,8 @@ export 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**
    *
@@ -9252,8 +9315,8 @@ export 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**
  *
@@ -9277,8 +9340,8 @@ export 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**
    *
@@ -9305,8 +9368,8 @@ export 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**
    *
@@ -9334,6 +9397,11 @@ export 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
@@ -9366,6 +9434,11 @@ export 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
@@ -9401,6 +9474,11 @@ export 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
@@ -9436,6 +9514,11 @@ export 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
@@ -9472,6 +9555,11 @@ export 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
@@ -9995,8 +10083,8 @@ export 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**
  *
@@ -10036,8 +10124,8 @@ export 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**
    *
@@ -10077,8 +10165,8 @@ export 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**
    *
@@ -10120,8 +10208,8 @@ export 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**
  *
@@ -10177,8 +10265,8 @@ export 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**
    *
@@ -10239,8 +10327,8 @@ export 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**
    *
@@ -10300,9 +10388,8 @@ export 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**
  *
@@ -10337,9 +10424,8 @@ export 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**
    *
@@ -10379,9 +10465,8 @@ export 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**
    *
@@ -10423,9 +10508,8 @@ export 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**
  *
@@ -10460,9 +10544,8 @@ export 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**
    *
@@ -10502,9 +10585,8 @@ export 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**
    *
@@ -10547,9 +10629,8 @@ export 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**
  *
@@ -10577,9 +10658,8 @@ export 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**
    *
@@ -10612,9 +10692,8 @@ export 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**
    *
@@ -10650,9 +10729,8 @@ export 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**
  *
@@ -10672,9 +10750,8 @@ export 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**
    *
@@ -10699,9 +10776,8 @@ export 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**
    *
@@ -10729,8 +10805,8 @@ export 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**
  *
@@ -10789,8 +10865,8 @@ export 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**
    *
@@ -10854,8 +10930,8 @@ export 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**
    *
@@ -10922,7 +10998,8 @@ export 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**
  *
@@ -10982,7 +11059,8 @@ export 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**
    *
@@ -11047,7 +11125,8 @@ export 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**
    *
@@ -12303,6 +12382,11 @@ export 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
@@ -12357,6 +12441,11 @@ export 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
@@ -12411,6 +12500,11 @@ export 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
@@ -12665,6 +12759,11 @@ export const scoped: <A, E, R>(
 /**
  * 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
@@ -12777,8 +12876,8 @@ export const acquireRelease: <A, E, R, R2>(
  *
  * **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**
  *
@@ -13595,10 +13694,8 @@ export 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**
  *
@@ -13660,14 +13757,8 @@ export const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
  *
  * **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**
  *
@@ -13727,14 +13818,8 @@ export 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**
    *
@@ -13794,14 +13879,8 @@ export 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**
    *
@@ -14326,7 +14405,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
    */
   export type Return<R, E, A, O extends Options<A>> = Effect<
@@ -14357,7 +14436,7 @@ export declare namespace Repeat {
   /**
    * Options that control whether and how an effect is repeated.
    *
-   * @category repetition / recursion
+   * @category repetition
    * @since 2.0.0
    */
   export interface Options<A> {
@@ -14395,7 +14474,7 @@ export declare namespace Repeat {
  * })
  * ```
  *
- * @category repetition / recursion
+ * @category repetition
  * @since 2.0.0
  */
 export const forever: <
@@ -14485,7 +14564,7 @@ export const forever: <
  * @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 const repeat: {
@@ -14562,7 +14641,7 @@ export 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>
@@ -14639,7 +14718,7 @@ export 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>
@@ -14716,7 +14795,7 @@ export 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>(
@@ -14797,7 +14876,7 @@ export 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>
@@ -14874,7 +14953,7 @@ export 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>(
@@ -14954,7 +15033,7 @@ export 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>(
@@ -14969,6 +15048,11 @@ export 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
@@ -15004,7 +15088,7 @@ export const repeat: {
  * )
  * ```
  *
- * @category repetition / recursion
+ * @category repetition
  * @since 2.0.0
  */
 export const repeatOrElse: {
@@ -15012,6 +15096,11 @@ export 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
@@ -15047,7 +15136,7 @@ export const repeatOrElse: {
    * )
    * ```
    *
-   * @category repetition / recursion
+   * @category repetition
    * @since 2.0.0
    */
   <R2, A, B, E, E2, E3, R3>(
@@ -15058,6 +15147,11 @@ export 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
@@ -15093,7 +15187,7 @@ export const repeatOrElse: {
    * )
    * ```
    *
-   * @category repetition / recursion
+   * @category repetition
    * @since 2.0.0
    */
   <A, E, R, R2, B, E2, E3, R3>(
@@ -15108,9 +15202,8 @@ export 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**
  *
@@ -15128,9 +15221,8 @@ export 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**
    *
@@ -15148,9 +15240,8 @@ export 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**
    *
@@ -15168,6 +15259,11 @@ export 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.
@@ -15190,6 +15286,11 @@ export 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.
@@ -15215,6 +15316,11 @@ export 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.
@@ -15240,6 +15346,11 @@ export 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.
@@ -15266,6 +15377,11 @@ export 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.
@@ -15335,7 +15451,7 @@ export 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 const schedule: {
@@ -15383,7 +15499,7 @@ export 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>
@@ -15431,7 +15547,7 @@ export 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>
@@ -15474,7 +15590,7 @@ export const schedule: {
  * // Returns the schedule count
  * ```
  *
- * @category repetition / recursion
+ * @category repetition
  * @since 2.0.0
  */
 export const scheduleFrom: {
@@ -15512,7 +15628,7 @@ export 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>
@@ -15550,7 +15666,7 @@ export const scheduleFrom: {
    * // Returns the schedule count
    * ```
    *
-   * @category repetition / recursion
+   * @category repetition
    * @since 2.0.0
    */
   <Input, E, R, Output, Error, Env>(
@@ -16668,9 +16784,7 @@ export 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)
  *
@@ -16712,9 +16826,7 @@ export 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)
    *
@@ -16756,9 +16868,7 @@ export 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)
    *
@@ -17182,7 +17292,7 @@ export const fiberId: Effect<number> = internal.fiberId
  * @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 {
@@ -17198,9 +17308,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)
  *
@@ -17223,7 +17331,7 @@ export interface RunOptions {
  * }, 500)
  * ```
  *
- * @category running effects
+ * @category running
  * @since 2.0.0
  */
 export const runFork: <A, E>(effect: Effect<A, E, never>, options?: RunOptions | undefined) => Fiber<A, E> =
@@ -17232,6 +17340,11 @@ export const runFork: <A, E>(effect: Effect<A, E, never>, options?: RunOptions |
 /**
  * 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
@@ -17256,7 +17369,7 @@ export const runFork: <A, E>(effect: Effect<A, E, never>, options?: RunOptions |
  * const fiber = Effect.runForkWith(services)(program)
  * ```
  *
- * @category running effects
+ * @category running
  * @since 4.0.0
  */
 export const runForkWith: <R>(
@@ -17266,6 +17379,11 @@ export const runForkWith: <R>(
 /**
  * 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.
@@ -17303,7 +17421,7 @@ export const runForkWith: <R>(
  * interrupt()
  * ```
  *
- * @category running effects
+ * @category running
  * @since 4.0.0
  */
 export const runCallbackWith: <R>(
@@ -17350,7 +17468,7 @@ export const runCallbackWith: <R>(
  * // interrupt() to cancel the fiber if needed
  * ```
  *
- * @category running effects
+ * @category running
  * @since 2.0.0
  */
 export const runCallback: <A, E>(
@@ -17391,7 +17509,7 @@ export const runCallback: <A, E>(
  * ```
  *
  * @see {@link runPromiseExit} for a version that returns an `Exit` type instead of rejecting.
- * @category running effects
+ * @category running
  * @since 2.0.0
  */
 export const runPromise: <A, E>(
@@ -17402,6 +17520,11 @@ export const runPromise: <A, E>(
 /**
  * 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
@@ -17425,7 +17548,7 @@ export const runPromise: <A, E>(
  * Effect.runPromiseWith(context)(program).then(console.log)
  * ```
  *
- * @category running effects
+ * @category running
  * @since 4.0.0
  */
 export const runPromiseWith: <R>(
@@ -17443,10 +17566,9 @@ export const runPromiseWith: <R>(
  *
  * **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)
  *
@@ -17478,7 +17600,7 @@ export const runPromiseWith: <R>(
  *
  * @see {@link runPromise} for a version that rejects on failure.
  *
- * @category running effects
+ * @category running
  * @since 2.0.0
  */
 export const runPromiseExit: <A, E>(
@@ -17489,6 +17611,11 @@ export const runPromiseExit: <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
@@ -17516,7 +17643,7 @@ export const runPromiseExit: <A, E>(
  * })
  * ```
  *
- * @category running effects
+ * @category running
  * @since 4.0.0
  */
 export const runPromiseExitWith: <R>(
@@ -17581,7 +17708,7 @@ export const runPromiseExitWith: <R>(
  *
  * @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 const runSync: <A, E>(effect: Effect<A, E>) => A = internal.runSync
@@ -17589,6 +17716,11 @@ export const runSync: <A, E>(effect: Effect<A, E>) => A = internal.runSync
 /**
  * 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
@@ -17613,7 +17745,7 @@ export const runSync: <A, E>(effect: Effect<A, E>) => A = internal.runSync
  * console.log(result) // 5
  * ```
  *
- * @category running effects
+ * @category running
  * @since 4.0.0
  */
 export const runSyncWith: <R>(
@@ -17631,10 +17763,9 @@ export const runSyncWith: <R>(
  *
  * **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
@@ -17690,7 +17821,7 @@ export const runSyncWith: <R>(
  *
  * @see {@link runSync} for a version that throws on failure.
  *
- * @category running effects
+ * @category running
  * @since 2.0.0
  */
 export const runSyncExit: <A, E>(effect: Effect<A, E>) => Exit.Exit<A, E> = internal.runSyncExit
@@ -17698,6 +17829,11 @@ export const runSyncExit: <A, E>(effect: Effect<A, E>) => Exit.Exit<A, E> = inte
 /**
  * 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
@@ -17731,7 +17867,7 @@ export const runSyncExit: <A, E>(effect: Effect<A, E>) => Exit.Exit<A, E> = inte
  * // Success: 42
  * ```
  *
- * @category running effects
+ * @category running
  * @since 4.0.0
  */
 export const runSyncExitWith: <R>(
@@ -24015,13 +24151,10 @@ export class Transaction extends Context.Service<
  * 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.
@@ -24351,7 +24484,7 @@ export declare namespace Effectify {
   /**
    * Extracts the callback error type from a callback-based function type.
    *
-   * @category utils
+   * @category effectify
    * @since 4.0.0
    */
   export type EffectifyError<T> = T extends {
@@ -24758,11 +24891,8 @@ export const satisfiesServicesType = <R>() => <A, E, R2 extends R>(effect: Effec
  *
  * **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)
  *
@@ -24792,11 +24922,8 @@ export 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)
    *
@@ -24826,11 +24953,8 @@ export 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)
    *
@@ -24863,11 +24987,9 @@ export 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)
  *
@@ -24901,11 +25023,9 @@ export 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)
    *
@@ -24939,11 +25059,9 @@ export 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)
    *
@@ -24978,11 +25096,9 @@ export 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)
  *
@@ -25017,11 +25133,9 @@ export 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)
    *
@@ -25058,11 +25172,9 @@ export 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)
    *
@@ -25102,11 +25214,9 @@ export 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)
  *
@@ -25139,11 +25249,9 @@ export 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)
    *
@@ -25176,11 +25284,9 @@ export 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)
    *
@@ -25215,11 +25321,9 @@ export 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)
  *
@@ -25262,11 +25366,9 @@ export 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)
    *
@@ -25309,11 +25411,9 @@ export 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)
    *