effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/Effect.js

@@ -14,12 +14,12 @@ import { internalCall } from "./Utils.js";
 /**
  * Runtime identifier used to recognize `Effect` values.
  *
- * @category Type identifiers
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId = core.EffectTypeId;
 /**
- * Tests if a value is an `Effect`.
+ * Checks whether a value is an `Effect`.
  *
  * **Example** (Checking whether a value is an Effect)
  *
@@ -38,6 +38,11 @@ export const isEffect = core.isEffect;
  * Combines an iterable or record of effects into one effect whose success shape
  * follows the input.
  *
+ * **When to use**
+ *
+ * Use to run a known collection of effects and collect results in the same
+ * tuple, iterable, or record shape.
+ *
  * **Details**
  *
  * Tuple and iterable inputs collect results in order. Record inputs collect
@@ -159,7 +164,7 @@ export const isEffect = core.isEffect;
  * ```
  *
  * @see {@link forEach} for iterating over elements and applying an effect.
- * @category Collecting
+ * @category collecting
  * @since 2.0.0
  */
 export const all = internal.all;
@@ -190,7 +195,7 @@ export const all = internal.all;
  * // [ ["0 is even", "2 is even"], [1, 3] ]
  * ```
  *
- * @category Collecting
+ * @category collecting
  * @since 2.0.0
  */
 export const partition = internal.partition;
@@ -229,7 +234,7 @@ export const partition = internal.partition;
  * // }
  * ```
  *
- * @category Error Accumulation
+ * @category error accumulation
  * @since 2.0.0
  */
 export const validate = internal.validate;
@@ -252,25 +257,37 @@ export const validate = internal.validate;
  * // { _id: 'Option', _tag: 'Some', value: 3 }
  * ```
  *
- * @category Collecting
+ * @category collecting
  * @since 2.0.0
  */
 export const findFirst = internal.findFirst;
 /**
  * Returns the first value that passes an effectful `FilterEffect`.
  *
+ * **When to use**
+ *
+ * Use when you need to find the first element that satisfies an effectful
+ * filter returning a `Result`, which also transforms the matching element.
+ *
  * **Details**
  *
  * The filter receives the element and index. Evaluation short-circuits on the
  * first `Result.succeed` and returns the transformed value in `Option.some`.
  *
- * @category Collecting
+ * @see {@link findFirst} for the simpler effectful predicate-based variant
+ *
+ * @category collecting
  * @since 4.0.0
  */
 export const findFirstFilter = internal.findFirstFilter;
 /**
  * Executes an effectful operation for each element in an `Iterable`.
  *
+ * **When to use**
+ *
+ * Use to traverse an iterable with an effectful function while preserving
+ * element order in the collected results.
+ *
  * **Details**
  *
  * The `forEach` function applies a provided operation to each element in the
@@ -334,7 +351,7 @@ export const findFirstFilter = internal.findFirstFilter;
  * ```
  *
  * @see {@link all} for combining multiple effects into one.
- * @category Collecting
+ * @category collecting
  * @since 2.0.0
  */
 export const forEach = internal.forEach;
@@ -363,7 +380,7 @@ export const forEach = internal.forEach;
  * // Current count: 5
  * ```
  *
- * @category Collecting
+ * @category collecting
  * @since 2.0.0
  */
 export const whileLoop = internal.whileLoop;
@@ -376,22 +393,21 @@ export const whileLoop = internal.whileLoop;
  *
  * **When to use**
  *
- * Use `promise` when you are sure the operation will not reject.
+ * Use to convert a `Promise` into an `Effect` when the async operation is
+ * guaranteed to succeed and will not reject.
  *
  * **Details**
  *
- * The provided function (`thunk`) returns a `Promise` that should never reject; if it does, the error
- * will be treated as a "defect".
+ * An optional `AbortSignal` can be provided to allow for interruption of the
+ * wrapped `Promise` API.
  *
- * This defect is not a standard error but indicates a flaw in the logic that
- * was expected to be error-free. You can think of it similar to an unexpected
- * crash in the program, which can be further managed or logged using tools like
- * {@link catchDefect}.
+ * **Gotchas**
  *
- * Interruptions:
+ * The `Promise` must not reject. If it rejects, the rejection is treated as a
+ * defect, not as a typed failure. Use `tryPromise` when rejection is expected.
  *
- * An optional `AbortSignal` can be provided to allow for interruption of the
- * wrapped `Promise` API.
+ * Interruption aborts the provided `AbortSignal`, but the underlying
+ * asynchronous operation only stops if it observes that signal.
  *
  * **Example** (Wrapping a non-rejecting Promise)
  *
@@ -414,7 +430,7 @@ export const whileLoop = internal.whileLoop;
  * ```
  *
  * @see {@link tryPromise} for a version that can handle failures.
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const promise = internal.promise;
@@ -424,11 +440,9 @@ export const promise = internal.promise;
  *
  * **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`
- * constructor. This constructor is designed to handle operations that could
- * throw exceptions by capturing those exceptions and transforming them into
- * manageable errors.
+ * Use when you need to perform asynchronous operations that might fail, such
+ * as fetching data from an API, and want thrown exceptions or rejected promises
+ * captured as Effect errors.
  *
  * **Details**
  *
@@ -482,7 +496,7 @@ export const promise = internal.promise;
  * ```
  *
  * @see {@link promise} if the effectful computation is asynchronous and does not throw errors.
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const tryPromise = internal.tryPromise;
@@ -491,7 +505,7 @@ export const tryPromise = internal.tryPromise;
  *
  * **When to use**
  *
- * Use this function when you need an effect that completes successfully with a
+ * Use when you use this function when you need an effect that completes successfully with a
  * specific value without any errors or external dependencies.
  *
  * **Example** (Creating a successful effect)
@@ -507,7 +521,7 @@ export const tryPromise = internal.tryPromise;
  * ```
  *
  * @see {@link fail} to create an effect that represents a failure.
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const succeed = internal.succeed;
@@ -525,7 +539,7 @@ export const succeed = internal.succeed;
  * // Output: { _id: 'Option', _tag: 'None' }
  * ```
  *
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const succeedNone = internal.succeedNone;
@@ -543,16 +557,16 @@ export const succeedNone = internal.succeedNone;
  * // Output: { _id: 'Option', _tag: 'Some', value: 42 }
  * ```
  *
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const succeedSome = internal.succeedSome;
 /**
- * Delays the creation of an `Effect` until it is actually needed.
+ * Creates an `Effect` lazily, delaying construction until it is needed.
  *
  * **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.
+ * Use when you need to defer the evaluation of an effect until it is required. This is particularly useful for optimizing expensive computations, managing circular dependencies, or resolving type inference issues.
  *
  * **Details**
  *
@@ -630,7 +644,7 @@ export const succeedSome = internal.succeedSome;
  *   )
  * ```
  *
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const suspend = internal.suspend;
@@ -639,17 +653,16 @@ export const suspend = internal.suspend;
  *
  * **When to use**
  *
- * Use `sync` when you are sure the operation will not fail.
+ * Use when you are sure the operation will not fail.
  *
  * **Details**
  *
- * The provided function (`thunk`) must not throw errors; if it does, the error
- * will be treated as a "defect".
+ * The provided function is evaluated lazily when the effect runs.
+ *
+ * **Gotchas**
  *
- * This defect is not a standard error but indicates a flaw in the logic that
- * was expected to be error-free. You can think of it similar to an unexpected
- * crash in the program, which can be further managed or logged using tools like
- * {@link catchDefect}.
+ * The function must not throw. If it throws, the thrown value is treated as a
+ * defect, not as a typed failure. Use `try` when throwing is expected.
  *
  * **Example** (Capturing synchronous logging in an Effect)
  *
@@ -667,7 +680,7 @@ export const suspend = internal.suspend;
  * ```
  *
  * @see {@link try_ | try} for a version that can handle failures.
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const sync = internal.sync;
@@ -676,7 +689,7 @@ export {
 /**
  * Returns an effect that succeeds with `void`.
  *
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 void_ as void };
@@ -685,7 +698,7 @@ export {
 /**
  * Returns an effect that succeeds with `undefined`.
  *
- * @category Creating Effects
+ * @category creating effects
  * @since 4.0.0
  */
 undefined_ as undefined };
@@ -694,7 +707,7 @@ undefined_ as undefined };
  *
  * **When to use**
  *
- * Use `Effect.callback` when integrating APIs that complete through callbacks
+ * Use when integrating APIs that complete through callbacks
  * instead of returning a `Promise`.
  *
  * **Details**
@@ -721,7 +734,7 @@ undefined_ as undefined };
  * const program = delay(1000)
  * ```
  *
- * @category Creating Effects
+ * @category creating effects
  * @since 4.0.0
  */
 export const callback = internal.callback;
@@ -744,13 +757,13 @@ export const callback = internal.callback;
  * const timedProgram = Effect.timeout(program, "1 second")
  * ```
  *
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const never = internal.never;
 /**
- * An `Effect` containing an empty record `{}`, used as the starting point for
- * do notation chains.
+ * Effect that succeeds with an empty record `{}`, used as the starting point
+ * for do notation chains.
  *
  * **Example** (Starting do notation)
  *
@@ -765,7 +778,7 @@ export const never = internal.never;
  * )
  * ```
  *
- * @category Do notation
+ * @category do notation
  * @since 2.0.0
  */
 export const Do = internal.Do;
@@ -773,7 +786,15 @@ export const Do = internal.Do;
  * Gives a name to the success value of an `Effect`, creating a single-key
  * record used in do notation pipelines.
  *
- * @category Do notation
+ * **When to use**
+ *
+ * Use to start a do-notation pipeline from an existing `Effect` when its
+ * success value should become the first named field in the accumulated record.
+ *
+ * @see {@link Do} for starting from an empty accumulated record
+ * @see {@link bind} for adding fields produced by effects
+ *
+ * @category do notation
  * @since 2.0.0
  */
 export const bindTo = internal.bindTo;
@@ -782,14 +803,51 @@ export {
 /**
  * Adds a computed plain value to the do notation record.
  *
- * @category Do notation
+ * **When to use**
+ *
+ * Use to add a derived, synchronous value to a do-notation pipeline when it
+ * depends on fields already accumulated in the record and does not need to run
+ * another `Effect`.
+ *
+ * **Details**
+ *
+ * The new field is added with object spreading. If the name already exists in
+ * the record, the computed value replaces it in the returned type.
+ *
+ * @see {@link bind} for adding fields produced by effects
+ * @see {@link bindTo} for naming an existing success value
+ * @see {@link Do} for starting from an empty accumulated record
+ * @see {@link gen} for sequencing without accumulating a record
+ *
+ * @category do notation
  * @since 2.0.0
  */
 let_ as let };
 /**
  * Adds an `Effect` value to the do notation record under a given name.
  *
- * @category Do notation
+ * **When to use**
+ *
+ * Use to sequence an effectful step in a do-notation pipeline when that step
+ * depends on fields already accumulated in the record and its success value
+ * should be stored under a name.
+ *
+ * **Details**
+ *
+ * The function receives the current record, runs the returned effect after the
+ * input effect succeeds, and inserts its success value under `name`. The
+ * resulting effect combines the error and service requirements of both steps.
+ *
+ * **Gotchas**
+ *
+ * Binding a name that already exists replaces that field in the resulting
+ * record.
+ *
+ * @see {@link Do} for starting from an empty do-notation record
+ * @see {@link bindTo} for naming the success value of an existing effect
+ * @see {@link gen} for generator-based sequencing without accumulating a record
+ *
+ * @category do notation
  * @since 2.0.0
  */
 export const bind = internal.bind;
