effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/Effect.js

@@ -12,14 +12,17 @@ import * as Metric from "./Metric.js";
 import { CurrentLogAnnotations, CurrentLogSpans } from "./References.js";
 import { internalCall } from "./Utils.js";
 /**
+ * Runtime identifier used to recognize `Effect` values.
+ *
  * @category Type identifiers
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const TypeId = core.EffectTypeId;
 /**
  * Tests if a value is an `Effect`.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -27,54 +30,30 @@ export const TypeId = core.EffectTypeId;
  * console.log(Effect.isEffect("hello")) // false
  * ```
  *
+ * @category guards
  * @since 2.0.0
- * @category Guards
  */
 export const isEffect = core.isEffect;
 /**
- * Combines multiple effects into one, returning results based on the input
- * structure.
+ * Combines an iterable or record of effects into one effect whose success shape
+ * follows the input.
  *
  * **Details**
  *
- * Use this function when you need to run multiple effects and combine their
- * results into a single output. It supports tuples, iterables, structs, and
- * records, making it flexible for different input types.
- *
- * For instance, if the input is a tuple:
- *
- * ```ts skip-type-checking
- * //         ┌─── a tuple of effects
- * //         ▼
- * Effect.all([effect1, effect2, ...])
- * ```
- *
- * the effects are executed sequentially, and the result is a new effect
- * containing the results as a tuple. The results in the tuple match the order
- * of the effects passed to `Effect.all`.
- *
- * **Concurrency**
+ * Tuple and iterable inputs collect results in order. Record inputs collect
+ * results under the same keys. By default, the combined effect fails on the
+ * first failure; with concurrent execution, effects that have already started
+ * may be interrupted, while effects not yet started are skipped.
  *
- * You can control the execution order (e.g., sequential vs. concurrent) using
- * the `concurrency` option.
+ * **Options**
  *
- * **Short-Circuiting Behavior**
+ * Use `concurrency` to control sequential or concurrent execution. Use
+ * `mode: "result"` to run every effect and collect each success or failure as a
+ * `Result` in the same output shape. Use `discard: true` to ignore successful
+ * values and return `void`.
  *
- * This function stops execution on the first error it encounters, this is
- * called "short-circuiting". If any effect in the collection fails, the
- * remaining effects will not run, and the error will be propagated. To change
- * this behavior, you can use the `mode` option, which allows all effects to run
- * and collect every success / failure as `Result` values.
+ * **Example** (Combining Effects in Tuples)
  *
- * **The `mode` option**
- *
- * The `{ mode: "result" }` option changes the behavior of `Effect.all` to
- * ensure all effects run, even if some fail. Instead of stopping on the first
- * failure, this mode collects both successes and failures, returning an array
- * of `Result` instances where each result is either an `Ok` (success) or a
- * `Err` (failure).
- *
- * @example Combining Effects in Tuples
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -94,7 +73,8 @@ export const isEffect = core.isEffect;
  * // [ 42, 'Hello' ]
  * ```
  *
- * @example Combining Effects in Iterables
+ * **Example** (Combining Effects in Iterables)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -114,7 +94,8 @@ export const isEffect = core.isEffect;
  * // [ 1, 2, 3 ]
  * ```
  *
- * @example Combining Effects in Structs
+ * **Example** (Combining Effects in Structs)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -134,7 +115,8 @@ export const isEffect = core.isEffect;
  * // { a: 42, b: 'Hello' }
  * ```
  *
- * @example Combining Effects in Records
+ * **Example** (Combining Effects in Records)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -154,7 +136,8 @@ export const isEffect = core.isEffect;
  * // { key1: 1, key2: 2 }
  * ```
  *
- * @example Short-Circuiting Behavior
+ * **Example** (Short-Circuiting Behavior)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -177,8 +160,8 @@ export const isEffect = core.isEffect;
  *
  * @see {@link forEach} for iterating over elements and applying an effect.
  *
- * @since 2.0.0
  * @category Collecting
+ * @since 2.0.0
  */
 export const all = internal.all;
 /**
@@ -193,7 +176,8 @@ export const all = internal.all;
  * This function runs every effect and never fails. Use `concurrency` to control
  * parallelism.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -205,8 +189,8 @@ export const all = internal.all;
  * // [ ["0 is even", "2 is even"], [1, 3] ]
  * ```
  *
- * @since 3.0.0
  * @category Collecting
+ * @since 2.0.0
  */
 export const partition = internal.partition;
 /**
@@ -219,7 +203,8 @@ export const partition = internal.partition;
  * Use `discard: true` to ignore successful values while still validating all
  * elements.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -241,8 +226,8 @@ export const partition = internal.partition;
  * // }
  * ```
  *
- * @since 4.0.0
  * @category Error Accumulation
+ * @since 2.0.0
  */
 export const validate = internal.validate;
 /**
@@ -251,7 +236,8 @@ export const validate = internal.validate;
  * The predicate receives the element and its index. Evaluation short-circuits
  * as soon as an element matches.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -261,8 +247,8 @@ export const validate = internal.validate;
  * // { _id: 'Option', _tag: 'Some', value: 3 }
  * ```
  *
- * @since 2.0.0
  * @category Collecting
+ * @since 2.0.0
  */
 export const findFirst = internal.findFirst;
 /**
@@ -271,8 +257,8 @@ export const findFirst = internal.findFirst;
  * The filter receives the element and index. Evaluation short-circuits on the
  * first `Result.succeed` and returns the transformed value in `Option.some`.
  *
- * @since 4.0.0
  * @category Collecting
+ * @since 4.0.0
  */
 export const findFirstFilter = internal.findFirstFilter;
 /**
@@ -298,11 +284,10 @@ export const findFirstFilter = internal.findFirstFilter;
  *
  * @see {@link all} for combining multiple effects into one.
  *
- * @example
+ * **Example** (Applying Effects to Iterable Elements)
+ *
  * ```ts
- * // Title: Applying Effects to Iterable Elements
- * import { Effect } from "effect"
- * import { Console } from "effect"
+ * import { Console, Effect } from "effect"
  *
  * const result = Effect.forEach(
  *   [1, 2, 3, 4, 5],
@@ -320,10 +305,10 @@ export const findFirstFilter = internal.findFirstFilter;
  * // [ 2, 4, 6, 8, 10 ]
  * ```
  *
- * @example
- * // Title: Using discard to Ignore Results
- * import { Effect } from "effect"
- * import { Console } from "effect"
+ * **Example** (Using discard to Ignore Results)
+ *
+ * ```ts
+ * import { Console, Effect } from "effect"
  *
  * // Apply effects but discard the results
  * const result = Effect.forEach(
@@ -341,15 +326,17 @@ export const findFirstFilter = internal.findFirstFilter;
  * // Currently at index 3
  * // Currently at index 4
  * // undefined
+ * ```
  *
- * @since 2.0.0
  * @category Collecting
+ * @since 2.0.0
  */
 export const forEach = internal.forEach;
 /**
  * Executes a body effect repeatedly while a condition holds true.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -370,8 +357,8 @@ export const forEach = internal.forEach;
  * // Current count: 5
  * ```
  *
- * @since 2.0.0
  * @category Collecting
+ * @since 2.0.0
  */
 export const whileLoop = internal.whileLoop;
 // -----------------------------------------------------------------------------
@@ -393,7 +380,7 @@ export const whileLoop = internal.whileLoop;
  * 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 catchAllDefect}.
+ * {@link catchDefect}.
  *
  * **Interruptions**
  *
@@ -402,9 +389,9 @@ export const whileLoop = internal.whileLoop;
  *
  * @see {@link tryPromise} for a version that can handle failures.
  *
- * @example
+ * **Example** (Delayed Message)
+ *
  * ```ts
- * // Title: Delayed Message
  * import { Effect } from "effect"
  *
  * const delay = (message: string) =>
@@ -422,8 +409,8 @@ export const whileLoop = internal.whileLoop;
  * const program = delay("Async operation completed successfully!")
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 export const promise = internal.promise;
 /**
@@ -452,7 +439,8 @@ export const promise = internal.promise;
  * An optional `AbortSignal` can be provided to allow for interruption of the
  * wrapped `Promise` API.
  *
- * @example Fetching a TODO Item
+ * **Example** (Fetching a TODO Item)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -467,7 +455,8 @@ export const promise = internal.promise;
  * const program = getTodo(1)
  * ```
  *
- * @example Custom Error Handling
+ * **Example** (Custom Error Handling)
+ *
  * ```ts
  * import { Data, Effect } from "effect"
  *
@@ -487,8 +476,8 @@ export const promise = internal.promise;
  *
  * @see {@link promise} if the effectful computation is asynchronous and does not throw errors.
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 export const tryPromise = internal.tryPromise;
 /**
@@ -501,9 +490,9 @@ export const tryPromise = internal.tryPromise;
  *
  * @see {@link fail} to create an effect that represents a failure.
  *
- * @example
+ * **Example** (Creating a Successful Effect)
+ *
  * ```ts
- * // Title: Creating a Successful Effect
  * import { Effect } from "effect"
  *
  * // Creating an effect that represents a successful scenario
@@ -513,14 +502,15 @@ export const tryPromise = internal.tryPromise;
  * const success = Effect.succeed(42)
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 export const succeed = internal.succeed;
 /**
  * Returns an effect which succeeds with `None`.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -530,14 +520,15 @@ export const succeed = internal.succeed;
  * // Output: { _id: 'Option', _tag: 'None' }
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 export const succeedNone = internal.succeedNone;
 /**
  * Returns an effect which succeeds with the value wrapped in a `Some`.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -547,8 +538,8 @@ export const succeedNone = internal.succeedNone;
  * // Output: { _id: 'Option', _tag: 'Some', value: 42 }
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 export const succeedSome = internal.succeedSome;
 /**
@@ -565,9 +556,9 @@ export const succeedSome = internal.succeedSome;
  * - **Handling Circular Dependencies**: Useful in managing circular dependencies, such as recursive functions that need to avoid eager evaluation to prevent stack overflow.
  * - **Unifying Return Types**: Can help TypeScript unify return types in situations where multiple branches of logic return different effects, simplifying type inference.
  *
- * @example
+ * **Example** (Lazy Evaluation with Side Effects)
+ *
  * ```ts
- * // Title: Lazy Evaluation with Side Effects
  * import { Effect } from "effect"
  *
  * let i = 0
@@ -583,8 +574,9 @@ export const succeedSome = internal.succeedSome;
  * console.log(Effect.runSync(good)) // Output: 2
  * ```
  *
- * @example
- * // Title: Recursive Fibonacci
+ * **Example** (Recursive Fibonacci)
+ *
+ * ```ts
  * import { Effect } from "effect"
  *
  * const blowsUp = (n: number): Effect.Effect<number> =>
@@ -606,9 +598,11 @@ export const succeedSome = internal.succeedSome;
  *
  * console.log(Effect.runSync(allGood(32)))
  * // Output: 3524578
+ * ```
+ *
+ * **Example** (Using Effect.suspend to Help TypeScript Infer Types)
  *
- * @example
- * // Title: Using Effect.suspend to Help TypeScript Infer Types
+ * ```ts
  * import { Effect } from "effect"
  *
  * //   Without suspend, TypeScript may struggle with type inference.
@@ -629,9 +623,10 @@ export const succeedSome = internal.succeedSome;
  *       ? Effect.fail(new Error("Cannot divide by zero"))
  *       : Effect.succeed(a / b)
  *   )
+ * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 export const suspend = internal.suspend;
 /**
@@ -649,13 +644,13 @@ export const suspend = internal.suspend;
  * 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 catchAllDefect}.
+ * {@link catchDefect}.
  *
  * @see {@link try_ | try} for a version that can handle failures.
  *
- * @example
+ * **Example** (Logging a Message)
+ *
  * ```ts
- * // Title: Logging a Message
  * import { Effect } from "effect"
  *
  * const log = (message: string) =>
@@ -668,54 +663,41 @@ export const suspend = internal.suspend;
  * const program = log("Hello, World!")
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 export const sync = internal.sync;
 const void_ = internal.void;
 export {
 /**
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 void_ as void };
 const undefined_ = internal.undefined;
 export {
 /**
- * @since 4.0.0
  * @category Creating Effects
+ * @since 4.0.0
  */
 undefined_ as undefined };
 /**
- * Creates an `Effect` from a callback-based asynchronous function.
+ * Creates an `Effect` from a callback-based asynchronous API.
  *
  * **Details**
  *
- * The `resume` function:
- * - Must be called exactly once. Any additional calls will be ignored.
- * - Can return an optional `Effect` that will be run if the `Fiber` executing
- *   this `Effect` is interrupted. This can be useful in scenarios where you
- *   need to handle resource cleanup if the operation is interrupted.
- * - Can receive an `AbortSignal` to handle interruption if needed.
- *
- * The `FiberId` of the fiber that may complete the async callback may also be
- * specified using the `blockingOn` argument. This is called the "blocking
- * fiber" because it suspends the fiber executing the `async` effect (i.e.
- * semantically blocks the fiber from making progress). Specifying this fiber id
- * in cases where it is known will improve diagnostics, but not affect the
- * behavior of the returned effect.
+ * The registration function receives a `resume` callback and, when requested,
+ * an `AbortSignal`. Call `resume` at most once with the effect that should
+ * complete the fiber; later calls are ignored. Return an optional cleanup
+ * effect from the registration function to run if the fiber is interrupted.
  *
  * **When to Use**
  *
- * Use `Effect.callback` when dealing with APIs that use callback-style instead of
- * `async/await` or `Promise`.
- * * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * Use `Effect.callback` when integrating APIs that complete through callbacks
+ * instead of returning a `Promise`.
  *
- * - `Effect.async`
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Effect } from "effect"
  *
@@ -731,15 +713,16 @@ undefined_ as undefined };
  * const program = delay(1000)
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 4.0.0
  */
 export const callback = internal.callback;
 /**
  * Returns an effect that will never produce anything. The moral equivalent of
  * `while(true) {}`, only without the wasted CPU cycles.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -753,18 +736,18 @@ export const callback = internal.callback;
  * const timedProgram = Effect.timeout(program, "1 second")
  * ```
  *
- * @since 2.0.0
  * @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.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Effect } from "effect"
- * import { pipe } from "effect/Function"
+ * import { Effect, pipe } from "effect"
  *
  * const program = pipe(
  *   Effect.Do,
@@ -774,16 +757,16 @@ export const never = internal.never;
  * )
  * ```
  *
- * @since 4.0.0
  * @category Do notation
+ * @since 2.0.0
  */
 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.
  *
- * @since 4.0.0
  * @category Do notation
+ * @since 2.0.0
  */
 export const bindTo = internal.bindTo;
 const let_ = internal.let;
