effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/Effect.ts

@@ -154,6 +154,8 @@ export const TypeId: TypeId = core.EffectTypeId
  * job. The workflow requires some context `R`, and may fail with an error of
  * type `E`, or succeed with a value of type `A`.
  *
+ * **Details**
+ *
  * `Effect` values model resourceful interaction with the outside world,
  * including synchronous, asynchronous, concurrent, and parallel interaction.
  * They use a fiber-based concurrency model, with built-in support for
@@ -407,7 +409,7 @@ export declare namespace All {
  * first failure; with concurrent execution, effects that have already started
  * may be interrupted, while effects not yet started are skipped.
  *
- * **Options**
+ * Options:
  *
  * Use `concurrency` to control sequential or concurrent execution. Use
  * `mode: "result"` to run every effect and collect each success or failure as a
@@ -521,7 +523,6 @@ export declare namespace All {
  * ```
  *
  * @see {@link forEach} for iterating over elements and applying an effect.
- *
  * @category Collecting
  * @since 2.0.0
  */
@@ -543,6 +544,8 @@ export const all: <
  * Applies an effectful function to each element and partitions failures and
  * successes.
  *
+ * **Details**
+ *
  * The returned tuple is `[excluded, satisfying]`, where:
  *
  * - `excluded` contains all failures.
@@ -572,6 +575,8 @@ export const partition: {
    * Applies an effectful function to each element and partitions failures and
    * successes.
    *
+   * **Details**
+   *
    * The returned tuple is `[excluded, satisfying]`, where:
    *
    * - `excluded` contains all failures.
@@ -604,6 +609,8 @@ export const partition: {
    * Applies an effectful function to each element and partitions failures and
    * successes.
    *
+   * **Details**
+   *
    * The returned tuple is `[excluded, satisfying]`, where:
    *
    * - `excluded` contains all failures.
@@ -638,6 +645,8 @@ export const partition: {
 /**
  * Applies an effectful function to each element and accumulates all failures.
  *
+ * **Details**
+ *
  * This function always evaluates every element. If at least one effect fails,
  * all failures are returned as a non-empty array and successes are discarded.
  * If all effects succeed, it returns all collected successes.
@@ -675,6 +684,8 @@ export const validate: {
   /**
    * Applies an effectful function to each element and accumulates all failures.
    *
+   * **Details**
+   *
    * This function always evaluates every element. If at least one effect fails,
    * all failures are returned as a non-empty array and successes are discarded.
    * If all effects succeed, it returns all collected successes.
@@ -718,6 +729,8 @@ export const validate: {
   /**
    * Applies an effectful function to each element and accumulates all failures.
    *
+   * **Details**
+   *
    * This function always evaluates every element. If at least one effect fails,
    * all failures are returned as a non-empty array and successes are discarded.
    * If all effects succeed, it returns all collected successes.
@@ -761,6 +774,8 @@ export const validate: {
   /**
    * Applies an effectful function to each element and accumulates all failures.
    *
+   * **Details**
+   *
    * This function always evaluates every element. If at least one effect fails,
    * all failures are returned as a non-empty array and successes are discarded.
    * If all effects succeed, it returns all collected successes.
@@ -805,6 +820,8 @@ export const validate: {
   /**
    * Applies an effectful function to each element and accumulates all failures.
    *
+   * **Details**
+   *
    * This function always evaluates every element. If at least one effect fails,
    * all failures are returned as a non-empty array and successes are discarded.
    * If all effects succeed, it returns all collected successes.
@@ -851,6 +868,8 @@ export const validate: {
 /**
  * Returns the first element that satisfies an effectful predicate.
  *
+ * **Details**
+ *
  * The predicate receives the element and its index. Evaluation short-circuits
  * as soon as an element matches.
  *
@@ -872,6 +891,8 @@ export const findFirst: {
   /**
    * Returns the first element that satisfies an effectful predicate.
    *
+   * **Details**
+   *
    * The predicate receives the element and its index. Evaluation short-circuits
    * as soon as an element matches.
    *
@@ -893,6 +914,8 @@ export const findFirst: {
   /**
    * Returns the first element that satisfies an effectful predicate.
    *
+   * **Details**
+   *
    * The predicate receives the element and its index. Evaluation short-circuits
    * as soon as an element matches.
    *
@@ -919,6 +942,8 @@ export const findFirst: {
 /**
  * Returns the first value that passes an effectful `FilterEffect`.
  *
+ * **Details**
+ *
  * The filter receives the element and index. Evaluation short-circuits on the
  * first `Result.succeed` and returns the transformed value in `Option.some`.
  *
@@ -929,6 +954,8 @@ export const findFirstFilter: {
   /**
    * Returns the first value that passes an effectful `FilterEffect`.
    *
+   * **Details**
+   *
    * The filter receives the element and index. Evaluation short-circuits on the
    * first `Result.succeed` and returns the transformed value in `Option.some`.
    *
@@ -941,6 +968,8 @@ export const findFirstFilter: {
   /**
    * Returns the first value that passes an effectful `FilterEffect`.
    *
+   * **Details**
+   *
    * The filter receives the element and index. Evaluation short-circuits on the
    * first `Result.succeed` and returns the transformed value in `Option.some`.
    *
@@ -964,18 +993,16 @@ export const findFirstFilter: {
  * If any effect fails, the iteration stops immediately (short-circuiting), and
  * the error is propagated.
  *
- * **Concurrency**
+ * Concurrency:
  *
  * The `concurrency` option controls how many operations are performed
  * concurrently. By default, the operations are performed sequentially.
  *
- * **Discarding Results**
+ * Discarding Results:
  *
  * If the `discard` option is set to `true`, the intermediate results are not
  * collected, and the final result of the operation is `void`.
  *
- * @see {@link all} for combining multiple effects into one.
- *
  * **Example** (Mapping over an iterable with effects)
  *
  * ```ts
@@ -1020,6 +1047,7 @@ export const findFirstFilter: {
  * // undefined
  * ```
  *
+ * @see {@link all} for combining multiple effects into one.
  * @category Collecting
  * @since 2.0.0
  */
@@ -1035,18 +1063,16 @@ export const forEach: {
    * If any effect fails, the iteration stops immediately (short-circuiting), and
    * the error is propagated.
    *
-   * **Concurrency**
+   * Concurrency:
    *
    * The `concurrency` option controls how many operations are performed
    * concurrently. By default, the operations are performed sequentially.
    *
-   * **Discarding Results**
+   * Discarding Results:
    *
    * If the `discard` option is set to `true`, the intermediate results are not
    * collected, and the final result of the operation is `void`.
    *
-   * @see {@link all} for combining multiple effects into one.
-   *
    * **Example** (Mapping over an iterable with effects)
    *
    * ```ts
@@ -1091,6 +1117,7 @@ export const forEach: {
    * // undefined
    * ```
    *
+   * @see {@link all} for combining multiple effects into one.
    * @category Collecting
    * @since 2.0.0
    */
@@ -1109,18 +1136,16 @@ export const forEach: {
    * If any effect fails, the iteration stops immediately (short-circuiting), and
    * the error is propagated.
    *
-   * **Concurrency**
+   * Concurrency:
    *
    * The `concurrency` option controls how many operations are performed
    * concurrently. By default, the operations are performed sequentially.
    *
-   * **Discarding Results**
+   * Discarding Results:
    *
    * If the `discard` option is set to `true`, the intermediate results are not
    * collected, and the final result of the operation is `void`.
    *
-   * @see {@link all} for combining multiple effects into one.
-   *
    * **Example** (Mapping over an iterable with effects)
    *
    * ```ts
@@ -1165,6 +1190,7 @@ export const forEach: {
    * // undefined
    * ```
    *
+   * @see {@link all} for combining multiple effects into one.
    * @category Collecting
    * @since 2.0.0
    */
@@ -1217,7 +1243,7 @@ export const whileLoop: <A, E, R>(options: {
  * Creates an `Effect` that represents an asynchronous computation guaranteed to
  * succeed.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `promise` when you are sure the operation will not reject.
  *
@@ -1231,13 +1257,11 @@ export const whileLoop: <A, E, R>(options: {
  * crash in the program, which can be further managed or logged using tools like
  * {@link catchDefect}.
  *
- * **Interruptions**
+ * Interruptions:
  *
  * An optional `AbortSignal` can be provided to allow for interruption of the
  * wrapped `Promise` API.
  *
- * @see {@link tryPromise} for a version that can handle failures.
- *
  * **Example** (Wrapping a non-rejecting Promise)
  *
  * ```ts
@@ -1258,6 +1282,7 @@ export const whileLoop: <A, E, R>(options: {
  * const program = delay("Async operation completed successfully!")
  * ```
  *
+ * @see {@link tryPromise} for a version that can handle failures.
  * @category Creating Effects
  * @since 2.0.0
  */
@@ -1269,7 +1294,7 @@ export const promise: <A>(
  * Creates an `Effect` that represents an asynchronous computation that might
  * fail.
  *
- * **When to Use**
+ * **When to use**
  *
  * In situations where you need to perform asynchronous operations that might
  * fail, such as fetching data from an API, you can use the `tryPromise`
@@ -1277,7 +1302,9 @@ export const promise: <A>(
  * throw exceptions by capturing those exceptions and transforming them into
  * manageable errors.
  *
- * **Error Handling**
+ * **Details**
+ *
+ * Error Handling:
  *
  * There are two ways to handle errors with `tryPromise`:
  *
@@ -1286,7 +1313,7 @@ export const promise: <A>(
  * 2. If you provide a `catch` function, the error is caught and the `catch`
  *    function maps it to an error of type `E`.
  *
- * **Interruptions**
+ * Interruptions:
  *
  * An optional `AbortSignal` can be provided to allow for interruption of the
  * wrapped `Promise` API.
@@ -1327,7 +1354,6 @@ export const promise: <A>(
  * ```
  *
  * @see {@link promise} if the effectful computation is asynchronous and does not throw errors.
- *
  * @category Creating Effects
  * @since 2.0.0
  */
@@ -1340,13 +1366,11 @@ export const tryPromise: <A, E = Cause.UnknownError>(
 /**
  * Creates an `Effect` that always succeeds with a given value.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use this function when you need an effect that completes successfully with a
  * specific value without any errors or external dependencies.
  *
- * @see {@link fail} to create an effect that represents a failure.
- *
  * **Example** (Creating a successful effect)
  *
  * ```ts
@@ -1359,6 +1383,7 @@ export const tryPromise: <A, E = Cause.UnknownError>(
  * const success = Effect.succeed(42)
  * ```
  *
+ * @see {@link fail} to create an effect that represents a failure.
  * @category Creating Effects
  * @since 2.0.0
  */
@@ -1405,7 +1430,7 @@ export const succeedSome: <A>(value: A) => Effect<Option<A>> = internal.succeedS
 /**
  * Delays the creation of an `Effect` until it is actually needed.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `suspend` 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.
  *
@@ -1495,7 +1520,7 @@ export const suspend: <A, E, R>(
 /**
  * Creates an `Effect` that represents a synchronous side-effectful computation.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `sync` when you are sure the operation will not fail.
  *
@@ -1509,8 +1534,6 @@ export const suspend: <A, E, R>(
  * crash in the program, which can be further managed or logged using tools like
  * {@link catchDefect}.
  *
- * @see {@link try_ | try} for a version that can handle failures.
- *
  * **Example** (Capturing synchronous logging in an Effect)
  *
  * ```ts
@@ -1526,6 +1549,7 @@ export const suspend: <A, E, R>(
  * const program = log("Hello, World!")
  * ```
  *
+ * @see {@link try_ | try} for a version that can handle failures.
  * @category Creating Effects
  * @since 2.0.0
  */
@@ -1534,6 +1558,8 @@ export const sync: <A>(thunk: LazyArg<A>) => Effect<A> = internal.sync
 const void_: Effect<void> = internal.void
 export {
   /**
+   * Returns an effect that succeeds with `void`.
+   *
    * @category Creating Effects
    * @since 2.0.0
    */
@@ -1543,6 +1569,8 @@ export {
 const undefined_: Effect<undefined> = internal.undefined
 export {
   /**
+   * Returns an effect that succeeds with `undefined`.
+   *
    * @category Creating Effects
    * @since 4.0.0
    */
@@ -1552,6 +1580,11 @@ export {
 /**
  * Creates an `Effect` from a callback-based asynchronous API.
  *
+ * **When to use**
+ *
+ * Use `Effect.callback` when integrating APIs that complete through callbacks
+ * instead of returning a `Promise`.
+ *
  * **Details**
  *
  * The registration function receives a `resume` callback and, when requested,
@@ -1559,11 +1592,6 @@ export {
  * complete the fiber; later calls are ignored. Return an optional cleanup
  * effect from the registration function to run if the fiber is interrupted.
  *
- * **When to Use**
- *
- * Use `Effect.callback` when integrating APIs that complete through callbacks
- * instead of returning a `Promise`.
- *
  * **Example** (Integrating callback APIs)
  *
  * ```ts
@@ -1717,7 +1745,7 @@ export const bind: {
  * Provides a way to write effectful code using generator functions, simplifying
  * control flow and error handling.
  *
- * **When to Use**
+ * **When to use**
  *
  * `gen` allows you to write code that looks and behaves like synchronous
  * code, but it can handle asynchronous tasks, errors, and complex control flow
@@ -1769,7 +1797,7 @@ export const gen: {
    * Provides a way to write effectful code using generator functions, simplifying
    * control flow and error handling.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `gen` allows you to write code that looks and behaves like synchronous
    * code, but it can handle asynchronous tasks, errors, and complex control flow
@@ -1829,7 +1857,7 @@ export const gen: {
    * Provides a way to write effectful code using generator functions, simplifying
    * control flow and error handling.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `gen` allows you to write code that looks and behaves like synchronous
    * code, but it can handle asynchronous tasks, errors, and complex control flow
@@ -1897,7 +1925,7 @@ export const gen: {
  *
  * @since 2.0.0
  */
-export namespace gen {
+export declare namespace gen {
   /**
    * Generator return type accepted by `Effect.gen`.
    *
@@ -1910,14 +1938,12 @@ export namespace gen {
 /**
  * Creates an `Effect` that represents a recoverable error.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use this function 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}.
  *
- * @see {@link succeed} to create an effect that represents a successful value.
- *
  * **Example** (Creating a failed effect)
  *
  * ```ts
@@ -1932,6 +1958,7 @@ export namespace gen {
  * )
  * ```
  *
+ * @see {@link succeed} to create an effect that represents a successful value.
  * @category Creating Effects
  * @since 2.0.0
  */
@@ -1940,6 +1967,8 @@ export const fail: <E>(error: E) => Effect<never, E> = internal.fail
 /**
  * Creates an `Effect` that represents a recoverable error using a lazy evaluation.
  *
+ * **Details**
+ *
  * This function is useful when you need to create an error effect but want to
  * defer the computation of the error value until the effect is actually run.
  *
@@ -1964,6 +1993,8 @@ export const failSync: <E>(evaluate: LazyArg<E>) => Effect<never, E> = internal.
 /**
  * Creates an `Effect` that represents a failure with a specific `Cause`.
  *
+ * **Details**
+ *
  * This function allows you to create effects that fail with complex error
  * structures, including multiple errors, defects, interruptions, and more.
  *
@@ -1988,6 +2019,8 @@ export const failCause: <E>(cause: Cause.Cause<E>) => Effect<never, E> = interna
 /**
  * Creates an `Effect` that represents a failure with a `Cause` computed lazily.
  *
+ * **Details**
+ *
  * This function is useful when you need to create a failure effect with a
  * complex cause but want to defer the computation until the effect is run.
  *
@@ -2014,7 +2047,7 @@ export const failCauseSync: <E>(
 /**
  * Creates an effect that terminates a fiber with a specified error.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `die` when encountering unexpected conditions in your code that should
  * not be handled as regular errors but instead represent unrecoverable defects.
@@ -2028,8 +2061,6 @@ export const failCauseSync: <E>(
  * The error channel of the resulting effect is of type `never`, indicating that
  * it cannot recover from this failure.
  *
- * @see {@link die} for a variant that dies with an already computed defect.
- *
  * **Example** (Failing when division by zero)
  *
  * ```ts
@@ -2050,6 +2081,7 @@ export const failCauseSync: <E>(
  * //   ...stack trace...
  * ```
  *
+ * @see {@link die} for a variant that dies with an already computed defect.
  * @category Creating Effects
  * @since 2.0.0
  */
@@ -2065,14 +2097,16 @@ export {
    * Creates an `Effect` that represents a synchronous computation that might
    * fail.
    *
-   * **When to Use**
+   * **When to use**
    *
    * 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.
    *
-   * **Error Handling**
+   * **Details**
+   *
+   * Error Handling:
    *
    * There are two ways to handle errors with `try`:
    *
@@ -2081,9 +2115,6 @@ export {
    * 2. If you provide a `catch` function, the error is caught and the `catch`
    *    function maps it to an error of type `E`.
    *
-   * @see {@link sync} if the effectful computation is synchronous and does not
-   * throw errors.
-   *
    * **Example** (Parsing JSON with typed error mapping)
    *
    * ```ts
@@ -2121,6 +2152,8 @@ export {
    * // Output: Exit.failure with custom Error message
    * ```
    *
+   * @see {@link sync} if the effectful computation is synchronous and does not
+   * throw errors.
    * @category Creating Effects
    * @since 2.0.0
    */
@@ -2225,6 +2258,8 @@ export const fromResult: <A, E>(result: Result.Result<A, E>) => Effect<A, E> = i
 /**
  * Converts an `Option` into an `Effect`.
  *
+ * **Details**
+ *
  * `Option.some` becomes a successful effect with the contained value, while
  * `Option.none` becomes a failed effect with `NoSuchElementError`.
  *
@@ -2286,15 +2321,11 @@ export const fromNullishOr: <A>(value: A) => Effect<NonNullable<A>, Cause.NoSuch
  * Chains effects to produce new `Effect` instances, useful for combining
  * operations that depend on previous results.
  *
- * **Syntax**
+ * **When to use**
  *
- * ```ts skip-type-checking
- * const flatMappedEffect = pipe(myEffect, Effect.flatMap(transformation))
- * // or
- * const flatMappedEffect = Effect.flatMap(myEffect, transformation)
- * // or
- * const flatMappedEffect = myEffect.pipe(Effect.flatMap(transformation))
- * ```
+ * Use `flatMap` when you need to chain multiple effects, ensuring that each
+ * step produces a new `Effect` while flattening any nested effects that may
+ * occur.
  *
  * **Details**
  *
@@ -2306,11 +2337,18 @@ export const fromNullishOr: <A>(value: A) => Effect<NonNullable<A>, Cause.NoSuch
  * Since effects are immutable, `flatMap` always returns a new effect instead of
  * changing the original one.
  *
- * **When to Use**
+ * **Example** (Syntax)
  *
- * Use `flatMap` when you need to chain multiple effects, ensuring that each
- * step produces a new `Effect` while flattening any nested effects that may
- * occur.
+ * ```ts
+ * import { Effect, pipe } from "effect"
+ *
+ * const myEffect = Effect.succeed(1)
+ * const transformation = (n: number) => Effect.succeed(n + 1)
+ *
+ * const flatMappedWithPipe = pipe(myEffect, Effect.flatMap(transformation))
+ * const flatMappedWithDataFirst = Effect.flatMap(myEffect, transformation)
+ * const flatMappedWithMethod = myEffect.pipe(Effect.flatMap(transformation))
+ * ```
  *
  * **Example** (Sequencing dependent effects)
  *
@@ -2342,7 +2380,6 @@ export const fromNullishOr: <A>(value: A) => Effect<NonNullable<A>, Cause.NoSuch
  * ```
  *
  * @see {@link tap} for a version that ignores the result of the effect.
- *
  * @category sequencing
  * @since 2.0.0
  */
@@ -2355,15 +2392,11 @@ export const flatMap: {
    * Chains effects to produce new `Effect` instances, useful for combining
    * operations that depend on previous results.
    *
-   * **Syntax**
+   * **When to use**
    *
-   * ```ts skip-type-checking
-   * const flatMappedEffect = pipe(myEffect, Effect.flatMap(transformation))
-   * // or
-   * const flatMappedEffect = Effect.flatMap(myEffect, transformation)
-   * // or
-   * const flatMappedEffect = myEffect.pipe(Effect.flatMap(transformation))
-   * ```
+   * Use `flatMap` when you need to chain multiple effects, ensuring that each
+   * step produces a new `Effect` while flattening any nested effects that may
+   * occur.
    *
    * **Details**
    *
@@ -2375,11 +2408,18 @@ export const flatMap: {
    * Since effects are immutable, `flatMap` always returns a new effect instead of
    * changing the original one.
    *
-   * **When to Use**
+   * **Example** (Syntax)
    *
-   * Use `flatMap` when you need to chain multiple effects, ensuring that each
-   * step produces a new `Effect` while flattening any nested effects that may
-   * occur.
+   * ```ts
+   * import { Effect, pipe } from "effect"
+   *
+   * const myEffect = Effect.succeed(1)
+   * const transformation = (n: number) => Effect.succeed(n + 1)
+   *
+   * const flatMappedWithPipe = pipe(myEffect, Effect.flatMap(transformation))
+   * const flatMappedWithDataFirst = Effect.flatMap(myEffect, transformation)
+   * const flatMappedWithMethod = myEffect.pipe(Effect.flatMap(transformation))
+   * ```
    *
    * **Example** (Sequencing dependent effects)
    *
@@ -2411,7 +2451,6 @@ export const flatMap: {
    * ```
    *
    * @see {@link tap} for a version that ignores the result of the effect.
-   *
    * @category sequencing
    * @since 2.0.0
    */
@@ -2424,15 +2463,11 @@ export const flatMap: {
    * Chains effects to produce new `Effect` instances, useful for combining
    * operations that depend on previous results.
    *
-   * **Syntax**
+   * **When to use**
    *
-   * ```ts skip-type-checking
-   * const flatMappedEffect = pipe(myEffect, Effect.flatMap(transformation))
-   * // or
-   * const flatMappedEffect = Effect.flatMap(myEffect, transformation)
-   * // or
-   * const flatMappedEffect = myEffect.pipe(Effect.flatMap(transformation))
-   * ```
+   * Use `flatMap` when you need to chain multiple effects, ensuring that each
+   * step produces a new `Effect` while flattening any nested effects that may
+   * occur.
    *
    * **Details**
    *
@@ -2444,11 +2479,18 @@ export const flatMap: {
    * Since effects are immutable, `flatMap` always returns a new effect instead of
    * changing the original one.
    *
-   * **When to Use**
+   * **Example** (Syntax)
    *
-   * Use `flatMap` when you need to chain multiple effects, ensuring that each
-   * step produces a new `Effect` while flattening any nested effects that may
-   * occur.
+   * ```ts
+   * import { Effect, pipe } from "effect"
+   *
+   * const myEffect = Effect.succeed(1)
+   * const transformation = (n: number) => Effect.succeed(n + 1)
+   *
+   * const flatMappedWithPipe = pipe(myEffect, Effect.flatMap(transformation))
+   * const flatMappedWithDataFirst = Effect.flatMap(myEffect, transformation)
+   * const flatMappedWithMethod = myEffect.pipe(Effect.flatMap(transformation))
+   * ```
    *
    * **Example** (Sequencing dependent effects)
    *
@@ -2480,7 +2522,6 @@ export const flatMap: {
    * ```
    *
    * @see {@link tap} for a version that ignores the result of the effect.
-   *
    * @category sequencing
    * @since 2.0.0
    */
@@ -2514,17 +2555,7 @@ export const flatten: <A, E, R, E2, R2>(self: Effect<Effect<A, E, R>, E2, R2>) =
  * Runs this effect and then runs another effect, optionally using the first
  * effect's success value to choose the next effect.
  *
- * **Syntax**
- *
- * ```ts skip-type-checking
- * const transformedEffect = pipe(myEffect, Effect.andThen(anotherEffect))
- * // or
- * const transformedEffect = Effect.andThen(myEffect, anotherEffect)
- * // or
- * const transformedEffect = myEffect.pipe(Effect.andThen(anotherEffect))
- * ```
- *
- * **When to Use**
+ * **When to use**
  *
  * Use `andThen` when one effect must run after another and the second effect
  * may depend on the first effect's success value.
@@ -2539,6 +2570,19 @@ export const flatten: <A, E, R, E2, R2>(self: Effect<Effect<A, E, R>, E2, R2>) =
  * Failures or requirements from either effect are preserved in the returned
  * effect.
  *
+ * **Example** (Syntax)
+ *
+ * ```ts
+ * import { Effect, pipe } from "effect"
+ *
+ * const myEffect = Effect.succeed(1)
+ * const anotherEffect = Effect.succeed("done")
+ *
+ * const transformedWithPipe = pipe(myEffect, Effect.andThen(anotherEffect))
+ * const transformedWithDataFirst = Effect.andThen(myEffect, anotherEffect)
+ * const transformedWithMethod = myEffect.pipe(Effect.andThen(anotherEffect))
+ * ```
+ *
  * **Example** (Sequencing a discount calculation after fetching a total)
  *
  * ```ts
@@ -2587,17 +2631,7 @@ export const andThen: {
    * Runs this effect and then runs another effect, optionally using the first
    * effect's success value to choose the next effect.
    *
-   * **Syntax**
-   *
-   * ```ts skip-type-checking
-   * const transformedEffect = pipe(myEffect, Effect.andThen(anotherEffect))
-   * // or
-   * const transformedEffect = Effect.andThen(myEffect, anotherEffect)
-   * // or
-   * const transformedEffect = myEffect.pipe(Effect.andThen(anotherEffect))
-   * ```
-   *
-   * **When to Use**
+   * **When to use**
    *
    * Use `andThen` when one effect must run after another and the second effect
    * may depend on the first effect's success value.
@@ -2612,6 +2646,19 @@ export const andThen: {
    * Failures or requirements from either effect are preserved in the returned
    * effect.
    *
+   * **Example** (Syntax)
+   *
+   * ```ts
+   * import { Effect, pipe } from "effect"
+   *
+   * const myEffect = Effect.succeed(1)
+   * const anotherEffect = Effect.succeed("done")
+   *
+   * const transformedWithPipe = pipe(myEffect, Effect.andThen(anotherEffect))
+   * const transformedWithDataFirst = Effect.andThen(myEffect, anotherEffect)
+   * const transformedWithMethod = myEffect.pipe(Effect.andThen(anotherEffect))
+   * ```
+   *
    * **Example** (Sequencing a discount calculation after fetching a total)
    *
    * ```ts
@@ -2660,17 +2707,7 @@ export const andThen: {
    * Runs this effect and then runs another effect, optionally using the first
    * effect's success value to choose the next effect.
    *
-   * **Syntax**
-   *
-   * ```ts skip-type-checking
-   * const transformedEffect = pipe(myEffect, Effect.andThen(anotherEffect))
-   * // or
-   * const transformedEffect = Effect.andThen(myEffect, anotherEffect)
-   * // or
-   * const transformedEffect = myEffect.pipe(Effect.andThen(anotherEffect))
-   * ```
-   *
-   * **When to Use**
+   * **When to use**
    *
    * Use `andThen` when one effect must run after another and the second effect
    * may depend on the first effect's success value.
@@ -2685,6 +2722,19 @@ export const andThen: {
    * Failures or requirements from either effect are preserved in the returned
    * effect.
    *
+   * **Example** (Syntax)
+   *
+   * ```ts
+   * import { Effect, pipe } from "effect"
+   *
+   * const myEffect = Effect.succeed(1)
+   * const anotherEffect = Effect.succeed("done")
+   *
+   * const transformedWithPipe = pipe(myEffect, Effect.andThen(anotherEffect))
+   * const transformedWithDataFirst = Effect.andThen(myEffect, anotherEffect)
+   * const transformedWithMethod = myEffect.pipe(Effect.andThen(anotherEffect))
+   * ```
+   *
    * **Example** (Sequencing a discount calculation after fetching a total)
    *
    * ```ts
@@ -2733,17 +2783,7 @@ export const andThen: {
    * Runs this effect and then runs another effect, optionally using the first
    * effect's success value to choose the next effect.
    *
-   * **Syntax**
-   *
-   * ```ts skip-type-checking
-   * const transformedEffect = pipe(myEffect, Effect.andThen(anotherEffect))
-   * // or
-   * const transformedEffect = Effect.andThen(myEffect, anotherEffect)
-   * // or
-   * const transformedEffect = myEffect.pipe(Effect.andThen(anotherEffect))
-   * ```
-   *
-   * **When to Use**
+   * **When to use**
    *
    * Use `andThen` when one effect must run after another and the second effect
    * may depend on the first effect's success value.
@@ -2758,6 +2798,19 @@ export const andThen: {
    * Failures or requirements from either effect are preserved in the returned
    * effect.
    *
+   * **Example** (Syntax)
+   *
+   * ```ts
+   * import { Effect, pipe } from "effect"
+   *
+   * const myEffect = Effect.succeed(1)
+   * const anotherEffect = Effect.succeed("done")
+   *
+   * const transformedWithPipe = pipe(myEffect, Effect.andThen(anotherEffect))
+   * const transformedWithDataFirst = Effect.andThen(myEffect, anotherEffect)
+   * const transformedWithMethod = myEffect.pipe(Effect.andThen(anotherEffect))
+   * ```
+   *
    * **Example** (Sequencing a discount calculation after fetching a total)
    *
    * ```ts
@@ -2806,17 +2859,7 @@ export const andThen: {
    * Runs this effect and then runs another effect, optionally using the first
    * effect's success value to choose the next effect.
    *
-   * **Syntax**
-   *
-   * ```ts skip-type-checking
-   * const transformedEffect = pipe(myEffect, Effect.andThen(anotherEffect))
-   * // or
-   * const transformedEffect = Effect.andThen(myEffect, anotherEffect)
-   * // or
-   * const transformedEffect = myEffect.pipe(Effect.andThen(anotherEffect))
-   * ```
-   *
-   * **When to Use**
+   * **When to use**
    *
    * Use `andThen` when one effect must run after another and the second effect
    * may depend on the first effect's success value.
@@ -2831,6 +2874,19 @@ export const andThen: {
    * Failures or requirements from either effect are preserved in the returned
    * effect.
    *
+   * **Example** (Syntax)
+   *
+   * ```ts
+   * import { Effect, pipe } from "effect"
+   *
+   * const myEffect = Effect.succeed(1)
+   * const anotherEffect = Effect.succeed("done")
+   *
+   * const transformedWithPipe = pipe(myEffect, Effect.andThen(anotherEffect))
+   * const transformedWithDataFirst = Effect.andThen(myEffect, anotherEffect)
+   * const transformedWithMethod = myEffect.pipe(Effect.andThen(anotherEffect))
+   * ```
+   *
    * **Example** (Sequencing a discount calculation after fetching a total)
    *
    * ```ts
@@ -2881,7 +2937,7 @@ export const andThen: {
  * Runs a side effect with the result of an effect without changing the original
  * value.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `tap` 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
@@ -2935,7 +2991,7 @@ export const tap: {
    * Runs a side effect with the result of an effect without changing the original
    * value.
    *
-   * **When to Use**
+   * **When to use**
    *
    * Use `tap` 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
@@ -2989,7 +3045,7 @@ export const tap: {
    * Runs a side effect with the result of an effect without changing the original
    * value.
    *
-   * **When to Use**
+   * **When to use**
    *
    * Use `tap` 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
@@ -3043,7 +3099,7 @@ export const tap: {
    * Runs a side effect with the result of an effect without changing the original
    * value.
    *
-   * **When to Use**
+   * **When to use**
    *
    * Use `tap` 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
@@ -3097,7 +3153,7 @@ export const tap: {
    * Runs a side effect with the result of an effect without changing the original
    * value.
    *
-   * **When to Use**
+   * **When to use**
    *
    * Use `tap` 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
@@ -3276,16 +3332,6 @@ export const exit: <A, E, R>(
 /**
  * Transforms the value inside an effect by applying a function to it.
  *
- * **Syntax**
- *
- * ```ts skip-type-checking
- * const mappedEffect = pipe(myEffect, Effect.map(transformation))
- * // or
- * const mappedEffect = Effect.map(myEffect, transformation)
- * // or
- * const mappedEffect = myEffect.pipe(Effect.map(transformation))
- * ```
- *
  * **Details**
  *
  * `map` takes a function and applies it to the value contained within an
@@ -3295,6 +3341,19 @@ export const exit: <A, E, R>(
  * effect is not modified. Instead, a new effect is returned with the updated
  * value.
  *
+ * **Example** (Syntax)
+ *
+ * ```ts
+ * import { Effect, pipe } from "effect"
+ *
+ * const myEffect = Effect.succeed(1)
+ * const transformation = (n: number) => n + 1
+ *
+ * const mappedWithPipe = pipe(myEffect, Effect.map(transformation))
+ * const mappedWithDataFirst = Effect.map(myEffect, transformation)
+ * const mappedWithMethod = myEffect.pipe(Effect.map(transformation))
+ * ```
+ *
  * **Example** (Adding a service charge)
  *
  * ```ts
@@ -3316,7 +3375,6 @@ export const exit: <A, E, R>(
  * @see {@link mapError} for a version that operates on the error channel.
  * @see {@link mapBoth} for a version that operates on both channels.
  * @see {@link flatMap} or {@link andThen} for a version that can return a new effect.
- *
  * @category mapping
  * @since 2.0.0
  */
@@ -3324,16 +3382,6 @@ export const map: {
   /**
    * Transforms the value inside an effect by applying a function to it.
    *
-   * **Syntax**
-   *
-   * ```ts skip-type-checking
-   * const mappedEffect = pipe(myEffect, Effect.map(transformation))
-   * // or
-   * const mappedEffect = Effect.map(myEffect, transformation)
-   * // or
-   * const mappedEffect = myEffect.pipe(Effect.map(transformation))
-   * ```
-   *
    * **Details**
    *
    * `map` takes a function and applies it to the value contained within an
@@ -3343,6 +3391,19 @@ export const map: {
    * effect is not modified. Instead, a new effect is returned with the updated
    * value.
    *
+   * **Example** (Syntax)
+   *
+   * ```ts
+   * import { Effect, pipe } from "effect"
+   *
+   * const myEffect = Effect.succeed(1)
+   * const transformation = (n: number) => n + 1
+   *
+   * const mappedWithPipe = pipe(myEffect, Effect.map(transformation))
+   * const mappedWithDataFirst = Effect.map(myEffect, transformation)
+   * const mappedWithMethod = myEffect.pipe(Effect.map(transformation))
+   * ```
+   *
    * **Example** (Adding a service charge)
    *
    * ```ts
@@ -3364,7 +3425,6 @@ export const map: {
    * @see {@link mapError} for a version that operates on the error channel.
    * @see {@link mapBoth} for a version that operates on both channels.
    * @see {@link flatMap} or {@link andThen} for a version that can return a new effect.
-   *
    * @category mapping
    * @since 2.0.0
    */
@@ -3372,16 +3432,6 @@ export const map: {
   /**
    * Transforms the value inside an effect by applying a function to it.
    *
-   * **Syntax**
-   *
-   * ```ts skip-type-checking
-   * const mappedEffect = pipe(myEffect, Effect.map(transformation))
-   * // or
-   * const mappedEffect = Effect.map(myEffect, transformation)
-   * // or
-   * const mappedEffect = myEffect.pipe(Effect.map(transformation))
-   * ```
-   *
    * **Details**
    *
    * `map` takes a function and applies it to the value contained within an
@@ -3391,6 +3441,19 @@ export const map: {
    * effect is not modified. Instead, a new effect is returned with the updated
    * value.
    *
+   * **Example** (Syntax)
+   *
+   * ```ts
+   * import { Effect, pipe } from "effect"
+   *
+   * const myEffect = Effect.succeed(1)
+   * const transformation = (n: number) => n + 1
+   *
+   * const mappedWithPipe = pipe(myEffect, Effect.map(transformation))
+   * const mappedWithDataFirst = Effect.map(myEffect, transformation)
+   * const mappedWithMethod = myEffect.pipe(Effect.map(transformation))
+   * ```
+   *
    * **Example** (Adding a service charge)
    *
    * ```ts
@@ -3412,7 +3475,6 @@ export const map: {
    * @see {@link mapError} for a version that operates on the error channel.
    * @see {@link mapBoth} for a version that operates on both channels.
    * @see {@link flatMap} or {@link andThen} for a version that can return a new effect.
-   *
    * @category mapping
    * @since 2.0.0
    */
@@ -3422,6 +3484,8 @@ export const map: {
 /**
  * Replaces the value inside an effect with a constant value.
  *
+ * **Details**
+ *
  * `as` allows you to ignore the original value inside an effect and
  * replace it with a new constant value.
  *
@@ -3444,6 +3508,8 @@ export const as: {
   /**
    * Replaces the value inside an effect with a constant value.
    *
+   * **Details**
+   *
    * `as` allows you to ignore the original value inside an effect and
    * replace it with a new constant value.
    *
@@ -3466,6 +3532,8 @@ export const as: {
   /**
    * Replaces the value inside an effect with a constant value.
    *
+   * **Details**
+   *
    * `as` allows you to ignore the original value inside an effect and
    * replace it with a new constant value.
    *
@@ -3534,6 +3602,8 @@ export const asVoid: <A, E, R>(self: Effect<A, E, R>) => Effect<void, E, R> = in
  * The `flip` function swaps the success and error channels of an effect,
  * so that the success becomes the error, and the error becomes the success.
  *
+ * **Details**
+ *
  * This function is useful when you need to reverse the flow of an effect,
  * treating the previously successful values as errors and vice versa. This can
  * be helpful in scenarios where you want to handle a success as a failure or
@@ -3565,17 +3635,16 @@ export const flip: <A, E, R>(self: Effect<A, E, R>) => Effect<E, A, R> = interna
 /**
  * Combines two effects into a single effect, producing a tuple with the results of both effects.
  *
+ * **Details**
+ *
  * The `zip` function executes the first effect (left) and then the second effect (right).
  * Once both effects succeed, their results are combined into a tuple.
  *
- * **Concurrency**
+ * Concurrency:
  *
  * By default, `zip` processes the effects sequentially. To execute the effects concurrently,
  * use the `{ concurrent: true }` option.
  *
- * @see {@link zipWith} for a version that combines the results with a custom function.
- * @see {@link validate} for a version that accumulates errors.
- *
  * **Example** (Combining two effects sequentially)
  *
  * ```ts
@@ -3627,6 +3696,8 @@ export const flip: <A, E, R>(self: Effect<A, E, R>) => Effect<E, A, R> = interna
  * // [ 1, 'hello' ]
  * ```
  *
+ * @see {@link zipWith} for a version that combines the results with a custom function.
+ * @see {@link validate} for a version that accumulates errors.
  * @category zipping
  * @since 2.0.0
  */
@@ -3638,17 +3709,16 @@ export const zip: {
   /**
    * Combines two effects into a single effect, producing a tuple with the results of both effects.
    *
+   * **Details**
+   *
    * The `zip` function executes the first effect (left) and then the second effect (right).
    * Once both effects succeed, their results are combined into a tuple.
    *
-   * **Concurrency**
+   * Concurrency:
    *
    * By default, `zip` processes the effects sequentially. To execute the effects concurrently,
    * use the `{ concurrent: true }` option.
    *
-   * @see {@link zipWith} for a version that combines the results with a custom function.
-   * @see {@link validate} for a version that accumulates errors.
-   *
    * **Example** (Combining two effects sequentially)
    *
    * ```ts
@@ -3700,6 +3770,8 @@ export const zip: {
    * // [ 1, 'hello' ]
    * ```
    *
+   * @see {@link zipWith} for a version that combines the results with a custom function.
+   * @see {@link validate} for a version that accumulates errors.
    * @category zipping
    * @since 2.0.0
    */
@@ -3714,17 +3786,16 @@ export const zip: {
   /**
    * Combines two effects into a single effect, producing a tuple with the results of both effects.
    *
+   * **Details**
+   *
    * The `zip` function executes the first effect (left) and then the second effect (right).
    * Once both effects succeed, their results are combined into a tuple.
    *
-   * **Concurrency**
+   * Concurrency:
    *
    * By default, `zip` processes the effects sequentially. To execute the effects concurrently,
    * use the `{ concurrent: true }` option.
    *
-   * @see {@link zipWith} for a version that combines the results with a custom function.
-   * @see {@link validate} for a version that accumulates errors.
-   *
    * **Example** (Combining two effects sequentially)
    *
    * ```ts
@@ -3776,6 +3847,8 @@ export const zip: {
    * // [ 1, 'hello' ]
    * ```
    *
+   * @see {@link zipWith} for a version that combines the results with a custom function.
+   * @see {@link validate} for a version that accumulates errors.
    * @category zipping
    * @since 2.0.0
    */
@@ -3790,13 +3863,15 @@ export const zip: {
  * Combines two effects sequentially and applies a function to their results to
  * produce a single value.
  *
- * **When to Use**
+ * **When to use**
  *
  * The `zipWith` function is similar to {@link zip}, but instead of returning a
  * tuple of results, it applies a provided function to the results of the two
  * effects, combining them into a single value.
  *
- * **Concurrency**
+ * **Details**
+ *
+ * Concurrency:
  *
  * By default, the effects are run sequentially. To execute them concurrently,
  * use the `{ concurrent: true }` option.
@@ -3837,13 +3912,15 @@ export const zipWith: {
    * Combines two effects sequentially and applies a function to their results to
    * produce a single value.
    *
-   * **When to Use**
+   * **When to use**
    *
    * The `zipWith` function is similar to {@link zip}, but instead of returning a
    * tuple of results, it applies a provided function to the results of the two
    * effects, combining them into a single value.
    *
-   * **Concurrency**
+   * **Details**
+   *
+   * Concurrency:
    *
    * By default, the effects are run sequentially. To execute them concurrently,
    * use the `{ concurrent: true }` option.
@@ -3888,13 +3965,15 @@ export const zipWith: {
    * Combines two effects sequentially and applies a function to their results to
    * produce a single value.
    *
-   * **When to Use**
+   * **When to use**
    *
    * The `zipWith` function is similar to {@link zip}, but instead of returning a
    * tuple of results, it applies a provided function to the results of the two
    * effects, combining them into a single value.
    *
-   * **Concurrency**
+   * **Details**
+   *
+   * Concurrency:
    *
    * By default, the effects are run sequentially. To execute them concurrently,
    * use the `{ concurrent: true }` option.
@@ -3978,7 +4057,7 @@ export {
  * Catches and handles specific errors by their `_tag` field, which is used as a
  * discriminator.
  *
- * **When to Use**
+ * **When to use**
  *
  * `catchTag` is useful when your errors are tagged with a readonly `_tag` field
  * that identifies the error type. You can use this function to handle specific
@@ -4020,7 +4099,7 @@ export const catchTag: {
    * Catches and handles specific errors by their `_tag` field, which is used as a
    * discriminator.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `catchTag` is useful when your errors are tagged with a readonly `_tag` field
    * that identifies the error type. You can use this function to handle specific
@@ -4077,7 +4156,7 @@ export const catchTag: {
    * Catches and handles specific errors by their `_tag` field, which is used as a
    * discriminator.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `catchTag` is useful when your errors are tagged with a readonly `_tag` field
    * that identifies the error type. You can use this function to handle specific
@@ -4138,7 +4217,7 @@ export const catchTag: {
 /**
  * Handles multiple errors in a single block of code using their `_tag` field.
  *
- * **When to Use**
+ * **When to use**
  *
  * `catchTags` is a convenient way to handle multiple error types at
  * once. Instead of using {@link catchTag} multiple times, you can pass an
@@ -4182,7 +4261,7 @@ export const catchTags: {
   /**
    * Handles multiple errors in a single block of code using their `_tag` field.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `catchTags` is a convenient way to handle multiple error types at
    * once. Instead of using {@link catchTag} multiple times, you can pass an
@@ -4254,7 +4333,7 @@ export const catchTags: {
   /**
    * Handles multiple errors in a single block of code using their `_tag` field.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `catchTags` is a convenient way to handle multiple error types at
    * once. Instead of using {@link catchTag} multiple times, you can pass an
@@ -4329,6 +4408,8 @@ export const catchTags: {
 /**
  * Catches a specific reason within a tagged error.
  *
+ * **Details**
+ *
  * Use this to handle nested error causes without removing the parent error
  * from the error channel. The handler receives the unwrapped reason.
  *
@@ -4366,6 +4447,8 @@ export const catchReason: {
   /**
    * Catches a specific reason within a tagged error.
    *
+   * **Details**
+   *
    * Use this to handle nested error causes without removing the parent error
    * from the error channel. The handler receives the unwrapped reason.
    *
@@ -4428,6 +4511,8 @@ export const catchReason: {
   /**
    * Catches a specific reason within a tagged error.
    *
+   * **Details**
+   *
    * Use this to handle nested error causes without removing the parent error
    * from the error channel. The handler receives the unwrapped reason.
    *
@@ -4676,6 +4761,8 @@ export const catchReasons: {
 /**
  * Type helper that keeps only error tags whose tagged error contains a tagged `reason` field.
  *
+ * **Details**
+ *
  * Used by `catchReasons` and `unwrapReason` to constrain the parent error tag to reason-bearing errors.
  *
  * @category error handling
@@ -4795,14 +4882,16 @@ export const unwrapReason: {
  * Handles both recoverable and unrecoverable errors by providing a recovery
  * effect.
  *
- * **When to Use**
+ * **When to use**
  *
  * The `catchCause` function allows you to handle all errors, including
  * unrecoverable defects, by providing a recovery effect. The recovery logic is
  * based on the `Cause` of the error, which provides detailed information about
  * the failure.
  *
- * **When to Recover from Defects**
+ * **Details**
+ *
+ * When to Recover from Defects:
  *
  * Defects are unexpected errors that typically shouldn't be recovered from, as
  * they often indicate serious issues. However, in some cases, such as
@@ -4835,14 +4924,16 @@ export const catchCause: {
    * Handles both recoverable and unrecoverable errors by providing a recovery
    * effect.
    *
-   * **When to Use**
+   * **When to use**
    *
    * The `catchCause` function allows you to handle all errors, including
    * unrecoverable defects, by providing a recovery effect. The recovery logic is
    * based on the `Cause` of the error, which provides detailed information about
    * the failure.
    *
-   * **When to Recover from Defects**
+   * **Details**
+   *
+   * When to Recover from Defects:
    *
    * Defects are unexpected errors that typically shouldn't be recovered from, as
    * they often indicate serious issues. However, in some cases, such as
@@ -4875,14 +4966,16 @@ export const catchCause: {
    * Handles both recoverable and unrecoverable errors by providing a recovery
    * effect.
    *
-   * **When to Use**
+   * **When to use**
    *
    * The `catchCause` function allows you to handle all errors, including
    * unrecoverable defects, by providing a recovery effect. The recovery logic is
    * based on the `Cause` of the error, which provides detailed information about
    * the failure.
    *
-   * **When to Recover from Defects**
+   * **Details**
+   *
+   * When to Recover from Defects:
    *
    * Defects are unexpected errors that typically shouldn't be recovered from, as
    * they often indicate serious issues. However, in some cases, such as
@@ -4916,7 +5009,7 @@ export const catchCause: {
 /**
  * Recovers from defects using a provided recovery function.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use this sparingly, usually at integration boundaries where defects must be
  * reported or translated for an external system.
@@ -4926,7 +5019,7 @@ export const catchCause: {
  * `catchDefect` handles unexpected defects, such as thrown exceptions or
  * values passed to `die`, without catching typed failures or interruptions.
  *
- * **When to Recover from Defects**
+ * When to Recover from Defects:
  *
  * Defects are unexpected errors that typically should not be recovered from, as
  * they often indicate serious issues. In some cases, such as dynamically loaded
@@ -4957,7 +5050,7 @@ export const catchDefect: {
   /**
    * Recovers from defects using a provided recovery function.
    *
-   * **When to Use**
+   * **When to use**
    *
    * Use this sparingly, usually at integration boundaries where defects must be
    * reported or translated for an external system.
@@ -4967,7 +5060,7 @@ export const catchDefect: {
    * `catchDefect` handles unexpected defects, such as thrown exceptions or
    * values passed to `die`, without catching typed failures or interruptions.
    *
-   * **When to Recover from Defects**
+   * When to Recover from Defects:
    *
    * Defects are unexpected errors that typically should not be recovered from, as
    * they often indicate serious issues. In some cases, such as dynamically loaded
@@ -4998,7 +5091,7 @@ export const catchDefect: {
   /**
    * Recovers from defects using a provided recovery function.
    *
-   * **When to Use**
+   * **When to use**
    *
    * Use this sparingly, usually at integration boundaries where defects must be
    * reported or translated for an external system.
@@ -5008,7 +5101,7 @@ export const catchDefect: {
    * `catchDefect` handles unexpected defects, such as thrown exceptions or
    * values passed to `die`, without catching typed failures or interruptions.
    *
-   * **When to Recover from Defects**
+   * When to Recover from Defects:
    *
    * Defects are unexpected errors that typically should not be recovered from, as
    * they often indicate serious issues. In some cases, such as dynamically loaded
@@ -5041,7 +5134,7 @@ export const catchDefect: {
 /**
  * Recovers from specific errors using a `Predicate` or `Refinement`.
  *
- * **When to Use**
+ * **When to use**
  *
  * `catchIf` lets you recover from errors that match a condition. Use a
  * `Refinement` for type narrowing or a `Predicate` for simple boolean
@@ -5081,7 +5174,7 @@ export const catchIf: {
   /**
    * Recovers from specific errors using a `Predicate` or `Refinement`.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `catchIf` lets you recover from errors that match a condition. Use a
    * `Refinement` for type narrowing or a `Predicate` for simple boolean
@@ -5125,7 +5218,7 @@ export const catchIf: {
   /**
    * Recovers from specific errors using a `Predicate` or `Refinement`.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `catchIf` lets you recover from errors that match a condition. Use a
    * `Refinement` for type narrowing or a `Predicate` for simple boolean
@@ -5169,7 +5262,7 @@ export const catchIf: {
   /**
    * Recovers from specific errors using a `Predicate` or `Refinement`.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `catchIf` lets you recover from errors that match a condition. Use a
    * `Refinement` for type narrowing or a `Predicate` for simple boolean
@@ -5214,7 +5307,7 @@ export const catchIf: {
   /**
    * Recovers from specific errors using a `Predicate` or `Refinement`.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `catchIf` lets you recover from errors that match a condition. Use a
    * `Refinement` for type narrowing or a `Predicate` for simple boolean
@@ -5293,6 +5386,8 @@ export const catchFilter: {
 /**
  * Catches `NoSuchElementError` failures and converts them to `Option.none`.
  *
+ * **Details**
+ *
  * Success values become `Option.some`, `NoSuchElementError` becomes
  * `Option.none`, and all other errors are preserved.
  *
@@ -5318,6 +5413,8 @@ export const catchNoSuchElement: <A, E, R>(
 /**
  * Recovers from specific failures based on a predicate.
  *
+ * **Details**
+ *
  * This function allows you to conditionally catch and recover from failures
  * that match a specific predicate. This is useful when you want to handle
  * only certain types of errors while letting others propagate.
@@ -5352,6 +5449,8 @@ export const catchCauseIf: {
   /**
    * Recovers from specific failures based on a predicate.
    *
+   * **Details**
+   *
    * This function allows you to conditionally catch and recover from failures
    * that match a specific predicate. This is useful when you want to handle
    * only certain types of errors while letting others propagate.
@@ -5389,6 +5488,8 @@ export const catchCauseIf: {
   /**
    * Recovers from specific failures based on a predicate.
    *
+   * **Details**
+   *
    * This function allows you to conditionally catch and recover from failures
    * that match a specific predicate. This is useful when you want to handle
    * only certain types of errors while letting others propagate.
@@ -5460,15 +5561,13 @@ export const catchCauseFilter: {
  * The `mapError` function is used to transform or modify the error
  * produced by an effect, without affecting its success value.
  *
+ * **Details**
+ *
  * This function is helpful when you want to enhance the error with additional
  * information, change the error type, or apply custom error handling while
  * keeping the original behavior of the effect's success values intact. It only
  * operates on the error channel and leaves the success channel unchanged.
  *
- * @see {@link map} for a version that operates on the success channel.
- * @see {@link mapBoth} for a version that operates on both channels.
- * @see {@link mapError} if you want to replace the error with a new one.
- *
  * **Example** (Transforming the error channel)
  *
  * ```ts
@@ -5488,6 +5587,9 @@ export const catchCauseFilter: {
  * )
  * ```
  *
+ * @see {@link map} for a version that operates on the success channel.
+ * @see {@link mapBoth} for a version that operates on both channels.
+ * @see {@link mapError} if you want to replace the error with a new one.
  * @category error handling
  * @since 2.0.0
  */
@@ -5496,15 +5598,13 @@ export const mapError: {
    * The `mapError` function is used to transform or modify the error
    * produced by an effect, without affecting its success value.
    *
+   * **Details**
+   *
    * This function is helpful when you want to enhance the error with additional
    * information, change the error type, or apply custom error handling while
    * keeping the original behavior of the effect's success values intact. It only
    * operates on the error channel and leaves the success channel unchanged.
    *
-   * @see {@link map} for a version that operates on the success channel.
-   * @see {@link mapBoth} for a version that operates on both channels.
-   * @see {@link mapError} if you want to replace the error with a new one.
-   *
    * **Example** (Transforming the error channel)
    *
    * ```ts
@@ -5524,6 +5624,9 @@ export const mapError: {
    * )
    * ```
    *
+   * @see {@link map} for a version that operates on the success channel.
+   * @see {@link mapBoth} for a version that operates on both channels.
+   * @see {@link mapError} if you want to replace the error with a new one.
    * @category error handling
    * @since 2.0.0
    */
@@ -5532,15 +5635,13 @@ export const mapError: {
    * The `mapError` function is used to transform or modify the error
    * produced by an effect, without affecting its success value.
    *
+   * **Details**
+   *
    * This function is helpful when you want to enhance the error with additional
    * information, change the error type, or apply custom error handling while
    * keeping the original behavior of the effect's success values intact. It only
    * operates on the error channel and leaves the success channel unchanged.
    *
-   * @see {@link map} for a version that operates on the success channel.
-   * @see {@link mapBoth} for a version that operates on both channels.
-   * @see {@link mapError} if you want to replace the error with a new one.
-   *
    * **Example** (Transforming the error channel)
    *
    * ```ts
@@ -5560,6 +5661,9 @@ export const mapError: {
    * )
    * ```
    *
+   * @see {@link map} for a version that operates on the success channel.
+   * @see {@link mapBoth} for a version that operates on both channels.
+   * @see {@link mapError} if you want to replace the error with a new one.
    * @category error handling
    * @since 2.0.0
    */
@@ -5685,13 +5789,11 @@ export const mapBoth: {
  * Converts typed failures from the error channel into defects, removing the
  * error type from the returned effect.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `orDie` when a typed failure represents an unrecoverable bug or invalid
  * state and should not be handled as a recoverable error.
  *
- * @see {@link mapError} to transform the error before converting it into a defect with {@link orDie}.
- *
  * **Example** (Converting typed failures into defects)
  *
  * ```ts
@@ -5714,6 +5816,7 @@ export const mapBoth: {
  * //   ...stack trace...
  * ```
  *
+ * @see {@link mapError} to transform the error before converting it into a defect with {@link orDie}.
  * @category Converting Failures to Defects
  * @since 2.0.0
  */
@@ -5823,6 +5926,8 @@ export const tapError: {
 /**
  * Runs an effectful handler when a failure's `_tag` matches.
  *
+ * **Details**
+ *
  * Use this with tagged-union errors to perform side effects for one tag or a
  * list of tags. When the handler succeeds, the original failure is preserved;
  * if the handler fails, its error is also included in the returned effect.
@@ -5859,6 +5964,8 @@ export const tapErrorTag: {
   /**
    * Runs an effectful handler when a failure's `_tag` matches.
    *
+   * **Details**
+   *
    * Use this with tagged-union errors to perform side effects for one tag or a
    * list of tags. When the handler succeeds, the original failure is preserved;
    * if the handler fails, its error is also included in the returned effect.
@@ -5898,6 +6005,8 @@ export const tapErrorTag: {
   /**
    * Runs an effectful handler when a failure's `_tag` matches.
    *
+   * **Details**
+   *
    * Use this with tagged-union errors to perform side effects for one tag or a
    * list of tags. When the handler succeeds, the original failure is preserved;
    * if the handler fails, its error is also included in the returned effect.
@@ -6043,6 +6152,8 @@ export const tapCause: {
 /**
  * Conditionally executes a side effect based on the cause of a failed effect.
  *
+ * **Details**
+ *
  * This function allows you to tap into the cause of an effect's failure only when
  * the cause matches a specific predicate. This is useful for conditional logging,
  * monitoring, or other side effects based on the type of failure.
@@ -6073,6 +6184,8 @@ export const tapCauseIf: {
   /**
    * Conditionally executes a side effect based on the cause of a failed effect.
    *
+   * **Details**
+   *
    * This function allows you to tap into the cause of an effect's failure only when
    * the cause matches a specific predicate. This is useful for conditional logging,
    * monitoring, or other side effects based on the type of failure.
@@ -6106,6 +6219,8 @@ export const tapCauseIf: {
   /**
    * Conditionally executes a side effect based on the cause of a failed effect.
    *
+   * **Details**
+   *
    * This function allows you to tap into the cause of an effect's failure only when
    * the cause matches a specific predicate. This is useful for conditional logging,
    * monitoring, or other side effects based on the type of failure.
@@ -6318,6 +6433,8 @@ export const tapDefect: {
 /**
  * Retries an effect until it succeeds, discarding failures.
  *
+ * **Details**
+ *
  * Yields between attempts so other fibers can run.
  *
  * **Example** (Retrying until success)
@@ -6407,6 +6524,11 @@ export declare namespace Retry {
 /**
  * Retries typed failures from an effect according to a retry policy.
  *
+ * **When to use**
+ *
+ * Use `retry` when typed failures may be transient, such as network issues or
+ * temporary resource unavailability.
+ *
  * **Details**
  *
  * The policy can be a `Schedule`, a schedule builder, or a `Retry.Options`
@@ -6416,11 +6538,6 @@ export declare namespace Retry {
  *
  * Defects and interruptions are not retried as typed failures.
  *
- * **When to Use**
- *
- * Use `retry` when typed failures may be transient, such as network issues or
- * temporary resource unavailability.
- *
  * **Example** (Retrying with a schedule)
  *
  * ```ts
@@ -6447,7 +6564,6 @@ export declare namespace Retry {
  *
  * @see {@link retryOrElse} for a version that allows you to run a fallback.
  * @see {@link repeat} if your retry condition is based on successful outcomes rather than errors.
- *
  * @category error handling
  * @since 2.0.0
  */
@@ -6455,6 +6571,11 @@ export const retry: {
   /**
    * Retries typed failures from an effect according to a retry policy.
    *
+   * **When to use**
+   *
+   * Use `retry` when typed failures may be transient, such as network issues or
+   * temporary resource unavailability.
+   *
    * **Details**
    *
    * The policy can be a `Schedule`, a schedule builder, or a `Retry.Options`
@@ -6464,11 +6585,6 @@ export const retry: {
    *
    * Defects and interruptions are not retried as typed failures.
    *
-   * **When to Use**
-   *
-   * Use `retry` when typed failures may be transient, such as network issues or
-   * temporary resource unavailability.
-   *
    * **Example** (Retrying with a schedule)
    *
    * ```ts
@@ -6495,7 +6611,6 @@ export const retry: {
    *
    * @see {@link retryOrElse} for a version that allows you to run a fallback.
    * @see {@link repeat} if your retry condition is based on successful outcomes rather than errors.
-   *
    * @category error handling
    * @since 2.0.0
    */
@@ -6503,6 +6618,11 @@ export const retry: {
   /**
    * Retries typed failures from an effect according to a retry policy.
    *
+   * **When to use**
+   *
+   * Use `retry` when typed failures may be transient, such as network issues or
+   * temporary resource unavailability.
+   *
    * **Details**
    *
    * The policy can be a `Schedule`, a schedule builder, or a `Retry.Options`
@@ -6512,11 +6632,6 @@ export const retry: {
    *
    * Defects and interruptions are not retried as typed failures.
    *
-   * **When to Use**
-   *
-   * Use `retry` when typed failures may be transient, such as network issues or
-   * temporary resource unavailability.
-   *
    * **Example** (Retrying with a schedule)
    *
    * ```ts
@@ -6543,7 +6658,6 @@ export const retry: {
    *
    * @see {@link retryOrElse} for a version that allows you to run a fallback.
    * @see {@link repeat} if your retry condition is based on successful outcomes rather than errors.
-   *
    * @category error handling
    * @since 2.0.0
    */
@@ -6551,6 +6665,11 @@ export const retry: {
   /**
    * Retries typed failures from an effect according to a retry policy.
    *
+   * **When to use**
+   *
+   * Use `retry` when typed failures may be transient, such as network issues or
+   * temporary resource unavailability.
+   *
    * **Details**
    *
    * The policy can be a `Schedule`, a schedule builder, or a `Retry.Options`
@@ -6560,11 +6679,6 @@ export const retry: {
    *
    * Defects and interruptions are not retried as typed failures.
    *
-   * **When to Use**
-   *
-   * Use `retry` when typed failures may be transient, such as network issues or
-   * temporary resource unavailability.
-   *
    * **Example** (Retrying with a schedule)
    *
    * ```ts
@@ -6591,7 +6705,6 @@ export const retry: {
    *
    * @see {@link retryOrElse} for a version that allows you to run a fallback.
    * @see {@link repeat} if your retry condition is based on successful outcomes rather than errors.
-   *
    * @category error handling
    * @since 2.0.0
    */
@@ -6603,6 +6716,11 @@ export const retry: {
   /**
    * Retries typed failures from an effect according to a retry policy.
    *
+   * **When to use**
+   *
+   * Use `retry` when typed failures may be transient, such as network issues or
+   * temporary resource unavailability.
+   *
    * **Details**
    *
    * The policy can be a `Schedule`, a schedule builder, or a `Retry.Options`
@@ -6612,11 +6730,6 @@ export const retry: {
    *
    * Defects and interruptions are not retried as typed failures.
    *
-   * **When to Use**
-   *
-   * Use `retry` when typed failures may be transient, such as network issues or
-   * temporary resource unavailability.
-   *
    * **Example** (Retrying with a schedule)
    *
    * ```ts
@@ -6643,7 +6756,6 @@ export const retry: {
    *
    * @see {@link retryOrElse} for a version that allows you to run a fallback.
    * @see {@link repeat} if your retry condition is based on successful outcomes rather than errors.
-   *
    * @category error handling
    * @since 2.0.0
    */
@@ -6651,6 +6763,11 @@ export const retry: {
   /**
    * Retries typed failures from an effect according to a retry policy.
    *
+   * **When to use**
+   *
+   * Use `retry` when typed failures may be transient, such as network issues or
+   * temporary resource unavailability.
+   *
    * **Details**
    *
    * The policy can be a `Schedule`, a schedule builder, or a `Retry.Options`
@@ -6660,11 +6777,6 @@ export const retry: {
    *
    * Defects and interruptions are not retried as typed failures.
    *
-   * **When to Use**
-   *
-   * Use `retry` when typed failures may be transient, such as network issues or
-   * temporary resource unavailability.
-   *
    * **Example** (Retrying with a schedule)
    *
    * ```ts
@@ -6691,7 +6803,6 @@ export const retry: {
    *
    * @see {@link retryOrElse} for a version that allows you to run a fallback.
    * @see {@link repeat} if your retry condition is based on successful outcomes rather than errors.
-   *
    * @category error handling
    * @since 2.0.0
    */
@@ -6699,6 +6810,11 @@ export const retry: {
   /**
    * Retries typed failures from an effect according to a retry policy.
    *
+   * **When to use**
+   *
+   * Use `retry` when typed failures may be transient, such as network issues or
+   * temporary resource unavailability.
+   *
    * **Details**
    *
    * The policy can be a `Schedule`, a schedule builder, or a `Retry.Options`
@@ -6708,11 +6824,6 @@ export const retry: {
    *
    * Defects and interruptions are not retried as typed failures.
    *
-   * **When to Use**
-   *
-   * Use `retry` when typed failures may be transient, such as network issues or
-   * temporary resource unavailability.
-   *
    * **Example** (Retrying with a schedule)
    *
    * ```ts
@@ -6739,7 +6850,6 @@ export const retry: {
    *
    * @see {@link retryOrElse} for a version that allows you to run a fallback.
    * @see {@link repeat} if your retry condition is based on successful outcomes rather than errors.
-   *
    * @category error handling
    * @since 2.0.0
    */
@@ -6754,6 +6864,11 @@ export const retry: {
 /**
  * Retries a failing effect and runs a fallback effect if retries are exhausted.
  *
+ * **When to use**
+ *
+ * This function is useful when you want to handle failures gracefully by
+ * specifying an alternative action after repeated failures.
+ *
  * **Details**
  *
  * The `Effect.retryOrElse` function attempts to retry a failing effect multiple
@@ -6762,13 +6877,6 @@ export const retry: {
  * If the retries are exhausted and the effect still fails, it runs a fallback
  * effect instead.
  *
- * **When to Use**
- *
- * This function is useful when you want to handle failures gracefully by
- * specifying an alternative action after repeated failures.
- *
- * @see {@link retry} for a version that does not run a fallback effect.
- *
  * **Example** (Falling back after retries are exhausted)
  *
  * ```ts
@@ -6805,6 +6913,7 @@ export const retry: {
  * // Network data
  * ```
  *
+ * @see {@link retry} for a version that does not run a fallback effect.
  * @category error handling
  * @since 2.0.0
  */
@@ -6812,6 +6921,11 @@ export const retryOrElse: {
   /**
    * Retries a failing effect and runs a fallback effect if retries are exhausted.
    *
+   * **When to use**
+   *
+   * This function is useful when you want to handle failures gracefully by
+   * specifying an alternative action after repeated failures.
+   *
    * **Details**
    *
    * The `Effect.retryOrElse` function attempts to retry a failing effect multiple
@@ -6820,13 +6934,6 @@ export const retryOrElse: {
    * If the retries are exhausted and the effect still fails, it runs a fallback
    * effect instead.
    *
-   * **When to Use**
-   *
-   * This function is useful when you want to handle failures gracefully by
-   * specifying an alternative action after repeated failures.
-   *
-   * @see {@link retry} for a version that does not run a fallback effect.
-   *
    * **Example** (Falling back after retries are exhausted)
    *
    * ```ts
@@ -6863,6 +6970,7 @@ export const retryOrElse: {
    * // Network data
    * ```
    *
+   * @see {@link retry} for a version that does not run a fallback effect.
    * @category error handling
    * @since 2.0.0
    */
@@ -6873,6 +6981,11 @@ export const retryOrElse: {
   /**
    * Retries a failing effect and runs a fallback effect if retries are exhausted.
    *
+   * **When to use**
+   *
+   * This function is useful when you want to handle failures gracefully by
+   * specifying an alternative action after repeated failures.
+   *
    * **Details**
    *
    * The `Effect.retryOrElse` function attempts to retry a failing effect multiple
@@ -6881,13 +6994,6 @@ export const retryOrElse: {
    * If the retries are exhausted and the effect still fails, it runs a fallback
    * effect instead.
    *
-   * **When to Use**
-   *
-   * This function is useful when you want to handle failures gracefully by
-   * specifying an alternative action after repeated failures.
-   *
-   * @see {@link retry} for a version that does not run a fallback effect.
-   *
    * **Example** (Falling back after retries are exhausted)
    *
    * ```ts
@@ -6924,6 +7030,7 @@ export const retryOrElse: {
    * // Network data
    * ```
    *
+   * @see {@link retry} for a version that does not run a fallback effect.
    * @category error handling
    * @since 2.0.0
    */
@@ -6972,7 +7079,7 @@ export const sandbox: <A, E, R>(
 /**
  * Discards both the success and failure values of an effect.
  *
- * **When to Use**
+ * **When to use**
  *
  * `ignore` allows you to run an effect without caring about its result, whether
  * it succeeds or fails. This is useful when you only care about the side
@@ -7029,6 +7136,8 @@ export const ignore: <
 /**
  * Ignores the effect's failure cause, including defects and interruptions.
  *
+ * **Details**
+ *
  * Use the `log` option to emit the full {@link Cause} when the effect fails,
  * and `message` to prepend a custom log message.
  *
@@ -7067,6 +7176,8 @@ export const ignoreCause: <
  * Apply an `ExecutionPlan` to an effect, retrying with step-provided resources
  * until it succeeds or the plan is exhausted.
  *
+ * **Details**
+ *
  * Each attempt updates `ExecutionPlan.CurrentMetadata` (attempt and step index),
  * and retry timing is derived per step (the first attempt uses the remaining
  * attempts schedule; later retries apply the step schedule at least once).
@@ -7102,6 +7213,8 @@ export const withExecutionPlan: {
    * Apply an `ExecutionPlan` to an effect, retrying with step-provided resources
    * until it succeeds or the plan is exhausted.
    *
+   * **Details**
+   *
    * Each attempt updates `ExecutionPlan.CurrentMetadata` (attempt and step index),
    * and retry timing is derived per step (the first attempt uses the remaining
    * attempts schedule; later retries apply the step schedule at least once).
@@ -7141,6 +7254,8 @@ export const withExecutionPlan: {
    * Apply an `ExecutionPlan` to an effect, retrying with step-provided resources
    * until it succeeds or the plan is exhausted.
    *
+   * **Details**
+   *
    * Each attempt updates `ExecutionPlan.CurrentMetadata` (attempt and step index),
    * and retry timing is derived per step (the first attempt uses the remaining
    * attempts schedule; later retries apply the step schedule at least once).
@@ -7180,6 +7295,8 @@ export const withExecutionPlan: {
 /**
  * Runs an effect and reports any errors to the configured `ErrorReporter`s.
  *
+ * **Details**
+ *
  * If the `defectsOnly` option is set to `true`, only defects (unrecoverable
  * errors) will be reported, while regular failures will be ignored.
  *
@@ -7325,6 +7442,12 @@ export const orElseSucceed: {
  * Runs a sequence of effects and returns the result of the first successful
  * one.
  *
+ * **When to use**
+ *
+ * Use `firstSuccessOf` when you have prioritized fallback strategies, such as
+ * attempting multiple APIs, reading configuration from several sources, or
+ * trying alternative resource locations in order.
+ *
  * **Details**
  *
  * This function executes the provided effects in sequence, stopping at the
@@ -7335,12 +7458,6 @@ export const orElseSucceed: {
  * effect. If the collection is empty, the returned effect defects with an
  * `Error` whose message is `"Received an empty collection of effects"`.
  *
- * **When to Use**
- *
- * Use `firstSuccessOf` when you have prioritized fallback strategies, such as
- * attempting multiple APIs, reading configuration from several sources, or
- * trying alternative resource locations in order.
- *
  * **Example** (Trying alternatives until one succeeds)
  *
  * ```ts
@@ -7377,14 +7494,14 @@ export const firstSuccessOf: <Eff extends Effect<any, any, any>>(
  * Adds a time limit to an effect, triggering a timeout if the effect exceeds
  * the duration.
  *
+ * **Details**
+ *
  * The `timeout` function allows you to specify a time limit for an
  * effect's execution. If the effect does not complete within the given time, a
  * `TimeoutException` is raised. This can be useful for controlling how long
  * your program waits for a task to finish, ensuring that it doesn't hang
  * indefinitely if the task takes too long.
  *
- * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
- *
  * **Example** (Failing when work takes too long)
  *
  * ```ts
@@ -7415,6 +7532,7 @@ export const firstSuccessOf: <Eff extends Effect<any, any, any>>(
  * // }
  * ```
  *
+ * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
  * @category Delays & Timeouts
  * @since 2.0.0
  */
@@ -7427,14 +7545,14 @@ export const timeout: {
    * Adds a time limit to an effect, triggering a timeout if the effect exceeds
    * the duration.
    *
+   * **Details**
+   *
    * The `timeout` function allows you to specify a time limit for an
    * effect's execution. If the effect does not complete within the given time, a
    * `TimeoutException` is raised. This can be useful for controlling how long
    * your program waits for a task to finish, ensuring that it doesn't hang
    * indefinitely if the task takes too long.
    *
-   * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
-   *
    * **Example** (Failing when work takes too long)
    *
    * ```ts
@@ -7465,6 +7583,7 @@ export const timeout: {
    * // }
    * ```
    *
+   * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
    * @category Delays & Timeouts
    * @since 2.0.0
    */
@@ -7477,14 +7596,14 @@ export const timeout: {
    * Adds a time limit to an effect, triggering a timeout if the effect exceeds
    * the duration.
    *
+   * **Details**
+   *
    * The `timeout` function allows you to specify a time limit for an
    * effect's execution. If the effect does not complete within the given time, a
    * `TimeoutException` is raised. This can be useful for controlling how long
    * your program waits for a task to finish, ensuring that it doesn't hang
    * indefinitely if the task takes too long.
    *
-   * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
-   *
    * **Example** (Failing when work takes too long)
    *
    * ```ts
@@ -7515,6 +7634,7 @@ export const timeout: {
    * // }
    * ```
    *
+   * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
    * @category Delays & Timeouts
    * @since 2.0.0
    */
@@ -7664,6 +7784,8 @@ export const timeoutOption: {
 /**
  * Applies a timeout to an effect, with a fallback effect executed if the timeout is reached.
  *
+ * **Details**
+ *
  * This function is useful when you want to set a maximum duration for an operation
  * and provide an alternative action if the timeout is exceeded.
  *
@@ -7702,6 +7824,8 @@ export const timeoutOrElse: {
   /**
    * Applies a timeout to an effect, with a fallback effect executed if the timeout is reached.
    *
+   * **Details**
+   *
    * This function is useful when you want to set a maximum duration for an operation
    * and provide an alternative action if the timeout is exceeded.
    *
@@ -7745,6 +7869,8 @@ export const timeoutOrElse: {
   /**
    * Applies a timeout to an effect, with a fallback effect executed if the timeout is reached.
    *
+   * **Details**
+   *
    * This function is useful when you want to set a maximum duration for an operation
    * and provide an alternative action if the timeout is exceeded.
    *
@@ -7884,6 +8010,8 @@ export const sleep: (duration: Duration.Input) => Effect<void> = internal.sleep
 /**
  * Measures the runtime of an effect and returns the duration with its result.
  *
+ * **Details**
+ *
  * The original success, failure, or interruption is preserved; only the success
  * value is paired with the duration.
  *
@@ -7911,6 +8039,11 @@ export const timed: <A, E, R>(self: Effect<A, E, R>) => Effect<[duration: Durati
 /**
  * Runs multiple effects concurrently and returns the first successful result.
  *
+ * **When to use**
+ *
+ * Use `raceAll` when early failures should be ignored until a success occurs
+ * or all effects fail.
+ *
  * **Details**
  *
  * Early failures do not finish the race; `raceAll` keeps waiting until one
@@ -7918,13 +8051,6 @@ export const timed: <A, E, R>(self: Effect<A, E, R>) => Effect<[duration: Durati
  * remaining effects are interrupted. If every effect fails, the returned effect
  * fails with a cause containing the collected failure reasons.
  *
- * **When to Use**
- *
- * Use `raceAll` when early failures should be ignored until a success occurs
- * or all effects fail.
- *
- * @see {@link race} for a version that handles only two effects.
- *
  * **Example** (Racing many effects)
  *
  * ```ts
@@ -7941,6 +8067,7 @@ export const timed: <A, E, R>(self: Effect<A, E, R>) => Effect<[duration: Durati
  * // Result: "Fast" (after ~100ms)
  * ```
  *
+ * @see {@link race} for a version that handles only two effects.
  * @category Racing
  * @since 2.0.0
  */
@@ -7998,6 +8125,8 @@ export const raceAllFirst: <Eff extends Effect<any, any, any>>(
 /**
  * Races two effects and returns the first successful result.
  *
+ * **Details**
+ *
  * If one effect succeeds, the other is interrupted and `onWinner` can observe the
  * winning fiber. If both fail, the race fails.
  *
@@ -8025,6 +8154,8 @@ export const race: {
   /**
    * Races two effects and returns the first successful result.
    *
+   * **Details**
+   *
    * If one effect succeeds, the other is interrupted and `onWinner` can observe the
    * winning fiber. If both fail, the race fails.
    *
@@ -8059,6 +8190,8 @@ export const race: {
   /**
    * Races two effects and returns the first successful result.
    *
+   * **Details**
+   *
    * If one effect succeeds, the other is interrupted and `onWinner` can observe the
    * winning fiber. If both fail, the race fails.
    *
@@ -8097,6 +8230,8 @@ export const race: {
  * Races two effects and returns the result of the first one to complete, whether
  * it succeeds or fails.
  *
+ * **Details**
+ *
  * The losing effect is interrupted, and `onWinner` can observe the winning fiber.
  *
  * **Example** (Observing the winning fiber)
@@ -8127,6 +8262,8 @@ export const raceFirst: {
    * Races two effects and returns the result of the first one to complete, whether
    * it succeeds or fails.
    *
+   * **Details**
+   *
    * The losing effect is interrupted, and `onWinner` can observe the winning fiber.
    *
    * **Example** (Observing the winning fiber)
@@ -8164,6 +8301,8 @@ export const raceFirst: {
    * Races two effects and returns the result of the first one to complete, whether
    * it succeeds or fails.
    *
+   * **Details**
+   *
    * The losing effect is interrupted, and `onWinner` can observe the winning fiber.
    *
    * **Example** (Observing the winning fiber)
@@ -8994,6 +9133,11 @@ export const filterMapOrFail: {
  * Conditionally runs an effect based on the result of an effectful boolean
  * condition.
  *
+ * **When to use**
+ *
+ * Use this when an effectful check decides whether to run another effect while
+ * representing the skipped case explicitly.
+ *
  * **Details**
  *
  * The condition effect is evaluated first. If it succeeds with `true`, the
@@ -9001,11 +9145,6 @@ export const filterMapOrFail: {
  * succeeds with `false`, the source effect is skipped and the result is
  * `Option.none`. If the condition effect fails, that failure is preserved.
  *
- * **When to Use**
- *
- * Use this when an effectful check decides whether to run another effect while
- * representing the skipped case explicitly.
- *
  * **Example** (Conditionally running an effect)
  *
  * ```ts
@@ -9024,7 +9163,6 @@ export const filterMapOrFail: {
  * ```
  *
  * @see {@link when} for conditional execution with a boolean condition.
- *
  * @category Conditional Operators
  * @since 2.0.0
  */
@@ -9037,6 +9175,11 @@ export const when: {
    * Conditionally runs an effect based on the result of an effectful boolean
    * condition.
    *
+   * **When to use**
+   *
+   * Use this when an effectful check decides whether to run another effect while
+   * representing the skipped case explicitly.
+   *
    * **Details**
    *
    * The condition effect is evaluated first. If it succeeds with `true`, the
@@ -9044,11 +9187,6 @@ export const when: {
    * succeeds with `false`, the source effect is skipped and the result is
    * `Option.none`. If the condition effect fails, that failure is preserved.
    *
-   * **When to Use**
-   *
-   * Use this when an effectful check decides whether to run another effect while
-   * representing the skipped case explicitly.
-   *
    * **Example** (Conditionally running an effect)
    *
    * ```ts
@@ -9067,7 +9205,6 @@ export const when: {
    * ```
    *
    * @see {@link when} for conditional execution with a boolean condition.
-   *
    * @category Conditional Operators
    * @since 2.0.0
    */
@@ -9080,6 +9217,11 @@ export const when: {
    * Conditionally runs an effect based on the result of an effectful boolean
    * condition.
    *
+   * **When to use**
+   *
+   * Use this when an effectful check decides whether to run another effect while
+   * representing the skipped case explicitly.
+   *
    * **Details**
    *
    * The condition effect is evaluated first. If it succeeds with `true`, the
@@ -9087,11 +9229,6 @@ export const when: {
    * succeeds with `false`, the source effect is skipped and the result is
    * `Option.none`. If the condition effect fails, that failure is preserved.
    *
-   * **When to Use**
-   *
-   * Use this when an effectful check decides whether to run another effect while
-   * representing the skipped case explicitly.
-   *
    * **Example** (Conditionally running an effect)
    *
    * ```ts
@@ -9110,7 +9247,6 @@ export const when: {
    * ```
    *
    * @see {@link when} for conditional execution with a boolean condition.
-   *
    * @category Conditional Operators
    * @since 2.0.0
    */
@@ -9125,6 +9261,11 @@ export const when: {
  * Handles both success and failure cases of an effect without performing side
  * effects.
  *
+ * **When to use**
+ *
+ * This is useful for structuring your code to respond differently to success or
+ * failure without triggering side effects.
+ *
  * **Details**
  *
  * `match` lets you define custom handlers for both success and failure
@@ -9132,13 +9273,6 @@ export const when: {
  * to process the result if the effect succeeds, or handle the error if the
  * effect fails.
  *
- * **When to Use**
- *
- * This is useful for structuring your code to respond differently to success or
- * failure without triggering side effects.
- *
- * @see {@link matchEffect} if you need to perform side effects in the handlers.
- *
  * **Example** (Matching success and failure values)
  *
  * ```ts
@@ -9171,6 +9305,7 @@ export const when: {
  * // Output: "failure: Uh oh!"
  * ```
  *
+ * @see {@link matchEffect} if you need to perform side effects in the handlers.
  * @category Pattern Matching
  * @since 2.0.0
  */
@@ -9183,6 +9318,11 @@ export const match: {
    * Handles both success and failure cases of an effect without performing side
    * effects.
    *
+   * **When to use**
+   *
+   * This is useful for structuring your code to respond differently to success or
+   * failure without triggering side effects.
+   *
    * **Details**
    *
    * `match` lets you define custom handlers for both success and failure
@@ -9190,14 +9330,7 @@ export const match: {
    * to process the result if the effect succeeds, or handle the error if the
    * effect fails.
    *
-   * **When to Use**
-   *
-   * This is useful for structuring your code to respond differently to success or
-   * failure without triggering side effects.
-   *
-   * @see {@link matchEffect} if you need to perform side effects in the handlers.
-   *
-   * **Example** (Matching success and failure values)
+   * **Example** (Matching success and failure values)
    *
    * ```ts
    * import { Data, Effect } from "effect"
@@ -9229,6 +9362,7 @@ export const match: {
    * // Output: "failure: Uh oh!"
    * ```
    *
+   * @see {@link matchEffect} if you need to perform side effects in the handlers.
    * @category Pattern Matching
    * @since 2.0.0
    */
@@ -9246,6 +9380,11 @@ export const match: {
    * Handles both success and failure cases of an effect without performing side
    * effects.
    *
+   * **When to use**
+   *
+   * This is useful for structuring your code to respond differently to success or
+   * failure without triggering side effects.
+   *
    * **Details**
    *
    * `match` lets you define custom handlers for both success and failure
@@ -9253,13 +9392,6 @@ export const match: {
    * to process the result if the effect succeeds, or handle the error if the
    * effect fails.
    *
-   * **When to Use**
-   *
-   * This is useful for structuring your code to respond differently to success or
-   * failure without triggering side effects.
-   *
-   * @see {@link matchEffect} if you need to perform side effects in the handlers.
-   *
    * **Example** (Matching success and failure values)
    *
    * ```ts
@@ -9292,6 +9424,7 @@ export const match: {
    * // Output: "failure: Uh oh!"
    * ```
    *
+   * @see {@link matchEffect} if you need to perform side effects in the handlers.
    * @category Pattern Matching
    * @since 2.0.0
    */
@@ -9308,6 +9441,12 @@ export const match: {
  * Handles both success and failure cases of an effect without performing side
  * effects, with eager evaluation for resolved effects.
  *
+ * **When to use**
+ *
+ * Use this 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.
+ *
  * **Details**
  *
  * `matchEager` works like `match` but provides better performance for resolved
@@ -9315,12 +9454,6 @@ export const match: {
  * the handlers immediately without fiber scheduling. For unresolved effects,
  * it falls back to the regular `match` behavior.
  *
- * **When to Use**
- *
- * Use this 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.
- *
  * **Example** (Pattern matching eagerly when possible)
  *
  * ```ts
@@ -9337,7 +9470,6 @@ export const match: {
  *
  * @see {@link match} for the non-eager version.
  * @see {@link matchEffect} if you need to perform side effects in the handlers.
- *
  * @category Pattern Matching
  * @since 4.0.0
  */
@@ -9346,6 +9478,12 @@ export const matchEager: {
    * Handles both success and failure cases of an effect without performing side
    * effects, with eager evaluation for resolved effects.
    *
+   * **When to use**
+   *
+   * Use this 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.
+   *
    * **Details**
    *
    * `matchEager` works like `match` but provides better performance for resolved
@@ -9353,12 +9491,6 @@ export const matchEager: {
    * the handlers immediately without fiber scheduling. For unresolved effects,
    * it falls back to the regular `match` behavior.
    *
-   * **When to Use**
-   *
-   * Use this 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.
-   *
    * **Example** (Pattern matching eagerly when possible)
    *
    * ```ts
@@ -9375,7 +9507,6 @@ export const matchEager: {
    *
    * @see {@link match} for the non-eager version.
    * @see {@link matchEffect} if you need to perform side effects in the handlers.
-   *
    * @category Pattern Matching
    * @since 4.0.0
    */
@@ -9389,6 +9520,12 @@ export const matchEager: {
    * Handles both success and failure cases of an effect without performing side
    * effects, with eager evaluation for resolved effects.
    *
+   * **When to use**
+   *
+   * Use this 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.
+   *
    * **Details**
    *
    * `matchEager` works like `match` but provides better performance for resolved
@@ -9396,12 +9533,6 @@ export const matchEager: {
    * the handlers immediately without fiber scheduling. For unresolved effects,
    * it falls back to the regular `match` behavior.
    *
-   * **When to Use**
-   *
-   * Use this 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.
-   *
    * **Example** (Pattern matching eagerly when possible)
    *
    * ```ts
@@ -9418,7 +9549,6 @@ export const matchEager: {
    *
    * @see {@link match} for the non-eager version.
    * @see {@link matchEffect} if you need to perform side effects in the handlers.
-   *
    * @category Pattern Matching
    * @since 4.0.0
    */
@@ -9434,17 +9564,17 @@ export const matchEager: {
 /**
  * Handles failures by matching the cause of failure.
  *
- * **Details**
- *
- * The `matchCause` function allows you to handle failures with access to the
- * full cause of the failure within a fiber.
- *
- * **When to Use**
+ * **When to use**
  *
  * 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.
  *
+ * **Details**
+ *
+ * The `matchCause` function allows you to handle failures with access to the
+ * full cause of the failure within a fiber.
+ *
  * **Example** (Matching on success or failure causes)
  *
  * ```ts
@@ -9464,7 +9594,6 @@ export const matchEager: {
  * @see {@link matchCauseEffect} if you need to perform side effects in the
  * handlers.
  * @see {@link match} if you don't need to handle the cause of the failure.
- *
  * @category Pattern Matching
  * @since 2.0.0
  */
@@ -9472,17 +9601,17 @@ export const matchCause: {
   /**
    * Handles failures by matching the cause of failure.
    *
-   * **Details**
-   *
-   * The `matchCause` function allows you to handle failures with access to the
-   * full cause of the failure within a fiber.
-   *
-   * **When to Use**
+   * **When to use**
    *
    * 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.
    *
+   * **Details**
+   *
+   * The `matchCause` function allows you to handle failures with access to the
+   * full cause of the failure within a fiber.
+   *
    * **Example** (Matching on success or failure causes)
    *
    * ```ts
@@ -9502,7 +9631,6 @@ export const matchCause: {
    * @see {@link matchCauseEffect} if you need to perform side effects in the
    * handlers.
    * @see {@link match} if you don't need to handle the cause of the failure.
-   *
    * @category Pattern Matching
    * @since 2.0.0
    */
@@ -9515,17 +9643,17 @@ export const matchCause: {
   /**
    * Handles failures by matching the cause of failure.
    *
-   * **Details**
-   *
-   * The `matchCause` function allows you to handle failures with access to the
-   * full cause of the failure within a fiber.
-   *
-   * **When to Use**
+   * **When to use**
    *
    * 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.
    *
+   * **Details**
+   *
+   * The `matchCause` function allows you to handle failures with access to the
+   * full cause of the failure within a fiber.
+   *
    * **Example** (Matching on success or failure causes)
    *
    * ```ts
@@ -9545,7 +9673,6 @@ export const matchCause: {
    * @see {@link matchCauseEffect} if you need to perform side effects in the
    * handlers.
    * @see {@link match} if you don't need to handle the cause of the failure.
-   *
    * @category Pattern Matching
    * @since 2.0.0
    */
@@ -9561,18 +9688,18 @@ export const matchCause: {
 /**
  * Handles failures by matching the cause of failure with eager evaluation.
  *
+ * **When to use**
+ *
+ * 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.
+ *
  * **Details**
  *
  * `matchCauseEager` works like `matchCause` but provides better performance for resolved
  * effects by immediately applying the matching function instead of deferring it
  * through the effect pipeline.
  *
- * **When to Use**
- *
- * 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.
- *
  * **Example** (Eagerly matching already completed effects)
  *
  * ```ts
@@ -9591,18 +9718,18 @@ export const matchCauseEager: {
   /**
    * Handles failures by matching the cause of failure with eager evaluation.
    *
+   * **When to use**
+   *
+   * 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.
+   *
    * **Details**
    *
    * `matchCauseEager` works like `matchCause` but provides better performance for resolved
    * effects by immediately applying the matching function instead of deferring it
    * through the effect pipeline.
    *
-   * **When to Use**
-   *
-   * 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.
-   *
    * **Example** (Eagerly matching already completed effects)
    *
    * ```ts
@@ -9626,18 +9753,18 @@ export const matchCauseEager: {
   /**
    * Handles failures by matching the cause of failure with eager evaluation.
    *
+   * **When to use**
+   *
+   * 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.
+   *
    * **Details**
    *
    * `matchCauseEager` works like `matchCause` but provides better performance for resolved
    * effects by immediately applying the matching function instead of deferring it
    * through the effect pipeline.
    *
-   * **When to Use**
-   *
-   * 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.
-   *
    * **Example** (Eagerly matching already completed effects)
    *
    * ```ts
@@ -9664,6 +9791,8 @@ export const matchCauseEager: {
 /**
  * Eagerly handles success or failure with effectful handlers when the effect is already resolved.
  *
+ * **Details**
+ *
  * If the effect is an `Exit`, the matching handler runs immediately; otherwise it behaves like
  * {@link matchCauseEffect}.
  *
@@ -9674,6 +9803,8 @@ export const matchCauseEffectEager: {
   /**
    * Eagerly handles success or failure with effectful handlers when the effect is already resolved.
    *
+   * **Details**
+   *
    * If the effect is an `Exit`, the matching handler runs immediately; otherwise it behaves like
    * {@link matchCauseEffect}.
    *
@@ -9689,6 +9820,8 @@ export const matchCauseEffectEager: {
   /**
    * Eagerly handles success or failure with effectful handlers when the effect is already resolved.
    *
+   * **Details**
+   *
    * If the effect is an `Exit`, the matching handler runs immediately; otherwise it behaves like
    * {@link matchCauseEffect}.
    *
@@ -9885,19 +10018,16 @@ export const matchCauseEffect: {
 /**
  * Handles both success and failure by running effectful handlers.
  *
+ * **When to use**
+ *
+ * Use this when the failure or success branch must run additional effects.
+ *
  * **Details**
  *
  * Use `matchEffect` when either branch needs to return an `Effect`, such as
  * performing logging, recovery, notification, or other effectful work. The
  * returned effect succeeds or fails according to the handler that is run.
  *
- * **When to Use**
- *
- * Use this when the failure or success branch must run additional effects.
- *
- * @see {@link match} if you don't need side effects and only want to handle the
- * result or failure.
- *
  * **Example** (Matching success and failure with effectful handlers)
  *
  * ```ts
@@ -9939,6 +10069,8 @@ export const matchCauseEffect: {
  * // failure: Uh oh!
  * ```
  *
+ * @see {@link match} if you don't need side effects and only want to handle the
+ * result or failure.
  * @category Pattern Matching
  * @since 2.0.0
  */
@@ -9946,19 +10078,16 @@ export const matchEffect: {
   /**
    * Handles both success and failure by running effectful handlers.
    *
+   * **When to use**
+   *
+   * Use this when the failure or success branch must run additional effects.
+   *
    * **Details**
    *
    * Use `matchEffect` when either branch needs to return an `Effect`, such as
    * performing logging, recovery, notification, or other effectful work. The
    * returned effect succeeds or fails according to the handler that is run.
    *
-   * **When to Use**
-   *
-   * Use this when the failure or success branch must run additional effects.
-   *
-   * @see {@link match} if you don't need side effects and only want to handle the
-   * result or failure.
-   *
    * **Example** (Matching success and failure with effectful handlers)
    *
    * ```ts
@@ -10000,6 +10129,8 @@ export const matchEffect: {
    * // failure: Uh oh!
    * ```
    *
+   * @see {@link match} if you don't need side effects and only want to handle the
+   * result or failure.
    * @category Pattern Matching
    * @since 2.0.0
    */
@@ -10012,19 +10143,16 @@ export const matchEffect: {
   /**
    * Handles both success and failure by running effectful handlers.
    *
+   * **When to use**
+   *
+   * Use this when the failure or success branch must run additional effects.
+   *
    * **Details**
    *
    * Use `matchEffect` when either branch needs to return an `Effect`, such as
    * performing logging, recovery, notification, or other effectful work. The
    * returned effect succeeds or fails according to the handler that is run.
    *
-   * **When to Use**
-   *
-   * Use this when the failure or success branch must run additional effects.
-   *
-   * @see {@link match} if you don't need side effects and only want to handle the
-   * result or failure.
-   *
    * **Example** (Matching success and failure with effectful handlers)
    *
    * ```ts
@@ -10066,6 +10194,8 @@ export const matchEffect: {
    * // failure: Uh oh!
    * ```
    *
+   * @see {@link match} if you don't need side effects and only want to handle the
+   * result or failure.
    * @category Pattern Matching
    * @since 2.0.0
    */
@@ -10085,6 +10215,8 @@ export const matchEffect: {
 /**
  * Determines whether an effect fails.
  *
+ * **Details**
+ *
  * Defects are not converted; if the effect dies, the resulting effect dies too.
  *
  * **Example** (Checking whether an effect fails)
@@ -10109,6 +10241,8 @@ export const isFailure: <A, E, R>(self: Effect<A, E, R>) => Effect<boolean, neve
 /**
  * Returns whether an effect completes successfully.
  *
+ * **Details**
+ *
  * Returns `false` for failures in the error channel, but defects still fail the
  * effect.
  *
@@ -10142,6 +10276,8 @@ export const isSuccess: <A, E, R>(self: Effect<A, E, R>) => Effect<boolean, neve
 /**
  * Returns the complete context.
  *
+ * **Details**
+ *
  * This function allows you to access all services that are currently available
  * in the effect's environment. This can be useful for debugging, introspection,
  * or when you need to pass the entire context to another function.
@@ -10183,6 +10319,8 @@ export const context: <R = never>() => Effect<Context.Context<R>, never, R> = in
 /**
  * Transforms the current context using the provided function.
  *
+ * **Details**
+ *
  * This function allows you to access the complete context and perform
  * computations based on all available services. This is useful when you need
  * to conditionally execute logic based on what services are available.
@@ -10832,6 +10970,8 @@ export const updateContext: {
  * Runs an effect with a service implementation transformed by the provided
  * function.
  *
+ * **Details**
+ *
  * The service must be available in the effect's context; `updateService`
  * replaces it for the wrapped effect with the value returned by the updater.
  *
@@ -10866,6 +11006,8 @@ export const updateService: {
    * Runs an effect with a service implementation transformed by the provided
    * function.
    *
+   * **Details**
+   *
    * The service must be available in the effect's context; `updateService`
    * replaces it for the wrapped effect with the value returned by the updater.
    *
@@ -10900,6 +11042,8 @@ export const updateService: {
    * Runs an effect with a service implementation transformed by the provided
    * function.
    *
+   * **Details**
+   *
    * The service must be available in the effect's context; `updateService`
    * replaces it for the wrapped effect with the value returned by the updater.
    *
@@ -10936,14 +11080,14 @@ export const updateService: {
  * The `provideService` function is used to provide an actual
  * implementation for a service in the context of an effect.
  *
+ * **Details**
+ *
  * This function allows you to associate a service with its implementation so
  * that it can be used in your program. You define the service (e.g., a random
  * number generator), and then you use `provideService` to link that
  * service to its implementation. Once the implementation is provided, the
  * effect can be run successfully without further requirements.
  *
- * @see {@link provide} for providing multiple layers to an effect.
- *
  * **Example** (Providing a service value)
  *
  * ```ts
@@ -10975,6 +11119,7 @@ export const updateService: {
  * // data
  * ```
  *
+ * @see {@link provide} for providing multiple layers to an effect.
  * @category Context
  * @since 2.0.0
  */
@@ -10983,14 +11128,14 @@ export const provideService: {
    * The `provideService` function is used to provide an actual
    * implementation for a service in the context of an effect.
    *
+   * **Details**
+   *
    * This function allows you to associate a service with its implementation so
    * that it can be used in your program. You define the service (e.g., a random
    * number generator), and then you use `provideService` to link that
    * service to its implementation. Once the implementation is provided, the
    * effect can be run successfully without further requirements.
    *
-   * @see {@link provide} for providing multiple layers to an effect.
-   *
    * **Example** (Providing a service value)
    *
    * ```ts
@@ -11022,6 +11167,7 @@ export const provideService: {
    * // data
    * ```
    *
+   * @see {@link provide} for providing multiple layers to an effect.
    * @category Context
    * @since 2.0.0
    */
@@ -11030,14 +11176,14 @@ export const provideService: {
      * The `provideService` function is used to provide an actual
      * implementation for a service in the context of an effect.
      *
+     * **Details**
+     *
      * This function allows you to associate a service with its implementation so
      * that it can be used in your program. You define the service (e.g., a random
      * number generator), and then you use `provideService` to link that
      * service to its implementation. Once the implementation is provided, the
      * effect can be run successfully without further requirements.
      *
-     * @see {@link provide} for providing multiple layers to an effect.
-     *
      * **Example** (Providing a service value)
      *
      * ```ts
@@ -11069,6 +11215,7 @@ export const provideService: {
      * // data
      * ```
      *
+     * @see {@link provide} for providing multiple layers to an effect.
      * @category Context
      * @since 2.0.0
      */
@@ -11077,14 +11224,14 @@ export const provideService: {
      * The `provideService` function is used to provide an actual
      * implementation for a service in the context of an effect.
      *
+     * **Details**
+     *
      * This function allows you to associate a service with its implementation so
      * that it can be used in your program. You define the service (e.g., a random
      * number generator), and then you use `provideService` to link that
      * service to its implementation. Once the implementation is provided, the
      * effect can be run successfully without further requirements.
      *
-     * @see {@link provide} for providing multiple layers to an effect.
-     *
      * **Example** (Providing a service value)
      *
      * ```ts
@@ -11116,6 +11263,7 @@ export const provideService: {
      * // data
      * ```
      *
+     * @see {@link provide} for providing multiple layers to an effect.
      * @category Context
      * @since 2.0.0
      */
@@ -11125,14 +11273,14 @@ export const provideService: {
    * The `provideService` function is used to provide an actual
    * implementation for a service in the context of an effect.
    *
+   * **Details**
+   *
    * This function allows you to associate a service with its implementation so
    * that it can be used in your program. You define the service (e.g., a random
    * number generator), and then you use `provideService` to link that
    * service to its implementation. Once the implementation is provided, the
    * effect can be run successfully without further requirements.
    *
-   * @see {@link provide} for providing multiple layers to an effect.
-   *
    * **Example** (Providing a service value)
    *
    * ```ts
@@ -11164,6 +11312,7 @@ export const provideService: {
    * // data
    * ```
    *
+   * @see {@link provide} for providing multiple layers to an effect.
    * @category Context
    * @since 2.0.0
    */
@@ -11172,14 +11321,14 @@ export const provideService: {
    * The `provideService` function is used to provide an actual
    * implementation for a service in the context of an effect.
    *
+   * **Details**
+   *
    * This function allows you to associate a service with its implementation so
    * that it can be used in your program. You define the service (e.g., a random
    * number generator), and then you use `provideService` to link that
    * service to its implementation. Once the implementation is provided, the
    * effect can be run successfully without further requirements.
    *
-   * @see {@link provide} for providing multiple layers to an effect.
-   *
    * **Example** (Providing a service value)
    *
    * ```ts
@@ -11211,6 +11360,7 @@ export const provideService: {
    * // data
    * ```
    *
+   * @see {@link provide} for providing multiple layers to an effect.
    * @category Context
    * @since 2.0.0
    */
@@ -11679,6 +11829,8 @@ export const acquireRelease: <A, E, R, R2>(
  * This function constructs a scoped resource from an Effect that acquires a
  * disposable value.
  *
+ * **Details**
+ *
  * The resource is automatically disposed when the surrounding
  * {@link Scope} is closed, using {@link Symbol.dispose} for
  * synchronous disposables or {@link Symbol.asyncDispose} for asynchronous
@@ -11688,8 +11840,6 @@ export const acquireRelease: <A, E, R, R2>(
  * JavaScript disposal protocal instead of requiring an explicit release
  * function.
  *
- * @see [JavaScript `using` declarations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using)
- *
  * **Example** (Acquiring a disposable resource)
  *
  * ```ts
@@ -11710,6 +11860,7 @@ export const acquireRelease: <A, E, R, R2>(
  * )
  * ```
  *
+ * @see [JavaScript `using` declarations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using)
  * @category resource management
  * @since 4.0.0
  */
@@ -11723,6 +11874,8 @@ export const acquireDisposable: <A extends AsyncDisposable | Disposable, E, R>(
  * etc.) will not be interrupted, and that the resource will always be released
  * when the `Effect` value completes execution.
  *
+ * **Details**
+ *
  * `acquireUseRelease` does the following:
  *
  *   1. Ensures that the `Effect` value that acquires the resource will not be
@@ -11800,6 +11953,8 @@ export const acquireUseRelease: <Resource, E, R, A, E2, R2, E3, R3>(
  * The finalizer is guaranteed to be run when the scope is closed, and it may
  * depend on the `Exit` value that the scope is closed with.
  *
+ * **Details**
+ *
  * Finalizers are useful for cleanup operations that must run regardless of
  * whether the effect succeeds or fails. They're commonly used for resource
  * cleanup, logging, or other side effects that should always occur.
@@ -11846,6 +12001,8 @@ export const addFinalizer: <R>(
  * specified `finalizer` is guaranteed to be executed, whether this effect
  * succeeds, fails, or is interrupted.
  *
+ * **Details**
+ *
  * For use cases that need access to the effect's result, see `onExit`.
  *
  * Finalizers offer very powerful guarantees, but they are low-level, and
@@ -11887,6 +12044,8 @@ export const ensuring: {
    * specified `finalizer` is guaranteed to be executed, whether this effect
    * succeeds, fails, or is interrupted.
    *
+   * **Details**
+   *
    * For use cases that need access to the effect's result, see `onExit`.
    *
    * Finalizers offer very powerful guarantees, but they are low-level, and
@@ -11928,6 +12087,8 @@ export const ensuring: {
    * specified `finalizer` is guaranteed to be executed, whether this effect
    * succeeds, fails, or is interrupted.
    *
+   * **Details**
+   *
    * For use cases that need access to the effect's result, see `onExit`.
    *
    * Finalizers offer very powerful guarantees, but they are low-level, and
@@ -12389,24 +12550,19 @@ export const onExitFilter: {
  * Returns an effect that lazily computes a result and caches it for subsequent
  * evaluations.
  *
- * **Details**
- *
- * This function wraps an effect and ensures that its result is computed only
- * once. Once the result is computed, it is cached, meaning that subsequent
- * evaluations of the same effect will return the cached result without
- * re-executing the logic.
- *
- * **When to Use**
+ * **When to use**
  *
  * 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.
  *
- * @see {@link cachedWithTTL} for a similar function that includes a
- * time-to-live duration for the cached value.
- * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
- * additional effect for manually invalidating the cached value.
+ * **Details**
+ *
+ * This function wraps an effect and ensures that its result is computed only
+ * once. Once the result is computed, it is cached, meaning that subsequent
+ * evaluations of the same effect will return the cached result without
+ * re-executing the logic.
  *
  * **Example** (Memoizing an effect until invalidated)
  *
@@ -12446,6 +12602,10 @@ export const onExitFilter: {
  * // result 3
  * ```
  *
+ * @see {@link cachedWithTTL} for a similar function that includes a
+ * time-to-live duration for the cached value.
+ * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
+ * additional effect for manually invalidating the cached value.
  * @category Caching
  * @since 2.0.0
  */
@@ -12455,6 +12615,17 @@ export const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
  * Returns an effect that caches its result for a specified `Duration`,
  * known as "timeToLive" (TTL).
  *
+ * **When to use**
+ *
+ * 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.
+ *
  * **Details**
  *
  * This function is used to cache the result of an effect for a specified amount
@@ -12467,22 +12638,6 @@ export const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
  * After the specified duration has passed, the cache expires, and the effect
  * will be recomputed upon the next evaluation.
  *
- * **When to Use**
- *
- * 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.
- *
- * @see {@link cached} for a similar function that caches the result
- * indefinitely.
- * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
- * additional effect for manually invalidating the cached value.
- *
  * **Example** (Memoizing an effect with TTL)
  *
  * ```ts
@@ -12515,6 +12670,10 @@ export const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
  * // result 2
  * ```
  *
+ * @see {@link cached} for a similar function that caches the result
+ * indefinitely.
+ * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
+ * additional effect for manually invalidating the cached value.
  * @category Caching
  * @since 2.0.0
  */
@@ -12523,6 +12682,17 @@ export const cachedWithTTL: {
    * Returns an effect that caches its result for a specified `Duration`,
    * known as "timeToLive" (TTL).
    *
+   * **When to use**
+   *
+   * 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.
+   *
    * **Details**
    *
    * This function is used to cache the result of an effect for a specified amount
@@ -12535,22 +12705,6 @@ export const cachedWithTTL: {
    * After the specified duration has passed, the cache expires, and the effect
    * will be recomputed upon the next evaluation.
    *
-   * **When to Use**
-   *
-   * 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.
-   *
-   * @see {@link cached} for a similar function that caches the result
-   * indefinitely.
-   * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
-   * additional effect for manually invalidating the cached value.
-   *
    * **Example** (Memoizing an effect with TTL)
    *
    * ```ts
@@ -12583,6 +12737,10 @@ export const cachedWithTTL: {
    * // result 2
    * ```
    *
+   * @see {@link cached} for a similar function that caches the result
+   * indefinitely.
+   * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
+   * additional effect for manually invalidating the cached value.
    * @category Caching
    * @since 2.0.0
    */
@@ -12591,19 +12749,7 @@ export const cachedWithTTL: {
    * Returns an effect that caches its result for a specified `Duration`,
    * known as "timeToLive" (TTL).
    *
-   * **Details**
-   *
-   * This function is used to cache the result of an effect for a specified amount
-   * of time. This means that the first time the effect is evaluated, its result
-   * is computed and stored.
-   *
-   * If the effect is evaluated again within the specified `timeToLive`, the
-   * cached result will be used, avoiding recomputation.
-   *
-   * After the specified duration has passed, the cache expires, and the effect
-   * will be recomputed upon the next evaluation.
-   *
-   * **When to Use**
+   * **When to use**
    *
    * 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.
@@ -12614,10 +12760,17 @@ export const cachedWithTTL: {
    * By caching the result, you can improve efficiency and reduce unnecessary
    * computations, especially in performance-critical applications.
    *
-   * @see {@link cached} for a similar function that caches the result
-   * indefinitely.
-   * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
-   * additional effect for manually invalidating the cached value.
+   * **Details**
+   *
+   * This function is used to cache the result of an effect for a specified amount
+   * of time. This means that the first time the effect is evaluated, its result
+   * is computed and stored.
+   *
+   * If the effect is evaluated again within the specified `timeToLive`, the
+   * cached result will be used, avoiding recomputation.
+   *
+   * After the specified duration has passed, the cache expires, and the effect
+   * will be recomputed upon the next evaluation.
    *
    * **Example** (Memoizing an effect with TTL)
    *
@@ -12651,6 +12804,10 @@ export const cachedWithTTL: {
    * // result 2
    * ```
    *
+   * @see {@link cached} for a similar function that caches the result
+   * indefinitely.
+   * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
+   * additional effect for manually invalidating the cached value.
    * @category Caching
    * @since 2.0.0
    */
@@ -12661,6 +12818,16 @@ export const cachedWithTTL: {
  * Caches an effect's result for a specified duration and allows manual
  * invalidation before expiration.
  *
+ * **When to use**
+ *
+ * Use this function when you have an effect whose result needs to be cached for
+ * a certain period, but you also want the option to refresh the cache manually
+ * before the expiration time.
+ *
+ * This is useful when you need to ensure that the cached data remains valid for
+ * a certain period but still want to invalidate it if the underlying data
+ * changes or if you want to force a recomputation.
+ *
  * **Details**
  *
  * This function behaves similarly to {@link cachedWithTTL} by caching the
@@ -12674,21 +12841,6 @@ export const cachedWithTTL: {
  * Once the cache is invalidated, the next time the effect is evaluated, the
  * result will be recomputed, and the cache will be refreshed.
  *
- * **When to Use**
- *
- * Use this function when you have an effect whose result needs to be cached for
- * a certain period, but you also want the option to refresh the cache manually
- * before the expiration time.
- *
- * This is useful when you need to ensure that the cached data remains valid for
- * a certain period but still want to invalidate it if the underlying data
- * changes or if you want to force a recomputation.
- *
- * @see {@link cached} for a similar function that caches the result
- * indefinitely.
- * @see {@link cachedWithTTL} for a similar function that caches the result for
- * a specified duration but does not include an effect for manual invalidation.
- *
  * **Example** (Memoizing with TTL and invalidation)
  *
  * ```ts
@@ -12724,6 +12876,10 @@ export const cachedWithTTL: {
  * // result 2
  * ```
  *
+ * @see {@link cached} for a similar function that caches the result
+ * indefinitely.
+ * @see {@link cachedWithTTL} for a similar function that caches the result for
+ * a specified duration but does not include an effect for manual invalidation.
  * @category Caching
  * @since 2.0.0
  */
@@ -12732,6 +12888,16 @@ export const cachedInvalidateWithTTL: {
    * Caches an effect's result for a specified duration and allows manual
    * invalidation before expiration.
    *
+   * **When to use**
+   *
+   * Use this function when you have an effect whose result needs to be cached for
+   * a certain period, but you also want the option to refresh the cache manually
+   * before the expiration time.
+   *
+   * This is useful when you need to ensure that the cached data remains valid for
+   * a certain period but still want to invalidate it if the underlying data
+   * changes or if you want to force a recomputation.
+   *
    * **Details**
    *
    * This function behaves similarly to {@link cachedWithTTL} by caching the
@@ -12745,21 +12911,6 @@ export const cachedInvalidateWithTTL: {
    * Once the cache is invalidated, the next time the effect is evaluated, the
    * result will be recomputed, and the cache will be refreshed.
    *
-   * **When to Use**
-   *
-   * Use this function when you have an effect whose result needs to be cached for
-   * a certain period, but you also want the option to refresh the cache manually
-   * before the expiration time.
-   *
-   * This is useful when you need to ensure that the cached data remains valid for
-   * a certain period but still want to invalidate it if the underlying data
-   * changes or if you want to force a recomputation.
-   *
-   * @see {@link cached} for a similar function that caches the result
-   * indefinitely.
-   * @see {@link cachedWithTTL} for a similar function that caches the result for
-   * a specified duration but does not include an effect for manual invalidation.
-   *
    * **Example** (Memoizing with TTL and invalidation)
    *
    * ```ts
@@ -12795,6 +12946,10 @@ export const cachedInvalidateWithTTL: {
    * // result 2
    * ```
    *
+   * @see {@link cached} for a similar function that caches the result
+   * indefinitely.
+   * @see {@link cachedWithTTL} for a similar function that caches the result for
+   * a specified duration but does not include an effect for manual invalidation.
    * @category Caching
    * @since 2.0.0
    */
@@ -12803,6 +12958,16 @@ export const cachedInvalidateWithTTL: {
    * Caches an effect's result for a specified duration and allows manual
    * invalidation before expiration.
    *
+   * **When to use**
+   *
+   * Use this function when you have an effect whose result needs to be cached for
+   * a certain period, but you also want the option to refresh the cache manually
+   * before the expiration time.
+   *
+   * This is useful when you need to ensure that the cached data remains valid for
+   * a certain period but still want to invalidate it if the underlying data
+   * changes or if you want to force a recomputation.
+   *
    * **Details**
    *
    * This function behaves similarly to {@link cachedWithTTL} by caching the
@@ -12816,21 +12981,6 @@ export const cachedInvalidateWithTTL: {
    * Once the cache is invalidated, the next time the effect is evaluated, the
    * result will be recomputed, and the cache will be refreshed.
    *
-   * **When to Use**
-   *
-   * Use this function when you have an effect whose result needs to be cached for
-   * a certain period, but you also want the option to refresh the cache manually
-   * before the expiration time.
-   *
-   * This is useful when you need to ensure that the cached data remains valid for
-   * a certain period but still want to invalidate it if the underlying data
-   * changes or if you want to force a recomputation.
-   *
-   * @see {@link cached} for a similar function that caches the result
-   * indefinitely.
-   * @see {@link cachedWithTTL} for a similar function that caches the result for
-   * a specified duration but does not include an effect for manual invalidation.
-   *
    * **Example** (Memoizing with TTL and invalidation)
    *
    * ```ts
@@ -12866,6 +13016,10 @@ export const cachedInvalidateWithTTL: {
    * // result 2
    * ```
    *
+   * @see {@link cached} for a similar function that caches the result
+   * indefinitely.
+   * @see {@link cachedWithTTL} for a similar function that caches the result for
+   * a specified duration but does not include an effect for manual invalidation.
    * @category Caching
    * @since 2.0.0
    */
@@ -13820,6 +13974,8 @@ export const repeatOrElse: {
 /**
  * Returns an array of `n` identical effects.
  *
+ * **Details**
+ *
  * Use with `Effect.all` to run the replicated effects and collect results.
  *
  * @category Collecting
@@ -13829,6 +13985,8 @@ export const replicate: {
   /**
    * Returns an array of `n` identical effects.
    *
+   * **Details**
+   *
    * Use with `Effect.all` to run the replicated effects and collect results.
    *
    * @category Collecting
@@ -13838,6 +13996,8 @@ export const replicate: {
   /**
    * Returns an array of `n` identical effects.
    *
+   * **Details**
+   *
    * Use with `Effect.all` to run the replicated effects and collect results.
    *
    * @category Collecting
@@ -13849,6 +14009,8 @@ export const replicate: {
 /**
  * Performs this effect `n` times and collects results with `Effect.all` semantics.
  *
+ * **Details**
+ *
  * Use `concurrency` to control parallelism and `discard: true` to ignore results.
  *
  * **Example** (Replicating an effect)
@@ -13869,6 +14031,8 @@ export const replicateEffect: {
   /**
    * Performs this effect `n` times and collects results with `Effect.all` semantics.
    *
+   * **Details**
+   *
    * Use `concurrency` to control parallelism and `discard: true` to ignore results.
    *
    * **Example** (Replicating an effect)
@@ -13892,6 +14056,8 @@ export const replicateEffect: {
   /**
    * Performs this effect `n` times and collects results with `Effect.all` semantics.
    *
+   * **Details**
+   *
    * Use `concurrency` to control parallelism and `discard: true` to ignore results.
    *
    * **Example** (Replicating an effect)
@@ -13915,6 +14081,8 @@ export const replicateEffect: {
   /**
    * Performs this effect `n` times and collects results with `Effect.all` semantics.
    *
+   * **Details**
+   *
    * Use `concurrency` to control parallelism and `discard: true` to ignore results.
    *
    * **Example** (Replicating an effect)
@@ -13939,6 +14107,8 @@ export const replicateEffect: {
   /**
    * Performs this effect `n` times and collects results with `Effect.all` semantics.
    *
+   * **Details**
+   *
    * Use `concurrency` to control parallelism and `discard: true` to ignore results.
    *
    * **Example** (Replicating an effect)
@@ -14780,6 +14950,8 @@ export const spanLinks: Effect<ReadonlyArray<SpanLink>> = internal.spanLinks
 /**
  * For all spans in this effect, add a link with the provided span.
  *
+ * **Details**
+ *
  * This is useful for connecting spans that are related but not in a direct
  * parent-child relationship. For example, you might want to link spans from
  * parallel operations or connect spans across different traces.
@@ -14833,6 +15005,8 @@ export const linkSpans: {
   /**
    * For all spans in this effect, add a link with the provided span.
    *
+   * **Details**
+   *
    * This is useful for connecting spans that are related but not in a direct
    * parent-child relationship. For example, you might want to link spans from
    * parallel operations or connect spans across different traces.
@@ -14889,6 +15063,8 @@ export const linkSpans: {
   /**
    * For all spans in this effect, add a link with the provided span.
    *
+   * **Details**
+   *
    * This is useful for connecting spans that are related but not in a direct
    * parent-child relationship. For example, you might want to link spans from
    * parallel operations or connect spans across different traces.
@@ -14975,6 +15151,8 @@ export const makeSpan: (name: string, options?: SpanOptionsNoTrace) => Effect<Sp
  * Create a new span for tracing, and automatically close it when the Scope
  * finalizes.
  *
+ * **Details**
+ *
  * The span is not added to the current span stack, so no child spans will be
  * created for it.
  *
@@ -15005,6 +15183,8 @@ export const makeSpanScoped: (
  * Create a new span for tracing, and automatically close it when the effect
  * completes.
  *
+ * **Details**
+ *
  * The span is not added to the current span stack, so no child spans will be
  * created for it.
  *
@@ -15031,6 +15211,8 @@ export const useSpan: {
    * Create a new span for tracing, and automatically close it when the effect
    * completes.
    *
+   * **Details**
+   *
    * The span is not added to the current span stack, so no child spans will be
    * created for it.
    *
@@ -15057,6 +15239,8 @@ export const useSpan: {
    * Create a new span for tracing, and automatically close it when the effect
    * completes.
    *
+   * **Details**
+   *
    * The span is not added to the current span stack, so no child spans will be
    * created for it.
    *
@@ -15163,6 +15347,8 @@ export const withSpan: {
 /**
  * Wraps the effect with a new span for tracing.
  *
+ * **Details**
+ *
  * The span is ended when the Scope is finalized.
  *
  * **Example** (Creating a scoped child span)
@@ -15186,6 +15372,8 @@ export const withSpanScoped: {
   /**
    * Wraps the effect with a new span for tracing.
    *
+   * **Details**
+   *
    * The span is ended when the Scope is finalized.
    *
    * **Example** (Creating a scoped child span)
@@ -15211,6 +15399,8 @@ export const withSpanScoped: {
   /**
    * Wraps the effect with a new span for tracing.
    *
+   * **Details**
+   *
    * The span is ended when the Scope is finalized.
    *
    * **Example** (Creating a scoped child span)
@@ -15409,6 +15599,8 @@ export const request: {
  * Low-level entry point that registers a request with a resolver and delivers the exit value via `onExit`.
  * Use this when you already have a `Context` and need to enqueue a request outside an `Effect`.
  *
+ * **Details**
+ *
  * It returns a canceler that removes the pending request entry.
  *
  * @category Requests & Batching
@@ -15432,6 +15624,8 @@ export const requestUnsafe: <A extends Request.Any>(
  * returning the fiber immediately, without waiting for it to begin executing
  * the effect.
  *
+ * **Details**
+ *
  * You can use the `forkChild` method whenever you want to execute an effect in a
  * new fiber, concurrently and without "blocking" the fiber executing other
  * effects. Using fibers can be tricky, so instead of using this method
@@ -15767,7 +15961,7 @@ export interface RunOptions {
  * The foundational function for running effects, returning a "fiber" that can
  * be observed or interrupted.
  *
- * **When to Use**
+ * **When to use**
  *
  * `runFork` is used to run an effect in the background by creating a
  * fiber. It is the base function for all other run functions. It starts a fiber
@@ -15840,6 +16034,8 @@ export const runForkWith: <R>(
 /**
  * Forks an effect with the provided services, registers `onExit` as a fiber observer, and returns an interruptor.
  *
+ * **Details**
+ *
  * The returned interruptor calls `fiber.interruptUnsafe`, optionally with an interruptor id.
  *
  * **Example** (Running with services and a callback)
@@ -15889,6 +16085,8 @@ export const runCallbackWith: <R>(
  * Runs an effect asynchronously, registering `onExit` as a fiber observer and
  * returning an interruptor.
  *
+ * **Details**
+ *
  * The interruptor calls `fiber.interruptUnsafe` with the optional interruptor
  * id.
  *
@@ -15931,7 +16129,7 @@ export const runCallback: <A, E>(
 /**
  * Executes an effect and returns the result as a `Promise`.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `runPromise` when you need to execute an effect and work with the
  * result using `Promise` syntax, typically for compatibility with other
@@ -15940,8 +16138,6 @@ export const runCallback: <A, E>(
  * If the effect succeeds, the promise will resolve with the result. If the
  * effect fails, the promise will reject with an error.
  *
- * @see {@link runPromiseExit} for a version that returns an `Exit` type instead of rejecting.
- *
  * **Example** (Running a successful effect as a Promise)
  *
  * ```ts
@@ -15962,6 +16158,7 @@ export const runCallback: <A, E>(
  * // (FiberFailure) Error: my error
  * ```
  *
+ * @see {@link runPromiseExit} for a version that returns an `Exit` type instead of rejecting.
  * @category Running Effects
  * @since 2.0.0
  */
@@ -16007,7 +16204,7 @@ export const runPromiseWith: <R>(
  * Runs an effect and returns a `Promise` that resolves to an `Exit`, which
  * represents the outcome (success or failure) of the effect.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `runPromiseExit` when you need to determine if an effect succeeded
  * or failed, including any defects, and you want to work with a `Promise`.
@@ -16096,7 +16293,7 @@ export const runPromiseExitWith: <R>(
 /**
  * Executes an effect synchronously and returns its success value.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `runSync` only for effects that can complete synchronously.
  *
@@ -16106,9 +16303,6 @@ export const runPromiseExitWith: <R>(
  * `runSync` throws a `FiberFailure` instead of returning a value. Use
  * `runSyncExit` when you want the failure captured as an `Exit`.
  *
- * @see {@link runSyncExit} for a version that returns an `Exit` type instead of
- * throwing an error.
- *
  * **Example** (Running a synchronous effect)
  *
  * ```ts
@@ -16150,6 +16344,8 @@ export const runPromiseExitWith: <R>(
  * // (FiberFailure) AsyncFiberException: Fiber #0 cannot be resolved synchronously. This is caused by using runSync on an effect that performs async work
  * ```
  *
+ * @see {@link runSyncExit} for a version that returns an `Exit` type instead of
+ * throwing an error.
  * @category Running Effects
  * @since 2.0.0
  */
@@ -16193,7 +16389,7 @@ export const runSyncWith: <R>(
  * Runs an effect synchronously and returns the result as an `Exit` type, which
  * represents the outcome (success or failure) of the effect.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `runSyncExit` to find out whether an effect succeeded or failed,
  * including any defects, without dealing with asynchronous operations.
@@ -16312,11 +16508,13 @@ export const runSyncExitWith: <R>(
 /**
  * Type helpers for functions built with `Effect.fn` and `Effect.fnUntraced`.
  *
+ * **Details**
+ *
  * Use these to describe generator-based signatures and traced or untraced variants.
  *
  * @since 3.11.0
  */
-export namespace fn {
+export declare namespace fn {
   /**
    * Generator return type accepted by `Effect.fn` and `Effect.fnUntraced`.
    *
@@ -20360,6 +20558,8 @@ export namespace fn {
 /**
  * Creates an Effect-returning function without tracing.
  *
+ * **Details**
+ *
  * `Effect.fnUntraced` also acts as a `pipe` function, so you can append transforms after the body.
  *
  * **Example** (Defining untraced effect functions)
@@ -20383,6 +20583,8 @@ export const fnUntraced: fn.Untraced = internal.fnUntraced
 /**
  * Creates a traced function with an optional span name and `SpanOptionsNoTrace` that adds spans and stack frames, plus pipeable post-processing that receives the Effect and the original arguments.
  *
+ * **Details**
+ *
  * Pipeable functions run after the body and can transform the resulting Effect.
  *
  * **Example** (Defining traced effect functions)
@@ -20451,6 +20653,8 @@ export const clockWith: <A, E, R>(
 /**
  * Creates a logger function that logs at the specified level.
  *
+ * **Details**
+ *
  * If no level is provided, the logger uses the fiber's current log level and
  * extracts any `Cause` values from the message list.
  *
@@ -20913,6 +21117,8 @@ export const annotateLogs = dual<
 /**
  * Adds log annotations to the current scope.
  *
+ * **Details**
+ *
  * This differs from `annotateLogs`, which only annotates a specific effect.
  * `annotateLogsScoped` updates annotations for the entire current `Scope` and
  * restores the previous annotations when the scope closes.
@@ -20940,6 +21146,8 @@ export const annotateLogsScoped: {
   /**
    * Adds log annotations to the current scope.
    *
+   * **Details**
+   *
    * This differs from `annotateLogs`, which only annotates a specific effect.
    * `annotateLogsScoped` updates annotations for the entire current `Scope` and
    * restores the previous annotations when the scope closes.
@@ -20967,6 +21175,8 @@ export const annotateLogsScoped: {
   /**
    * Adds log annotations to the current scope.
    *
+   * **Details**
+   *
    * This differs from `annotateLogs`, which only annotates a specific effect.
    * `annotateLogsScoped` updates annotations for the entire current `Scope` and
    * restores the previous annotations when the scope closes.
@@ -21106,6 +21316,8 @@ export const withLogSpan = dual<
 /**
  * Updates the `Metric` every time the `Effect` is executed.
  *
+ * **Details**
+ *
  * Also accepts an optional function which can be used to map the `Exit` value
  * of the `Effect` into a valid `Input` for the `Metric`.
  *
@@ -21161,6 +21373,8 @@ export const track: {
   /**
    * Updates the `Metric` every time the `Effect` is executed.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the `Exit` value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -21216,6 +21430,8 @@ export const track: {
   /**
    * Updates the `Metric` every time the `Effect` is executed.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the `Exit` value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -21271,6 +21487,8 @@ export const track: {
   /**
    * Updates the `Metric` every time the `Effect` is executed.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the `Exit` value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -21330,6 +21548,8 @@ export const track: {
   /**
    * Updates the `Metric` every time the `Effect` is executed.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the `Exit` value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -21398,6 +21618,8 @@ export const track: {
  * Updates the provided `Metric` every time the wrapped `Effect` succeeds with
  * a value.
  *
+ * **Details**
+ *
  * Also accepts an optional function which can be used to map the success value
  * of the `Effect` into a valid `Input` for the `Metric`.
  *
@@ -21446,6 +21668,8 @@ export const trackSuccesses: {
    * Updates the provided `Metric` every time the wrapped `Effect` succeeds with
    * a value.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the success value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -21494,6 +21718,8 @@ export const trackSuccesses: {
    * Updates the provided `Metric` every time the wrapped `Effect` succeeds with
    * a value.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the success value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -21542,6 +21768,8 @@ export const trackSuccesses: {
    * Updates the provided `Metric` every time the wrapped `Effect` succeeds with
    * a value.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the success value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -21594,6 +21822,8 @@ export const trackSuccesses: {
    * Updates the provided `Metric` every time the wrapped `Effect` succeeds with
    * a value.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the success value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -21655,6 +21885,8 @@ export const trackSuccesses: {
  * Updates the provided `Metric` every time the wrapped `Effect` fails with an
  * **expected** error.
  *
+ * **Details**
+ *
  * Also accepts an optional function which can be used to map the error value
  * of the `Effect` into a valid `Input` for the `Metric`.
  *
@@ -21705,6 +21937,8 @@ export const trackErrors: {
    * Updates the provided `Metric` every time the wrapped `Effect` fails with an
    * **expected** error.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the error value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -21755,6 +21989,8 @@ export const trackErrors: {
    * Updates the provided `Metric` every time the wrapped `Effect` fails with an
    * **expected** error.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the error value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -21805,6 +22041,8 @@ export const trackErrors: {
    * Updates the provided `Metric` every time the wrapped `Effect` fails with an
    * **expected** error.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the error value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -21859,6 +22097,8 @@ export const trackErrors: {
    * Updates the provided `Metric` every time the wrapped `Effect` fails with an
    * **expected** error.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the error value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -21922,6 +22162,8 @@ export const trackErrors: {
  * Updates the provided `Metric` every time the wrapped `Effect` fails with an
  * **unexpected** error (i.e. a defect).
  *
+ * **Details**
+ *
  * Also accepts an optional function which can be used to map the defect value
  * of the `Effect` into a valid `Input` for the `Metric`.
  *
@@ -21973,6 +22215,8 @@ export const trackDefects: {
    * Updates the provided `Metric` every time the wrapped `Effect` fails with an
    * **unexpected** error (i.e. a defect).
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the defect value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -22024,6 +22268,8 @@ export const trackDefects: {
    * Updates the provided `Metric` every time the wrapped `Effect` fails with an
    * **unexpected** error (i.e. a defect).
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the defect value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -22075,6 +22321,8 @@ export const trackDefects: {
    * Updates the provided `Metric` every time the wrapped `Effect` fails with an
    * **unexpected** error (i.e. a defect).
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the defect value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -22130,6 +22378,8 @@ export const trackDefects: {
    * Updates the provided `Metric` every time the wrapped `Effect` fails with an
    * **unexpected** error (i.e. a defect).
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the defect value
    * of the `Effect` into a valid `Input` for the `Metric`.
    *
@@ -22190,6 +22440,8 @@ export const trackDefects: {
  * Updates the provided `Metric` with the `Duration` of time (in nanoseconds)
  * that the wrapped `Effect` took to complete.
  *
+ * **Details**
+ *
  * Also accepts an optional function which can be used to map the `Duration`
  * that the wrapped `Effect` took to complete into a valid `Input` for the
  * `Metric`.
@@ -22237,6 +22489,8 @@ export const trackDuration: {
    * Updates the provided `Metric` with the `Duration` of time (in nanoseconds)
    * that the wrapped `Effect` took to complete.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the `Duration`
    * that the wrapped `Effect` took to complete into a valid `Input` for the
    * `Metric`.
@@ -22287,6 +22541,8 @@ export const trackDuration: {
    * Updates the provided `Metric` with the `Duration` of time (in nanoseconds)
    * that the wrapped `Effect` took to complete.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the `Duration`
    * that the wrapped `Effect` took to complete into a valid `Input` for the
    * `Metric`.
@@ -22334,6 +22590,8 @@ export const trackDuration: {
    * Updates the provided `Metric` with the `Duration` of time (in nanoseconds)
    * that the wrapped `Effect` took to complete.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the `Duration`
    * that the wrapped `Effect` took to complete into a valid `Input` for the
    * `Metric`.
@@ -22385,6 +22643,8 @@ export const trackDuration: {
    * Updates the provided `Metric` with the `Duration` of time (in nanoseconds)
    * that the wrapped `Effect` took to complete.
    *
+   * **Details**
+   *
    * Also accepts an optional function which can be used to map the `Duration`
    * that the wrapped `Effect` took to complete into a valid `Input` for the
    * `Metric`.
@@ -22456,6 +22716,8 @@ export const trackDuration: {
 /**
  * Service that holds the current transaction state, it includes
  *
+ * **Details**
+ *
  * - a journal that stores any non committed change to TxRef values
  * - a retry flag to know if the transaction should be retried
  *
@@ -22493,6 +22755,8 @@ export class Transaction extends Context.Service<
  * Defines a transaction boundary. Transactions are "all or nothing" with respect to changes
  * made to transactional values (i.e. TxRef) that occur within the transaction body.
  *
+ * **Details**
+ *
  * 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.
  *
@@ -22624,10 +22888,9 @@ function clearTransaction(state: Transaction["Service"]) {
 /**
  * Signals that the current transaction needs to be retried.
  *
- * NOTE: the transaction retries on any change to transactional values (i.e. TxRef) accessed in its body.
+ * **Details**
  *
- * @category Transactions
- * @since 4.0.0
+ * NOTE: the transaction retries on any change to transactional values (i.e. TxRef) accessed in its body.
  *
  * **Example** (Retrying transactions)
  *
@@ -22657,6 +22920,9 @@ function clearTransaction(state: Transaction["Service"]) {
  *
  * Effect.runPromise(program).catch(console.error)
  * ```
+ *
+ * @category Transactions
+ * @since 4.0.0
  */
 export const txRetry: Effect<never, never, Transaction> = flatMap(
   Transaction,
@@ -23138,6 +23404,8 @@ export const effectify: {
 /**
  * Ensures that an effect's success type extends a given type `A`.
  *
+ * **Details**
+ *
  * This function provides compile-time type checking to ensure that the success
  * value of an effect conforms to a specific type constraint.
  *
@@ -23166,6 +23434,8 @@ export const satisfiesSuccessType = <A>() => <A2 extends A, E, R>(effect: Effect
 /**
  * Ensures that an effect's error type extends a given type `E`.
  *
+ * **Details**
+ *
  * This function provides compile-time type checking to ensure that the error
  * type of an effect conforms to a specific type constraint.
  *
@@ -23196,6 +23466,8 @@ export const satisfiesErrorType = <E>() => <A, E2 extends E, R>(effect: Effect<A
 /**
  * Ensures that an effect's requirements type extends a given type `R`.
  *
+ * **Details**
+ *
  * This function provides compile-time type checking to ensure that the
  * requirements (context) type of an effect conforms to a specific type constraint.
  *
@@ -23225,13 +23497,15 @@ export const satisfiesServicesType = <R>() => <A, E, R2 extends R>(effect: Effec
  * An optimized version of `map` that checks if an effect is already resolved
  * and applies the mapping function eagerly when possible.
  *
- * **When to Use**
+ * **When to use**
  *
  * `mapEager` provides better performance for effects that are already resolved
  * by applying the transformation immediately instead of deferring it through
  * the effect pipeline.
  *
- * **Behavior**
+ * **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
@@ -23259,13 +23533,15 @@ export const mapEager: {
    * An optimized version of `map` that checks if an effect is already resolved
    * and applies the mapping function eagerly when possible.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `mapEager` provides better performance for effects that are already resolved
    * by applying the transformation immediately instead of deferring it through
    * the effect pipeline.
    *
-   * **Behavior**
+   * **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
@@ -23293,13 +23569,15 @@ export const mapEager: {
    * An optimized version of `map` that checks if an effect is already resolved
    * and applies the mapping function eagerly when possible.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `mapEager` provides better performance for effects that are already resolved
    * by applying the transformation immediately instead of deferring it through
    * the effect pipeline.
    *
-   * **Behavior**
+   * **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
@@ -23329,13 +23607,15 @@ export const mapEager: {
  * An optimized version of `mapError` that checks if an effect is already resolved
  * and applies the error mapping function eagerly when possible.
  *
- * **When to Use**
+ * **When to use**
  *
  * `mapErrorEager` provides better performance for effects that are already resolved
  * by applying the error transformation immediately instead of deferring it through
  * the effect pipeline.
  *
- * **Behavior**
+ * **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
@@ -23366,13 +23646,15 @@ export const mapErrorEager: {
    * An optimized version of `mapError` that checks if an effect is already resolved
    * and applies the error mapping function eagerly when possible.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `mapErrorEager` provides better performance for effects that are already resolved
    * by applying the error transformation immediately instead of deferring it through
    * the effect pipeline.
    *
-   * **Behavior**
+   * **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
@@ -23403,13 +23685,15 @@ export const mapErrorEager: {
    * An optimized version of `mapError` that checks if an effect is already resolved
    * and applies the error mapping function eagerly when possible.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `mapErrorEager` provides better performance for effects that are already resolved
    * by applying the error transformation immediately instead of deferring it through
    * the effect pipeline.
    *
-   * **Behavior**
+   * **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
@@ -23442,13 +23726,15 @@ export const mapErrorEager: {
  * An optimized version of `mapBoth` that checks if an effect is already resolved
  * and applies the appropriate mapping function eagerly when possible.
  *
- * **When to Use**
+ * **When to use**
  *
  * `mapBothEager` provides better performance for effects that are already resolved
  * by applying the transformation immediately instead of deferring it through
  * the effect pipeline.
  *
- * **Behavior**
+ * **Details**
+ *
+ * Behavior:
  *
  * - For **Success effects**: Applies the `onSuccess` function immediately to the value
  * - For **Failure effects**: Applies the `onFailure` function immediately to the error
@@ -23481,13 +23767,15 @@ export const mapBothEager: {
    * An optimized version of `mapBoth` that checks if an effect is already resolved
    * and applies the appropriate mapping function eagerly when possible.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `mapBothEager` provides better performance for effects that are already resolved
    * by applying the transformation immediately instead of deferring it through
    * the effect pipeline.
    *
-   * **Behavior**
+   * **Details**
+   *
+   * Behavior:
    *
    * - For **Success effects**: Applies the `onSuccess` function immediately to the value
    * - For **Failure effects**: Applies the `onFailure` function immediately to the error
@@ -23522,13 +23810,15 @@ export const mapBothEager: {
    * An optimized version of `mapBoth` that checks if an effect is already resolved
    * and applies the appropriate mapping function eagerly when possible.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `mapBothEager` provides better performance for effects that are already resolved
    * by applying the transformation immediately instead of deferring it through
    * the effect pipeline.
    *
-   * **Behavior**
+   * **Details**
+   *
+   * Behavior:
    *
    * - For **Success effects**: Applies the `onSuccess` function immediately to the value
    * - For **Failure effects**: Applies the `onFailure` function immediately to the error
@@ -23566,13 +23856,15 @@ export const mapBothEager: {
  * An optimized version of `flatMap` that checks if an effect is already resolved
  * and applies the flatMap function eagerly when possible.
  *
- * **When to Use**
+ * **When to use**
  *
  * `flatMapEager` provides better performance for effects that are already resolved
  * by applying the transformation immediately instead of deferring it through
  * the effect pipeline.
  *
- * **Behavior**
+ * **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
@@ -23603,13 +23895,15 @@ export const flatMapEager: {
    * An optimized version of `flatMap` that checks if an effect is already resolved
    * and applies the flatMap function eagerly when possible.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `flatMapEager` provides better performance for effects that are already resolved
    * by applying the transformation immediately instead of deferring it through
    * the effect pipeline.
    *
-   * **Behavior**
+   * **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
@@ -23640,13 +23934,15 @@ export const flatMapEager: {
    * An optimized version of `flatMap` that checks if an effect is already resolved
    * and applies the flatMap function eagerly when possible.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `flatMapEager` provides better performance for effects that are already resolved
    * by applying the transformation immediately instead of deferring it through
    * the effect pipeline.
    *
-   * **Behavior**
+   * **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
@@ -23679,13 +23975,15 @@ export const flatMapEager: {
  * An optimized version of `catch` that checks if an effect is already resolved
  * and applies the catch function eagerly when possible.
  *
- * **When to Use**
+ * **When to use**
  *
  * `catchEager` provides better performance for effects that are already resolved
  * by applying the error recovery immediately instead of deferring it through
  * the effect pipeline.
  *
- * **Behavior**
+ * **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
@@ -23726,13 +24024,15 @@ export const catchEager: {
    * An optimized version of `catch` that checks if an effect is already resolved
    * and applies the catch function eagerly when possible.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `catchEager` provides better performance for effects that are already resolved
    * by applying the error recovery immediately instead of deferring it through
    * the effect pipeline.
    *
-   * **Behavior**
+   * **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
@@ -23773,13 +24073,15 @@ export const catchEager: {
    * An optimized version of `catch` that checks if an effect is already resolved
    * and applies the catch function eagerly when possible.
    *
-   * **When to Use**
+   * **When to use**
    *
    * `catchEager` provides better performance for effects that are already resolved
    * by applying the error recovery immediately instead of deferring it through
    * the effect pipeline.
    *
-   * **Behavior**
+   * **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
@@ -23821,6 +24123,8 @@ export const catchEager: {
 /**
  * Creates untraced function effects with eager evaluation optimization.
  *
+ * **Details**
+ *
  * Executes generator functions eagerly when all yielded effects are synchronous,
  * stopping at the first async effect and deferring to normal execution.
  *