@@ -799,7 +857,7 @@ export const bind = internal.bind;
  *
  * **When to use**
  *
- * `gen` allows you to write code that looks and behaves like synchronous
+ * Use when `gen` allows you to write code that looks and behaves like synchronous
  * code, but it can handle asynchronous tasks, errors, and complex control flow
  * (like loops and conditions). It helps make asynchronous code more readable
  * and easier to manage.
@@ -841,7 +899,7 @@ export const bind = internal.bind;
  * })
  * ```
  *
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const gen = internal.gen;
@@ -850,7 +908,7 @@ export const gen = internal.gen;
  *
  * **When to use**
  *
- * Use this function to explicitly signal an error in an `Effect`. The error
+ * Use to explicitly signal an error in an `Effect`. The error
  * will keep propagating unless it is handled. You can handle the error with
  * functions like {@link catchTag} or {@link catchTags}.
  *
@@ -869,17 +927,20 @@ export const gen = internal.gen;
  * ```
  *
  * @see {@link succeed} to create an effect that represents a successful value.
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const fail = internal.fail;
 /**
  * Creates an `Effect` that represents a recoverable error using a lazy evaluation.
  *
+ * **When to use**
+ *
+ * Use to defer computing a recoverable error value until the effect is run.
+ *
  * **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.
+ * The error-producing function is evaluated each time the effect is executed.
  *
  * **Example** (Lazily creating failures)
  *
@@ -894,7 +955,7 @@ export const fail = internal.fail;
  * // Output: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const failSync = internal.failSync;
@@ -919,17 +980,20 @@ export const failSync = internal.failSync;
  * // Output: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const failCause = internal.failCause;
 /**
  * Creates an `Effect` that represents a failure with a `Cause` computed lazily.
  *
+ * **When to use**
+ *
+ * Use to defer computing a full `Cause` until the effect is run.
+ *
  * **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.
+ * The cause-producing function is evaluated each time the effect is executed.
  *
  * **Example** (Lazily creating a Cause)
  *
@@ -944,7 +1008,7 @@ export const failCause = internal.failCause;
  * // Output: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const failCauseSync = internal.failCauseSync;
@@ -953,7 +1017,7 @@ export const failCauseSync = internal.failCauseSync;
  *
  * **When to use**
  *
- * Use `die` when encountering unexpected conditions in your code that should
+ * Use when encountering unexpected conditions in your code that should
  * not be handled as regular errors but instead represent unrecoverable defects.
  *
  * **Details**
@@ -985,8 +1049,7 @@ export const failCauseSync = internal.failCauseSync;
  * //   ...stack trace...
  * ```
  *
- * @see {@link die} for a variant that dies with an already computed defect.
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const die = internal.die;
@@ -998,7 +1061,7 @@ export {
  *
  * **When to use**
  *
- * In situations where you need to perform synchronous operations that might
+ * Use when in situations where you need to perform synchronous operations that might
  * fail, such as parsing JSON, you can use the `try` constructor. This
  * constructor is designed to handle operations that could throw exceptions by
  * capturing those exceptions and transforming them into manageable errors.
@@ -1053,7 +1116,7 @@ export {
  *
  * @see {@link sync} if the effectful computation is synchronous and does not
  * throw errors.
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 try_ as try };
@@ -1074,7 +1137,7 @@ try_ as try };
  * Effect.runPromise(program)
  * ```
  *
- * @category Creating Effects
+ * @category creating effects
  * @since 2.0.0
  */
 export const yieldNow = internal.yieldNow;
@@ -1095,7 +1158,7 @@ export const yieldNow = internal.yieldNow;
  * Effect.runPromise(program)
  * ```
  *
- * @category Creating Effects
+ * @category creating effects
  * @since 4.0.0
  */
 export const yieldNowWith = internal.yieldNowWith;
@@ -1115,7 +1178,7 @@ export const yieldNowWith = internal.yieldNowWith;
  * // Output: Fiber ID: 1
  * ```
  *
- * @category Creating Effects
+ * @category creating effects
  * @since 4.0.0
  */
 export const withFiber = core.withFiber;
@@ -1208,7 +1271,7 @@ export const fromNullishOr = internal.fromNullishOr;
  *
  * **When to use**
  *
- * Use `flatMap` when you need to chain multiple effects, ensuring that each
+ * Use when you need to chain multiple effects, ensuring that each
  * step produces a new `Effect` while flattening any nested effects that may
  * occur.
  *
@@ -1296,7 +1359,7 @@ export const flatten = internal.flatten;
  *
  * **When to use**
  *
- * Use `andThen` when one effect must run after another and the second effect
+ * Use when one effect must run after another and the second effect
  * may depend on the first effect's success value.
  *
  * **Details**
@@ -1372,7 +1435,7 @@ export const andThen = internal.andThen;
  *
  * **When to use**
  *
- * Use `tap` when you want to perform a side effect, like logging or tracking,
+ * Use when you want to perform a side effect, like logging or tracking,
  * without modifying the main value. This is useful when you need to observe or
  * record an action but want the original value to be passed to the next step.
  *
@@ -1421,7 +1484,13 @@ export const andThen = internal.andThen;
  */
 export const tap = internal.tap;
 /**
- * Encapsulates both success and failure of an `Effect` into a `Result` type.
+ * Converts both success and failure of an `Effect` into a `Result` type.
+ *
+ * **When to use**
+ *
+ * Use when you want to handle typed failures as data while preserving
+ * the original error value. Use `option` when you only care whether the effect
+ * succeeded, and `exit` when you need the full failure cause.
  *
  * **Details**
  *
@@ -1435,14 +1504,15 @@ export const tap = internal.tap;
  * you want to chain effects and manage both success and failure in the same
  * logical flow.
  *
- * It's important to note that unrecoverable errors, often referred to as
- * "defects," are still thrown and not captured within the `Result` type. Only
- * failures that are explicitly represented as recoverable errors in the effect
- * are encapsulated.
- *
  * The resulting effect cannot fail directly because all recoverable failures
  * are represented inside the `Result` type.
  *
+ * **Gotchas**
+ *
+ * `result` only captures typed, recoverable failures. Defects and
+ * interruptions are not captured inside the `Result` and still fail the
+ * effect.
+ *
  * **Example** (Capturing success or failure as Result)
  *
  * ```ts
@@ -1464,18 +1534,33 @@ export const tap = internal.tap;
  * @see {@link option} for a version that uses `Option` instead.
  * @see {@link exit} for a version that encapsulates both recoverable errors and defects in an `Exit`.
  *
- * @category Outcome Encapsulation
+ * @category outcome encapsulation
  * @since 4.0.0
  */
 export const result = internal.result;
 /**
- * Convert success to `Option.some` and failure to `Option.none`.
+ * Converts success to `Option.some` and failure to `Option.none`.
+ *
+ * **When to use**
+ *
+ * Use when the failure value is not important and absence is enough.
+ * Use `result` when you need the original typed failure, and `exit` when you
+ * need the full failure cause.
  *
  * **Details**
  *
  * Success values become `Option.some`, recoverable failures become
  * `Option.none`, and defects still fail the effect.
  *
+ * **Gotchas**
+ *
+ * `option` only captures typed, recoverable failures as `Option.none`.
+ * Defects and interruptions are not captured inside the `Option` and still
+ * fail the effect.
+ *
+ * `option` also discards typed failure values. Use `result` if the failure
+ * value matters.
+ *
  * **Example** (Capturing success or failure as Option)
  *
  * ```ts
@@ -1497,7 +1582,7 @@ export const result = internal.result;
  * @see {@link result} for a version that uses `Result` instead.
  * @see {@link exit} for a version that encapsulates both recoverable errors and defects in an `Exit`.
  *
- * @category Output Encapsulation
+ * @category outcome encapsulation
  * @since 2.0.0
  */
 export const option = internal.option;
@@ -1505,6 +1590,12 @@ export const option = internal.option;
  * Transforms an effect to encapsulate both failure and success using the `Exit`
  * data type.
  *
+ * **When to use**
+ *
+ * Use when you need to inspect the full outcome, including typed
+ * failures, defects, and interruptions. Use `result` or `option` when you only
+ * need to handle typed failures.
+ *
  * **Details**
  *
  * `exit` wraps an effect's success or failure inside an `Exit` type, allowing
@@ -1535,13 +1626,19 @@ export const option = internal.option;
  * @see {@link option} for a version that uses `Option` instead.
  * @see {@link result} for a version that uses `Result` instead.
  *
- * @category Outcome Encapsulation
+ * @category outcome encapsulation
  * @since 2.0.0
  */
 export const exit = internal.exit;
 /**
  * Transforms the value inside an effect by applying a function to it.
  *
+ * **When to use**
+ *
+ * Use to transform an effect's success value with a function that returns a
+ * plain value, producing a new effect without changing the original effect's
+ * typed error or context requirements.
+ *
  * **Details**
  *
  * `map` takes a function and applies it to the value contained within an
@@ -1592,6 +1689,11 @@ export const map = internal.map;
 /**
  * Replaces the value inside an effect with a constant value.
  *
+ * **When to use**
+ *
+ * Use to replace a successful value with a constant while preserving failures
+ * and requirements.
+ *
  * **Details**
  *
  * `as` allows you to ignore the original value inside an effect and
@@ -1609,14 +1711,15 @@ export const map = internal.map;
  * // Output: "new value"
  * ```
  *
+ * @see {@link map} for deriving the replacement value from the success value
+ * @see {@link asVoid} for replacing the success value with `void`
+ *
  * @category mapping
  * @since 2.0.0
  */
 export const as = internal.as;
 /**
- * This function maps the success value of an `Effect` value to a `Some` value
- * in an `Option` value. If the original `Effect` value fails, the returned
- * `Effect` value will also fail.
+ * Maps the success value of an `Effect` to `Some`, preserving failures.
  *
  * **Example** (Wrapping success in Option.some)
  *
@@ -1634,10 +1737,7 @@ export const as = internal.as;
  */
 export const asSome = internal.asSome;
 /**
- * This function maps the success value of an `Effect` value to `void`. If the
- * original `Effect` value succeeds, the returned `Effect` value will also
- * succeed. If the original `Effect` value fails, the returned `Effect` value
- * will fail with the same error.
+ * Maps the success value of an `Effect` to `void`, preserving failures.
  *
  * **Example** (Discarding success values)
  *
@@ -1655,15 +1755,16 @@ export const asSome = internal.asSome;
  */
 export const asVoid = internal.asVoid;
 /**
- * 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.
+ * Swaps an effect's success and failure channels.
+ *
+ * **When to use**
+ *
+ * Use to handle the failure value as a success, or to move the success value
+ * into the failure channel.
  *
  * **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
- * treat an error as a valid result.
+ * For an `Effect<A, E, R>`, the returned effect has type `Effect<E, A, R>`.
  *
  * **Example** (Swapping success and failure channels)
  *
@@ -1689,6 +1790,10 @@ export const flip = internal.flip;
 /**
  * Combines two effects into a single effect, producing a tuple with the results of both effects.
  *
+ * **When to use**
+ *
+ * Use to combine exactly two effects into a tuple.
+ *
  * **Details**
  *
  * The `zip` function executes the first effect (left) and then the second effect (right).
@@ -1751,7 +1856,8 @@ export const flip = internal.flip;
  * ```
  *
  * @see {@link zipWith} for a version that combines the results with a custom function.
- * @see {@link validate} for a version that accumulates errors.
+ * @see {@link all} for collecting a larger structure of effects.
+ *
  * @category zipping
  * @since 2.0.0
  */