@@ -791,15 +774,15 @@ export {
 /**
  * Adds a computed plain value to the do notation record.
  *
- * @since 4.0.0
  * @category Do notation
+ * @since 2.0.0
  */
 let_ as let };
 /**
  * Adds an `Effect` value to the do notation record under a given name.
  *
- * @since 4.0.0
  * @category Do notation
+ * @since 2.0.0
  */
 export const bind = internal.bind;
 /**
@@ -817,7 +800,8 @@ export const bind = internal.bind;
  * explicit control over the execution of effects. You can `yield*` values from
  * effects and return the final result at the end.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Data, Effect } from "effect"
  *
@@ -849,8 +833,8 @@ export const bind = internal.bind;
  * })
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 export const gen = internal.gen;
 /**
@@ -860,13 +844,13 @@ export const gen = internal.gen;
  *
  * Use this function to explicitly signal an error in an `Effect`. The error
  * will keep propagating unless it is handled. You can handle the error with
- * functions like {@link catchAll} or {@link catchTag}.
+ * functions like {@link catchTag} or {@link catchTags}.
  *
  * @see {@link succeed} to create an effect that represents a successful value.
  *
- * @example
+ * **Example** (Creating a Failed Effect)
+ *
  * ```ts
- * // Title: Creating a Failed Effect
  * import { Data, Effect } from "effect"
  *
  * class OperationFailedError extends Data.TaggedError("OperationFailedError")<{}> {}
@@ -878,8 +862,8 @@ export const gen = internal.gen;
  * )
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 export const fail = internal.fail;
 /**
@@ -888,7 +872,8 @@ export const fail = internal.fail;
  * 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.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Data, Effect } from "effect"
  *
@@ -900,8 +885,8 @@ export const fail = internal.fail;
  * // Output: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 export const failSync = internal.failSync;
 /**
@@ -910,7 +895,8 @@ export const failSync = internal.failSync;
  * This function allows you to create effects that fail with complex error
  * structures, including multiple errors, defects, interruptions, and more.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Cause, Effect } from "effect"
  *
@@ -922,8 +908,8 @@ export const failSync = internal.failSync;
  * // Output: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 export const failCause = internal.failCause;
 /**
@@ -932,7 +918,8 @@ export const failCause = internal.failCause;
  * 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.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Cause, Effect } from "effect"
  *
@@ -944,8 +931,8 @@ export const failCause = internal.failCause;
  * // Output: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 export const failCauseSync = internal.failCauseSync;
 /**
@@ -965,12 +952,11 @@ export const failCauseSync = internal.failCauseSync;
  * The error channel of the resulting effect is of type `never`, indicating that
  * it cannot recover from this failure.
  *
- * @see {@link dieSync} for a variant that throws a specified error, evaluated lazily.
- * @see {@link dieMessage} for a variant that throws a `RuntimeException` with a message.
+ * @see {@link die} for a variant that dies with an already computed defect.
+ *
+ * **Example** (Terminating on Division by Zero with a Specified Error)
  *
- * @example
  * ```ts
- * // Title: Terminating on Division by Zero with a Specified Error
  * import { Effect } from "effect"
  *
  * const divide = (a: number, b: number) =>
@@ -988,8 +974,8 @@ export const failCauseSync = internal.failCauseSync;
  * //   ...stack trace...
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 export const die = internal.die;
 const try_ = internal.try;
@@ -1017,7 +1003,8 @@ export {
  * @see {@link sync} if the effectful computation is synchronous and does not
  * throw errors.
  *
- * @example Basic Usage with Default Error Handling
+ * **Example** (Basic Usage with Default Error Handling)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -1036,7 +1023,8 @@ export {
  * // Output: Exit.failure with Error
  * ```
  *
- * @example Custom Error Handling
+ * **Example** (Custom Error Handling)
+ *
  * ```ts
  * import { Data, Effect } from "effect"
  *
@@ -1052,14 +1040,15 @@ export {
  * // Output: Exit.failure with custom Error message
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 try_ as try };
 /**
  * Yields control back to the Effect runtime, allowing other fibers to execute.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -1072,14 +1061,15 @@ try_ as try };
  * Effect.runPromise(program)
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 2.0.0
  */
 export const yieldNow = internal.yieldNow;
 /**
  * Yields control back to the Effect runtime with a specified priority, allowing other fibers to execute.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -1092,14 +1082,15 @@ export const yieldNow = internal.yieldNow;
  * Effect.runPromise(program)
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 4.0.0
  */
 export const yieldNowWith = internal.yieldNowWith;
 /**
  * Provides access to the current fiber within an effect computation.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -1111,8 +1102,8 @@ export const yieldNowWith = internal.yieldNowWith;
  * // Output: Fiber ID: 1
  * ```
  *
- * @since 2.0.0
  * @category Creating Effects
+ * @since 4.0.0
  */
 export const withFiber = core.withFiber;
 // -----------------------------------------------------------------------------
@@ -1121,7 +1112,8 @@ export const withFiber = core.withFiber;
 /**
  * Converts a `Result` to an `Effect`.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect, Result } from "effect"
  *
@@ -1136,14 +1128,18 @@ export const withFiber = core.withFiber;
  * // { _id: 'Exit', _tag: 'Failure', cause: { _id: 'Cause', _tag: 'Fail', failure: 'Something went wrong' } }
  * ```
  *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export const fromResult = internal.fromResult;
 /**
- * Converts an `Option` to an `Effect`.
+ * Converts an `Option` into an `Effect`.
+ *
+ * `Option.some` becomes a successful effect with the contained value, while
+ * `Option.none` becomes a failed effect with `NoSuchElementError`.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Effect, Option } from "effect"
  *
@@ -1158,15 +1154,16 @@ export const fromResult = internal.fromResult;
  * // { _id: 'Exit', _tag: 'Failure', cause: { _id: 'Cause', _tag: 'Fail', failure: { _id: 'NoSuchElementError' } } }
  * ```
  *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export const fromOption = internal.fromOption;
 /**
  * Converts a nullable value to an `Effect`, failing with a `NoSuchElementError`
  * when the value is `null` or `undefined`.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -1183,8 +1180,8 @@ export const fromOption = internal.fromOption;
  * // Output: hello
  * ```
  *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export const fromNullishOr = internal.fromNullishOr;
 // -----------------------------------------------------------------------------
@@ -1220,7 +1217,8 @@ export const fromNullishOr = internal.fromNullishOr;
  * step produces a new `Effect` while flattening any nested effects that may
  * occur.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Data, Effect, pipe } from "effect"
  *
@@ -1250,14 +1248,15 @@ export const fromNullishOr = internal.fromNullishOr;
  *
  * @see {@link tap} for a version that ignores the result of the effect.
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const flatMap = internal.flatMap;
 /**
  * Flattens an `Effect` that produces another `Effect` into a single effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -1270,13 +1269,13 @@ export const flatMap = internal.flatMap;
  * })
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const flatten = internal.flatten;
 /**
- * Chains two actions, where the second action can depend on the result of the
- * first.
+ * Runs this effect and then runs another effect, optionally using the first
+ * effect's success value to choose the next effect.
  *
  * **Syntax**
  *
@@ -1290,31 +1289,21 @@ export const flatten = internal.flatten;
  *
  * **When to Use**
  *
- * Use `andThen` when you need to run multiple actions in sequence, with the
- * second action depending on the result of the first. This is useful for
- * combining effects or handling computations that must happen in order.
+ * Use `andThen` when one effect must run after another and the second effect
+ * may depend on the first effect's success value.
  *
  * **Details**
  *
- * The second action can be:
- *
- * - A constant value (similar to {@link as})
- * - A function returning a value (similar to {@link map})
- * - A `Promise`
- * - A function returning a `Promise`
- * - An `Effect`
- * - A function returning an `Effect` (similar to {@link flatMap})
- *
- * **Note:** `andThen` works well with both `Option` and `Result` types,
- * treating them as effects.
- *
- * **Previously Known As**
+ * When the second argument is an `Effect`, the first success value is discarded
+ * and the returned effect produces the second effect's value. When the second
+ * argument is a function, it receives the first success value and must return
+ * the next `Effect`.
  *
- * This API replaces the following from Effect 3.x:
+ * Failures or requirements from either effect are preserved in the returned
+ * effect.
  *
- * - `Effect.zipRight`
+ * **Example** (Applying a Discount Based on Fetched Amount)
  *
- * @example Applying a Discount Based on Fetched Amount
  * ```ts
  * import { Data, Effect, pipe } from "effect"
  *
@@ -1353,8 +1342,8 @@ export const flatten = internal.flatten;
  * // Output: 190
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const andThen = internal.andThen;
 /**
@@ -1374,17 +1363,10 @@ export const andThen = internal.andThen;
  * next part of the chain. Note that if the side effect fails, the entire chain
  * will fail too.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.zipLeft`
+ * **Example** (Logging a step in a pipeline)
  *
- * @example
  * ```ts
- * // Title: Logging a step in a pipeline
- * import { Data, Effect, pipe } from "effect"
- * import { Console } from "effect"
+ * import { Console, Data, Effect, pipe } from "effect"
  *
  * class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}
  *
@@ -1414,8 +1396,8 @@ export const andThen = internal.andThen;
  * // 95
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const tap = internal.tap;
 /**
@@ -1441,13 +1423,8 @@ export const tap = internal.tap;
  * The resulting effect cannot fail directly because all recoverable failures
  * are represented inside the `Result` type.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Usage)
  *
- * - `Effect.either`
- *
- * @example
  * ```ts
  * import { Effect } from "effect"
  *
@@ -1467,8 +1444,8 @@ 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`.
  *
- * @since 4.0.0
  * @category Outcome Encapsulation
+ * @since 4.0.0
  */
 export const result = internal.result;
 /**
@@ -1479,7 +1456,8 @@ export const result = internal.result;
  * Success values become `Option.some`, recoverable failures become
  * `Option.none`, and defects still fail the effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect, Option } from "effect"
  *
@@ -1499,8 +1477,8 @@ 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`.
  *
- * @since 2.0.0
  * @category Output Encapsulation
+ * @since 2.0.0
  */
 export const option = internal.option;
 /**
@@ -1516,7 +1494,8 @@ export const option = internal.option;
  * the `Exit.Failure` type. The error type is set to `never`, indicating that
  * the effect is structured to never fail directly.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -1536,8 +1515,8 @@ 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.
  *
- * @since 2.0.0
  * @category Outcome Encapsulation
+ * @since 2.0.0
  */
 export const exit = internal.exit;
 /**
@@ -1562,7 +1541,8 @@ export const exit = internal.exit;
  * effect is not modified. Instead, a new effect is returned with the updated
  * value.
  *
- * @example Adding a Service Charge
+ * **Example** (Adding a Service Charge)
+ *
  * ```ts
  * import { Effect, pipe } from "effect"
  *
@@ -1583,8 +1563,8 @@ export const exit = internal.exit;
  * @see {@link mapBoth} for a version that operates on both channels.
  * @see {@link flatMap} or {@link andThen} for a version that can return a new effect.
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 export const map = internal.map;
 /**
@@ -1593,9 +1573,9 @@ export const map = internal.map;
  * `as` allows you to ignore the original value inside an effect and
  * replace it with a new constant value.
  *
- * @example
+ * **Example** (Replacing a Value)
+ *
  * ```ts
- * // Title: Replacing a Value
  * import { Effect, pipe } from "effect"
  *
  * // Replaces the value 5 with the constant "new value"
@@ -1605,8 +1585,8 @@ export const map = internal.map;
  * // Output: "new value"
  * ```
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 export const as = internal.as;
 /**
@@ -1614,7 +1594,8 @@ export const as = internal.as;
  * in an `Option` value. If the original `Effect` value fails, the returned
  * `Effect` value will also fail.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -1624,7 +1605,7 @@ export const as = internal.as;
  * // { _id: 'Option', _tag: 'Some', value: 42 }
  * ```
  *
- * @category Mapping
+ * @category mapping
  * @since 2.0.0
  */
 export const asSome = internal.asSome;
@@ -1634,7 +1615,8 @@ export const asSome = internal.asSome;
  * succeed. If the original `Effect` value fails, the returned `Effect` value
  * will fail with the same error.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -1644,8 +1626,8 @@ export const asSome = internal.asSome;
  * // undefined (void)
  * ```
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 export const asVoid = internal.asVoid;
 /**
@@ -1657,7 +1639,8 @@ export const asVoid = internal.asVoid;
  * be helpful in scenarios where you want to handle a success as a failure or
  * treat an error as a valid result.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -1670,8 +1653,8 @@ export const asVoid = internal.asVoid;
  * const flipped = Effect.flip(program)
  * ```
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 export const flip = internal.flip;
 // -----------------------------------------------------------------------------
@@ -1691,9 +1674,9 @@ 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.
  *
- * @example
+ * **Example** (Combining Two Effects Sequentially)
+ *
  * ```ts
- * // Title: Combining Two Effects Sequentially
  * import { Effect } from "effect"
  *
  * const task1 = Effect.succeed(1).pipe(
@@ -1718,8 +1701,9 @@ export const flip = internal.flip;
  * // [ 1, 'hello' ]
  * ```
  *
- * @example
- * // Title: Combining Two Effects Concurrently
+ * **Example** (Combining Two Effects Concurrently)
+ *
+ * ```ts
  * import { Effect } from "effect"
  *
  * const task1 = Effect.succeed(1).pipe(
@@ -1739,9 +1723,10 @@ export const flip = internal.flip;
  * // timestamp=... level=INFO fiber=#0 message="task2 done"
  * // timestamp=... level=INFO fiber=#0 message="task1 done"
  * // [ 1, 'hello' ]
+ * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const zip = internal.zip;
 /**
@@ -1759,9 +1744,9 @@ export const zip = internal.zip;
  * By default, the effects are run sequentially. To execute them concurrently,
  * use the `{ concurrent: true }` option.
  *
- * @example
+ * **Example** (Combining Effects with a Custom Function)
+ *
  * ```ts