@@ -1762,9 +1868,8 @@ export const zip = internal.zip;
  *
  * **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.
+ * Use when you need to run two effects sequentially and combine their results
+ * with a function instead of keeping the results as a tuple.
  *
  * **Details**
  *
@@ -1835,13 +1940,13 @@ catch_ as catch };
  *
  * **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
- * error types by matching the `_tag` value. This allows for precise error
- * handling, ensuring that only specific errors are caught and handled.
+ * Use when recovering from one specific tagged error in an effect error
+ * channel.
  *
- * The error type must have a readonly `_tag` field to use `catchTag`. This
- * field is used to identify and match errors.
+ * **Details**
+ *
+ * The error type must have a readonly `_tag` field. `catchTag` matches that
+ * field and only handles errors with the requested tag.
  *
  * **Example** (Handling a tagged error)
  *
@@ -1867,6 +1972,9 @@ catch_ as catch };
  * )
  * ```
  *
+ * @see {@link catchTags} for handling multiple tagged errors in one call
+ * @see {@link catchIf} for recovering from errors that match a predicate
+ *
  * @category error handling
  * @since 2.0.0
  */
@@ -1876,12 +1984,9 @@ export const catchTag = internal.catchTag;
  *
  * **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
- * object where each key is an error type's `_tag`, and the value is the handler
- * for that specific error. This allows you to catch and recover from multiple
- * error types in a single call. You can also provide a fallback handler for
- * unhandled errors.
+ * Use when one recovery step should handle several tagged error types by
+ * matching their readonly `_tag` fields. Pass a handler table whose keys are
+ * tags, plus an optional fallback for unmatched errors.
  *
  * The error type must have a readonly `_tag` field to use `catchTag`. This
  * field is used to identify and match errors.
@@ -1918,6 +2023,11 @@ export const catchTags = internal.catchTags;
 /**
  * Catches a specific reason within a tagged error.
  *
+ * **When to use**
+ *
+ * Use to handle one nested reason inside a tagged error while preserving the
+ * parent error shape for unmatched reasons.
+ *
  * **Details**
  *
  * Use this to handle nested error causes without removing the parent error
@@ -1950,6 +2060,8 @@ export const catchTags = internal.catchTags;
  * )
  * ```
  *
+ * @see {@link catchReasons} for handling several nested reason tags
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -2028,10 +2140,8 @@ export const unwrapReason = internal.unwrapReason;
  *
  * **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.
+ * Use when recovery needs the full `Cause`, including recoverable failures,
+ * defects, and interruptions, instead of only the typed error value.
  *
  * **Details**
  *
@@ -2069,7 +2179,7 @@ export const catchCause = internal.catchCause;
  *
  * **When to use**
  *
- * Use this sparingly, usually at integration boundaries where defects must be
+ * Use when you use this sparingly, usually at integration boundaries where defects must be
  * reported or translated for an external system.
  *
  * **Details**
@@ -2110,7 +2220,7 @@ export const catchDefect = internal.catchDefect;
  *
  * **When to use**
  *
- * `catchIf` lets you recover from errors that match a condition. Use a
+ * Use when you need to recover from errors that match a condition. Use a
  * `Refinement` for type narrowing or a `Predicate` for simple boolean
  * matching. Non-matching errors re-fail with the original cause. Defects and
  * interrupts are not caught.
@@ -2148,6 +2258,24 @@ export const catchIf = internal.catchIf;
 /**
  * Recovers from specific errors using a `Filter`.
  *
+ * **When to use**
+ *
+ * Use to recover from typed `Effect` errors with a reusable `Filter` when
+ * matching can also narrow or transform the error before choosing the recovery
+ * effect.
+ *
+ * **Details**
+ *
+ * The filter runs on typed failures extracted from the `Cause`. Successful
+ * filter results are passed to `f`; failed filter results are passed to
+ * `orElse` when provided. Without `orElse`, the original failure cause is
+ * preserved.
+ *
+ * @see {@link catchIf} for predicate-based recovery from typed errors
+ * @see {@link catchTag} for recovering from a single tagged error
+ * @see {@link catchTags} for recovering from several tagged errors
+ * @see {@link catchCauseFilter} for filtering full causes instead of typed errors
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -2155,6 +2283,10 @@ export const catchFilter = internal.catchFilter;
 /**
  * Catches `NoSuchElementError` failures and converts them to `Option.none`.
  *
+ * **When to use**
+ *
+ * Use to convert `NoSuchElementError` failures into `Option.none`.
+ *
  * **Details**
  *
  * Success values become `Option.some`, `NoSuchElementError` becomes
@@ -2172,6 +2304,10 @@ export const catchFilter = internal.catchFilter;
  * Effect.runPromise(none).then(console.log) // { _id: 'Option', _tag: 'None' }
  * ```
  *
+ * @see {@link fromOption} for converting `Option.none` into `NoSuchElementError`
+ * @see {@link fromNullishOr} for converting nullish values into `NoSuchElementError`
+ * @see {@link option} for converting any failure into `Option.none`
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -2179,6 +2315,10 @@ export const catchNoSuchElement = internal.catchNoSuchElement;
 /**
  * Recovers from specific failures based on a predicate.
  *
+ * **When to use**
+ *
+ * Use to recover from full causes selected by a predicate.
+ *
  * **Details**
  *
  * This function allows you to conditionally catch and recover from failures
@@ -2208,6 +2348,10 @@ export const catchNoSuchElement = internal.catchNoSuchElement;
  * // Then: "Fallback response"
  * ```
  *
+ * @see {@link catchCause} for recovering from every cause
+ * @see {@link catchCauseFilter} for selecting full causes with a `Filter`
+ * @see {@link catchIf} for predicate-based recovery from typed errors
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -2215,20 +2359,36 @@ export const catchCauseIf = internal.catchCauseIf;
 /**
  * Recovers from specific failures based on a `Filter`.
  *
+ * **When to use**
+ *
+ * Use when you need to recover only from causes selected by a `Filter`, and the
+ * recovery needs both the selected value and the original `Cause`.
+ *
+ * **Details**
+ *
+ * The filter is applied to the full `Cause`. When it succeeds, the handler
+ * receives the selected value and the original cause. When it fails, the effect
+ * re-fails with the residual cause returned by the filter.
+ *
+ * @see {@link catchCauseIf} for predicate-based cause selection
+ * @see {@link catchFilter} for filtering typed error values instead of full causes
+ * @see {@link catchCause} for recovering from every cause without filtering
+ *
  * @category error handling
  * @since 4.0.0
  */
 export const catchCauseFilter = internal.catchCauseFilter;
 /**
- * The `mapError` function is used to transform or modify the error
- * produced by an effect, without affecting its success value.
+ * Transforms the failure value of an effect without changing its success value.
+ *
+ * **When to use**
+ *
+ * Use to translate typed failures while leaving successful values unchanged.
  *
  * **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.
+ * Only the failure channel is transformed. The success channel and requirements
+ * are preserved.
  *
  * **Example** (Transforming the error channel)
  *
@@ -2251,7 +2411,7 @@ export const catchCauseFilter = internal.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
  */
@@ -2259,6 +2419,11 @@ export const mapError = internal.mapError;
 /**
  * Applies transformations to both the success and error channels of an effect.
  *
+ * **When to use**
+ *
+ * Use to transform both success and failure values without changing whether the
+ * effect succeeds or fails.
+ *
  * **Details**
  *
  * This function takes two map functions as arguments: one for the error channel
@@ -2298,7 +2463,7 @@ export const mapBoth = internal.mapBoth;
  *
  * **When to use**
  *
- * Use `orDie` when a typed failure represents an unrecoverable bug or invalid
+ * Use when a typed failure represents an unrecoverable bug or invalid
  * state and should not be handled as a recoverable error.
  *
  * **Example** (Converting typed failures into defects)
@@ -2323,8 +2488,7 @@ export const mapBoth = internal.mapBoth;
  * //   ...stack trace...
  * ```
  *
- * @see {@link mapError} to transform the error before converting it into a defect with {@link orDie}.
- * @category Converting Failures to Defects
+ * @category converting failures to defects
  * @since 2.0.0
  */
 export const orDie = internal.orDie;
@@ -2431,7 +2595,7 @@ export const tapErrorTag = internal.tapErrorTag;
  */
 export const tapCause = internal.tapCause;
 /**
- * Conditionally executes a side effect based on the cause of a failed effect.
+ * Executes a side effect conditionally when a failed effect's cause matches a predicate.
  *
  * **Details**
  *
@@ -2463,7 +2627,22 @@ export const tapCause = internal.tapCause;
  */
 export const tapCauseIf = internal.tapCauseIf;
 /**
- * Conditionally executes a side effect based on the cause of a failed effect.
+ * Executes a side effect conditionally when a failed effect's cause passes a filter.
+ *
+ * **When to use**
+ *
+ * Use when you need to observe only failure causes selected by a `Filter`, and
+ * the side effect needs both the selected value and the original `Cause`.
+ *
+ * **Details**
+ *
+ * A successful filter result runs the side effect with the selected value and
+ * original cause. A failed filter result skips the side effect and preserves the
+ * original cause.
+ *
+ * @see {@link tapCauseIf} for selecting causes with a boolean predicate
+ * @see {@link tapCause} for observing every failure cause
+ * @see {@link catchCauseFilter} for recovering from selected causes instead of only observing them
  *
  * @category sequencing
  * @since 4.0.0
@@ -2550,7 +2729,7 @@ export const tapDefect = internal.tapDefect;
  * // Ready
  * ```
  *
- * @category Repetition / Recursion
+ * @category repetition / recursion
  * @since 2.0.0
  */
 export const eventually = internal.eventually;
@@ -2559,7 +2738,7 @@ export const eventually = internal.eventually;
  *
  * **When to use**
  *
- * Use `retry` when typed failures may be transient, such as network issues or
+ * Use when typed failures may be transient, such as network issues or
  * temporary resource unavailability.
  *
  * **Details**
@@ -2569,7 +2748,13 @@ export const eventually = internal.eventually;
  * succeeds, the returned effect succeeds with that value. If the policy stops
  * while the effect is still failing, the last failure is propagated.
  *
- * Defects and interruptions are not retried as typed failures.
+ * **Gotchas**
+ *
+ * The source effect is always evaluated once before any retry policy is
+ * applied. For example, `Schedule.recurs(3)` allows up to three retries after
+ * the initial attempt.
+ *
+ * Defects and interruptions are not retried.
  *
  * **Example** (Retrying with a schedule)
  *
@@ -2606,8 +2791,8 @@ export const retry = internalSchedule.retry;
  *
  * **When to use**
  *
- * This function is useful when you want to handle failures gracefully by
- * specifying an alternative action after repeated failures.
+ * Use when you want to handle failures gracefully by specifying an alternative
+ * action after repeated failures.
  *
  * **Details**
  *
@@ -2684,8 +2869,6 @@ export const retryOrElse = internalSchedule.retryOrElse;
  * // Output: "Caught cause: Something went wrong"
  * ```
  *
- * @see {@link sandbox} to expose failures as full causes.
- *
  * @category error handling
  * @since 2.0.0
  */
@@ -2695,9 +2878,8 @@ export const sandbox = internal.sandbox;
  *
  * **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
- * effects of the effect and do not need to handle or process its outcome.
+ * Use when an effect should run for its side effects while both success and
+ * failure values are discarded.
  *
  * Use the `log` option to emit the full {@link Cause} when the effect fails,
  * and `message` to prepend a custom log message.
@@ -2755,7 +2937,7 @@ export const ignore = internal.ignore;
  */
 export const ignoreCause = internal.ignoreCause;
 /**
- * Apply an `ExecutionPlan` to an effect, retrying with step-provided resources
+ * Applies an `ExecutionPlan` to an effect, retrying with step-provided resources
  * until it succeeds or the plan is exhausted.
  *
  * **Details**
@@ -2787,7 +2969,7 @@ export const ignoreCause = internal.ignoreCause;
  * const program = Effect.withExecutionPlan(fetchUrl, plan)
  * ```
  *
- * @category Fallback
+ * @category fallback
  * @since 3.16.0
  */
 export const withExecutionPlan = internalExecutionPlan.withExecutionPlan;
@@ -2839,7 +3021,7 @@ export const withErrorReporting = internal.withErrorReporting;
  * // { _id: 'Exit', _tag: 'Success', value: 18 }
  * ```
  *
- * @category Fallback
+ * @category fallback
  * @since 2.0.0
  */
 export const orElseSucceed = internal.orElseSucceed;
@@ -2849,7 +3031,7 @@ export const orElseSucceed = internal.orElseSucceed;
  *
  * **When to use**
  *
- * Use `firstSuccessOf` when you have prioritized fallback strategies, such as
+ * Use when you have prioritized fallback strategies, such as
  * attempting multiple APIs, reading configuration from several sources, or
  * trying alternative resource locations in order.
  *
@@ -2884,7 +3066,7 @@ export const orElseSucceed = internal.orElseSucceed;
  * // Output: "secondary result"
  * ```
  *
- * @category Fallback
+ * @category fallback
  * @since 2.0.0
  */
 export const firstSuccessOf = internal.firstSuccessOf;
@@ -2895,6 +3077,12 @@ export const firstSuccessOf = internal.firstSuccessOf;
  * Adds a time limit to an effect, triggering a timeout if the effect exceeds
  * the duration.
  *
+ * **When to use**
+ *
+ * Use when exceeding the time limit should be represented as a typed
+ * failure. Use `timeoutOption` when a timeout should become `Option.none`, and
+ * `timeoutOrElse` when you want to run a fallback effect.
+ *
  * **Details**
  *
  * The `timeout` function allows you to specify a time limit for an
@@ -2903,6 +3091,10 @@ export const firstSuccessOf = internal.firstSuccessOf;
  * your program waits for a task to finish, ensuring that it doesn't hang
  * indefinitely if the task takes too long.
  *
+ * **Gotchas**
+ *
+ * If the timeout wins, the source effect is interrupted.
+ *
  * **Example** (Failing when work takes too long)
  *
  * ```ts
@@ -2933,8 +3125,10 @@ export const firstSuccessOf = internal.firstSuccessOf;
  * // }
  * ```
  *
+ * @see {@link timeoutOption} for returning `Option.none` on timeout.
  * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
- * @category Delays & Timeouts
+ *
+ * @category delays & timeouts
  * @since 2.0.0
  */
 export const timeout = internal.timeout;
@@ -2942,6 +3136,12 @@ export const timeout = internal.timeout;
  * Runs an effect with a time limit and represents only the timeout case as
  * `Option.none`.
  *
+ * **When to use**
+ *
+ * Use when a timeout should be handled as absence. Use
+ * `timeout` when a timeout should fail the effect, and `timeoutOrElse` when
+ * you want to run a fallback effect.
+ *
  * **Details**
  *
  * If the source effect succeeds before the timeout, the returned effect
@@ -2949,9 +3149,6 @@ export const timeout = internal.timeout;
  * interrupted and the returned effect succeeds with `Option.none`. If the
  * source effect fails before the timeout, that failure is preserved.
  *
- * @see {@link timeout} for a version that raises a `TimeoutException`.
- * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
- *
  * **Example** (Returning None on timeout)
  *
  * ```ts
@@ -2980,17 +3177,31 @@ export const timeout = internal.timeout;
  * // ]
  * ```
  *
- * @category Delays & Timeouts
+ * @see {@link timeout} for a version that raises a `TimeoutException`.
+ * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
+ *
+ * @category delays & timeouts
  * @since 3.1.0
  */
 export const timeoutOption = internal.timeoutOption;
 /**
  * Applies a timeout to an effect, with a fallback effect executed if the timeout is reached.
  *
+ * **When to use**
+ *
+ * Use when a timeout should switch to a fallback effect. Use
+ * `timeout` when a timeout should fail the effect, and `timeoutOption` when a
+ * timeout should become `Option.none`.
+ *
  * **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.
+ * The fallback effect is created lazily by `orElse` and may introduce its own
+ * success, failure, and requirement types.
+ *
+ * **Gotchas**
+ *
+ * If the timeout wins, the source effect is interrupted before the fallback is
+ * run.
  *
  * **Example** (Falling back on timeout)
  *
@@ -3020,7 +3231,10 @@ export const timeoutOption = internal.timeoutOption;
  * // Cached result
  * ```
  *
- * @category Delays & Timeouts
+ * @see {@link timeout} for failing with a `TimeoutException`.
+ * @see {@link timeoutOption} for returning `Option.none` on timeout.
+ *
+ * @category delays & timeouts
  * @since 4.0.0
  */
 export const timeoutOrElse = internal.timeoutOrElse;
@@ -3042,7 +3256,7 @@ export const timeoutOrElse = internal.timeoutOrElse;
  * // Waits 1 second, then prints: "Delayed message"
  * ```
  *
- * @category Delays & Timeouts
+ * @category delays & timeouts
  * @since 2.0.0
  */
 export const delay = internal.delay;
@@ -3066,12 +3280,12 @@ export const delay = internal.delay;
  * // Output: "End" (after 2 seconds)
  * ```
  *
- * @category Delays & Timeouts
+ * @category delays & timeouts
  * @since 2.0.0
  */
 export const sleep = internal.sleep;
 /**
- * Measures the runtime of an effect and returns the duration with its result.
+ * Returns the runtime duration of an effect together with its result.
  *
  * **Details**
  *
@@ -3089,7 +3303,7 @@ export const sleep = internal.sleep;
  * })
  * ```
  *
- * @category Delays & Timeouts
+ * @category delays & timeouts
  * @since 2.0.0
  */
 export const timed = internal.timed;
@@ -3101,7 +3315,7 @@ export const timed = internal.timed;
  *
  * **When to use**
  *
- * Use `raceAll` when early failures should be ignored until a success occurs
+ * Use when early failures should be ignored until a success occurs
  * or all effects fail.
  *
  * **Details**
@@ -3128,7 +3342,7 @@ export const timed = internal.timed;
  * ```
  *
  * @see {@link race} for a version that handles only two effects.
- * @category Racing
+ * @category racing
  * @since 2.0.0
  */
 export const raceAll = internal.raceAll;
@@ -3158,7 +3372,7 @@ export const raceAll = internal.raceAll;
  * // Result: "First" (after ~200ms, even though effect2 completes first but fails)
  * ```
  *
- * @category Racing
+ * @category racing
  * @since 4.0.0
  */
 export const raceAllFirst = internal.raceAllFirst;
@@ -3187,7 +3401,7 @@ export const raceAllFirst = internal.raceAllFirst;
  * // Output: winner: slow-success
  * ```
  *
- * @category Racing
+ * @category racing
  * @since 2.0.0
  */
 export const race = internal.race;
@@ -3219,7 +3433,7 @@ export const race = internal.race;
  * // Output: failed: fast-fail
  * ```
  *
- * @category Racing
+ * @category racing
  * @since 2.0.0
  */
 export const raceFirst = internal.raceFirst;
@@ -3251,12 +3465,43 @@ export const filter = internal.filter;
 /**
  * Filters and maps elements of an iterable with a `Filter`.
  *
+ * **When to use**
+ *
+ * Use to keep only iterable elements accepted by a `Filter` and collect each
+ * filter success value.
+ *
+ * **Details**
+ *
+ * `Result.succeed` values are collected in the returned array, and
+ * `Result.fail` values are skipped.
+ *
+ * @see {@link filter} for keeping original elements with a boolean predicate, refinement, or effectful predicate
+ * @see {@link filterMapEffect} for using an effectful `Filter`
+ *
  * @category filtering
  * @since 2.0.0
  */
 export const filterMap = internal.filterMap;
 /**
- * Effectfully filters and maps elements of an iterable with a `FilterEffect`.
+ * Filters and maps elements of an iterable effectfully with a `FilterEffect`.
+ *
+ * **When to use**
+ *
+ * Use when filtering each iterable element requires effects and accepted
+ * elements should be transformed into successful output values.
+ *
+ * **Details**
+ *
+ * `Result.succeed` values are collected in the returned array, and
+ * `Result.fail` values are skipped.
+ *
+ * **Gotchas**
+ *
+ * With concurrent execution, successful values are collected in completion
+ * order, not input order.
+ *
+ * @see {@link filterMap} for using a synchronous `Filter`
+ * @see {@link filter} for keeping original elements with a predicate
  *
  * @category filtering
  * @since 4.0.0
@@ -3297,6 +3542,20 @@ export const filterOrElse = internal.filterOrElse;
 /**
  * Filters an effect with a `Filter`, providing an alternative effect on failure.
  *
+ * **When to use**
+ *
+ * Use when a successful effect value should be accepted and transformed by a
+ * `Filter`, while rejected values should continue with an alternative effect
+ * built from the filter failure.
+ *
+ * **Details**
+ *
+ * `Result.succeed` becomes the returned success value, and `Result.fail` is
+ * passed to `orElse`.
+ *
+ * @see {@link filterOrElse} for using a predicate and fallback effect
+ * @see {@link filterMapOrFail} for failing the effect when the filter fails
+ *
  * @category filtering
  * @since 4.0.0
  */
@@ -3333,7 +3592,21 @@ export const filterMapOrElse = internal.filterMapOrElse;
  */
 export const filterOrFail = internal.filterOrFail;
 /**
- * Filters an effect with a `Filter`, failing when the filter fails.
+ * Filters and maps an effect with a `Filter`, failing when the filter fails.
+ *
+ * **When to use**
+ *
+ * Use when validating and transforming one effect success with a synchronous
+ * `Filter`, while rejected values should fail the effect.
+ *
+ * **Details**
+ *
+ * `Result.succeed` becomes the returned success value. `Result.fail` is mapped
+ * with `orFailWith` when provided, or fails with `NoSuchElementError`.
+ *
+ * @see {@link filterMapOrElse} for continuing with a fallback effect when the filter fails
+ * @see {@link filterOrFail} for validating with a predicate instead of a `Filter`
+ * @see {@link filterMap} for filtering and mapping iterable elements
  *
  * @category filtering
  * @since 4.0.0
@@ -3343,12 +3616,12 @@ export const filterMapOrFail = internal.filterMapOrFail;
 // Conditional Operators
 // -----------------------------------------------------------------------------
 /**
- * Conditionally runs an effect based on the result of an effectful boolean
+ * Runs an effect conditionally 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
+ * Use when an effectful check decides whether to run another effect while
  * representing the skipped case explicitly.
  *
  * **Details**
@@ -3375,8 +3648,7 @@ export const filterMapOrFail = internal.filterMapOrFail;
  * // { _id: 'Option', _tag: 'Some', value: undefined }
  * ```
  *
- * @see {@link when} for conditional execution with a boolean condition.
- * @category Conditional Operators
+ * @category conditional operators
  * @since 2.0.0
  */
 export const when = internal.when;