- * // Title: Combining Effects with a Custom Function
  * import { Effect } from "effect"
  *
  * const task1 = Effect.succeed(1).pipe(
@@ -1787,8 +1772,8 @@ export const zip = internal.zip;
  * // 6
  * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const zipWith = internal.zipWith;
 // -----------------------------------------------------------------------------
@@ -1811,14 +1796,8 @@ export {
  *
  * @see {@link catchCause} for a version that can recover from both recoverable and unrecoverable errors.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.catchAll`
- *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 catch_ as catch };
 /**
@@ -1835,7 +1814,8 @@ catch_ as catch };
  * The error type must have a readonly `_tag` field to use `catchTag`. This
  * field is used to identify and match errors.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -1858,8 +1838,8 @@ catch_ as catch };
  * )
  * ```
  *
+ * @category error handling
  * @since 2.0.0
- * @category Error Handling
  */
 export const catchTag = internal.catchTag;
 /**
@@ -1877,7 +1857,8 @@ export const catchTag = internal.catchTag;
  * The error type must have a readonly `_tag` field to use `catchTag`. This
  * field is used to identify and match errors.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Data, Effect } from "effect"
  *
@@ -1901,8 +1882,8 @@ export const catchTag = internal.catchTag;
  * })
  * ```
  *
+ * @category error handling
  * @since 2.0.0
- * @category Error Handling
  */
 export const catchTags = internal.catchTags;
 /**
@@ -1911,7 +1892,8 @@ export const catchTags = internal.catchTags;
  * Use this to handle nested error causes without removing the parent error
  * from the error channel. The handler receives the unwrapped reason.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Data, Effect } from "effect"
  *
@@ -1937,14 +1919,15 @@ export const catchTags = internal.catchTags;
  * )
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const catchReason = internal.catchReason;
 /**
  * Catches multiple reasons within a tagged error using an object of handlers.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Data, Effect } from "effect"
  *
@@ -1972,15 +1955,16 @@ export const catchReason = internal.catchReason;
  * )
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const catchReasons = internal.catchReasons;
 /**
  * Promotes nested reason errors into the Effect error channel, replacing
  * the parent error.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Data, Effect } from "effect"
  *
@@ -2003,8 +1987,8 @@ export const catchReasons = internal.catchReasons;
  * const unwrapped = program.pipe(Effect.unwrapReason("AiError"))
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const unwrapReason = internal.unwrapReason;
 /**
@@ -2024,13 +2008,8 @@ export const unwrapReason = internal.unwrapReason;
  * they often indicate serious issues. However, in some cases, such as
  * dynamically loaded plugins, controlled recovery might be needed.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Usage)
  *
- * - `Effect.catchAllCause`
- *
- * @example
  * ```ts
  * import { Cause, Console, Effect } from "effect"
  *
@@ -2048,40 +2027,31 @@ export const unwrapReason = internal.unwrapReason;
  * })
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const catchCause = internal.catchCause;
 /**
- * Recovers from all defects using a provided recovery function.
+ * Recovers from defects using a provided recovery function.
  *
  * **When to Use**
  *
- * There is no sensible way to recover from defects. This method should be used
- * only at the boundary between Effect and an external system, to transmit
- * information on a defect for diagnostic or explanatory purposes.
+ * Use this sparingly, usually at integration boundaries where defects must be
+ * reported or translated for an external system.
  *
  * **Details**
  *
- * `catchAllDefect` allows you to handle defects, which are unexpected errors
- * that usually cause the program to terminate. This function lets you recover
- * from these defects by providing a function that handles the error. However,
- * it does not handle expected errors (like those from {@link fail}) or
- * execution interruptions (like those from {@link interrupt}).
+ * `catchDefect` handles unexpected defects, such as thrown exceptions or
+ * values passed to `die`, without catching typed failures or interruptions.
  *
  * **When to Recover from Defects**
  *
- * Defects are unexpected errors that typically shouldn't be recovered from, as
- * they often indicate serious issues. However, in some cases, such as
- * dynamically loaded plugins, controlled recovery might be needed.
- *
- * **Previously Known As**
+ * Defects are unexpected errors that typically should not be recovered from, as
+ * they often indicate serious issues. In some cases, such as dynamically loaded
+ * plugins, controlled recovery may be needed.
  *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Usage)
  *
- * - `Effect.catchAllDefect`
- *
- * @example
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -2098,8 +2068,8 @@ export const catchCause = internal.catchCause;
  * })
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const catchDefect = internal.catchDefect;
 /**
@@ -2112,14 +2082,8 @@ export const catchDefect = internal.catchDefect;
  * matching. Non-matching errors re-fail with the original cause. Defects and
  * interrupts are not caught.
  *
- * **Previously Known As**
- *
- * This API replaces the following:
- *
- * - `Effect.catchSome` (Effect 3.x)
- * - `Effect.catchIf`
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Data, Effect, Filter } from "effect"
  *
@@ -2144,15 +2108,15 @@ export const catchDefect = internal.catchDefect;
  * )
  * ```
  *
+ * @category error handling
  * @since 2.0.0
- * @category Error Handling
  */
 export const catchIf = internal.catchIf;
 /**
  * Recovers from specific errors using a `Filter`.
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const catchFilter = internal.catchFilter;
 /**
@@ -2161,7 +2125,8 @@ export const catchFilter = internal.catchFilter;
  * Success values become `Option.some`, `NoSuchElementError` becomes
  * `Option.none`, and all other errors are preserved.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect, Option } from "effect"
  *
@@ -2172,14 +2137,8 @@ export const catchFilter = internal.catchFilter;
  * Effect.runPromise(none).then(console.log) // { _id: 'Option', _tag: 'None' }
  * ```
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.optionFromOptional`
- *
- * @since 2.0.0
- * @category Error Handling
+ * @category error handling
+ * @since 4.0.0
  */
 export const catchNoSuchElement = internal.catchNoSuchElement;
 /**
@@ -2189,13 +2148,8 @@ export const catchNoSuchElement = internal.catchNoSuchElement;
  * that match a specific predicate. This is useful when you want to handle
  * only certain types of errors while letting others propagate.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.catchSomeCause`
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Cause, Console, Effect } from "effect"
  *
@@ -2217,15 +2171,15 @@ export const catchNoSuchElement = internal.catchNoSuchElement;
  * // Then: "Fallback response"
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const catchCauseIf = internal.catchCauseIf;
 /**
  * Recovers from specific failures based on a `Filter`.
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const catchCauseFilter = internal.catchCauseFilter;
 /**
@@ -2239,9 +2193,10 @@ 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 orElseFail} if you want to replace the error with a new one.
+ * @see {@link mapError} if you want to replace the error with a new one.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Data, Effect } from "effect"
  *
@@ -2259,8 +2214,8 @@ export const catchCauseFilter = internal.catchCauseFilter;
  * )
  * ```
  *
+ * @category error handling
  * @since 2.0.0
- * @category Error Handling
  */
 export const mapError = internal.mapError;
 /**
@@ -2273,7 +2228,8 @@ export const mapError = internal.mapError;
  * the error and the success values without altering the overall success or
  * failure status of the effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Data, Effect } from "effect"
  *
@@ -2294,28 +2250,24 @@ export const mapError = internal.mapError;
  * @see {@link map} for a version that operates on the success channel.
  * @see {@link mapError} for a version that operates on the error channel.
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 export const mapBoth = internal.mapBoth;
 /**
- * Converts an effect's failure into a fiber termination, removing the error from the effect's type.
+ * Converts typed failures from the error channel into defects, removing the
+ * error type from the returned effect.
  *
- * **When to Use*
- *
- * Use `orDie` when failures should be treated as unrecoverable defects and no error handling is required.
+ * **When to Use**
  *
- * **Details**
+ * Use `orDie` when a typed failure represents an unrecoverable bug or invalid
+ * state and should not be handled as a recoverable error.
  *
- * The `orDie` function is used when you encounter errors that you do not want to handle or recover from.
- * It removes the error type from the effect and ensures that any failure will terminate the fiber.
- * This is useful for propagating failures as defects, signaling that they should not be handled within the effect.
+ * @see {@link mapError} to transform the error before converting it into a defect with {@link orDie}.
  *
- * @see {@link orDieWith} if you need to customize the error.
+ * **Example** (Propagating an Error as a Defect)
  *
- * @example
  * ```ts
- * // Title: Propagating an Error as a Defect
  * import { Data, Effect } from "effect"
  *
  * class DivideByZeroError extends Data.TaggedError("DivideByZeroError")<{}> {}
@@ -2335,20 +2287,22 @@ export const mapBoth = internal.mapBoth;
  * //   ...stack trace...
  * ```
  *
- * @since 2.0.0
  * @category Converting Failures to Defects
+ * @since 2.0.0
  */
 export const orDie = internal.orDie;
 /**
- * The `tapError` function executes an effectful operation to inspect the
- * failure of an effect without modifying it.
+ * Runs an effectful operation when the source effect fails, while preserving
+ * the original failure when the operation succeeds.
  *
- * This function is useful when you want to perform some side effect (like
- * logging or tracking) on the failure of an effect, but without changing the
- * result of the effect itself. The error remains in the effect's error channel,
- * while the operation you provide can inspect or act on it.
+ * **Details**
+ *
+ * Use this for logging, metrics, or other failure-side observations. If the
+ * operation passed to `tapError` fails, that error is also represented in the
+ * returned effect's error channel.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -2366,17 +2320,19 @@ export const orDie = internal.orDie;
  * // expected error: NetworkError
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const tapError = internal.tapError;
 /**
  * Runs an effectful handler when a failure's `_tag` matches.
  *
- * Use this with tagged-union errors to perform side effects for a tag (or tag
- * list) while preserving the original failure.
+ * Use this with tagged-union errors to perform side effects for one tag or a
+ * list of tags. When the handler succeeds, the original failure is preserved;
+ * if the handler fails, its error is also included in the returned effect.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Console, Data, Effect } from "effect"
  *
@@ -2400,26 +2356,22 @@ export const tapError = internal.tapError;
  * // expected error: 504
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const tapErrorTag = internal.tapErrorTag;
 /**
- * The `tapCause` function allows you to inspect the complete cause
- * of an error, including failures and defects.
- *
- * This function is helpful when you need to log, monitor, or handle specific
- * error causes in your effects. It gives you access to the full error cause,
- * whether it's a failure, defect, or other exceptional conditions, without
- * altering the error or the overall result of the effect.
+ * Runs an effectful operation with the full `Cause` when the source effect
+ * fails.
  *
- * **Previously Known As**
+ * **Details**
  *
- * This API replaces the following from Effect 3.x:
+ * Use this to log or inspect typed failures, defects, and interruptions. When
+ * the operation succeeds, the original cause is preserved. If the operation
+ * fails, its error is also represented in the returned effect.
  *
- * - `Effect.tapErrorCause`
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Cause, Console, Effect } from "effect"
  *
@@ -2435,8 +2387,8 @@ export const tapErrorTag = internal.tapErrorTag;
  * // Then: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @since 2.0.0
- * @category Sequencing
+ * @category sequencing
+ * @since 4.0.0
  */
 export const tapCause = internal.tapCause;
 /**
@@ -2446,7 +2398,8 @@ export const tapCause = internal.tapCause;
  * the cause matches a specific predicate. This is useful for conditional logging,
  * monitoring, or other side effects based on the type of failure.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Cause, Console, Effect } from "effect"
  *
@@ -2464,34 +2417,29 @@ export const tapCause = internal.tapCause;
  * // Then: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
+ * @category sequencing
  * @since 4.0.0
- * @category Sequencing
  */
 export const tapCauseIf = internal.tapCauseIf;
 /**
  * Conditionally executes a side effect based on the cause of a failed effect.
  *
+ * @category sequencing
  * @since 4.0.0
- * @category Sequencing
  */
 export const tapCauseFilter = internal.tapCauseFilter;
 /**
- * Inspect severe errors or defects (non-recoverable failures) in an effect.
+ * Runs an effectful operation when the source effect dies with a defect.
  *
  * **Details**
  *
- * This function is specifically designed to handle and inspect defects, which
- * are critical failures in your program, such as unexpected runtime exceptions
- * or system-level errors. Unlike normal recoverable errors, defects typically
- * indicate serious issues that cannot be addressed through standard error
- * handling.
+ * Use this for diagnostics such as logging unexpected thrown exceptions or
+ * values passed to `die`. Recoverable failures are not handled. When the
+ * operation succeeds, the original defect is preserved; if the operation fails,
+ * its error is also represented in the returned effect.
  *
- * When a defect occurs in an effect, the function you provide to this function
- * will be executed, allowing you to log, monitor, or handle the defect in some
- * way. Importantly, this does not alter the main result of the effect. If no
- * defect occurs, the effect behaves as if this function was not used.
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -2524,8 +2472,8 @@ export const tapCauseFilter = internal.tapCauseFilter;
  * //   ... stack trace ...
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const tapDefect = internal.tapDefect;
 /**
@@ -2533,7 +2481,8 @@ export const tapDefect = internal.tapDefect;
  *
  * Yields between attempts so other fibers can run.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -2558,32 +2507,29 @@ export const tapDefect = internal.tapDefect;
  * // Ready
  * ```
  *
- * @since 2.0.0
  * @category Repetition / Recursion
+ * @since 2.0.0
  */
 export const eventually = internal.eventually;
 /**
- * Retries a failing effect based on a defined retry policy.
+ * Retries typed failures from an effect according to a retry policy.
  *
  * **Details**
  *
- * The `Effect.retry` function takes an effect and a {@link Schedule} policy,
- * and will automatically retry the effect if it fails, following the rules of
- * the policy.
- *
- * If the effect ultimately succeeds, the result will be returned.
+ * The policy can be a `Schedule`, a schedule builder, or a `Retry.Options`
+ * object using `schedule`, `times`, `while`, or `until`. If a retry eventually
+ * succeeds, the returned effect succeeds with that value. If the policy stops
+ * while the effect is still failing, the last failure is propagated.
  *
- * If the maximum retries are exhausted and the effect still fails, the failure
- * is propagated.
+ * Defects and interruptions are not retried as typed failures.
  *
  * **When to Use**
  *
- * This can be useful when dealing with intermittent failures, such as network
- * issues or temporary resource unavailability. By defining a retry policy, you
- * can control the number of retries, the delay between them, and when to stop
- * retrying.
+ * Use `retry` when typed failures may be transient, such as network issues or
+ * temporary resource unavailability.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Data, Effect, Schedule } from "effect"
  *
@@ -2609,8 +2555,8 @@ export const eventually = internal.eventually;
  * @see {@link retryOrElse} for a version that allows you to run a fallback.
  * @see {@link repeat} if your retry condition is based on successful outcomes rather than errors.
  *
+ * @category error handling
  * @since 2.0.0
- * @category Error Handling
  */
 export const retry = internalSchedule.retry;
 /**
@@ -2631,7 +2577,8 @@ export const retry = internalSchedule.retry;
  *
  * @see {@link retry} for a version that does not run a fallback effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -2666,24 +2613,21 @@ export const retry = internalSchedule.retry;
  * // Network data
  * ```
  *
+ * @category error handling
  * @since 2.0.0
- * @category Error Handling
  */
 export const retryOrElse = internalSchedule.retryOrElse;
 /**
- * The `sandbox` function transforms an effect by exposing the full cause
- * of any error, defect, or fiber interruption that might occur during its
- * execution. It changes the error channel of the effect to include detailed
- * information about the cause, which is wrapped in a `Cause<E>` type.
+ * Exposes an effect's full failure cause in the error channel as `Cause<E>`.
+ *
+ * **Details**
+ *
+ * Use `sandbox` when downstream error handling needs to distinguish typed
+ * failures, defects, and interruptions. Use `unsandbox` to restore the original
+ * typed error channel after cause-level handling.
  *
- * This function is useful when you need access to the complete underlying cause
- * of failures, defects, or interruptions, enabling more detailed error
- * handling. Once you apply `sandbox`, you can use operators like
- * {@link catchAll} and {@link catchTags} to handle specific error conditions.
- * If necessary, you can revert the sandboxing operation with {@link unsandbox}
- * to return to the original error handling behavior.
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Cause, Effect } from "effect"
  *
@@ -2699,10 +2643,10 @@ export const retryOrElse = internalSchedule.retryOrElse;
  * // Output: "Caught cause: Something went wrong"
  * ```
  *
- * @see {@link unsandbox} to restore the original error handling.
+ * @see {@link sandbox} to expose failures as full causes.
  *
+ * @category error handling
  * @since 2.0.0
- * @category Error Handling
  */
 export const sandbox = internal.sandbox;
 /**
@@ -2717,9 +2661,9 @@ export const sandbox = internal.sandbox;
  * Use the `log` option to emit the full {@link Cause} when the effect fails,
  * and `message` to prepend a custom log message.
  *
- * @example
+ * **Example** (Using Effect.ignore to Discard Values)
+ *
  * ```ts
- * // Title: Using Effect.ignore to Discard Values
  * import { Effect } from "effect"
  *
  * //      ┌─── Effect<number, string, never>
@@ -2731,9 +2675,9 @@ export const sandbox = internal.sandbox;
  * const program = task.pipe(Effect.ignore)
  * ```
  *
- * @example
+ * **Example** (Logging failures while ignoring results)
+ *
  * ```ts
- * // Title: Logging failures while ignoring results
  * import { Effect } from "effect"
  *
  * const task = Effect.fail("Uh oh!")
@@ -2742,14 +2686,8 @@ export const sandbox = internal.sandbox;
  * const programWarn = task.pipe(Effect.ignore({ log: "Warn", message: "Ignoring task failure" }))
  * ```
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.ignoreLogged`
- *
+ * @category error handling
  * @since 2.0.0
- * @category Error Handling
  */
 export const ignore = internal.ignore;
 /**
@@ -2758,7 +2696,8 @@ export const ignore = internal.ignore;
  * Use the `log` option to emit the full {@link Cause} when the effect fails,
  * and `message` to prepend a custom log message.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -2768,8 +2707,8 @@ export const ignore = internal.ignore;
  * const programLog = task.pipe(Effect.ignoreCause({ log: true, message: "Ignoring failure cause" }))
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const ignoreCause = internal.ignoreCause;
 /**
@@ -2780,9 +2719,10 @@ export const ignoreCause = internal.ignoreCause;
  * and retry timing is derived per step (the first attempt uses the remaining
  * attempts schedule; later retries apply the step schedule at least once).
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Effect, ExecutionPlan, Layer, Context } from "effect"
+ * import { Context, Effect, ExecutionPlan, Layer } from "effect"
  *
  * const Endpoint = Context.Service<{ url: string }>("Endpoint")
  *
@@ -2802,8 +2742,8 @@ export const ignoreCause = internal.ignoreCause;
  * const program = Effect.withExecutionPlan(fetchUrl, plan)
  * ```
  *
- * @since 3.16.0
  * @category Fallback
+ * @since 3.16.0
  */
 export const withExecutionPlan = internalExecutionPlan.withExecutionPlan;
 /**
@@ -2812,31 +2752,26 @@ export const withExecutionPlan = internalExecutionPlan.withExecutionPlan;
  * If the `defectsOnly` option is set to `true`, only defects (unrecoverable
  * errors) will be reported, while regular failures will be ignored.
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const withErrorReporting = internal.withErrorReporting;
 // -----------------------------------------------------------------------------
 // Fallback
 // -----------------------------------------------------------------------------
 /**
- * Replaces the original failure with a success value, ensuring the effect
- * cannot fail.
+ * Recovers from a typed failure by producing a fallback success value.
  *
- * `orElseSucceed` allows you to replace the failure of an effect with a
- * success value. If the effect fails, it will instead succeed with the provided
- * value, ensuring the effect always completes successfully. This is useful when
- * you want to guarantee a successful result regardless of whether the original
- * effect failed.
+ * **Details**
+ *
+ * If the source effect succeeds, its value is preserved. If it fails in the
+ * error channel, `orElseSucceed` evaluates the fallback and succeeds with that
+ * value, removing the typed error from the returned effect.
  *
- * The function ensures that any failure is effectively "swallowed" and replaced
- * by a successful value, which can be helpful for providing default values in
- * case of failure.
+ * Defects and interruptions are not recovered by this operator.
  *
- * **Important**: This function only applies to failed effects. If the effect
- * already succeeds, it will remain unchanged.
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Effect } from "effect"
  *
@@ -2857,8 +2792,8 @@ export const withErrorReporting = internal.withErrorReporting;
  * // { _id: 'Exit', _tag: 'Success', value: 18 }
  * ```
  *
- * @since 2.0.0
  * @category Fallback
+ * @since 2.0.0
  */
 export const orElseSucceed = internal.orElseSucceed;
 /**
@@ -2881,7 +2816,8 @@ export const orElseSucceed = internal.orElseSucceed;
  * attempting multiple APIs, reading configuration from several sources, or
  * trying alternative resource locations in order.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -2901,8 +2837,8 @@ export const orElseSucceed = internal.orElseSucceed;
  * // Output: "secondary result"
  * ```
  *
- * @since 2.0.0
  * @category Fallback
+ * @since 2.0.0
  */
 export const firstSuccessOf = internal.firstSuccessOf;
 // -----------------------------------------------------------------------------
@@ -2918,11 +2854,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.
  *
- * @see {@link timeoutFail} for a version that raises a custom error.
- * @see {@link timeoutFailCause} for a version that raises a custom defect.
- * @see {@link timeoutTo} for a version that allows specifying both success and timeout handlers.
+ * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Effect } from "effect"
  *
@@ -2951,30 +2886,26 @@ export const firstSuccessOf = internal.firstSuccessOf;
  * // }
  * ```
  *
- * @since 2.0.0
  * @category Delays & Timeouts
+ * @since 2.0.0
  */
 export const timeout = internal.timeout;
 /**
- * Handles timeouts by returning an `Option` that represents either the result
- * or a timeout.
+ * Runs an effect with a time limit and represents only the timeout case as
+ * `Option.none`.
  *
- * The `timeoutOption` function provides a way to gracefully handle
- * timeouts by wrapping the outcome of an effect in an `Option` type. If the
- * effect completes within the specified time, it returns a `Some` containing
- * the result. If the effect times out, it returns a `None`, allowing you to
- * treat the timeout as a regular result instead of throwing an error.
+ * **Details**
  *
- * This is useful when you want to handle timeouts without causing the program
- * to fail, making it easier to manage situations where you expect tasks might
- * take too long but want to continue executing other tasks.
+ * If the source effect succeeds before the timeout, the returned effect
+ * succeeds with `Option.some(value)`. If the timeout wins, the source effect is
+ * 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 timeoutFail} for a version that raises a custom error.
- * @see {@link timeoutFailCause} for a version that raises a custom defect.
- * @see {@link timeoutTo} for a version that allows specifying both success and timeout handlers.
+ * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Effect } from "effect"
  *
@@ -3001,8 +2932,8 @@ export const timeout = internal.timeout;
  * // ]
  * ```
  *
- * @since 3.1.0
  * @category Delays & Timeouts
+ * @since 3.1.0
  */
 export const timeoutOption = internal.timeoutOption;
 /**
@@ -3011,7 +2942,8 @@ export const timeoutOption = internal.timeoutOption;
  * 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.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -3038,15 +2970,16 @@ export const timeoutOption = internal.timeoutOption;
  * // Cached result
  * ```
  *
- * @since 3.1.0
  * @category Delays & Timeouts
+ * @since 4.0.0
  */
 export const timeoutOrElse = internal.timeoutOrElse;
 /**
  * Returns an effect that is delayed from this effect by the specified
  * `Duration`.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -3059,15 +2992,16 @@ export const timeoutOrElse = internal.timeoutOrElse;
  * // Waits 1 second, then prints: "Delayed message"
  * ```
  *
- * @since 2.0.0
  * @category Delays & Timeouts
+ * @since 2.0.0
  */
 export const delay = internal.delay;
 /**
- * Returns an effect that suspends for the specified duration. This method is
- * asynchronous, and does not actually block the fiber executing the effect.
+ * Returns an effect that suspends the current fiber for the specified duration
+ * without blocking a JavaScript thread.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -3082,8 +3016,8 @@ export const delay = internal.delay;
  * // Output: "End" (after 2 seconds)
  * ```
  *
- * @since 2.0.0
  * @category Delays & Timeouts
+ * @since 2.0.0
  */
 export const sleep = internal.sleep;
 /**
@@ -3092,7 +3026,8 @@ export const sleep = internal.sleep;
  * The original success, failure, or interruption is preserved; only the success
  * value is paired with the duration.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Duration, Effect } from "effect"
  *
@@ -3102,35 +3037,32 @@ export const sleep = internal.sleep;
  * })
  * ```
  *
- * @since 2.0.0
  * @category Delays & Timeouts
+ * @since 2.0.0
  */
 export const timed = internal.timed;
 // -----------------------------------------------------------------------------
 // Racing
 // -----------------------------------------------------------------------------
 /**
- * Races multiple effects and returns the first successful result.
+ * Runs multiple effects concurrently and returns the first successful result.
  *
  * **Details**
  *
- * This function runs multiple effects concurrently and returns the result of
- * the first one to succeed. If one effect succeeds, the others will be
- * interrupted.
- *
- * If none of the effects succeed, the function will fail with the last error
- * encountered.
+ * Early failures do not finish the race; `raceAll` keeps waiting until one
+ * effect succeeds or every effect has failed. When one effect succeeds, the
+ * remaining effects are interrupted. If every effect fails, the returned effect
+ * fails with a cause containing the collected failure reasons.
  *
  * **When to Use**
  *
- * This is useful when you want to race multiple effects, but only care about
- * the first one to succeed. It is commonly used in cases like timeouts,
- * retries, or when you want to optimize for the faster response without
- * worrying about the other effects.
+ * Use `raceAll` when early failures should be ignored until a success occurs
+ * or all effects fail.
  *
  * @see {@link race} for a version that handles only two effects.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Duration, Effect } from "effect"
  *
@@ -3145,20 +3077,22 @@ export const timed = internal.timed;
  * // Result: "Fast" (after ~100ms)
  * ```
  *
- * @since 2.0.0
  * @category Racing
+ * @since 2.0.0
  */
 export const raceAll = internal.raceAll;
 /**
- * Races multiple effects and returns the first successful result.
+ * Runs multiple effects concurrently and completes with the first effect to
+ * finish, whether it succeeds or fails.
  *
  * **Details**
  *
- * Similar to `raceAll`, this function runs multiple effects concurrently
- * and returns the result of the first one to succeed. If one effect succeeds,
- * the others will be interrupted.
+ * After the first effect completes, all remaining effects are interrupted. Use
+ * `raceAll` when early failures should be ignored until a success occurs or
+ * all effects fail.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Duration, Effect } from "effect"
  *
@@ -3173,8 +3107,8 @@ export const raceAll = internal.raceAll;
  * // Result: "First" (after ~200ms, even though effect2 completes first but fails)
  * ```
  *
- * @since 4.0.0
  * @category Racing
+ * @since 4.0.0
  */
 export const raceAllFirst = internal.raceAllFirst;
 /**
@@ -3183,7 +3117,8 @@ export const raceAllFirst = internal.raceAllFirst;
  * If one effect succeeds, the other is interrupted and `onWinner` can observe the
  * winning fiber. If both fail, the race fails.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Duration, Effect } from "effect"
  *
@@ -3199,8 +3134,8 @@ export const raceAllFirst = internal.raceAllFirst;
  * // Output: winner: slow-success
  * ```
  *
- * @since 2.0.0
  * @category Racing
+ * @since 2.0.0
  */
 export const race = internal.race;
 /**
@@ -3209,7 +3144,8 @@ export const race = internal.race;
  *
  * The losing effect is interrupted, and `onWinner` can observe the winning fiber.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Duration, Effect } from "effect"
  *
@@ -3228,8 +3164,8 @@ export const race = internal.race;
  * // Output: failed: fast-fail
  * ```
  *
- * @since 2.0.0
  * @category Racing
+ * @since 2.0.0
  */
 export const raceFirst = internal.raceFirst;
 // -----------------------------------------------------------------------------
@@ -3239,7 +3175,8 @@ export const raceFirst = internal.raceFirst;
  * Filters elements of an iterable using a predicate, refinement, or effectful
  * predicate.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -3252,22 +3189,22 @@ export const raceFirst = internal.raceFirst;
  * // Use Effect.filterMapEffect for effectful Filter.Filter callbacks
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const filter = internal.filter;
 /**
  * Filters and maps elements of an iterable with a `Filter`.
  *
- * @since 4.0.0
- * @category Filtering
+ * @category filtering
+ * @since 2.0.0
  */
 export const filterMap = internal.filterMap;
 /**
  * Effectfully filters and maps elements of an iterable with a `FilterEffect`.
  *
+ * @category filtering
  * @since 4.0.0
- * @category Filtering
  */
 export const filterMapEffect = internal.filterMapEffect;
 /**
@@ -3280,7 +3217,8 @@ export const filterMapEffect = internal.filterMapEffect;
  * `orElse` effect can produce an alternative value or perform additional
  * computations.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -3297,15 +3235,15 @@ export const filterMapEffect = internal.filterMapEffect;
  * // Result: "Number 5 is odd" (since 5 is not even)
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const filterOrElse = internal.filterOrElse;
 /**
  * Filters an effect with a `Filter`, providing an alternative effect on failure.
  *
+ * @category filtering
  * @since 4.0.0
- * @category Filtering
  */
 export const filterMapOrElse = internal.filterMapOrElse;
 /**
@@ -3317,7 +3255,8 @@ export const filterMapOrElse = internal.filterMapOrElse;
  * predicate evaluates to `false`, the effect fails with either a custom
  * error (if `orFailWith` is provided) or a `NoSuchElementError`.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -3334,37 +3273,38 @@ export const filterMapOrElse = internal.filterMapOrElse;
  * // Result: Effect.fail("Expected even number, got 5")
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const filterOrFail = internal.filterOrFail;
 /**
  * Filters an effect with a `Filter`, failing when the filter fails.
  *
+ * @category filtering
  * @since 4.0.0
- * @category Filtering
  */
 export const filterMapOrFail = internal.filterMapOrFail;
 // -----------------------------------------------------------------------------
 // Conditional Operators
 // -----------------------------------------------------------------------------
 /**
- * Conditionally executes an effect based on a boolean condition.
+ * Conditionally runs an effect based on the result of an effectful boolean
+ * condition.
  *
  * **Details**
  *
- * This function allows you to run an effect only if a given condition evaluates
- * to `true`. If the condition is `true`, the effect is executed, and its result
- * is wrapped in an `Option.some`. If the condition is `false`, the effect is
- * skipped, and the result is `Option.none`.
+ * The condition effect is evaluated first. If it succeeds with `true`, the
+ * source effect is run and its success value is wrapped in `Option.some`. If it
+ * succeeds with `false`, the source effect is skipped and the result is
+ * `Option.none`. If the condition effect fails, that failure is preserved.
  *
  * **When to Use**
  *
- * This function is useful for scenarios where you need to dynamically decide
- * whether to execute an effect based on runtime logic, while also representing
- * the skipped case explicitly.
+ * Use this when an effectful check decides whether to run another effect while
+ * representing the skipped case explicitly.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -3380,11 +3320,10 @@ export const filterMapOrFail = internal.filterMapOrFail;
  * // { _id: 'Option', _tag: 'Some', value: undefined }
  * ```
  *
- * @see {@link whenEffect} for a version that allows the condition to be an effect.
- * @see {@link unless} for a version that executes the effect when the condition is `false`.
+ * @see {@link when} for conditional execution with a boolean condition.
  *
- * @since 2.0.0
  * @category Conditional Operators
+ * @since 2.0.0
  */
 export const when = internal.when;
 // -----------------------------------------------------------------------------
@@ -3408,9 +3347,9 @@ export const when = internal.when;
  *
  * @see {@link matchEffect} if you need to perform side effects in the handlers.
  *
- * @example
+ * **Example** (Handling Both Success and Failure Cases)
+ *
  * ```ts
- * // Title: Handling Both Success and Failure Cases
  * import { Data, Effect } from "effect"
  *
  * class ExampleError extends Data.TaggedError("ExampleError")<{ readonly message: string }> {}
@@ -3440,8 +3379,8 @@ export const when = internal.when;
  * // Output: "failure: Uh oh!"
  * ```
  *
- * @since 2.0.0
  * @category Pattern Matching
+ * @since 2.0.0
  */
 export const match = internal.match;
 /**
@@ -3461,7 +3400,8 @@ export const match = internal.match;
  * optimal performance for resolved effects. This is particularly useful in
  * scenarios where you frequently work with already computed values.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -3477,8 +3417,8 @@ 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.
  *
- * @since 2.0.0
  * @category Pattern Matching
+ * @since 4.0.0
  */
 export const matchEager = internal.matchEager;
 /**
@@ -3495,7 +3435,8 @@ export const matchEager = internal.matchEager;
  * regular failures, defects, or interruptions. You can provide specific
  * handling logic for each failure type based on the cause.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Cause, Effect } from "effect"
  *
@@ -3514,8 +3455,8 @@ export const matchEager = internal.matchEager;
  * handlers.
  * @see {@link match} if you don't need to handle the cause of the failure.
  *
- * @since 2.0.0
  * @category Pattern Matching
+ * @since 2.0.0
  */
 export const matchCause = internal.matchCause;
 /**
@@ -3533,7 +3474,8 @@ export const matchCause = internal.matchCause;
  * and you want to avoid the overhead of the effect pipeline. For pending effects,
  * it automatically falls back to the regular `matchCause` behavior.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -3543,8 +3485,8 @@ export const matchCause = internal.matchCause;
  * })
  * ```
  *
- * @since 3.8.0
  * @category Pattern Matching
+ * @since 4.0.0
  */
 export const matchCauseEager = internal.matchCauseEager;
 /**
@@ -3553,8 +3495,8 @@ export const matchCauseEager = internal.matchCauseEager;
  * If the effect is an `Exit`, the matching handler runs immediately; otherwise it behaves like
  * {@link matchCauseEffect}.
  *
- * @since 4.0.0
  * @category Pattern Matching
+ * @since 4.0.0
  */
 export const matchCauseEffectEager = internal.matchCauseEffectEager;
 /**
@@ -3569,7 +3511,8 @@ export const matchCauseEffectEager = internal.matchCauseEffectEager;
  * you to respond accordingly while performing side effects (like logging or
  * other operations).
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Cause, Console, Data, Effect, Result } from "effect"
  *
@@ -3607,30 +3550,29 @@ 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.
  *
- * @since 2.0.0
  * @category Pattern Matching
+ * @since 2.0.0
  */
 export const matchCauseEffect = internal.matchCauseEffect;
 /**
- * Handles both success and failure cases of an effect, allowing for additional
- * side effects.
+ * Handles both success and failure by running effectful handlers.
  *
  * **Details**
  *
- * The `matchEffect` function is similar to {@link match}, but it enables you to
- * perform side effects in the handlers for both success and failure outcomes.
+ * Use `matchEffect` when either branch needs to return an `Effect`, such as
+ * performing logging, recovery, notification, or other effectful work. The
+ * returned effect succeeds or fails according to the handler that is run.
  *
  * **When to Use**
  *
- * This is useful when you need to execute additional actions, like logging or
- * notifying users, based on whether an effect succeeds or fails.
+ * Use this when the failure or success branch must run additional effects.
  *
  * @see {@link match} if you don't need side effects and only want to handle the
  * result or failure.
  *
- * @example
+ * **Example** (Handling Both Success and Failure Cases with Side Effects)
+ *
  * ```ts
- * // Title: Handling Both Success and Failure Cases with Side Effects
  * import { Data, Effect } from "effect"
  *
  * class ExampleError extends Data.TaggedError("ExampleError")<{ readonly message: string }> {}
@@ -3669,8 +3611,8 @@ export const matchCauseEffect = internal.matchCauseEffect;
  * // failure: Uh oh!
  * ```
  *
- * @since 2.0.0
  * @category Pattern Matching
+ * @since 2.0.0
  */
 export const matchEffect = internal.matchEffect;
 // -----------------------------------------------------------------------------
@@ -3681,7 +3623,7 @@ export const matchEffect = internal.matchEffect;
  *
  * Defects are not converted; if the effect dies, the resulting effect dies too.
  *
- * **Example**
+ * **Example** (Checking whether an effect fails)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -3695,8 +3637,8 @@ export const matchEffect = internal.matchEffect;
  * // Output: true
  * ```
  *
- * @since 2.0.0
  * @category Condition Checking
+ * @since 2.0.0
  */
 export const isFailure = internal.isFailure;
 /**
@@ -3705,7 +3647,7 @@ export const isFailure = internal.isFailure;
  * Returns `false` for failures in the error channel, but defects still fail the
  * effect.
  *
- * **Example**
+ * **Example** (Checking whether an effect succeeds)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -3723,8 +3665,8 @@ export const isFailure = internal.isFailure;
  * // failed: false
  * ```
  *
- * @since 2.0.0
  * @category Condition Checking
+ * @since 2.0.0
  */
 export const isSuccess = internal.isSuccess;
 // -----------------------------------------------------------------------------
@@ -3737,9 +3679,10 @@ export const isSuccess = internal.isSuccess;
  * in the effect's environment. This can be useful for debugging, introspection,
  * or when you need to pass the entire context to another function.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Console, Effect, Option, Context } from "effect"