@@ -3389,7 +3661,7 @@ export const when = internal.when;
  *
  * **When to use**
  *
- * This is useful for structuring your code to respond differently to success or
+ * Use when this is useful for structuring your code to respond differently to success or
  * failure without triggering side effects.
  *
  * **Details**
@@ -3432,7 +3704,7 @@ export const when = internal.when;
  * ```
  *
  * @see {@link matchEffect} if you need to perform side effects in the handlers.
- * @category Pattern Matching
+ * @category pattern matching
  * @since 2.0.0
  */
 export const match = internal.match;
@@ -3442,7 +3714,7 @@ export const match = internal.match;
  *
  * **When to use**
  *
- * Use this when you need to handle both success and failure cases and want
+ * Use when you need to handle both success and failure cases and want
  * optimal performance for resolved effects. This is particularly useful in
  * scenarios where you frequently work with already computed values.
  *
@@ -3469,7 +3741,7 @@ export const match = internal.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
+ * @category pattern matching
  * @since 4.0.0
  */
 export const matchEager = internal.matchEager;
@@ -3478,7 +3750,7 @@ export const matchEager = internal.matchEager;
  *
  * **When to use**
  *
- * This is useful for differentiating between different types of errors, such as
+ * Use when this is useful for differentiating between different types of errors, such as
  * regular failures, defects, or interruptions. You can provide specific
  * handling logic for each failure type based on the cause.
  *
@@ -3506,7 +3778,7 @@ export const matchEager = internal.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
+ * @category pattern matching
  * @since 2.0.0
  */
 export const matchCause = internal.matchCause;
@@ -3515,7 +3787,7 @@ export const matchCause = internal.matchCause;
  *
  * **When to use**
  *
- * This is useful when you have effects that are likely to be already resolved
+ * Use when this is useful when you have effects that are likely to be already resolved
  * and you want to avoid the overhead of the effect pipeline. For pending effects,
  * it automatically falls back to the regular `matchCause` behavior.
  *
@@ -3536,25 +3808,40 @@ export const matchCause = internal.matchCause;
  * })
  * ```
  *
- * @category Pattern Matching
+ * @category pattern matching
  * @since 4.0.0
  */
 export const matchCauseEager = internal.matchCauseEager;
 /**
- * Eagerly handles success or failure with effectful handlers when the effect is already resolved.
+ * Handles success or failure eagerly with effectful handlers when the effect is already resolved.
+ *
+ * **When to use**
+ *
+ * Use when success and cause-aware failure handlers return effects and the
+ * input may already be resolved, so the selected handler can run immediately
+ * while unresolved inputs keep normal effectful matching behavior.
  *
  * **Details**
  *
  * If the effect is an `Exit`, the matching handler runs immediately; otherwise it behaves like
  * {@link matchCauseEffect}.
  *
- * @category Pattern Matching
+ * @see {@link matchCauseEffect} for the non-eager effectful variant
+ * @see {@link matchCauseEager} for eager cause matching with pure handlers
+ * @see {@link matchEffect} for effectful matching on typed failures instead of full causes
+ *
+ * @category pattern matching
  * @since 4.0.0
  */
 export const matchCauseEffectEager = internal.matchCauseEffectEager;
 /**
  * Handles failures with access to the cause and allows performing side effects.
  *
+ * **When to use**
+ *
+ * Use when both success and failure handling must return effects and the
+ * failure branch needs the full `Cause`.
+ *
  * **Details**
  *
  * The `matchCauseEffect` function works similarly to {@link matchCause}, but it
@@ -3603,7 +3890,7 @@ export const matchCauseEffectEager = internal.matchCauseEffectEager;
  * @see {@link matchCause} if you don't need side effects and only want to handle the result or failure.
  * @see {@link matchEffect} if you don't need to handle the cause of the failure.
  *
- * @category Pattern Matching
+ * @category pattern matching
  * @since 2.0.0
  */
 export const matchCauseEffect = internal.matchCauseEffect;
@@ -3612,7 +3899,7 @@ export const matchCauseEffect = internal.matchCauseEffect;
  *
  * **When to use**
  *
- * Use this when the failure or success branch must run additional effects.
+ * Use when the failure or success branch must run additional effects.
  *
  * **Details**
  *
@@ -3663,7 +3950,7 @@ export const matchCauseEffect = internal.matchCauseEffect;
  *
  * @see {@link match} if you don't need side effects and only want to handle the
  * result or failure.
- * @category Pattern Matching
+ * @category pattern matching
  * @since 2.0.0
  */
 export const matchEffect = internal.matchEffect;
@@ -3691,7 +3978,7 @@ export const matchEffect = internal.matchEffect;
  * // Output: true
  * ```
  *
- * @category Condition Checking
+ * @category condition checking
  * @since 2.0.0
  */
 export const isFailure = internal.isFailure;
@@ -3721,7 +4008,7 @@ export const isFailure = internal.isFailure;
  * // failed: false
  * ```
  *
- * @category Condition Checking
+ * @category condition checking
  * @since 2.0.0
  */
 export const isSuccess = internal.isSuccess;
@@ -3731,6 +4018,10 @@ export const isSuccess = internal.isSuccess;
 /**
  * Returns the complete context.
  *
+ * **When to use**
+ *
+ * Use to read the complete `Context` available to the current effect.
+ *
  * **Details**
  *
  * This function allows you to access all services that are currently available
@@ -3766,13 +4057,20 @@ export const isSuccess = internal.isSuccess;
  * const provided = Effect.provideContext(program, context)
  * ```
  *
- * @category Environment
+ * @see {@link contextWith} for deriving an effect from the complete context
+ * @see {@link service} for reading one service from the context
+ *
+ * @category environment
  * @since 2.0.0
  */
 export const context = internal.context;
 /**
  * Transforms the current context using the provided function.
  *
+ * **When to use**
+ *
+ * Use to derive an effect from the complete `Context`.
+ *
  * **Details**
  *
  * This function allows you to access the complete context and perform
@@ -3814,7 +4112,10 @@ export const context = internal.context;
  * })
  * ```
  *
- * @category Environment
+ * @see {@link context} for reading the complete context as a value
+ * @see {@link service} for reading one service from the context
+ *
+ * @category environment
  * @since 2.0.0
  */
 export const contextWith = internal.contextWith;
@@ -3849,7 +4150,7 @@ export const contextWith = internal.contextWith;
  * // Output: "Result for: SELECT * FROM users"
  * ```
  *
- * @category Environment
+ * @category environment
  * @since 2.0.0
  */
 export const provide = internalLayer.provide;
@@ -3890,7 +4191,7 @@ export const provide = internalLayer.provide;
  * const provided = Effect.provideContext(program, context)
  * ```
  *
- * @category Environment
+ * @category environment
  * @since 4.0.0
  */
 export const provideContext = internal.provideContext;
@@ -3914,13 +4215,18 @@ export const provideContext = internal.provideContext;
  * })
  * ```
  *
- * @category Context
+ * @category context
  * @since 4.0.0
  */
 export const service = internal.service;
 /**
  * Optionally accesses a service from the environment.
  *
+ * **When to use**
+ *
+ * Use to read an optional dependency from the current context without making
+ * that dependency part of the effect's required environment.
+ *
  * **Details**
  *
  * This function attempts to access a service from the environment. If the
@@ -3950,7 +4256,7 @@ export const service = internal.service;
  * })
  * ```
  *
- * @category Context
+ * @category context
  * @since 2.0.0
  */
 export const serviceOption = internal.serviceOption;
@@ -3992,7 +4298,7 @@ export const serviceOption = internal.serviceOption;
  * })
  * ```
  *
- * @category Context
+ * @category context
  * @since 4.0.0
  */
 export const updateContext = internal.updateContext;
@@ -4028,21 +4334,21 @@ export const updateContext = internal.updateContext;
  * // 1
  * ```
  *
- * @category Context
+ * @category context
  * @since 2.0.0
  */
 export const updateService = internal.updateService;
 /**
- * The `provideService` function is used to provide an actual
- * implementation for a service in the context of an effect.
+ * Provides one concrete service implementation to an effect.
+ *
+ * **When to use**
+ *
+ * Use to satisfy one service requirement with an already-built implementation.
  *
  * **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.
+ * The service requirement identified by the `Context.Key` is removed from the
+ * effect requirements after the implementation is provided.
  *
  * **Example** (Providing a service value)
  *
@@ -4076,7 +4382,9 @@ export const updateService = internal.updateService;
  * ```
  *
  * @see {@link provide} for providing multiple layers to an effect.
- * @category Context
+ * @see {@link provideServiceEffect} for acquiring the service implementation effectfully.
+ * @see {@link provideContext} for providing a complete context.
+ * @category context
  * @since 2.0.0
  */
 export const provideService = internal.provideService;
@@ -4130,7 +4438,7 @@ export const provideService = internal.provideService;
  * // Result for: SELECT * FROM users
  * ```
  *
- * @category Context
+ * @category context
  * @since 2.0.0
  */
 export const provideServiceEffect = internal.provideServiceEffect;
@@ -4207,9 +4515,16 @@ export const withConcurrency = internal.withConcurrency;
  */
 export const scope = internal.scope;
 /**
- * Scopes all resources used in this workflow to the lifetime of the workflow,
- * ensuring that their finalizers are run as soon as this workflow completes
- * execution, whether by success, failure, or interruption.
+ * Runs an effect with a scope that closes when the effect completes.
+ *
+ * **When to use**
+ *
+ * Use to acquire scoped resources for the duration of a single workflow.
+ *
+ * **Details**
+ *
+ * Finalizers for resources acquired inside the workflow run as soon as the
+ * workflow completes, whether by success, failure, or interruption.
  *
  * **Example** (Running a scoped acquisition)
  *
@@ -4283,6 +4598,10 @@ export const scopedWith = internal.scopedWith;
  * Constructs a scoped resource from an acquisition effect and a release
  * finalizer.
  *
+ * **When to use**
+ *
+ * Use to acquire a scoped resource with an explicit release finalizer.
+ *
  * **Details**
  *
  * If acquisition succeeds, the release finalizer is added to the current scope
@@ -4330,13 +4649,20 @@ export const scopedWith = internal.scopedWith;
  * )
  * ```
  *
+ * @see {@link acquireDisposable} for resources that implement JavaScript disposal protocols
+ * @see {@link acquireUseRelease} for bracketing acquire, use, and release in one effect
+ *
  * @category resource management
  * @since 2.0.0
  */
 export const acquireRelease = internal.acquireRelease;
 /**
- * This function constructs a scoped resource from an Effect that acquires a
- * disposable value.
+ * Acquires a scoped resource that implements JavaScript disposal protocols.
+ *
+ * **When to use**
+ *
+ * Use with JavaScript `Disposable` or `AsyncDisposable` resources that should
+ * be closed with the surrounding scope.
  *
  * **Details**
  *
@@ -4346,8 +4672,9 @@ export const acquireRelease = internal.acquireRelease;
  * disposables.
  *
  * This is similar to {@link acquireRelease}, but uses the standard
- * JavaScript disposal protocal instead of requiring an explicit release
- * function.
+ * JavaScript disposal protocol instead of requiring an explicit release
+ * function. It works with JavaScript `Disposable` and `AsyncDisposable`
+ * resources.
  *
  * **Example** (Acquiring a disposable resource)
  *
@@ -4369,16 +4696,18 @@ export const acquireRelease = internal.acquireRelease;
  * )
  * ```
  *
- * @see [JavaScript `using` declarations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using)
+ * @see {@link acquireRelease} for resources that need an explicit finalizer
+ *
  * @category resource management
  * @since 4.0.0
  */
 export const acquireDisposable = internal.acquireDisposable;
 /**
- * This function is used to ensure that an `Effect` value that represents the
- * acquisition of a resource (for example, opening a file, launching a thread,
- * etc.) will not be interrupted, and that the resource will always be released
- * when the `Effect` value completes execution.
+ * Runs resource acquisition, usage, and release as one bracketed effect.
+ *
+ * **When to use**
+ *
+ * Use to bracket acquire, use, and release logic in one effect.
  *
  * **Details**
  *
@@ -4445,20 +4774,23 @@ export const acquireDisposable = internal.acquireDisposable;
  * // Closing connection to db://localhost:5432 (success)
  * ```
  *
+ * @see {@link acquireRelease} for scoped resources whose use happens later
+ *
  * @category resource management
  * @since 2.0.0
  */
 export const acquireUseRelease = internal.acquireUseRelease;
 /**
- * This function adds a finalizer to the scope of the calling `Effect` value.
- * 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.
+ * Adds a finalizer to the current scope.
+ *
+ * **When to use**
+ *
+ * Use to register low-level cleanup in the current scope.
  *
  * **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.
+ * The finalizer runs when the surrounding scope is closed and receives the
+ * `Exit` value used to close the scope.
  *
  * **Example** (Registering scope finalizers)
  *
@@ -4490,6 +4822,9 @@ export const acquireUseRelease = internal.acquireUseRelease;
  * // operation result
  * ```
  *
+ * @see {@link acquireRelease} for resource acquisition with a release finalizer
+ * @see {@link ensuring} for attaching a finalizer to one effect
+ *
  * @category resource management
  * @since 2.0.0
  */
@@ -4593,6 +4928,16 @@ export const onErrorIf = internal.onErrorIf;
 /**
  * Runs the finalizer only when this effect fails and the cause matches the provided `Filter`.
  *
+ * **When to use**
+ *
+ * Use when cleanup or diagnostics should run only for failures whose full
+ * `Cause` is accepted or transformed by a `Filter`, and the finalizer needs the
+ * filter's pass value plus the original cause.
+ *
+ * @see {@link onError} for cleanup on every failure
+ * @see {@link onErrorIf} for selecting failures with a boolean predicate
+ * @see {@link onExitFilter} for selecting from every exit instead of only failures
+ *
  * @category resource management
  * @since 4.0.0
  */
@@ -4601,18 +4946,26 @@ export const onErrorFilter = internal.onErrorFilter;
  * Runs an optional finalizer with the effect's `Exit` value when the effect
  * completes.
  *
+ * **When to use**
+ *
+ * Use when you are building a low-level `Effect` operator that must inspect the
+ * source effect's `Exit`, may skip finalization by returning `undefined`, or
+ * must choose whether finalization is forced into an uninterruptible region.
+ *
  * **Details**
  *
  * This low-level operator preserves the source effect's result unless the
  * finalizer fails. Prefer `onExit` for normal cleanup logic.
  *
+ * @see {@link onExit} for ordinary exit-aware cleanup whose finalizer always returns an effect
+ *
  * @category resource management
  * @since 4.0.0
  */
 export const onExitPrimitive = internal.onExitPrimitive;
 /**
- * Ensures that a cleanup functions runs, whether this effect succeeds, fails,
- * or is interrupted.
+ * Ensures that a cleanup function runs whether this effect succeeds, fails, or
+ * is interrupted.
  *
  * **Example** (Observing every exit)
  *
@@ -4664,6 +5017,21 @@ export const onExitIf = internal.onExitIf;
 /**
  * Runs the cleanup effect only when the `Exit` matches the provided `Filter`.
  *
+ * **When to use**
+ *
+ * Use when cleanup should run only for `Exit` values selected by a `Filter`,
+ * and the cleanup needs the extracted pass value together with the original
+ * `Exit`.
+ *
+ * **Details**
+ *
+ * `Result.fail` skips cleanup, and `Result.succeed` runs cleanup with the
+ * selected value and the original `Exit`.
+ *
+ * @see {@link onExit} for cleanup on every exit
+ * @see {@link onExitIf} for selecting exits with a boolean predicate
+ * @see {@link onErrorFilter} for selecting only failure causes
+ *
  * @category resource management
  * @since 4.0.0
  */
@@ -4677,7 +5045,7 @@ export const onExitFilter = internal.onExitFilter;
  *
  * **When to use**
  *
- * Use this function when you have an expensive or time-consuming operation that
+ * Use when you use this function when you have an expensive or time-consuming operation that
  * you want to avoid repeating. The first evaluation will compute the result,
  * and all following evaluations will immediately return the cached value,
  * improving performance and reducing unnecessary work.
@@ -4731,7 +5099,7 @@ export const onExitFilter = internal.onExitFilter;
  * 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
+ * @category caching
  * @since 2.0.0
  */
 export const cached = internal.cached;
@@ -4741,7 +5109,7 @@ export const cached = internal.cached;
  *
  * **When to use**
  *
- * Use this function when you have an effect that involves costly operations or
+ * Use when you use this function when you have an effect that involves costly operations or
  * computations, and you want to avoid repeating them within a short time frame.
  *
  * It's ideal for scenarios where the result of an effect doesn't change
@@ -4798,23 +5166,19 @@ export const cached = internal.cached;
  * indefinitely.
  * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
  * additional effect for manually invalidating the cached value.
- * @category Caching
+ * @category caching
  * @since 2.0.0
  */
 export const cachedWithTTL = internal.cachedWithTTL;
 /**
- * Caches an effect's result for a specified duration and allows manual
+ * Creates a cached effect 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.
+ * Use when an effect result should be cached for a bounded time and callers
+ * also need a manual invalidation effect to force recomputation before
+ * expiration.
  *
  * **Details**
  *
@@ -4868,7 +5232,7 @@ export const cachedWithTTL = internal.cachedWithTTL;
  * 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
+ * @category caching
  * @since 2.0.0
  */
 export const cachedInvalidateWithTTL = internal.cachedInvalidateWithTTL;
@@ -4892,7 +5256,7 @@ export const cachedInvalidateWithTTL = internal.cachedInvalidateWithTTL;
  * // Throws: InterruptedException
  * ```
  *
- * @category Interruption
+ * @category interruption
  * @since 2.0.0
  */
 export const interrupt = internal.interrupt;
@@ -4913,7 +5277,7 @@ export const interrupt = internal.interrupt;
  * // Later: fiber.interrupt()
  * ```
  *
- * @category Interruption
+ * @category interruption
  * @since 2.0.0
  */
 export const interruptible = internal.interruptible;
@@ -4938,7 +5302,7 @@ export const interruptible = internal.interruptible;
  * // Output: Task was interrupted, cleaning up...
  * ```
  *
- * @category Interruption
+ * @category interruption
  * @since 2.0.0
  */
 export const onInterrupt = internal.onInterrupt;
@@ -4963,7 +5327,7 @@ export const onInterrupt = internal.onInterrupt;
  * Effect.runPromise(Fiber.interrupt(fiber))
  * ```
  *
- * @category Interruption
+ * @category interruption
  * @since 2.0.0
  */
 export const uninterruptible = internal.uninterruptible;
@@ -4994,14 +5358,13 @@ export const uninterruptible = internal.uninterruptible;
  * )
  * ```
  *
- * @category Interruption
+ * @category interruption
  * @since 2.0.0
  */
 export const uninterruptibleMask = internal.uninterruptibleMask;
 /**
- * This function behaves like {@link interruptible}, but it also provides a
- * `restore` function. This function can be used to restore the interruptibility
- * of any specific region of code.
+ * Runs an effect in an interruptible region while providing `restore` for
+ * locally restoring the previous interruptibility.
  *
  * **Example** (Controlling interruptibility locally)
  *
@@ -5026,14 +5389,32 @@ export const uninterruptibleMask = internal.uninterruptibleMask;
  * )
  * ```
  *
- * @category Interruption
+ * @category interruption
  * @since 2.0.0
  */
 export const interruptibleMask = internal.interruptibleMask;
 /**
  * Creates an AbortSignal that is managed by the provided scope.
  *
- * @category Interruption
+ * **When to use**
+ *
+ * Use to obtain a scope-managed `AbortSignal` for APIs that accept cancellation
+ * through a signal.
+ *
+ * **Details**
+ *
+ * Each acquisition creates a fresh `AbortController`. Closing the owning scope
+ * runs a finalizer that aborts the controller and the effect succeeds with the
+ * controller's signal.
+ *
+ * **Gotchas**
+ *
+ * The signal is aborted when its owning scope closes, so avoid keeping it for
+ * work that outlives that scope.
+ *
+ * @see {@link scoped} for binding resource lifetime to a scope
+ *
+ * @category interruption
  * @since 4.0.0
  */
 export const abortSignal = internal.abortSignal;
@@ -5064,13 +5445,17 @@ export const abortSignal = internal.abortSignal;
  * })
  * ```
  *
- * @category Repetition / Recursion
+ * @category repetition / recursion
  * @since 2.0.0
  */
 export const forever = internal.forever;
 /**
  * Repeats an effect based on a specified schedule or until the first failure.
  *
+ * **When to use**
+ *
+ * Use to rerun an effect after successful executions.
+ *
  * **Details**
  *
  * This function executes an effect repeatedly according to the given schedule.
@@ -5090,6 +5475,11 @@ export const forever = internal.forever;
  * delays, limiting recursions, or dynamically adjusting based on the outcome of
  * each execution.
  *
+ * **Gotchas**
+ *
+ * The source effect is always evaluated once before the schedule is stepped.
+ * The schedule controls additional repetitions, not the initial execution.
+ *
  * **Example** (Repeating successful effects with a schedule)
  *
  * ```ts
@@ -5129,7 +5519,10 @@ export const forever = internal.forever;
  * // Effect.runPromiseExit(program).then(console.log)
  * ```
  *
- * @category Repetition / Recursion
+ * @see {@link retry} for failure-based repetition
+ * @see {@link repeatOrElse} for fallback handling when repetition fails
+ *
+ * @category repetition / recursion
  * @since 2.0.0
  */
 export const repeat = internalSchedule.repeat;
@@ -5172,18 +5565,27 @@ export const repeat = internalSchedule.repeat;
  * )
  * ```
  *
- * @category Repetition / Recursion
+ * @category repetition / recursion
  * @since 2.0.0
  */
 export const repeatOrElse = internalSchedule.repeatOrElse;
 /**
  * Returns an array of `n` identical effects.
  *
+ * **When to use**
+ *
+ * Use to create an array containing the same effect multiple times when you
+ * want to pass those effects to another collector or control execution
+ * separately.
+ *
  * **Details**
  *
- * Use with `Effect.all` to run the replicated effects and collect results.
+ * This only creates the array of effects. It does not run or collect them.
  *
- * @category Collecting
+ * @see {@link all} for running the returned effects and collecting results
+ * @see {@link replicateEffect} for repeating an effect and collecting results in one step with concurrency and discard options
+ *
+ * @category collecting
  * @since 2.0.0
  */
 export const replicate = internal.replicate;