+ * import { Console, Context, Effect, Option } from "effect"
  *
  * const Logger = Context.Service<{
  *   log: (msg: string) => void
@@ -3765,8 +3708,8 @@ export const isSuccess = internal.isSuccess;
  * const provided = Effect.provideContext(program, context)
  * ```
  *
- * @since 2.0.0
  * @category Environment
+ * @since 2.0.0
  */
 export const context = internal.context;
 /**
@@ -3776,9 +3719,10 @@ export const context = internal.context;
  * computations based on all available services. This is useful when you need
  * to conditionally execute logic based on what services are available.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Console, Effect, Option, Context } from "effect"
+ * import { Console, Context, Effect, Option } from "effect"
  *
  * const Logger = Context.Service<{
  *   log: (msg: string) => void
@@ -3810,8 +3754,8 @@ export const context = internal.context;
  * })
  * ```
  *
- * @since 2.0.0
  * @category Environment
+ * @since 2.0.0
  */
 export const contextWith = internal.contextWith;
 /**
@@ -3819,9 +3763,10 @@ export const contextWith = internal.contextWith;
  * to build the layer every time; by default, layers are shared between provide
  * calls.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * interface Database {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -3844,8 +3789,8 @@ export const contextWith = internal.contextWith;
  * // Output: "Result for: SELECT * FROM users"
  * ```
  *
- * @since 2.0.0
  * @category Environment
+ * @since 2.0.0
  */
 export const provide = internalLayer.provide;
 /**
@@ -3857,9 +3802,10 @@ export const provide = internalLayer.provide;
  * that contains all the required services. It removes the provided services
  * from the effect's requirements, making them available to the effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * // Define service keys
  * const Logger = Context.Service<{
@@ -3884,16 +3830,17 @@ export const provide = internalLayer.provide;
  * const provided = Effect.provideContext(program, context)
  * ```
  *
- * @since 2.0.0
  * @category Environment
+ * @since 4.0.0
  */
 export const provideContext = internal.provideContext;
 /**
  * Accesses a service from the context.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * interface Database {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -3907,8 +3854,8 @@ export const provideContext = internal.provideContext;
  * })
  * ```
  *
- * @since 4.0.0
  * @category Context
+ * @since 4.0.0
  */
 export const service = internal.service;
 /**
@@ -3921,9 +3868,10 @@ export const service = internal.service;
  * available, it returns `None`. Unlike `service`, this function does not
  * require the service to be present in the environment.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Effect, Option, Context } from "effect"
+ * import { Context, Effect, Option } from "effect"
  *
  * // Define a service key
  * const Logger = Context.Service<{
@@ -3942,8 +3890,8 @@ export const service = internal.service;
  * })
  * ```
  *
- * @since 2.0.0
  * @category Context
+ * @since 2.0.0
  */
 export const serviceOption = internal.serviceOption;
 /**
@@ -3954,9 +3902,10 @@ export const serviceOption = internal.serviceOption;
  * This function allows you to transform the context required by an effect,
  * providing part of the context and leaving the rest to be fulfilled later.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * // Define services
  * const Logger = Context.Service<{
@@ -3983,16 +3932,21 @@ export const serviceOption = internal.serviceOption;
  * })
  * ```
  *
- * @since 4.0.0
  * @category Context
+ * @since 4.0.0
  */
 export const updateContext = internal.updateContext;
 /**
- * Updates the service with the required service entry.
+ * Runs an effect with a service implementation transformed by the provided
+ * function.
+ *
+ * The service must be available in the effect's context; `updateService`
+ * replaces it for the wrapped effect with the value returned by the updater.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
- * import { Console, Effect, Context } from "effect"
+ * import { Console, Context, Effect } from "effect"
  *
  * // Define a counter service
  * const Counter = Context.Service<{ count: number }>("Counter")
@@ -4012,8 +3966,8 @@ export const updateContext = internal.updateContext;
  * // 1
  * ```
  *
- * @since 2.0.0
  * @category Context
+ * @since 2.0.0
  */
 export const updateService = internal.updateService;
 /**
@@ -4028,9 +3982,10 @@ export const updateService = internal.updateService;
  *
  * @see {@link provide} for providing multiple layers to an effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Console, Effect, Context } from "effect"
+ * import { Console, Context, Effect } from "effect"
  *
  * // Define a service for configuration
  * const Config = Context.Service<{
@@ -4058,23 +4013,24 @@ export const updateService = internal.updateService;
  * // data
  * ```
  *
- * @since 2.0.0
  * @category Context
+ * @since 2.0.0
  */
 export const provideService = internal.provideService;
 /**
- * Provides the effect with the single service it requires. If the effect
- * requires more than one service use `provide` instead.
+ * Provides one service to an effect using an effectful acquisition.
  *
- * This function is similar to `provideService`, but instead of providing a
- * static service implementation, it allows you to provide an effect that
- * will produce the service. This is useful when the service needs to be
- * acquired through an effectful computation (e.g., reading from a database,
- * making an HTTP request, or allocating resources).
+ * **Details**
+ *
+ * `provideServiceEffect` runs the acquisition effect to produce the service
+ * implementation, removes that service from the wrapped effect's requirements,
+ * and leaves any other requirements to be provided later. Acquisition failures
+ * are included in the returned effect's error channel.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
- * import { Console, Effect, Context } from "effect"
+ * import { Console, Context, Effect } from "effect"
  *
  * // Define a database connection service
  * interface DatabaseConnection {
@@ -4111,8 +4067,8 @@ export const provideService = internal.provideService;
  * // Result for: SELECT * FROM users
  * ```
  *
- * @since 2.0.0
  * @category Context
+ * @since 2.0.0
  */
 export const provideServiceEffect = internal.provideServiceEffect;
 // -----------------------------------------------------------------------------
@@ -4121,7 +4077,8 @@ export const provideServiceEffect = internal.provideServiceEffect;
 /**
  * Sets the concurrency level for parallel operations within an effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -4146,8 +4103,8 @@ export const provideServiceEffect = internal.provideServiceEffect;
  * // [1, 2, 3, 4, 5]
  * ```
  *
+ * @category references
  * @since 2.0.0
- * @category References
  */
 export const withConcurrency = internal.withConcurrency;
 // -----------------------------------------------------------------------------
@@ -4156,7 +4113,8 @@ export const withConcurrency = internal.withConcurrency;
 /**
  * Returns the current scope for resource management.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -4181,8 +4139,8 @@ export const withConcurrency = internal.withConcurrency;
  * // Releasing resource
  * ```
  *
+ * @category resource management
  * @since 2.0.0
- * @category Resource Management & Finalization
  */
 export const scope = internal.scope;
 /**
@@ -4190,7 +4148,8 @@ export const scope = internal.scope;
  * ensuring that their finalizers are run as soon as this workflow completes
  * execution, whether by success, failure, or interruption.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -4213,14 +4172,15 @@ export const scope = internal.scope;
  * // Output: "Releasing resource"
  * ```
  *
+ * @category resource management
  * @since 2.0.0
- * @category Resource Management & Finalization
  */
 export const scoped = internal.scoped;
 /**
  * Creates a scoped effect by providing access to the scope.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect, Scope } from "effect"
  *
@@ -4252,24 +4212,25 @@ export const scoped = internal.scoped;
  * // Manual finalizer
  * ```
  *
- * @since 2.0.0
- * @category Resource Management & Finalization
+ * @category resource management
+ * @since 3.11.0
  */
 export const scopedWith = internal.scopedWith;
 /**
- * This function constructs a scoped resource from an `acquire` and `release`
- * `Effect` value.
+ * Constructs a scoped resource from an acquisition effect and a release
+ * finalizer.
  *
- * If the `acquire` `Effect` value successfully completes execution, then the
- * `release` `Effect` value will be added to the finalizers associated with the
- * scope of this `Effect` value, and it is guaranteed to be run when the scope
- * is closed.
+ * **Details**
+ *
+ * If acquisition succeeds, the release finalizer is added to the current scope
+ * and is guaranteed to run when that scope closes. The finalizer receives the
+ * `Exit` value used to close the scope.
+ *
+ * By default, acquisition is protected by an uninterruptible region. Pass
+ * `{ interruptible: true }` to allow the acquisition effect to be interrupted.
  *
- * The `acquire` and `release` `Effect` values will be run uninterruptibly.
- * Additionally, the `release` `Effect` value may depend on the `Exit` value
- * specified when the scope is closed.
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Console, Effect, Exit } from "effect"
  *
@@ -4306,8 +4267,8 @@ export const scopedWith = internal.scopedWith;
  * )
  * ```
  *
+ * @category resource management
  * @since 2.0.0
- * @category Resource Management & Finalization
  */
 export const acquireRelease = internal.acquireRelease;
 /**
@@ -4323,12 +4284,13 @@ export const acquireRelease = internal.acquireRelease;
  * JavaScript disposal protocal instead of requiring an explicit release
  * function.
  *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using}
+ * @see [JavaScript `using` declarations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using)
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import sqlite from "node:sqlite";
- * import { Effect } from "effect";
+ * import { Effect } from "effect"
  *
  * const program = Effect.scoped(
  *   Effect.gen(function* () {
@@ -4344,8 +4306,8 @@ export const acquireRelease = internal.acquireRelease;
  * )
  * ```
  *
+ * @category resource management
  * @since 4.0.0
- * @category Resource Management & Finalization
  */
 export const acquireDisposable = internal.acquireDisposable;
 /**
@@ -4371,7 +4333,8 @@ export const acquireDisposable = internal.acquireDisposable;
  * is not desired, errors produced by the `release` `Effect` value can be caught
  * and ignored.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect, Exit } from "effect"
  *
@@ -4416,8 +4379,8 @@ export const acquireDisposable = internal.acquireDisposable;
  * // Closing connection to db://localhost:5432 (success)
  * ```
  *
+ * @category resource management
  * @since 2.0.0
- * @category Resource Management & Finalization
  */
 export const acquireUseRelease = internal.acquireUseRelease;
 /**
@@ -4429,7 +4392,8 @@ export const acquireUseRelease = internal.acquireUseRelease;
  * whether the effect succeeds or fails. They're commonly used for resource
  * cleanup, logging, or other side effects that should always occur.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect, Exit } from "effect"
  *
@@ -4458,8 +4422,8 @@ export const acquireUseRelease = internal.acquireUseRelease;
  * // operation result
  * ```
  *
+ * @category resource management
  * @since 2.0.0
- * @category Resource Management & Finalization
  */
 export const addFinalizer = internal.addFinalizer;
 /**
@@ -4473,7 +4437,8 @@ export const addFinalizer = internal.addFinalizer;
  * should generally not be used for releasing resources. For higher-level
  * logic built on `ensuring`, see the `acquireRelease` family of methods.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -4498,17 +4463,18 @@ export const addFinalizer = internal.addFinalizer;
  * // 42
  * ```
  *
+ * @category resource management
  * @since 2.0.0
- * @category Resource Management & Finalization
  */
 export const ensuring = internal.ensuring;
 /**
  * Runs the specified effect if this effect fails, providing the error to the
  * effect if it exists. The provided effect will not be interrupted.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Cause, Data, Console, Effect } from "effect"
+ * import { Cause, Console, Data, Effect } from "effect"
  *
  * class TaskError extends Data.TaggedError("TaskError")<{ readonly message: string }> {}
  *
@@ -4525,15 +4491,16 @@ export const ensuring = internal.ensuring;
  * // TaskError: Something went wrong
  * ```
  *
+ * @category resource management
  * @since 2.0.0
- * @category Resource Management & Finalization
  */
 export const onError = internal.onError;
 /**
  * Runs the finalizer only when this effect fails and the `Cause` matches the
  * provided predicate.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Cause, Console, Effect } from "effect"
  *
@@ -4549,31 +4516,36 @@ export const onError = internal.onError;
  * )
  * ```
  *
+ * @category resource management
  * @since 4.0.0
- * @category Resource Management & Finalization
  */
 export const onErrorIf = internal.onErrorIf;
 /**
  * Runs the finalizer only when this effect fails and the cause matches the provided `Filter`.
  *
+ * @category resource management
  * @since 4.0.0
- * @category Resource Management & Finalization
  */
 export const onErrorFilter = internal.onErrorFilter;
 /**
- * The low level primitive that powers `onExit`.
- * function is used to run a finalizer when the effect exits, regardless of the
- * exit status.
+ * Runs an optional finalizer with the effect's `Exit` value when the effect
+ * completes.
  *
- * @since 2.0.0
- * @category Resource Management & Finalization
+ * **Details**
+ *
+ * This low-level operator preserves the source effect's result unless the
+ * finalizer fails. Prefer `onExit` for normal cleanup logic.
+ *
+ * @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.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect, Exit } from "effect"
  *
@@ -4592,15 +4564,16 @@ export const onExitPrimitive = internal.onExitPrimitive;
  * // 42
  * ```
  *
+ * @category resource management
  * @since 2.0.0
- * @category Resource Management & Finalization
  */
 export const onExit = internal.onExit;
 /**
  * Runs the cleanup effect only when the `Exit` satisfies the provided
  * predicate.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect, Exit } from "effect"
  *
@@ -4614,15 +4587,15 @@ export const onExit = internal.onExit;
  * )
  * ```
  *
+ * @category resource management
  * @since 4.0.0
- * @category Resource Management & Finalization
  */
 export const onExitIf = internal.onExitIf;
 /**
  * Runs the cleanup effect only when the `Exit` matches the provided `Filter`.
  *
+ * @category resource management
  * @since 4.0.0
- * @category Resource Management & Finalization
  */
 export const onExitFilter = internal.onExitFilter;
 // -----------------------------------------------------------------------------
@@ -4651,7 +4624,8 @@ export const onExitFilter = internal.onExitFilter;
  * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
  * additional effect for manually invalidating the cached value.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -4688,8 +4662,8 @@ export const onExitFilter = internal.onExitFilter;
  * // result 3
  * ```
  *
- * @since 2.0.0
  * @category Caching
+ * @since 2.0.0
  */
 export const cached = internal.cached;
 /**
@@ -4724,7 +4698,8 @@ export const cached = internal.cached;
  * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
  * additional effect for manually invalidating the cached value.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -4755,8 +4730,8 @@ export const cached = internal.cached;
  * // result 2
  * ```
  *
- * @since 2.0.0
  * @category Caching
+ * @since 2.0.0
  */
 export const cachedWithTTL = internal.cachedWithTTL;
 /**
@@ -4791,7 +4766,8 @@ export const cachedWithTTL = internal.cachedWithTTL;
  * @see {@link cachedWithTTL} for a similar function that caches the result for
  * a specified duration but does not include an effect for manual invalidation.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -4825,8 +4801,8 @@ export const cachedWithTTL = internal.cachedWithTTL;
  * // result 2
  * ```
  *
- * @since 2.0.0
  * @category Caching
+ * @since 2.0.0
  */
 export const cachedInvalidateWithTTL = internal.cachedInvalidateWithTTL;
 // -----------------------------------------------------------------------------
@@ -4835,7 +4811,8 @@ export const cachedInvalidateWithTTL = internal.cachedInvalidateWithTTL;
 /**
  * Returns an effect that is immediately interrupted.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -4848,14 +4825,15 @@ export const cachedInvalidateWithTTL = internal.cachedInvalidateWithTTL;
  * // Throws: InterruptedException
  * ```
  *
- * @since 2.0.0
  * @category Interruption
+ * @since 2.0.0
  */
 export const interrupt = internal.interrupt;
 /**
  * Returns a new effect that allows the effect to be interruptible.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -4868,14 +4846,15 @@ export const interrupt = internal.interrupt;
  * // Later: fiber.interrupt()
  * ```
  *
- * @since 2.0.0
  * @category Interruption
+ * @since 2.0.0
  */
 export const interruptible = internal.interruptible;
 /**
  * Runs the specified finalizer effect if this effect is interrupted.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect, Fiber } from "effect"
  *
@@ -4892,14 +4871,15 @@ export const interruptible = internal.interruptible;
  * // Output: Task was interrupted, cleaning up...
  * ```
  *
- * @since 2.0.0
  * @category Interruption
+ * @since 2.0.0
  */
 export const onInterrupt = internal.onInterrupt;
 /**
  * Returns a new effect that disables interruption for the given effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect, Fiber } from "effect"
  *
@@ -4916,15 +4896,16 @@ export const onInterrupt = internal.onInterrupt;
  * Effect.runPromise(Fiber.interrupt(fiber))
  * ```
  *
- * @since 2.0.0
  * @category Interruption
+ * @since 2.0.0
  */
 export const uninterruptible = internal.uninterruptible;
 /**
  * Disables interruption and provides a restore function to restore the
  * interruptible state within the effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -4946,8 +4927,8 @@ export const uninterruptible = internal.uninterruptible;
  * )
  * ```
  *
- * @since 2.0.0
  * @category Interruption
+ * @since 2.0.0
  */
 export const uninterruptibleMask = internal.uninterruptibleMask;
 /**
@@ -4955,7 +4936,8 @@ export const uninterruptibleMask = internal.uninterruptibleMask;
  * `restore` function. This function can be used to restore the interruptibility
  * of any specific region of code.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -4977,21 +4959,22 @@ export const uninterruptibleMask = internal.uninterruptibleMask;
  * )
  * ```
  *
- * @since 2.0.0
  * @category Interruption
+ * @since 2.0.0
  */
 export const interruptibleMask = internal.interruptibleMask;
 /**
  * Creates an AbortSignal that is managed by the provided scope.
  *
- * @since 4.0.0
  * @category Interruption
+ * @since 4.0.0
  */
 export const abortSignal = internal.abortSignal;
 /**
  * Repeats this effect forever (until the first error).
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect, Fiber } from "effect"
  *
@@ -5014,8 +4997,8 @@ export const abortSignal = internal.abortSignal;
  * })
  * ```
  *
- * @since 2.0.0
  * @category Repetition / Recursion
+ * @since 2.0.0
  */
 export const forever = internal.forever;
 /**
@@ -5040,12 +5023,11 @@ export const forever = internal.forever;
  * delays, limiting recursions, or dynamically adjusting based on the outcome of
  * each execution.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * // Success Example
- * import { Effect } from "effect"
- * import { Schedule } from "effect"
- * import { Console } from "effect"
+ * import { Console, Effect, Schedule } from "effect"
  *
  * const action = Console.log("success")
  * const policy = Schedule.addDelay(Schedule.recurs(2), () => Effect.succeed("100 millis"))
@@ -5054,10 +5036,11 @@ export const forever = internal.forever;
  * // Effect.runPromise(program).then((n) => console.log(`repetitions: ${n}`))
  * ```
  *
- * @example
+ * **Example** (Usage)
+ *
+ * ```ts
  * // Failure Example
- * import { Effect } from "effect"
- * import { Schedule } from "effect"
+ * import { Effect, Schedule } from "effect"
  *
  * let count = 0
  *
@@ -5077,33 +5060,27 @@ export const forever = internal.forever;
  * const program = Effect.repeat(action, policy)
  *
  * // Effect.runPromiseExit(program).then(console.log)
+ * ```
  *
- * @since 2.0.0
  * @category Repetition / Recursion
+ * @since 2.0.0
  */
 export const repeat = internalSchedule.repeat;
 /**
- * Repeats an effect with a schedule, handling failures using a custom handler.
+ * Repeats an effect according to a schedule and runs a fallback effect if
+ * repetition fails before the schedule completes.
  *
  * **Details**
  *
- * This function allows you to execute an effect repeatedly based on a specified
- * schedule. If the effect fails at any point, a custom failure handler is
- * invoked. The handler is provided with both the failure value and the output
- * of the schedule at the time of failure. If the effect fails immediately, the
- * schedule will never be executed and the output provided to the handler will
- * be `None`. This enables advanced error recovery or alternative fallback logic
- * while maintaining flexibility in how repetitions are handled.
+ * If the repeated effect or schedule step fails, `orElse` receives the failure
+ * and the latest schedule metadata when at least one schedule step has run;
+ * otherwise it receives `None`. If the schedule completes normally, the
+ * returned effect succeeds with the schedule's output.
  *
- * For example, using a schedule with `recurs(2)` will allow for two additional
- * repetitions after the initial execution, provided the effect succeeds. If a
- * failure occurs during any iteration, the failure handler is invoked to handle
- * the situation.
+ * **Example** (Usage)
  *
- * @example
  * ```ts
- * import { Console, Effect, Schedule } from "effect"
- * import * as Option from "effect/Option"
+ * import { Console, Effect, Option, Schedule } from "effect"
  *
  * let attempt = 0
  * const task = Effect.gen(function*() {
@@ -5128,8 +5105,8 @@ export const repeat = internalSchedule.repeat;
  * )
  * ```
  *
- * @since 2.0.0
  * @category Repetition / Recursion
+ * @since 2.0.0
  */
 export const repeatOrElse = internalSchedule.repeatOrElse;
 /**
@@ -5137,8 +5114,8 @@ export const repeatOrElse = internalSchedule.repeatOrElse;
  *
  * Use with `Effect.all` to run the replicated effects and collect results.
  *
- * @since 2.0.0
  * @category Collecting
+ * @since 2.0.0
  */
 export const replicate = internal.replicate;
 /**
@@ -5146,7 +5123,8 @@ export const replicate = internal.replicate;
  *
  * Use `concurrency` to control parallelism and `discard: true` to ignore results.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -5156,27 +5134,24 @@ export const replicate = internal.replicate;
  * })
  * ```
  *
- * @since 2.0.0
  * @category Collecting
+ * @since 2.0.0
  */
 export const replicateEffect = internal.replicateEffect;
 /**
- * Repeats an effect based on a specified schedule.
+ * Runs an effect repeatedly according to a schedule and returns the schedule's
+ * final output.
  *
  * **Details**
  *
- * This function allows you to execute an effect repeatedly according to a given
- * schedule. The schedule determines the timing and number of repetitions. Each
- * repetition can also depend on the decision of the schedule, providing
- * flexibility for complex workflows. This function does not modify the effect's
- * success or failure; it only controls its repetition.
+ * The schedule is first stepped with `undefined`. After each successful
+ * execution, the effect's success value is fed to the schedule to decide
+ * whether to run again. The returned effect fails if the effect or schedule
+ * fails, and otherwise succeeds with the schedule output when the schedule
+ * completes.
  *
- * For example, you can use a schedule that recurs a specific number of times,
- * adds delays between repetitions, or customizes repetition behavior based on
- * external inputs. The effect runs initially and is repeated according to the
- * schedule.
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -5202,26 +5177,24 @@ 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.
  *
- * @since 2.0.0
  * @category Repetition / Recursion
+ * @since 2.0.0
  */
 export const schedule = /*#__PURE__*/dual(2, (self, schedule) => scheduleFrom(self, undefined, schedule));
 /**
- * Runs an effect repeatedly according to a schedule, starting from a specified
- * initial input value.
+ * Runs an effect repeatedly according to a schedule that is initialized with a
+ * specific schedule input.
  *
  * **Details**
  *
- * This function allows you to repeatedly execute an effect based on a schedule.
- * The schedule starts with the given `initial` input value, which is passed to
- * the first execution. Subsequent executions of the effect are controlled by
- * the schedule's rules, using the output of the previous iteration as the input
- * for the next one.
+ * `initial` is passed to the schedule before the first execution, not to the
+ * effect itself. After each successful execution, the effect's success value is
+ * fed back into the schedule to decide whether to continue. The returned effect
+ * succeeds with the schedule output when the schedule completes and fails if
+ * the effect or schedule fails.
  *
- * The returned effect will complete when the schedule ends or the effect fails,
- * propagating the error.
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -5242,8 +5215,8 @@ export const schedule = /*#__PURE__*/dual(2, (self, schedule) => scheduleFrom(se
  * // Returns the schedule count
  * ```
  *
- * @since 2.0.0
  * @category Repetition / Recursion
+ * @since 2.0.0
  */
 export const scheduleFrom = internalSchedule.scheduleFrom;
 // -----------------------------------------------------------------------------
@@ -5252,7 +5225,8 @@ export const scheduleFrom = internalSchedule.scheduleFrom;
 /**
  * Returns the current tracer from the context.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5263,14 +5237,15 @@ export const scheduleFrom = internalSchedule.scheduleFrom;
  * })
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const tracer = internal.tracer;
 /**
  * Provides a tracer to an effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5283,14 +5258,20 @@ export const tracer = internal.tracer;
  * // const traced = Effect.withTracer(program, customTracer)
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const withTracer = internal.withTracer;
 /**
- * Disable the tracer for the given Effect.
+ * Enables or disables tracing for spans created by the given effect.
+ *
+ * **Details**
+ *
+ * When `enabled` is `false`, spans created inside the effect are not registered
+ * with the current tracer and do not propagate as normal trace parents.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5301,14 +5282,15 @@ export const withTracer = internal.withTracer;
  * )
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const withTracerEnabled = internal.withTracerEnabled;
 /**
  * Enables or disables tracer timing for the given Effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5319,14 +5301,15 @@ export const withTracerEnabled = internal.withTracerEnabled;
  * )
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const withTracerTiming = internal.withTracerTiming;
 /**
  * Adds an annotation to each span in this effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5346,14 +5329,15 @@ export const withTracerTiming = internal.withTracerTiming;
  * })
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const annotateSpans = internal.annotateSpans;
 /**
  * Adds an annotation to the current span if available.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5370,14 +5354,20 @@ export const annotateSpans = internal.annotateSpans;
  * const traced = Effect.withSpan(program, "user-operation")
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const annotateCurrentSpan = internal.annotateCurrentSpan;
 /**
- * Returns the current span from the context.
+ * Returns the currently active local tracing span.
+ *
+ * **Details**
+ *
+ * The effect fails with `NoSuchElementError` when there is no active local
+ * `Span`.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5390,14 +5380,21 @@ export const annotateCurrentSpan = internal.annotateCurrentSpan;
  * const traced = Effect.withSpan(program, "my-span")
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const currentSpan = internal.currentSpan;
 /**
- * Returns the current parent span from the context.
+ * Returns the current parent span from the effect context.
+ *
+ * **Details**
+ *
+ * The effect succeeds with either a local span or external span when one is
+ * present, and fails with `NoSuchElementError` when no parent span is
+ * available.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5415,14 +5412,20 @@ export const currentSpan = internal.currentSpan;
  * const traced = Effect.withSpan(program, "parent-span")
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const currentParentSpan = internal.currentParentSpan;
 /**
- * Returns the annotations of the current span.
+ * Returns the tracing span annotations currently carried in the effect context.
+ *
+ * **Details**
+ *
+ * These annotations are applied to spans created inside the context, such as
+ * spans created by `withSpan`, `useSpan`, or `makeSpan`.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5442,18 +5445,20 @@ export const currentParentSpan = internal.currentParentSpan;
  * // Output: Current span annotations: { userId: "123", operation: "data-processing" }
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const spanAnnotations = internal.spanAnnotations;
 /**
- * Retrieves the span links associated with the current span.
+ * Returns the tracing span links currently carried in the effect context.
+ *
+ * **Details**
+ *
+ * These links are attached to spans created inside the context. Span links
+ * connect related spans without making one span the parent of another.
  *
- * Span links are connections between spans that are related but not in a
- * parent-child relationship. They are useful for linking spans across different
- * traces or connecting spans from parallel operations.
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5465,8 +5470,8 @@ export const spanAnnotations = internal.spanAnnotations;
  * })
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const spanLinks = internal.spanLinks;
 /**
@@ -5476,7 +5481,8 @@ export const spanLinks = internal.spanLinks;
  * parent-child relationship. For example, you might want to link spans from
  * parallel operations or connect spans across different traces.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5498,7 +5504,8 @@ export const spanLinks = internal.spanLinks;
  * })
  * ```
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5516,14 +5523,21 @@ export const spanLinks = internal.spanLinks;
  * })
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const linkSpans = internal.linkSpans;
 /**
- * Create a new span for tracing.
+ * Creates a new tracing span and returns it without managing its lifetime.
+ *
+ * **Details**
+ *
+ * The span is not added to the current span stack and is not ended
+ * automatically. Use `withSpan`, `useSpan`, or `makeSpanScoped` when the span
+ * should be installed as context or closed automatically.
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5534,8 +5548,8 @@ export const linkSpans = internal.linkSpans;
  * })
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const makeSpan = internal.makeSpan;
 /**
@@ -5545,7 +5559,8 @@ export const makeSpan = internal.makeSpan;
  * The span is not added to the current span stack, so no child spans will be
  * created for it.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5559,8 +5574,8 @@ export const makeSpan = internal.makeSpan;
  * )
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const makeSpanScoped = internal.makeSpanScoped;
 /**
@@ -5570,7 +5585,8 @@ export const makeSpanScoped = internal.makeSpanScoped;
  * The span is not added to the current span stack, so no child spans will be
  * created for it.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5584,14 +5600,15 @@ export const makeSpanScoped = internal.makeSpanScoped;
  * )
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const useSpan = internal.useSpan;
 /**
  * Wraps the effect with a new span for tracing.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5605,8 +5622,8 @@ export const useSpan = internal.useSpan;
  * })
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const withSpan = internal.withSpan;
 /**
@@ -5614,7 +5631,8 @@ export const withSpan = internal.withSpan;
  *
  * The span is ended when the Scope is finalized.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5627,14 +5645,15 @@ export const withSpan = internal.withSpan;
  * )
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const withSpanScoped = internal.withSpanScoped;
 /**
  * Adds the provided span to the current span stack.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5646,8 +5665,8 @@ export const withSpanScoped = internal.withSpanScoped;
  * })
  * ```
  *
+ * @category tracing
  * @since 2.0.0
- * @category Tracing
  */
 export const withParentSpan = internal.withParentSpan;
 // -----------------------------------------------------------------------------
@@ -5656,10 +5675,11 @@ export const withParentSpan = internal.withParentSpan;
 /**
  * Executes a request using the provided resolver.
  *
- * @since 2.0.0
  * @category Requests & Batching
+ * @since 2.0.0
+ *
+ * **Example** (Usage)
  *
- * @example
  * ```ts
  * import { Console, Effect, Exit, Request, RequestResolver } from "effect"
  *
@@ -5690,8 +5710,8 @@ export const request = internalRequest.request;
  *
  * It returns a canceler that removes the pending request entry.
  *
- * @since 4.0.0
  * @category Requests & Batching
+ * @since 4.0.0
  */
 export const requestUnsafe = internalRequest.requestUnsafe;
 // -----------------------------------------------------------------------------
@@ -5718,7 +5738,8 @@ export const requestUnsafe = internalRequest.requestUnsafe;
  * fibers leak. This behavior is called "auto supervision", and if this
  * behavior is not desired, you may use the `forkDetach` or `forkIn` methods.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect, Fiber } from "effect"
  *
@@ -5740,15 +5761,16 @@ export const requestUnsafe = internalRequest.requestUnsafe;
  * })
  * ```
  *
- * @since 4.0.0
  * @category Supervision & Fibers
+ * @since 4.0.0
  */
 export const forkChild = internal.forkChild;
 /**
  * Forks the effect in the specified scope. The fiber will be interrupted
  * when the scope is closed.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5768,14 +5790,15 @@ export const forkChild = internal.forkChild;
  * )
  * ```
  *
- * @since 2.0.0
  * @category Supervision & Fibers
+ * @since 2.0.0
  */
 export const forkIn = internal.forkIn;
 /**
  * Forks the fiber in a `Scope`, interrupting it when the scope is closed.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5801,8 +5824,8 @@ export const forkIn = internal.forkIn;
  * )
  * ```
  *
- * @since 2.0.0
  * @category Supervision & Fibers
+ * @since 2.0.0
  */
 export const forkScoped = internal.forkScoped;
 /**
@@ -5810,7 +5833,8 @@ export const forkScoped = internal.forkScoped;
  * new fiber is attached to the global scope, when the fiber executing the
  * returned effect terminates, the forked fiber will continue running.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5834,22 +5858,23 @@ export const forkScoped = internal.forkScoped;
  * })
  * ```
  *
- * @since 2.0.0
  * @category Supervision & Fibers
+ * @since 4.0.0
  */
 export const forkDetach = internal.forkDetach;
 /**
  * Waits for all child fibers forked by this effect to complete before this
  * effect completes.
  *
- * @since 2.0.0
  * @category Supervision & Fibers
+ * @since 2.0.0
  */
 export const awaitAllChildren = internal.awaitAllChildren;
 /**
  * Access the fiber currently executing the effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -5859,14 +5884,15 @@ export const awaitAllChildren = internal.awaitAllChildren;
  * })
  * ```
  *
- * @since 4.0.0
  * @category Supervision & Fibers
+ * @since 4.0.0
  */
 export const fiber = internal.fiber;
 /**
  * Access the current fiber id executing the effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -5881,8 +5907,8 @@ export const fiber = internal.fiber;
  * )
  * ```
  *
- * @since 4.0.0
  * @category Supervision & Fibers
+ * @since 2.0.0
  */
 export const fiberId = internal.fiberId;
 /**
@@ -5898,13 +5924,10 @@ export const fiberId = internal.fiberId;
  * Unless you specifically need a `Promise` or synchronous operation,
  * `runFork` is a good default choice.
  *
- * @example
+ * **Example** (Running an Effect in the Background)
+ *
  * ```ts
- * // Title: Running an Effect in the Background
- * import { Effect } from "effect"
- * import { Schedule } from "effect"
- * import { Fiber } from "effect"
- * import { Console } from "effect"
+ * import { Console, Effect, Fiber, Schedule } from "effect"
  *
  * //      ┌─── Effect<number, never, never>
  * //      ▼
@@ -5922,16 +5945,17 @@ export const fiberId = internal.fiberId;
  * }, 500)
  * ```
  *
- * @since 2.0.0
  * @category Running Effects
+ * @since 2.0.0
  */
 export const runFork = internal.runFork;
 /**
  * Runs an effect in the background with the provided services.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * interface Logger {
  *   log: (message: string) => void
@@ -5952,8 +5976,8 @@ export const runFork = internal.runFork;
  * const fiber = Effect.runForkWith(services)(program)
  * ```
  *
- * @since 4.0.0
  * @category Running Effects
+ * @since 4.0.0
  */
 export const runForkWith = internal.runForkWith;
 /**
@@ -5961,9 +5985,10 @@ export const runForkWith = internal.runForkWith;
  *
  * The returned interruptor calls `fiber.interruptUnsafe`, optionally with an interruptor id.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Console, Effect, Exit, Context } from "effect"
+ * import { Console, Context, Effect, Exit } from "effect"
  *
  * interface Logger {
  *   log: (message: string) => Effect.Effect<void>
@@ -5993,8 +6018,8 @@ export const runForkWith = internal.runForkWith;
  * interrupt()
  * ```
  *
- * @since 4.0.0
  * @category Running Effects
+ * @since 4.0.0
  */
 export const runCallbackWith = internal.runCallbackWith;
 /**
@@ -6004,7 +6029,8 @@ export const runCallbackWith = internal.runCallbackWith;
  * The interruptor calls `fiber.interruptUnsafe` with the optional interruptor
  * id.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect, Exit } from "effect"
  *
@@ -6031,8 +6057,8 @@ export const runCallbackWith = internal.runCallbackWith;
  * // interrupt() to cancel the fiber if needed
  * ```
  *
- * @since 4.0.0
  * @category Running Effects
+ * @since 2.0.0
  */
 export const runCallback = internal.runCallback;
 /**
@@ -6049,33 +6075,37 @@ export const runCallback = internal.runCallback;
  *
  * @see {@link runPromiseExit} for a version that returns an `Exit` type instead of rejecting.
  *
- * @example
+ * **Example** (Running a Successful Effect as a Promise)
+ *
  * ```ts
- * // Title: Running a Successful Effect as a Promise
  * import { Effect } from "effect"
  *
  * Effect.runPromise(Effect.succeed(1)).then(console.log)
  * // Output: 1
  * ```
  *
- * @example
+ * **Example** (Usage)
+ *
+ * ```ts
  * //Example: Handling a Failing Effect as a Rejected Promise
  * import { Effect } from "effect"
  *
  * Effect.runPromise(Effect.fail("my error")).catch(console.error)
  * // Output:
  * // (FiberFailure) Error: my error
+ * ```
  *
- * @since 2.0.0
  * @category Running Effects
+ * @since 2.0.0
  */
 export const runPromise = internal.runPromise;
 /**
  * Executes an effect as a Promise with the provided services.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * interface Config {
  *   apiUrl: string
@@ -6095,8 +6125,8 @@ export const runPromise = internal.runPromise;
  * Effect.runPromiseWith(context)(program).then(console.log)
  * ```
  *
- * @since 4.0.0
  * @category Running Effects
+ * @since 4.0.0
  */
 export const runPromiseWith = internal.runPromiseWith;
 /**
@@ -6115,9 +6145,9 @@ export const runPromiseWith = internal.runPromiseWith;
  * - If it fails, the failure information is provided as a `Failure` containing
  *   a `Cause` type.
  *
- * @example
+ * **Example** (Handling Results as Exit)
+ *
  * ```ts
- * // Title: Handling Results as Exit
  * import { Effect } from "effect"
  *
  * // Execute a successful effect and get the Exit result as a Promise
@@ -6143,16 +6173,17 @@ export const runPromiseWith = internal.runPromiseWith;
  * // }
  * ```
  *
- * @since 2.0.0
  * @category Running Effects
+ * @since 2.0.0
  */
 export const runPromiseExit = internal.runPromiseExit;
 /**
  * Runs an effect and returns a Promise of Exit with provided services.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Effect, Exit, Context } from "effect"
+ * import { Context, Effect, Exit } from "effect"
  *
  * interface Database {
  *   query: (sql: string) => string
@@ -6176,28 +6207,29 @@ export const runPromiseExit = internal.runPromiseExit;
  * })
  * ```
  *
- * @since 4.0.0
  * @category Running Effects
+ * @since 4.0.0
  */
 export const runPromiseExitWith = internal.runPromiseExitWith;
 /**
- * Executes an effect synchronously, running it immediately and returning the
- * result.
+ * Executes an effect synchronously and returns its success value.
  *
  * **When to Use**
  *
- * Use `runSync` to run an effect that does not fail and does not include
- * any asynchronous operations.
+ * Use `runSync` only for effects that can complete synchronously.
+ *
+ * **Details**
  *
- * If the effect fails or involves asynchronous work, it will throw an error,
- * and execution will stop where the failure or async operation occurs.
+ * If the effect fails, dies, is interrupted, or performs asynchronous work,
+ * `runSync` throws a `FiberFailure` instead of returning a value. Use
+ * `runSyncExit` when you want the failure captured as an `Exit`.
  *
  * @see {@link runSyncExit} for a version that returns an `Exit` type instead of
  * throwing an error.
  *
- * @example
+ * **Example** (Synchronous Logging)
+ *
  * ```ts
- * // Title: Synchronous Logging
  * import { Effect } from "effect"
  *
  * const program = Effect.sync(() => {
@@ -6212,8 +6244,9 @@ export const runPromiseExitWith = internal.runPromiseExitWith;
  * // Output: 1
  * ```
  *
- * @example
- * // Title: Incorrect Usage with Failing or Async Effects
+ * **Example** (Incorrect Usage with Failing or Async Effects)
+ *
+ * ```ts
  * import { Effect } from "effect"
  *
  * try {
@@ -6233,17 +6266,19 @@ export const runPromiseExitWith = internal.runPromiseExitWith;
  * }
  * // Output:
  * // (FiberFailure) AsyncFiberException: Fiber #0 cannot be resolved synchronously. This is caused by using runSync on an effect that performs async work
+ * ```
  *
- * @since 2.0.0
  * @category Running Effects
+ * @since 2.0.0
  */
 export const runSync = internal.runSync;
 /**
  * Executes an effect synchronously with provided services.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * interface MathService {
  *   add: (a: number, b: number) => number
@@ -6264,8 +6299,8 @@ export const runSync = internal.runSync;
  * console.log(result) // 5
  * ```
  *
- * @since 4.0.0
  * @category Running Effects
+ * @since 4.0.0
  */
 export const runSyncWith = internal.runSyncWith;
 /**
@@ -6288,9 +6323,9 @@ export const runSyncWith = internal.runSyncWith;
  * return an `Failure` with a `Die` cause, indicating that the effect cannot be
  * resolved synchronously.
  *
- * @example
+ * **Example** (Handling Results as Exit)
+ *
  * ```ts
- * // Title: Handling Results as Exit
  * import { Effect } from "effect"
  *
  * console.log(Effect.runSyncExit(Effect.succeed(1)))
@@ -6314,8 +6349,9 @@ export const runSyncWith = internal.runSyncWith;
  * // }
  * ```
  *
- * @example
- * // Title: Asynchronous Operation Resulting in Die
+ * **Example** (Asynchronous Operation Resulting in Die)
+ *
+ * ```ts
  * import { Effect } from "effect"
  *
  * console.log(Effect.runSyncExit(Effect.promise(() => Promise.resolve(1))))
@@ -6333,17 +6369,19 @@ export const runSyncWith = internal.runSyncWith;
  * //     }
  * //   }
  * // }
+ * ```
  *
- * @since 2.0.0
  * @category Running Effects
+ * @since 2.0.0
  */
 export const runSyncExit = internal.runSyncExit;
 /**
  * Runs an effect synchronously with provided services, returning an Exit result.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
- * import { Effect, Exit, Context } from "effect"
+ * import { Context, Effect, Exit } from "effect"
  *
  * // Define a logger service
  * const Logger = Context.Service<{
@@ -6373,8 +6411,8 @@ export const runSyncExit = internal.runSyncExit;
  * // Success: 42
  * ```
  *
- * @since 4.0.0
  * @category Running Effects
+ * @since 4.0.0
  */
 export const runSyncExitWith = internal.runSyncExitWith;
 /**
@@ -6382,7 +6420,8 @@ export const runSyncExitWith = internal.runSyncExitWith;
  *
  * `Effect.fnUntraced` also acts as a `pipe` function, so you can append transforms after the body.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -6394,8 +6433,8 @@ export const runSyncExitWith = internal.runSyncExitWith;
  * Effect.runFork(greet("Ada"))
  * ```
  *
- * @since 3.12.0
  * @category Function
+ * @since 3.12.0
  */
 export const fnUntraced = internal.fnUntraced;
 /**
@@ -6403,7 +6442,8 @@ export const fnUntraced = internal.fnUntraced;
  *
  * Pipeable functions run after the body and can transform the resulting Effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -6422,8 +6462,8 @@ export const fnUntraced = internal.fnUntraced;
  * })
  * ```
  *
- * @since 3.12.0
  * @category Function
+ * @since 3.11.0
  */
 export const fn = internal.fn;
 // ========================================================================