@@ -5205,7 +5607,7 @@ export const replicate = internal.replicate;
  * })
  * ```
  *
- * @category Collecting
+ * @category collecting
  * @since 2.0.0
  */
 export const replicateEffect = internal.replicateEffect;
@@ -5213,6 +5615,11 @@ export const replicateEffect = internal.replicateEffect;
  * Runs an effect repeatedly according to a schedule and returns the schedule's
  * final output.
  *
+ * **When to use**
+ *
+ * Use to rerun a successful effect according to a `Schedule` when the schedule
+ * does not need a custom initial input.
+ *
  * **Details**
  *
  * The schedule is first stepped with `undefined`. After each successful
@@ -5248,7 +5655,7 @@ export const replicateEffect = internal.replicateEffect;
  * @see {@link scheduleFrom} for a variant that allows the schedule's decision
  * to depend on the result of this effect.
  *
- * @category Repetition / Recursion
+ * @category repetition / recursion
  * @since 2.0.0
  */
 export const schedule = /*#__PURE__*/dual(2, (self, schedule) => scheduleFrom(self, undefined, schedule));
@@ -5286,7 +5693,7 @@ export const schedule = /*#__PURE__*/dual(2, (self, schedule) => scheduleFrom(se
  * // Returns the schedule count
  * ```
  *
- * @category Repetition / Recursion
+ * @category repetition / recursion
  * @since 2.0.0
  */
 export const scheduleFrom = internalSchedule.scheduleFrom;
@@ -5546,7 +5953,7 @@ export const spanAnnotations = internal.spanAnnotations;
  */
 export const spanLinks = internal.spanLinks;
 /**
- * For all spans in this effect, add a link with the provided span.
+ * Adds a link with the provided span to all spans in this effect.
  *
  * **Details**
  *
@@ -5682,7 +6089,7 @@ export const makeSpanScoped = internal.makeSpanScoped;
  */
 export const useSpan = internal.useSpan;
 /**
- * Wraps the effect with a new span for tracing.
+ * Wraps the effect with a child span for tracing.
  *
  * **Example** (Wrapping an effect in a child span)
  *
@@ -5704,7 +6111,7 @@ export const useSpan = internal.useSpan;
  */
 export const withSpan = internal.withSpan;
 /**
- * Wraps the effect with a new span for tracing.
+ * Wraps the effect with a scoped child span for tracing.
  *
  * **Details**
  *
@@ -5754,8 +6161,11 @@ export const withParentSpan = internal.withParentSpan;
 /**
  * Executes a request using the provided resolver.
  *
- * @category Requests & Batching
- * @since 2.0.0
+ * **When to use**
+ *
+ * Use to execute a typed `Request` through a `RequestResolver` when you want
+ * concurrent requests made with the same resolver to be collected and completed
+ * by resolver logic.
  *
  * **Example** (Executing a request through a resolver)
  *
@@ -5781,17 +6191,28 @@ export const withParentSpan = internal.withParentSpan;
  *   yield* Console.log(name)
  * })
  * ```
+ *
+ * @see {@link requestUnsafe} for the low-level entry point when you already have a `Context` and need to enqueue outside an `Effect`
+ *
+ * @category requests & batching
+ * @since 2.0.0
  */
 export const request = internalRequest.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`.
+ * Registers a request with a resolver and delivers the exit value via `onExit`.
+ *
+ * **When to use**
+ *
+ * Use when you already have a `Context` and need to enqueue a request outside
+ * an `Effect` while receiving completion through `onExit`.
  *
  * **Details**
  *
  * It returns a canceler that removes the pending request entry.
  *
- * @category Requests & Batching
+ * @see {@link request} for the `Effect`-returning API used for normal request execution
+ *
+ * @category requests & batching
  * @since 4.0.0
  */
 export const requestUnsafe = internalRequest.requestUnsafe;
@@ -5844,7 +6265,7 @@ export const requestUnsafe = internalRequest.requestUnsafe;
  * })
  * ```
  *
- * @category Supervision & Fibers
+ * @category supervision & fibers
  * @since 4.0.0
  */
 export const forkChild = internal.forkChild;
@@ -5873,7 +6294,7 @@ export const forkChild = internal.forkChild;
  * )
  * ```
  *
- * @category Supervision & Fibers
+ * @category supervision & fibers
  * @since 2.0.0
  */
 export const forkIn = internal.forkIn;
@@ -5907,7 +6328,7 @@ export const forkIn = internal.forkIn;
  * )
  * ```
  *
- * @category Supervision & Fibers
+ * @category supervision & fibers
  * @since 2.0.0
  */
 export const forkScoped = internal.forkScoped;
@@ -5941,7 +6362,7 @@ export const forkScoped = internal.forkScoped;
  * })
  * ```
  *
- * @category Supervision & Fibers
+ * @category supervision & fibers
  * @since 4.0.0
  */
 export const forkDetach = internal.forkDetach;
@@ -5949,12 +6370,27 @@ export const forkDetach = internal.forkDetach;
  * Waits for all child fibers forked by this effect to complete before this
  * effect completes.
  *
- * @category Supervision & Fibers
+ * **When to use**
+ *
+ * Use to let an effect start child work concurrently while still delaying its
+ * own completion until that child work is done.
+ *
+ * **Gotchas**
+ *
+ * Child fibers that already exist before the wrapped effect starts are not
+ * awaited.
+ *
+ * @see {@link forkChild} for forking child fibers that are awaited by this operator
+ * @see {@link forkDetach} for forking fibers outside the child scope
+ * @see {@link forkIn} for forking into an explicit scope
+ * @see {@link forkScoped} for forking fibers tied to the current scope
+ *
+ * @category supervision & fibers
  * @since 2.0.0
  */
 export const awaitAllChildren = internal.awaitAllChildren;
 /**
- * Access the fiber currently executing the effect.
+ * Accesses the fiber currently executing the effect.
  *
  * **Example** (Accessing the current fiber)
  *
@@ -5967,12 +6403,12 @@ export const awaitAllChildren = internal.awaitAllChildren;
  * })
  * ```
  *
- * @category Supervision & Fibers
+ * @category supervision & fibers
  * @since 4.0.0
  */
 export const fiber = internal.fiber;
 /**
- * Access the current fiber id executing the effect.
+ * Accesses the current fiber id executing the effect.
  *
  * **Example** (Accessing the current fiber id)
  *
@@ -5990,22 +6426,19 @@ export const fiber = internal.fiber;
  * )
  * ```
  *
- * @category Supervision & Fibers
+ * @category supervision & fibers
  * @since 2.0.0
  */
 export const fiberId = internal.fiberId;
 /**
- * The foundational function for running effects, returning a "fiber" that can
+ * Runs an effect in the background, returning a fiber that can
  * be observed or interrupted.
  *
  * **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
- * that can be observed or interrupted.
- *
- * Unless you specifically need a `Promise` or synchronous operation,
- * `runFork` is a good default choice.
+ * Use when an effect should start in the background and return a fiber that can
+ * be observed or interrupted. Prefer this when you do not need a `Promise` or
+ * synchronous result.
  *
  * **Example** (Running an effect in the background)
  *
@@ -6028,7 +6461,7 @@ export const fiberId = internal.fiberId;
  * }, 500)
  * ```
  *
- * @category Running Effects
+ * @category running effects
  * @since 2.0.0
  */
 export const runFork = internal.runFork;
@@ -6059,7 +6492,7 @@ export const runFork = internal.runFork;
  * const fiber = Effect.runForkWith(services)(program)
  * ```
  *
- * @category Running Effects
+ * @category running effects
  * @since 4.0.0
  */
 export const runForkWith = internal.runForkWith;
@@ -6103,7 +6536,7 @@ export const runForkWith = internal.runForkWith;
  * interrupt()
  * ```
  *
- * @category Running Effects
+ * @category running effects
  * @since 4.0.0
  */
 export const runCallbackWith = internal.runCallbackWith;
@@ -6144,7 +6577,7 @@ export const runCallbackWith = internal.runCallbackWith;
  * // interrupt() to cancel the fiber if needed
  * ```
  *
- * @category Running Effects
+ * @category running effects
  * @since 2.0.0
  */
 export const runCallback = internal.runCallback;
@@ -6153,7 +6586,7 @@ export const runCallback = internal.runCallback;
  *
  * **When to use**
  *
- * Use `runPromise` when you need to execute an effect and work with the
+ * Use when you need to execute an effect and work with the
  * result using `Promise` syntax, typically for compatibility with other
  * promise-based code.
  *
@@ -6181,7 +6614,7 @@ export const runCallback = internal.runCallback;
  * ```
  *
  * @see {@link runPromiseExit} for a version that returns an `Exit` type instead of rejecting.
- * @category Running Effects
+ * @category running effects
  * @since 2.0.0
  */
 export const runPromise = internal.runPromise;
@@ -6211,7 +6644,7 @@ export const runPromise = internal.runPromise;
  * Effect.runPromiseWith(context)(program).then(console.log)
  * ```
  *
- * @category Running Effects
+ * @category running effects
  * @since 4.0.0
  */
 export const runPromiseWith = internal.runPromiseWith;
@@ -6221,7 +6654,7 @@ export const runPromiseWith = internal.runPromiseWith;
  *
  * **When to use**
  *
- * Use `runPromiseExit` when you need to determine if an effect succeeded
+ * Use when you need to determine if an effect succeeded
  * or failed, including any defects, and you want to work with a `Promise`.
  *
  * **Details**
@@ -6259,7 +6692,9 @@ export const runPromiseWith = internal.runPromiseWith;
  * // }
  * ```
  *
- * @category Running Effects
+ * @see {@link runPromise} for a version that rejects on failure.
+ *
+ * @category running effects
  * @since 2.0.0
  */
 export const runPromiseExit = internal.runPromiseExit;
@@ -6293,7 +6728,7 @@ export const runPromiseExit = internal.runPromiseExit;
  * })
  * ```
  *
- * @category Running Effects
+ * @category running effects
  * @since 4.0.0
  */
 export const runPromiseExitWith = internal.runPromiseExitWith;
@@ -6302,7 +6737,8 @@ export const runPromiseExitWith = internal.runPromiseExitWith;
  *
  * **When to use**
  *
- * Use `runSync` only for effects that can complete synchronously.
+ * Use when you need to execute an effect that is guaranteed to complete
+ * synchronously.
  *
  * **Details**
  *
@@ -6353,7 +6789,7 @@ export const runPromiseExitWith = internal.runPromiseExitWith;
  *
  * @see {@link runSyncExit} for a version that returns an `Exit` type instead of
  * throwing an error.
- * @category Running Effects
+ * @category running effects
  * @since 2.0.0
  */
 export const runSync = internal.runSync;
@@ -6384,17 +6820,17 @@ export const runSync = internal.runSync;
  * console.log(result) // 5
  * ```
  *