@@ -6433,7 +6473,8 @@ export const fn = internal.fn;
  * Retrieves the `Clock` service from the context and provides it to the
  * specified effectful function.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  *
@@ -6449,8 +6490,8 @@ export const fn = internal.fn;
  * // Current time is: 1735484929744
  * ```
  *
- * @since 2.0.0
  * @category Clock
+ * @since 2.0.0
  */
 export const clockWith = internal.clockWith;
 // ========================================================================
@@ -6462,7 +6503,8 @@ export const clockWith = internal.clockWith;
  * If no level is provided, the logger uses the fiber's current log level and
  * extracts any `Cause` values from the message list.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -6473,14 +6515,15 @@ export const clockWith = internal.clockWith;
  * })
  * ```
  *
+ * @category logging
  * @since 2.0.0
- * @category Logging
  */
 export const logWithLevel = internal.logWithLevel;
 /**
  * Logs one or more messages using the default log level.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -6500,14 +6543,15 @@ export const logWithLevel = internal.logWithLevel;
  * // 4
  * ```
  *
+ * @category logging
  * @since 2.0.0
- * @category Logging
  */
 export const log = /*#__PURE__*/internal.logWithLevel();
 /**
  * Logs one or more messages at the FATAL level.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -6528,14 +6572,15 @@ export const log = /*#__PURE__*/internal.logWithLevel();
  * // timestamp=2023-... level=FATAL message="System shutting down"
  * ```
  *
+ * @category logging
  * @since 2.0.0
- * @category Logging
  */
 export const logFatal = /*#__PURE__*/internal.logWithLevel("Fatal");
 /**
  * Logs one or more messages at the WARNING level.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -6557,14 +6602,15 @@ export const logFatal = /*#__PURE__*/internal.logWithLevel("Fatal");
  * // timestamp=2023-... level=WARN message="Using deprecated API endpoint"
  * ```
  *
+ * @category logging
  * @since 2.0.0
- * @category Logging
  */
 export const logWarning = /*#__PURE__*/internal.logWithLevel("Warn");
 /**
  * Logs one or more messages at the ERROR level.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -6589,14 +6635,15 @@ export const logWarning = /*#__PURE__*/internal.logWithLevel("Warn");
  * // timestamp=2023-... level=ERROR message="Caught error: Something went wrong"
  * ```
  *
+ * @category logging
  * @since 2.0.0
- * @category Logging
  */
 export const logError = /*#__PURE__*/internal.logWithLevel("Error");
 /**
  * Logs one or more messages at the INFO level.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -6616,14 +6663,15 @@ export const logError = /*#__PURE__*/internal.logWithLevel("Error");
  * // timestamp=2023-... level=INFO message="Application version: 1.2.3"
  * ```
  *
+ * @category logging
  * @since 2.0.0
- * @category Logging
  */
 export const logInfo = /*#__PURE__*/internal.logWithLevel("Info");
 /**
  * Logs one or more messages at the DEBUG level.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -6644,14 +6692,15 @@ export const logInfo = /*#__PURE__*/internal.logWithLevel("Info");
  * // timestamp=2023-... level=DEBUG message="Variable state: x=10 y=20 z=30"
  * ```
  *
+ * @category logging
  * @since 2.0.0
- * @category Logging
  */
 export const logDebug = /*#__PURE__*/internal.logWithLevel("Debug");
 /**
  * Logs one or more messages at the TRACE level.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -6675,14 +6724,15 @@ export const logDebug = /*#__PURE__*/internal.logWithLevel("Debug");
  * // timestamp=2023-... level=TRACE message="Exiting function processData"
  * ```
  *