- * @category Running Effects
+ * @category running effects
  * @since 4.0.0
  */
 export const runSyncWith = internal.runSyncWith;
 /**
- * Runs an effect synchronously and returns the result as an `Exit` type, which
+ * Runs an effect synchronously and captures the outcome safely as an `Exit` type, which
  * represents the outcome (success or failure) of the effect.
  *
  * **When to use**
  *
- * Use `runSyncExit` to find out whether an effect succeeded or failed,
+ * Use to find out whether an effect succeeded or failed,
  * including any defects, without dealing with asynchronous operations.
  *
  * **Details**
@@ -6456,12 +6892,14 @@ export const runSyncWith = internal.runSyncWith;
  * // }
  * ```
  *
- * @category Running Effects
+ * @see {@link runSync} for a version that throws on failure.
+ *
+ * @category running effects
  * @since 2.0.0
  */
 export const runSyncExit = internal.runSyncExit;
 /**
- * Runs an effect synchronously with provided services, returning an Exit result.
+ * Runs an effect synchronously with provided services, returning an Exit result safely.
  *
  * **Example** (Running synchronously with services as Exit)
  *
@@ -6496,7 +6934,7 @@ export const runSyncExit = internal.runSyncExit;
  * // Success: 42
  * ```
  *
- * @category Running Effects
+ * @category running effects
  * @since 4.0.0
  */
 export const runSyncExitWith = internal.runSyncExitWith;
@@ -6520,7 +6958,7 @@ export const runSyncExitWith = internal.runSyncExitWith;
  * Effect.runFork(greet("Ada"))
  * ```
  *
- * @category Function
+ * @category functions
  * @since 3.12.0
  */
 export const fnUntraced = internal.fnUntraced;
@@ -6551,7 +6989,7 @@ export const fnUntraced = internal.fnUntraced;
  * })
  * ```
  *
- * @category Function
+ * @category functions
  * @since 3.11.0
  */
 export const fn = internal.fn;
@@ -6579,7 +7017,7 @@ export const fn = internal.fn;
  * // Current time is: 1735484929744
  * ```
  *
- * @category Clock
+ * @category clock
  * @since 2.0.0
  */
 export const clockWith = internal.clockWith;
@@ -6892,6 +7330,10 @@ export const annotateLogs = /*#__PURE__*/dual(args => isEffect(args[0]), (effect
 /**
  * Adds log annotations to the current scope.
  *
+ * **When to use**
+ *
+ * Use to attach log annotations that last until the current scope closes.
+ *
  * **Details**
  *
  * This differs from `annotateLogs`, which only annotates a specific effect.
@@ -6914,6 +7356,8 @@ export const annotateLogs = /*#__PURE__*/dual(args => isEffect(args[0]), (effect
  * Effect.runPromise(program)
  * ```
  *
+ * @see {@link annotateLogs} for annotating one effect
+ *
  * @category logging
  * @since 3.1.0
  */
@@ -7005,7 +7449,7 @@ export const withLogSpan = /*#__PURE__*/dual(2, (effect, label) => internal.flat
  * )
  * ```
  *
- * @category Tracking
+ * @category tracking
  * @since 4.0.0
  */
 export const track = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric, f) => onExit(self, exit => {
@@ -7058,7 +7502,7 @@ export const track = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric,
  * )
  * ```
  *
- * @category Tracking
+ * @category tracking
  * @since 4.0.0
  */
 export const trackSuccesses = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric, f) => tap(self, value => {
@@ -7113,7 +7557,7 @@ export const trackSuccesses = /*#__PURE__*/dual(args => isEffect(args[0]), (self
  * )
  * ```
  *
- * @category Tracking
+ * @category tracking
  * @since 4.0.0
  */
 export const trackErrors = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric, f) => tapError(self, error => {
@@ -7169,7 +7613,7 @@ export const trackErrors = /*#__PURE__*/dual(args => isEffect(args[0]), (self, m
  * )
  * ```
  *
- * @category Tracking
+ * @category tracking
  * @since 4.0.0
  */
 export const trackDefects = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric, f) => tapDefect(self, defect => {
@@ -7221,7 +7665,7 @@ export const trackDefects = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
  * )
  * ```
  *
- * @category Tracking
+ * @category tracking
  * @since 4.0.0
  */
 export const trackDuration = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric, f) => clockWith(clock => {
@@ -7237,12 +7681,12 @@ export const trackDuration = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
 // Transactions
 // -----------------------------------------------------------------------------
 /**
- * Service that holds the current transaction state, it includes
+ * Service that holds the current transaction state.
  *
  * **Details**
  *
- * - a journal that stores any non committed change to TxRef values
- * - a retry flag to know if the transaction should be retried
+ * It includes a journal that stores non-committed changes to `TxRef` values and
+ * a retry flag that records whether the transaction should be retried.
  *
  * **Example** (Building transactions)
  *
@@ -7257,7 +7701,7 @@ export const trackDuration = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
  * })
  * ```
  *
- * @category Transactions
+ * @category transactions
  * @since 4.0.0
  */
 export class Transaction extends /*#__PURE__*/Context.Service()("effect/Effect/Transaction") {}
@@ -7303,7 +7747,7 @@ export class Transaction extends /*#__PURE__*/Context.Service()("effect/Effect/T
  * })
  * ```
  *
- * @category Transactions
+ * @category transactions
  * @since 4.0.0
  */
 export const tx = effect => withFiber(fiber => {
@@ -7383,7 +7827,7 @@ function clearTransaction(state) {
   state.journal.clear();
 }
 /**
- * Signals that the current transaction needs to be retried.
+ * Retries the current transaction by signaling that it must be retried.
  *
  * **Details**
  *
@@ -7418,7 +7862,7 @@ function clearTransaction(state) {
  * Effect.runPromise(program).catch(console.error)
  * ```
  *
- * @category Transactions
+ * @category transactions
  * @since 4.0.0
  */
 export const txRetry = /*#__PURE__*/flatMap(Transaction, state => {
@@ -7470,7 +7914,7 @@ export const txRetry = /*#__PURE__*/flatMap(Transaction, state => {
  * // Output: Exit.failure with custom error message
  * ```
  *
- * @category Effectify
+ * @category effectify
  * @since 4.0.0
  */
 export const effectify = (fn, onError, onSyncError) => (...args) => callback(resume => {
@@ -7494,8 +7938,8 @@ export const effectify = (fn, onError, onSyncError) => (...args) => callback(res
  *
  * **Details**
  *
- * This function provides compile-time type checking to ensure that the success
- * value of an effect conforms to a specific type constraint.
+ * This helper is checked at compile time and does not change the effect's
+ * runtime behavior.
  *
  * **Example** (Constraining the success type)
  *
@@ -7514,7 +7958,7 @@ export const effectify = (fn, onError, onSyncError) => (...args) => callback(res
  * // Type 'string' is not assignable to type 'number'
  * ```
  *
- * @category Type Constraints
+ * @category utility types
  * @since 4.0.0
  */
 export const satisfiesSuccessType = () => effect => effect;
@@ -7523,8 +7967,8 @@ export const satisfiesSuccessType = () => effect => effect;
  *
  * **Details**
  *
- * This function provides compile-time type checking to ensure that the error
- * type of an effect conforms to a specific type constraint.
+ * This helper is checked at compile time and does not change the effect's
+ * runtime behavior.
  *
  * **Example** (Constraining the error type)
  *
@@ -7545,7 +7989,7 @@ export const satisfiesSuccessType = () => effect => effect;
  * // Type 'string' is not assignable to type 'ValidationError'
  * ```
  *
- * @category Type Constraints
+ * @category utility types
  * @since 4.0.0
  */
 export const satisfiesErrorType = () => effect => effect;
@@ -7554,8 +7998,8 @@ export const satisfiesErrorType = () => effect => effect;
  *
  * **Details**
  *
- * This function provides compile-time type checking to ensure that the
- * requirements (context) type of an effect conforms to a specific type constraint.
+ * This helper is checked at compile time and does not change the effect's
+ * runtime behavior.
  *
  * **Example** (Constraining the services type)
  *
@@ -7574,19 +8018,17 @@ export const satisfiesErrorType = () => effect => effect;
  * // const constrainedInvalid = satisfiesStringServices(invalidEffect)
  * ```
  *
- * @category Type Constraints
+ * @category utility types
  * @since 4.0.0
  */
 export const satisfiesServicesType = () => effect => effect;
 /**
- * An optimized version of `map` that checks if an effect is already resolved
- * and applies the mapping function eagerly when possible.
+ * Applies `map` eagerly when an effect is already resolved.
  *
  * **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.
+ * Use when an already-resolved effect should apply a success transformation
+ * immediately while pending effects still use regular mapping.
  *
  * **Details**
  *
@@ -7610,19 +8052,18 @@ export const satisfiesServicesType = () => effect => effect;
  * const mappedPending = Effect.mapEager(pending, (n) => n * 2) // Uses regular map
  * ```
  *
- * @category Eager
+ * @category eager
  * @since 4.0.0
  */
 export const mapEager = internal.mapEager;
 /**
- * An optimized version of `mapError` that checks if an effect is already resolved
- * and applies the error mapping function eagerly when possible.
+ * Applies `mapError` eagerly when an effect is already resolved.
  *
  * **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.
+ * Use when an already-resolved failed effect should apply an error
+ * transformation immediately while pending effects still use regular error
+ * mapping.
  *
  * **Details**
  *
@@ -7649,19 +8090,17 @@ export const mapEager = internal.mapEager;
  * ) // Uses regular mapError
  * ```
  *
- * @category Eager
+ * @category eager
  * @since 4.0.0
  */
 export const mapErrorEager = internal.mapErrorEager;
 /**
- * An optimized version of `mapBoth` that checks if an effect is already resolved
- * and applies the appropriate mapping function eagerly when possible.
+ * Applies `mapBoth` eagerly when an effect is already resolved.
  *
  * **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.
+ * Use when an already-resolved effect should transform either success or
+ * failure immediately while pending effects still use regular channel mapping.
  *
  * **Details**
  *
@@ -7690,19 +8129,17 @@ export const mapErrorEager = internal.mapErrorEager;
  * }) // onFailure applied eagerly
  * ```
  *
- * @category Eager
+ * @category eager
  * @since 4.0.0
  */
 export const mapBothEager = internal.mapBothEager;
 /**
- * An optimized version of `flatMap` that checks if an effect is already resolved
- * and applies the flatMap function eagerly when possible.
+ * Applies `flatMap` eagerly when an effect is already resolved.
  *
  * **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.
+ * Use when an already-resolved successful effect should bind immediately to the
+ * next effect while pending effects still use regular flat mapping.
  *
  * **Details**
  *
@@ -7729,19 +8166,17 @@ export const mapBothEager = internal.mapBothEager;
  * ) // Uses regular flatMap
  * ```
  *
- * @category Eager
+ * @category eager
  * @since 4.0.0
  */
 export const flatMapEager = internal.flatMapEager;
 /**
- * An optimized version of `catch` that checks if an effect is already resolved
- * and applies the catch function eagerly when possible.
+ * Applies `catch` eagerly when an effect is already resolved.
  *
  * **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.
+ * Use when an already-resolved failed effect should recover immediately while
+ * pending effects still use regular error recovery.
  *
  * **Details**
  *
@@ -7778,7 +8213,7 @@ export const flatMapEager = internal.flatMapEager;
  * ) // Uses regular catch
  * ```
  *
- * @category Eager
+ * @category eager
  * @since 4.0.0
  */
 export const catchEager = internal.catchEager;
@@ -7804,7 +8239,7 @@ export const catchEager = internal.catchEager;
  * const effect = computation() // Executed immediately if all effects are sync
  * ```
  *
- * @category Eager
+ * @category eager
  * @since 4.0.0
  */
 export const fnUntracedEager = internal.fnUntracedEager;