+ * @category logging
  * @since 2.0.0
- * @category Logging
  */
 export const logTrace = /*#__PURE__*/internal.logWithLevel("Trace");
 /**
  * Adds a logger to the set of loggers which will output logs for this effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -6703,14 +6753,15 @@ export const logTrace = /*#__PURE__*/internal.logWithLevel("Trace");
  * // Output includes both default and custom log outputs
  * ```
  *
- * @since 2.0.0
- * @category Logging
+ * @category logging
+ * @since 4.0.0
  */
 export const withLogger = /*#__PURE__*/dual(2, (effect, logger) => internal.updateService(effect, internal.CurrentLoggers, loggers => new Set([...loggers, logger])));
 /**
  * Adds an annotation to each log line in this effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -6733,8 +6784,8 @@ export const withLogger = /*#__PURE__*/dual(2, (effect, logger) => internal.upda
  * // All log messages will include the userId and operation annotations
  * ```
  *
+ * @category logging
  * @since 2.0.0
- * @category Logging
  */
 export const annotateLogs = /*#__PURE__*/dual(args => isEffect(args[0]), (effect, ...args) => internal.updateService(effect, CurrentLogAnnotations, annotations => {
   const newAnnotations = {
@@ -6754,7 +6805,8 @@ export const annotateLogs = /*#__PURE__*/dual(args => isEffect(args[0]), (effect
  * `annotateLogsScoped` updates annotations for the entire current `Scope` and
  * restores the previous annotations when the scope closes.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -6769,14 +6821,15 @@ export const annotateLogs = /*#__PURE__*/dual(args => isEffect(args[0]), (effect
  * Effect.runPromise(program)
  * ```
  *
- * @since 4.0.0
- * @category Logging
+ * @category logging
+ * @since 3.1.0
  */
 export const annotateLogsScoped = internal.annotateLogsScoped;
 /**
  * Adds a span to each log line in this effect.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -6800,8 +6853,8 @@ export const annotateLogsScoped = internal.annotateLogsScoped;
  * // All log messages will include span information showing the nested operation context
  * ```
  *
+ * @category logging
  * @since 2.0.0
- * @category Logging
  */
 export const withLogSpan = /*#__PURE__*/dual(2, (effect, label) => internal.flatMap(internal.currentTimeMillis, now => internal.updateService(effect, CurrentLogSpans, spans => {
   const span = [label, now];
@@ -6816,7 +6869,8 @@ export const withLogSpan = /*#__PURE__*/dual(2, (effect, label) => internal.flat
  * Also accepts an optional function which can be used to map the `Exit` value
  * of the `Effect` into a valid `Input` for the `Metric`.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect, Metric } from "effect"
  *
@@ -6835,7 +6889,8 @@ export const withLogSpan = /*#__PURE__*/dual(2, (effect, label) => internal.flat
  * )
  * ```
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect, Exit, Metric } from "effect"
  *
@@ -6855,8 +6910,8 @@ export const withLogSpan = /*#__PURE__*/dual(2, (effect, label) => internal.flat
  * )
  * ```
  *
- * @since 4.0.0
  * @category Tracking
+ * @since 4.0.0
  */
 export const track = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric, f) => onExit(self, exit => {
   const input = f === undefined ? exit : internalCall(() => f(exit));
@@ -6869,7 +6924,8 @@ export const track = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric,
  * Also accepts an optional function which can be used to map the success value
  * of the `Effect` into a valid `Input` for the `Metric`.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect, Metric } from "effect"
  *
@@ -6887,7 +6943,8 @@ export const track = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric,
  * )
  * ```
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect, Metric } from "effect"
  *
@@ -6904,8 +6961,8 @@ export const track = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric,
  * )
  * ```
  *
- * @since 4.0.0
  * @category Tracking
+ * @since 4.0.0
  */
 export const trackSuccesses = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric, f) => tap(self, value => {
   const input = f === undefined ? value : f(value);
@@ -6918,7 +6975,8 @@ export const trackSuccesses = /*#__PURE__*/dual(args => isEffect(args[0]), (self
  * Also accepts an optional function which can be used to map the error value
  * of the `Effect` into a valid `Input` for the `Metric`.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect, Metric } from "effect"
  *
@@ -6936,7 +6994,8 @@ export const trackSuccesses = /*#__PURE__*/dual(args => isEffect(args[0]), (self
  * )
  * ```
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -6955,8 +7014,8 @@ export const trackSuccesses = /*#__PURE__*/dual(args => isEffect(args[0]), (self
  * )
  * ```
  *
- * @since 4.0.0
  * @category Tracking
+ * @since 4.0.0
  */
 export const trackErrors = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric, f) => tapError(self, error => {
   const input = f === undefined ? error : internalCall(() => f(error));
@@ -6969,7 +7028,8 @@ export const trackErrors = /*#__PURE__*/dual(args => isEffect(args[0]), (self, m
  * Also accepts an optional function which can be used to map the defect value
  * of the `Effect` into a valid `Input` for the `Metric`.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect, Metric } from "effect"
  *
@@ -6987,7 +7047,8 @@ export const trackErrors = /*#__PURE__*/dual(args => isEffect(args[0]), (self, m
  * )
  * ```
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect, Metric } from "effect"
  *
@@ -7007,8 +7068,8 @@ export const trackErrors = /*#__PURE__*/dual(args => isEffect(args[0]), (self, m
  * )
  * ```
  *
- * @since 4.0.0
  * @category Tracking
+ * @since 4.0.0
  */
 export const trackDefects = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric, f) => tapDefect(self, defect => {
   const input = f === undefined ? defect : internalCall(() => f(defect));
@@ -7022,7 +7083,8 @@ export const trackDefects = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
  * that the wrapped `Effect` took to complete into a valid `Input` for the
  * `Metric`.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect, Metric } from "effect"
  *
@@ -7038,7 +7100,8 @@ export const trackDefects = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
  * )
  * ```
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Duration, Effect, Metric } from "effect"
  *
@@ -7055,8 +7118,8 @@ export const trackDefects = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
  * )
  * ```
  *
- * @since 4.0.0
  * @category Tracking
+ * @since 4.0.0
  */
 export const trackDuration = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric, f) => clockWith(clock => {
   const startTime = clock.currentTimeNanosUnsafe();
@@ -7076,7 +7139,8 @@ export const trackDuration = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
  * - a journal that stores any non committed change to TxRef values
  * - a retry flag to know if the transaction should be retried
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -7088,8 +7152,8 @@ export const trackDuration = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
  * })
  * ```
  *
- * @since 4.0.0
  * @category Transactions
+ * @since 4.0.0
  */
 export class Transaction extends /*#__PURE__*/Context.Service()("effect/Effect/Transaction") {}
 /**
@@ -7110,7 +7174,8 @@ export class Transaction extends /*#__PURE__*/Context.Service()("effect/Effect/T
  * The outermost `tx` call creates the transaction boundary and commits or rolls back the full
  * composed transaction.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
@@ -7131,8 +7196,8 @@ export class Transaction extends /*#__PURE__*/Context.Service()("effect/Effect/T
  * })
  * ```
  *
- * @since 4.0.0
  * @category Transactions
+ * @since 4.0.0
  */
 export const tx = effect => withFiber(fiber => {
   if (fiber.context.mapUnsafe.has(Transaction.key)) {
@@ -7215,10 +7280,10 @@ function clearTransaction(state) {
  *
  * NOTE: the transaction retries on any change to transactional values (i.e. TxRef) accessed in its body.
  *
- * @since 4.0.0
  * @category Transactions
+ * @since 4.0.0
  *
- * @example
+ * **Example** (Usage)
  *
  * ```ts
  * import { Effect, TxRef } from "effect"
@@ -7252,9 +7317,19 @@ export const txRetry = /*#__PURE__*/flatMap(Transaction, state => {
   return interrupt;
 });
 /**
- * Converts a callback-based function to a function that returns an `Effect`.
+ * Converts an error-first callback API into a function that returns an
+ * `Effect`.
+ *
+ * **Details**
+ *
+ * The original function is called with the supplied arguments plus a final
+ * callback. A non-null callback error fails the returned effect, while a
+ * successful callback value becomes the effect success. Use `onError` to map
+ * callback errors and `onSyncError` to turn synchronous throws into typed
+ * failures; otherwise synchronous throws become defects.
+ *
+ * **Example** (Basic Usage)
  *
- * @example Basic Usage
  * ```ts
  * import { Effect } from "effect"
  * import * as fs from "fs"
@@ -7269,7 +7344,8 @@ export const txRetry = /*#__PURE__*/flatMap(Transaction, state => {
  * // Output: contents of package.json
  * ```
  *
- * @example Custom Error Handling
+ * **Example** (Custom Error Handling)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as fs from "fs"
@@ -7285,8 +7361,8 @@ export const txRetry = /*#__PURE__*/flatMap(Transaction, state => {
  * // Output: Exit.failure with custom error message
  * ```
  *
- * @since 4.0.0
  * @category Effectify
+ * @since 4.0.0
  */
 export const effectify = (fn, onError, onSyncError) => (...args) => callback(resume => {
   try {
@@ -7310,7 +7386,8 @@ export const effectify = (fn, onError, onSyncError) => (...args) => callback(res
  * This function provides compile-time type checking to ensure that the success
  * value of an effect conforms to a specific type constraint.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -7326,8 +7403,8 @@ export const effectify = (fn, onError, onSyncError) => (...args) => callback(res
  * // Type 'string' is not assignable to type 'number'
  * ```
  *
- * @since 4.0.0
  * @category Type Constraints
+ * @since 4.0.0
  */
 export const satisfiesSuccessType = () => effect => effect;
 /**
@@ -7336,7 +7413,8 @@ export const satisfiesSuccessType = () => effect => effect;
  * This function provides compile-time type checking to ensure that the error
  * type of an effect conforms to a specific type constraint.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Data, Effect } from "effect"
  *
@@ -7354,8 +7432,8 @@ export const satisfiesSuccessType = () => effect => effect;
  * // Type 'string' is not assignable to type 'ValidationError'
  * ```
  *
- * @since 4.0.0
  * @category Type Constraints
+ * @since 4.0.0
  */
 export const satisfiesErrorType = () => effect => effect;
 /**
@@ -7364,7 +7442,8 @@ export const satisfiesErrorType = () => effect => effect;
  * This function provides compile-time type checking to ensure that the
  * requirements (context) type of an effect conforms to a specific type constraint.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -7380,8 +7459,8 @@ export const satisfiesErrorType = () => effect => effect;
  * // const constrainedInvalid = satisfiesStringServices(invalidEffect)
  * ```
  *
- * @since 4.0.0
  * @category Type Constraints
+ * @since 4.0.0
  */
 export const satisfiesServicesType = () => effect => effect;
 /**
@@ -7400,7 +7479,8 @@ export const satisfiesServicesType = () => effect => effect;
  * - For **Failure effects**: Returns the failure as-is without applying the mapping
  * - For **Pending effects**: Falls back to the regular `map` behavior
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -7413,8 +7493,8 @@ export const satisfiesServicesType = () => effect => effect;
  * const mappedPending = Effect.mapEager(pending, (n) => n * 2) // Uses regular map
  * ```
  *
- * @since 4.0.0
  * @category Eager
+ * @since 4.0.0
  */
 export const mapEager = internal.mapEager;
 /**
@@ -7433,7 +7513,8 @@ export const mapEager = internal.mapEager;
  * - For **Failure effects**: Applies the mapping function immediately to the error
  * - For **Pending effects**: Falls back to the regular `mapError` behavior
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -7449,8 +7530,8 @@ export const mapEager = internal.mapEager;
  * ) // Uses regular mapError
  * ```
  *
- * @since 4.0.0
  * @category Eager
+ * @since 4.0.0
  */
 export const mapErrorEager = internal.mapErrorEager;
 /**
@@ -7469,7 +7550,8 @@ export const mapErrorEager = internal.mapErrorEager;
  * - For **Failure effects**: Applies the `onFailure` function immediately to the error
  * - For **Pending effects**: Falls back to the regular `mapBoth` behavior
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -7487,8 +7569,8 @@ export const mapErrorEager = internal.mapErrorEager;
  * }) // onFailure applied eagerly
  * ```
  *
- * @since 4.0.0
  * @category Eager
+ * @since 4.0.0
  */
 export const mapBothEager = internal.mapBothEager;
 /**
@@ -7507,7 +7589,8 @@ export const mapBothEager = internal.mapBothEager;
  * - For **Failure effects**: Returns the failure as-is without applying the flatMap
  * - For **Pending effects**: Falls back to the regular `flatMap` behavior
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -7523,8 +7606,8 @@ export const mapBothEager = internal.mapBothEager;
  * ) // Uses regular flatMap
  * ```
  *
- * @since 4.0.0
  * @category Eager
+ * @since 4.0.0
  */
 export const flatMapEager = internal.flatMapEager;
 /**
@@ -7543,7 +7626,8 @@ export const flatMapEager = internal.flatMapEager;
  * - For **Failure effects**: Applies the catch function immediately to the error
  * - For **Pending effects**: Falls back to the regular `catch` behavior
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -7569,8 +7653,8 @@ export const flatMapEager = internal.flatMapEager;
  * ) // Uses regular catch
  * ```
  *
- * @since 4.0.0
  * @category Eager
+ * @since 4.0.0
  */
 export const catchEager = internal.catchEager;
 /**
@@ -7579,7 +7663,8 @@ export const catchEager = internal.catchEager;
  * Executes generator functions eagerly when all yielded effects are synchronous,
  * stopping at the first async effect and deferring to normal execution.
  *
- * @example
+ * **Example** (Usage)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -7592,8 +7677,8 @@ export const catchEager = internal.catchEager;
  * const effect = computation() // Executed immediately if all effects are sync
  * ```
  *
- * @since 4.0.0
  * @category Eager
+ * @since 4.0.0
  */
 export const fnUntracedEager = internal.fnUntracedEager;
 //# sourceMappingURL=Effect.js.map